Intentions MCP Server

Call when the user asks about timing a decision for a specific date, or wants to pick the best day from a multi-day window. Covers trip dates, launch days, interview/meeting days, publish/send dates, travel, negotiation windows, relationship moments — any "when to X" question where the answer is a date ("should I X on April 23", "best day this month to Y", "下周四怎么样"). Modes: single date, compare up to 5 dates, or scan a range up to 31 days. On the free tier a range must sit inside the past week and the week ahead; single and compared dates are free anywhere in the window. Returns score (0-100), verdict, per-layer year/month/day breakdown (alerts + dimension signals), element breakdown, adverse alerts. For multi-month windows use `intentions_ask_month`; for hour precision use `intentions_ask_hour`.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The decision or action being considered"
    },
    "targetDate": {
      "type": "string",
      "description": "YYYY-MM-DD. Default: today"
    },
    "compareDates": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 4,
      "description": "Up to 4 additional YYYY-MM-DD dates to compare against targetDate"
    },
    "dateRange": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string"
        },
        "end": {
          "type": "string"
        }
      },
      "description": "Find best dates in range. Max 31 days — use ask_month for longer windows. Free tier: the past week and the week ahead only."
    },
    "category": {
      "type": "string",
      "enum": [
        "career",
        "relationship",
        "health",
        "finance",
        "travel",
        "general"
      ],
      "description": "Decision domain — tunes the analysis weighting. Default: general."
    },
    "birthInfo": {
      "type": "object",
      "description": "Optional override. If provided, all 6 fields required: { year, month, day, hour, minute, gender } — use null for unknown hour/minute/gender. Omit entirely to use the stored profile."
    }
  },
  "required": [
    "question"
  ]
}

Call when the user asks about timing within a specific day — best hour to act, morning vs afternoon, when during the day ("best time today to X", "morning or afternoon for Y", "几点去见面好"). Use for interview slots, meeting times, send/publish times, departure times, workout windows. Pro subscription required; on the free tier this returns a `subscription_required` error whose payload suggests `intentions_ask_day` for day-level analysis or `intentions_energy_chart` with period `weekly` / `yearly` for a visual overview (the caller LLM decides whether to retry). Modes: single (date+hour), compare up to 5 hour-pairs, or scan all 12 two-hour blocks of one day. Accepts any clock hour 0..23; internally mapped to the containing 2-hour block midpoint (0/2/4/…/22). 23:00–23:59 automatically rolls the effective day forward by one. Every output entry includes a `window { start, end }` local wall-clock span (`YYYY-MM-DDTHH:MM`, no timezone offset — interpret in the same frame as the input hour). Always cite this when presenting the time. Returns score, verdict, adverse alerts.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The decision or action being considered"
    },
    "targetDate": {
      "type": "string",
      "description": "YYYY-MM-DD. Default: today (single mode only)"
    },
    "targetHour": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Clock hour 0..23. Auto-rounded to the containing 2-hour block. 23:XX rolls the effective day forward by one."
    },
    "compareHours": {
      "type": "array",
      "maxItems": 4,
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          },
          "hour": {
            "type": "integer",
            "minimum": 0,
            "maximum": 23
          }
        },
        "required": [
          "date",
          "hour"
        ]
      },
      "description": "Up to 4 additional (date, clock-hour 0..23) pairs to compare against targetDate+targetHour. Pairs that resolve to the same 2-hour block (e.g. hours 7 and 8 on the same date) are deduplicated — submit distinct blocks if you want distinct results."
    },
    "bestInDay": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string"
        },
        "top": {
          "type": "integer",
          "minimum": 1,
          "maximum": 12,
          "description": "Number of top hours to return (default 5)"
        }
      },
      "required": [
        "date"
      ],
      "description": "Find best hours within a single day. Each entry carries an explicit `window` span."
    },
    "category": {
      "type": "string",
      "enum": [
        "career",
        "relationship",
        "health",
        "finance",
        "travel",
        "general"
      ],
      "description": "Decision domain — tunes the analysis weighting. Default: general."
    },
    "birthInfo": {
      "type": "object",
      "description": "Optional override. If provided, all 6 fields required: { year, month, day, hour, minute, gender } — use null for unknown hour/minute/gender. Omit entirely to use the stored profile."
    }
  },
  "required": [
    "question"
  ]
}

Call when the user asks about a full calendar year as a whole ("how is 2026", "今年怎么样", "what's next year like overall"). Returns year-level score, verdict, adverse alerts, and element dimensions. For month precision use `intentions_ask_month`; for day use `intentions_ask_day`. Window: currentYear-3 to currentYear+3 only.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The decision or action being considered"
    },
    "targetYear": {
      "type": "integer",
      "description": "YYYY. Default: current year. Allowed: currentYear-3 .. currentYear+3."
    },
    "category": {
      "type": "string",
      "enum": [
        "career",
        "relationship",
        "health",
        "finance",
        "travel",
        "general"
      ],
      "description": "Decision domain — tunes the analysis weighting. Default: general."
    },
    "birthInfo": {
      "type": "object",
      "description": "Optional override. If provided, all 6 fields required: { year, month, day, hour, minute, gender } — use null for unknown hour/minute/gender. Omit entirely to use the stored profile."
    }
  },
  "required": [
    "question"
  ]
}

Call when the user asks at month granularity or wants the best month from a multi-month window ("how is next month", "best month in 2026 to X", "下个月适合吗"). Use for trip-month selection, launch months, content-calendar planning, quarterly/annual decisions. Modes: single month, compare up to 5 months, or scan up to 12 months (returns top 5). Single and compared months are free; scanning a range is free inside last year and this year, and Pro further out. Returns month score, element breakdown, adverse alerts. For day precision near the 4th–6th of a month use `intentions_ask_day`; for hour precision use `intentions_ask_hour`.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The decision or action being considered"
    },
    "targetMonth": {
      "type": "string",
      "description": "YYYY-MM. Default: current month"
    },
    "compareMonths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 4,
      "description": "Up to 4 additional YYYY-MM months to compare against targetMonth"
    },
    "monthRange": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string"
        },
        "end": {
          "type": "string"
        }
      },
      "description": "Find best months in range. Max 12 months. Inclusive on both ends. Free inside last year and this year; Pro further out."
    },
    "category": {
      "type": "string",
      "enum": [
        "career",
        "relationship",
        "health",
        "finance",
        "travel",
        "general"
      ],
      "description": "Decision domain — tunes the analysis weighting. Default: general."
    },
    "birthInfo": {
      "type": "object",
      "description": "Optional override. If provided, all 6 fields required: { year, month, day, hour, minute, gender } — use null for unknown hour/minute/gender. Omit entirely to use the stored profile."
    }
  },
  "required": [
    "question"
  ]
}

Call when the user wants a visual overview rather than a narrative answer ("show me this week", "chart for today", "next 12 months", "看一下图"). Returns an ASCII chart: `hourly` = 12 two-hour blocks of one day, `weekly` = 7 days, `yearly` = 12 months. The `hourly` mode emits the same hour-resolution scores as `intentions_ask_hour` and is Pro: on the free tier it returns a `subscription_required` error whose payload suggests alternatives. `weekly` is free for the past week and the week ahead (omit `date` for this week), and `yearly` for the months of last year and this year (omit `date` for this year); further out both are Pro too.

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "enum": [
        "hourly",
        "weekly",
        "yearly"
      ],
      "description": "Which chart to render: `hourly` = 12 two-hour blocks of one day (Pro), `weekly` = 7 days from `date` (free inside the past week and the week ahead), `yearly` = the 12 months of the year of `date` (free for last year and this year)."
    },
    "date": {
      "type": "string",
      "description": "YYYY-MM-DD. Default: today"
    },
    "birthInfo": {
      "type": "object",
      "description": "Optional override. If provided, all 6 fields required: { year, month, day, hour, minute, gender } — use null for unknown hour/minute/gender. Omit to use the stored profile."
    }
  },
  "required": [
    "period"
  ]
}

Call once to register the user's birth date/time/gender. Each call is a complete replacement — all 6 fields must be supplied. For fields the user does not know or prefers not to share, pass `null` explicitly (e.g. `hour: null` for unknown birth time, `gender: null` for unspecified). To update just one field, first call `intentions_get_profile` to fetch the current values, merge the user's new input, then call this tool with the full merged payload. Changes to the date, gender or a known hour (including setting a known hour back to null) are limited to 3 per calendar month (UTC); filling in a previously-null hour, or the minute, is always free. `intentions_get_profile` returns how many are left. Returns the element profile.

{
  "type": "object",
  "properties": {
    "year": {
      "type": "integer",
      "minimum": 1920,
      "maximum": 2030,
      "description": "Birth year, 1920–2030."
    },
    "month": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12,
      "description": "Birth month, 1–12."
    },
    "day": {
      "type": "integer",
      "minimum": 1,
      "maximum": 31,
      "description": "Birth day of month, 1–31."
    },
    "hour": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "maximum": 23,
      "description": "null if unknown"
    },
    "minute": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "maximum": 59,
      "description": "null if unknown; requires hour to also be non-null"
    },
    "gender": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "M",
        "F",
        null
      ],
      "description": "null if unspecified"
    }
  },
  "required": [
    "year",
    "month",
    "day",
    "hour",
    "minute",
    "gender"
  ]
}

Fetch the user's currently stored birth info. Use this before `intentions_set_birth_info` when updating an existing profile so you can send back a complete merged payload. Returns { hasProfile, birthInfo: { year, month, day, hour, minute, gender } | null, profileChanges: { remaining, resetsAt } | null } where any unknown birth field (e.g. unknown hour) is returned as `null`. `profileChanges` is how many changes to the date, gender or a known hour are left this calendar month (UTC) and the ISO instant they come back; if `remaining` is 0, tell the user before attempting such a change. No quota cost.

{
  "type": "object",
  "properties": {}
}