@openephemeris/mcp-server 3.24.0 → 4.1.0

package/dist/oauth/session-utils.d.ts

@@ -1,21 +1,3 @@
-/**
- * src/oauth/session-utils.ts — Pure helpers for session reliability.
- *
- * Two concerns live here so they can be unit-tested without spinning up the
- * full SSE server:
- *
- *   1. JWT expiry decoding — read the `exp` claim WITHOUT signature
- *      verification. The signature is validated downstream by the Go API's
- *      ValidateSupabaseJWT; here we only need to know whether a token is
- *      already expired so the /mcp gate can trigger the host's OAuth refresh
- *      (401 invalid_token) instead of letting it die as a confusing tool error.
- *
- *   2. Machine-scoped session IDs — Fly runs min_machines_running >= 2, but the
- *      HTTP/SSE session store is a per-process Map. A resume request can land on
- *      a different machine and 404. We embed the FLY_MACHINE_ID into generated
- *      session IDs so an incoming request can be re-routed to the owning machine
- *      via the `fly-replay` header. Local/dev (no FLY_MACHINE_ID) is a no-op.
- */
 /**
  * Decode a JWT's payload without verifying the signature and return its `exp`
  * claim (seconds since epoch), or null if the token is malformed / has no exp.
@@ -57,3 +39,45 @@ export declare function replayTargetMachine(sessionId: string, opts: {
     selfMachineId?: string;
     alreadyReplayed: boolean;
 }): string | null;
+/**
+ * Decode a JWT's `sub` (subject) claim without verifying the signature.
+ * The subject is the stable Supabase user id — it survives token refresh,
+ * whereas the raw JWT string rotates roughly hourly. Returns null when the
+ * token is malformed or carries no usable string `sub`.
+ */
+export declare function decodeJwtSub(token: string): string | null;
+/**
+ * Compute the STABLE binding token for a presented credential — the value a
+ * session is bound to at init and re-checked on every resume:
+ *
+ *   - API key → the raw key. A given key is re-presented verbatim on every
+ *     request, so binding to it is exact.
+ *   - JWT     → the `sub` claim (Supabase user id), NOT the raw token. claude.ai
+ *     rotates the Bearer JWT ~hourly via /oauth/token; binding to the raw token
+ *     would 403 every legitimate refresh. The subject is constant across
+ *     refreshes for the same user, so binding survives rotation while still
+ *     rejecting a different user's token.
+ *   - JWT with no decodable `sub` → fall back to the raw token (best effort;
+ *     Supabase access tokens always carry `sub`, so this is a degenerate case).
+ *
+ * Returns null when neither credential is present.
+ */
+export declare function credentialBindingToken(auth: {
+    apiKey?: string;
+    jwt?: string;
+}): string | null;
+/** SHA-256 hex digest of a binding token — what we store on the session record. */
+export declare function hashBindingToken(token: string): string;
+/**
+ * Compute the stored/compared binding hash for a request's auth, or null when
+ * the request carries no credential.
+ */
+export declare function credentialBindingHash(auth: {
+    apiKey?: string;
+    jwt?: string;
+}): string | null;
+/**
+ * Constant-time comparison of two binding hashes. Both are fixed-length hex
+ * digests; a length mismatch (or a null presented hash) is a non-match.
+ */
+export declare function bindingHashMatches(stored: string, presented: string | null): boolean;

package/dist/oauth/session-utils.js

@@ -15,7 +15,14 @@
  *      a different machine and 404. We embed the FLY_MACHINE_ID into generated
  *      session IDs so an incoming request can be re-routed to the owning machine
  *      via the `fly-replay` header. Local/dev (no FLY_MACHINE_ID) is a no-op.
+ *
+ *   3. Session-credential binding — a session id is a bearer-ish routing token,
+ *      not proof of identity. We bind each session to the credential that
+ *      initialized it (see credentialBinding* below) so a leaked session id
+ *      alone can't be used with a *different* valid credential to hijack another
+ *      user's session or SSE stream.
  */
+import { createHash, timingSafeEqual } from "node:crypto";
 /**
  * Decode a JWT's payload without verifying the signature and return its `exp`
  * claim (seconds since epoch), or null if the token is malformed / has no exp.
@@ -108,3 +115,75 @@ export function replayTargetMachine(sessionId, opts) {
         return null; // we own it
     return target;
 }
+// ---------------------------------------------------------------------------
+// Session-credential binding
+// ---------------------------------------------------------------------------
+/**
+ * Decode a JWT's `sub` (subject) claim without verifying the signature.
+ * The subject is the stable Supabase user id — it survives token refresh,
+ * whereas the raw JWT string rotates roughly hourly. Returns null when the
+ * token is malformed or carries no usable string `sub`.
+ */
+export function decodeJwtSub(token) {
+    if (typeof token !== "string" || !token)
+        return null;
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const payloadJson = Buffer.from(parts[1], "base64url").toString("utf8");
+        const payload = JSON.parse(payloadJson);
+        if (typeof payload.sub === "string" && payload.sub)
+            return payload.sub;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute the STABLE binding token for a presented credential — the value a
+ * session is bound to at init and re-checked on every resume:
+ *
+ *   - API key → the raw key. A given key is re-presented verbatim on every
+ *     request, so binding to it is exact.
+ *   - JWT     → the `sub` claim (Supabase user id), NOT the raw token. claude.ai
+ *     rotates the Bearer JWT ~hourly via /oauth/token; binding to the raw token
+ *     would 403 every legitimate refresh. The subject is constant across
+ *     refreshes for the same user, so binding survives rotation while still
+ *     rejecting a different user's token.
+ *   - JWT with no decodable `sub` → fall back to the raw token (best effort;
+ *     Supabase access tokens always carry `sub`, so this is a degenerate case).
+ *
+ * Returns null when neither credential is present.
+ */
+export function credentialBindingToken(auth) {
+    if (auth.apiKey)
+        return `key:${auth.apiKey}`;
+    if (auth.jwt) {
+        const sub = decodeJwtSub(auth.jwt);
+        return sub ? `sub:${sub}` : `jwt:${auth.jwt}`;
+    }
+    return null;
+}
+/** SHA-256 hex digest of a binding token — what we store on the session record. */
+export function hashBindingToken(token) {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+/**
+ * Compute the stored/compared binding hash for a request's auth, or null when
+ * the request carries no credential.
+ */
+export function credentialBindingHash(auth) {
+    const token = credentialBindingToken(auth);
+    return token ? hashBindingToken(token) : null;
+}
+/**
+ * Constant-time comparison of two binding hashes. Both are fixed-length hex
+ * digests; a length mismatch (or a null presented hash) is a non-match.
+ */
+export function bindingHashMatches(stored, presented) {
+    if (!presented || stored.length !== presented.length)
+        return false;
+    return timingSafeEqual(Buffer.from(stored, "utf8"), Buffer.from(presented, "utf8"));
+}

package/dist/prompts.js

@@ -68,13 +68,15 @@ export const PROMPTS = [
             "   Default to Placidus if they're unsure.\n\n" +
             "## Step 2 — Resolve Coordinates and Timezone (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones from memory.** Use the API tools to resolve them:\n\n" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'City Name, Country' }`. This returns verified decimal lat/lon.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`. " +
-            "This returns the correct IANA timezone and UTC offset for the birth year, including historical DST.\n\n" +
-            "- Format: pass `datetime` as local ISO 8601 (e.g. `1990-04-15T14:30:00`) " +
-            "and `timezone` as the IANA name returned by the lookup. Do NOT append Z to a local birth time.\n\n" +
+            "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
+            "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
+            "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- Pass the local wall-clock time as `datetime` (e.g. `1990-04-15T14:30:00`) together with " +
+            "the `timezone` from the search. Do NOT convert to UTC yourself and do NOT append a Z to a " +
+            "local birth time — a zone-less datetime is rejected, and a hand-converted one is how charts " +
+            "end up hours off.\n\n" +
             "## Step 3 — Tool Call\n" +
             "Make a single call to `explore_natal_chart` (the interactive chart wheel) with:\n" +
             "- `datetime`: local ISO 8601 (no Z)\n" +
@@ -146,10 +148,11 @@ export const PROMPTS = [
             "4. **Any major events coming up** they already know about — reframes the transits around real context\n\n" +
             "## Step 2 — Resolve Coordinates and Timezone (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones from memory.** Use the API tools:\n\n" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`. Use the returned decimal lat/lon.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
+            "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
+            "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
+            "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
             "- Set `start_date` to today and `end_date` to the end of the forecast window\n\n" +
             "## Step 3 — Tool Call Sequence\n" +
             "Two calls minimum, run sequentially:\n\n" +
@@ -211,11 +214,13 @@ export const PROMPTS = [
             "7. **House system**: Placidus (default), Whole Sign, Koch, Equal?\n\n" +
             "## Step 2 — Resolve Both Sets of Coordinates (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones.** For EACH person:\n\n" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
-            "- Format: local ISO 8601 datetime (no Z) + IANA timezone name separately for each person\n" +
+            "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
+            "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
+            "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- Do this for BOTH people. Pass each local wall-clock datetime with its own `timezone`; " +
+            "never convert to UTC by hand.\n" +
             "- Note if either birth time is unknown — flag this upfront before running tools\n\n" +
             "## Step 3 — Tool Call\n" +
             "Make a single call to `ephemeris_synastry` with:\n" +
@@ -283,12 +288,14 @@ export const PROMPTS = [
             "sometimes it explains why a place felt 'off'\n\n" +
             "## Step 2 — Resolve Coordinates (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones.** Use the API tools:\n\n" +
-            "**A) Geocode birth city** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
-            "**C) Geocode each target city** — repeat the autocomplete call for each destination city.\n\n" +
-            "- Format birth datetime as local ISO 8601 (no Z), pass IANA timezone separately\n\n" +
+            "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
+            "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
+            "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "**Then geocode each target city** — one `location_search` per destination.\n\n" +
+            "- Pass the birth datetime as local wall-clock time with its `timezone`; never append a Z " +
+            "to a local time.\n\n" +
             "## Step 3 — Tool Call Sequence\n" +
             "Two calls minimum. Start lean, offer more after delivery.\n\n" +
             "**A) City-Level Hits** — for EACH target city, call `acg_hits` with:\n" +
@@ -372,13 +379,15 @@ export const PROMPTS = [
             "4. **Birth city and country** — needed for timezone conversion\n\n" +
             "## Step 2 — CRITICAL: Convert to UTC\n" +
             "Human Design requires **UTC datetime**. The tool rejects local times without a UTC offset.\n\n" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n" +
-            "This returns the UTC offset for the birth year, including historical DST.\n\n" +
-            "- Use the returned offset to convert local birth time → UTC\n" +
-            "- Format as ISO 8601 with Z: e.g. `1990-04-15T19:30:00Z`\n\n" +
+            "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
+            "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
+            "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- Pass the local wall-clock time as `datetime` (e.g. `1990-04-15T14:30:00`) together with " +
+            "the `timezone` from the search. Do NOT convert to UTC yourself and do NOT append a Z to a " +
+            "local birth time — a zone-less datetime is rejected, and a hand-converted one is how charts " +
+            "end up hours off.\n\n" +
             "**Why HD needs UTC**: The system calculates two activation moments:\n" +
             "- **Personality (Conscious / Black)**: the birth datetime\n" +
             "- **Design (Unconscious / Red)**: 88° of the Sun's arc before birth (approximately 88–89 days, varying by season)\n" +
@@ -545,13 +554,15 @@ export const PROMPTS = [
             "   Default to Lahiri if unsure.\n\n" +
             "## Step 2 — Convert to UTC (MANDATORY)\n" +
             "The `vedic_chart` tool requires a UTC datetime (with Z suffix):\n\n" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n" +
-            "This returns the correct IANA timezone and UTC offset for the birth year, including historical DST.\n\n" +
-            "- Use the returned offset to convert local birth time → UTC\n" +
-            "- Format: `1990-01-15T03:00:00Z`\n\n" +
+            "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
+            "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
+            "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- Pass the local wall-clock time as `datetime` (e.g. `1990-04-15T14:30:00`) together with " +
+            "the `timezone` from the search. Do NOT convert to UTC yourself and do NOT append a Z to a " +
+            "local birth time — a zone-less datetime is rejected, and a hand-converted one is how charts " +
+            "end up hours off.\n\n" +
             "## Step 3 — Call the Tool\n" +
             "Call `vedic_chart` with:\n" +
             "- `datetime`: UTC ISO 8601 with Z\n" +
@@ -772,12 +783,14 @@ export const PROMPTS = [
             "4. **House system**: Placidus (default), Whole Sign, Koch, Equal?\n\n" +
             "## Step 2 — Resolve Data (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones.** Use the API tools:\n\n" +
-            "**A) Geocode birth city** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
-            "- For `birth_datetime`, include the UTC offset from the timezone lookup: `1985-06-21T14:00:00-05:00`\n" +
-            "  (or convert to UTC with Z: `1985-06-21T19:00:00Z`)\n\n" +
+            "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
+            "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
+            "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- For `birth_datetime`, either append `utcOffsetAtDate` from the search " +
+            "(`1985-06-21T14:00:00-05:00`) or pass the local time with its `timezone`. Both are accepted; " +
+            "a zone-less value is not.\n\n" +
             "**C) Geocode birthday location** — repeat the autocomplete call for the city where they'll be " +
             "on their birthday. This becomes `return_latitude`/`return_longitude`.\n\n" +
             "## Step 3 — Tool Call\n" +

package/dist/server-sse.js

@@ -23,7 +23,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { InMemoryEventStore } from "./event-store.js";
 import { captureEvent, distinctIdFor } from "./analytics.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
-import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools } from "./tools/index.js";
+import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface } from "./tools/index.js";
 import { BackendClient, runWithClient } from "./backend/client.js";
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
 import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
@@ -40,7 +40,7 @@ import { oauthDcrRouter } from "./oauth/dcr.js";
 import { oauthTokenRouter } from "./oauth/token.js";
 import { OAuthStore } from "./oauth/store.js";
 import { createRateLimiter } from "./oauth/rate-limit.js";
-import { isJwtExpired, encodeSessionId, replayTargetMachine, } from "./oauth/session-utils.js";
+import { isJwtExpired, encodeSessionId, replayTargetMachine, credentialBindingHash, bindingHashMatches, } from "./oauth/session-utils.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -204,7 +204,23 @@ const WELCOME_PROMPT_CONTENT = [
 // ---------------------------------------------------------------------------
 // MCP Server factory — one per SSE/HTTP session
 // ---------------------------------------------------------------------------
-function createMcpServer(analyticsId = "anonymous") {
+/**
+ * Properties attached to every remote-transport event, mirroring the stdio
+ * shape in src/index.ts so a single PostHog query can compare the two.
+ * `client_name` comes from the MCP initialize handshake and identifies the
+ * connecting host (claude.ai, Claude Desktop, Cursor, …).
+ */
+function transportProps(server, surface) {
+    const info = server.getClientVersion();
+    return {
+        transport: "http",
+        surface,
+        client_name: info?.name ?? "unknown",
+        client_version: info?.version ?? "unknown",
+        server_version: version,
+    };
+}
+function createMcpServer(analyticsId = "anonymous", surface = "core") {
     const server = new Server({
         name: "openephemeris-mcp",
         title: "Open Ephemeris",
@@ -220,7 +236,7 @@ function createMcpServer(analyticsId = "anonymous") {
         // but the SDK's Zod schema doesn't include it yet — pass via spread
         ...{
             description: "NASA JPL DE440-backed astronomical computation engine for AI agents. " +
-                "52+ typed tools covering natal charts, transit forecasting, Human Design " +
+                "90+ typed tools covering natal charts, transit forecasting, Human Design " +
                 "bodygraphs, eclipses, astrocartography power lines, Venus Star Points, " +
                 "electional timing, synastry, composite charts, Vedic/Jyotish, Chinese BaZi, " +
                 "and more — powered by JPL DE440 ephemerides for sub-arcsecond accuracy.",
@@ -257,7 +273,7 @@ function createMcpServer(analyticsId = "anonymous") {
     });
     // --- Tool handlers ---
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: modelVisibleTools("http").map((tool) => ({
+        tools: modelVisibleTools("http", surface).map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -305,15 +321,30 @@ function createMcpServer(analyticsId = "anonymous") {
             // composite ~9.3s) with a wide margin.
             const result = await withTimeout(tool.handler(request.params.arguments ?? {}), TOOL_CALL_TIMEOUT_MS, toolName);
             const durationMs = Date.now() - startTime;
-            captureEvent("mcp_tool_call", analyticsId, { tool: toolName, duration_ms: durationMs });
+            captureEvent("mcp_tool_call", analyticsId, {
+                tool: toolName,
+                duration_ms: durationMs,
+                ...transportProps(server, surface),
+            });
             return formatToolResponse(toolName, result, durationMs);
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             console.error(`[MCP] ❌ Failed: ${toolName} - ${errorMessage}`);
             // status makes 402 (paywall) and 429 (rate limit) countable in PostHog.
-            const status = error?.response?.status;
-            captureEvent("mcp_tool_error", analyticsId, { tool: toolName, status: status ?? "unknown" });
+            // Errors thrown locally (validateRequired, withTimeout) are plain Errors
+            // with no status — previously they all landed as status:"unknown", which
+            // made a burst of client-side argument errors indistinguishable from a
+            // backend outage. error_kind splits the two.
+            const err = error;
+            const status = err?.status ?? err?.response?.status;
+            captureEvent("mcp_tool_error", analyticsId, {
+                tool: toolName,
+                status: status ?? "unknown",
+                error_kind: status != null ? "backend" : "local",
+                code: err?.code ?? "none",
+                ...transportProps(server, surface),
+            });
             // All failures surface as isError: true so the host can recover
             // (retry / OAuth refresh). The remote transport has no device-auth flow,
             // so formatToolError's device-auth exception never fires here — a 401
@@ -435,6 +466,20 @@ function createMcpServer(analyticsId = "anonymous") {
     });
     return server;
 }
+/**
+ * Shared 403 for a resume/attach whose presented credential does not match the
+ * one the session was initialized with. RFC 7807 problem+json.
+ */
+function rejectCredentialMismatch(res) {
+    res.status(403).type("application/problem+json").json({
+        type: "https://openephemeris.com/problems/session-credential-mismatch",
+        title: "Session credential mismatch",
+        status: 403,
+        error: "session_credential_mismatch",
+        detail: "This MCP session belongs to a different credential. Re-initialize a new " +
+            "session with your own API key or Bearer token instead of resuming this one.",
+    });
+}
 const httpSessions = new Map();
 // Sessions are held in memory and only freed on explicit DELETE / transport
 // close. Hosts that vanish without teardown (tab closed, network drop) would
@@ -552,7 +597,7 @@ export async function createSseApp() {
             res.setHeader("Vary", "Origin");
         }
         res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-API-Key, X-OpenEphemeris-API-Key, mcp-session-id");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-API-Key, X-OpenEphemeris-API-Key, X-OE-Tool-Surface, mcp-session-id");
         if (req.method === "OPTIONS") {
             res.status(204).end();
             return;
@@ -610,7 +655,10 @@ export async function createSseApp() {
     // Spec: https://smithery.ai/docs/build/publish#server-scanning
     // ---------------------------------------------------------------------------
     app.get("/.well-known/mcp/server-card.json", (_req, res) => {
-        const tools = modelVisibleTools("http").map((tool) => ({
+        // Deliberately "full": the card is a registry catalogue, not model context.
+        // Smithery and friends should see every callable tool even though a live
+        // session advertises the leaner core surface by default.
+        const tools = modelVisibleTools("http", "full").map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -621,7 +669,7 @@ export async function createSseApp() {
             serverInfo: {
                 name: "Open Ephemeris",
                 version,
-                description: "NASA JPL DE440-backed astronomical computation engine for AI agents. 52+ typed tools covering " +
+                description: "NASA JPL DE440-backed astronomical computation engine for AI agents. 90+ typed tools covering " +
                     "natal charts, transit forecasting, Human Design bodygraphs, eclipses, astrocartography " +
                     "power lines, Venus Star Points, electional timing, synastry, composite charts, Vedic/Jyotish, " +
                     "Chinese BaZi, and more — powered by JPL DE440 ephemerides for sub-arcsecond " +
@@ -695,6 +743,15 @@ export async function createSseApp() {
                 });
                 return;
             }
+            // Session-credential binding: the presented credential must hash to the
+            // same stable binding token the session was initialized with. This is the
+            // check that turns the session id from a bearer token into a routing token
+            // — a leaked id plus a *different* valid key/JWT cannot hijack the session.
+            // (JWT binds to `sub`, so claude.ai's ~hourly token refresh still matches.)
+            if (!bindingHashMatches(session.credentialHash, credentialBindingHash(resumedAuth))) {
+                rejectCredentialMismatch(res);
+                return;
+            }
             // Refresh the session's Bearer JWT if the host rotated it. claude.ai
             // refreshes tokens via /oauth/token roughly hourly (self-signed Supabase
             // JWTs expire in 1h); the frozen JWT captured at init would otherwise 401
@@ -763,6 +820,11 @@ export async function createSseApp() {
             });
             return;
         }
+        // Bind the session to the initializing credential. Computed BEFORE the
+        // transport is created so onsessioninitialized (which fires synchronously
+        // inside handleRequest, before any resume can arrive) can store it.
+        // Non-null past the auth gate above (apiKey || jwt is guaranteed here).
+        const credentialHash = credentialBindingHash({ apiKey, jwt }) ?? "";
         // Create per-session transport, server, and client
         const transport = new StreamableHTTPServerTransport({
             // Embed the Fly machine id so a resume request landing on another machine
@@ -774,14 +836,27 @@ export async function createSseApp() {
             // — the session is machine-pinned via fly-replay.
             eventStore: new InMemoryEventStore(),
             onsessioninitialized: (id) => {
-                httpSessions.set(id, { server, transport, client, lastSeen: Date.now() });
+                httpSessions.set(id, { server, transport, client, credentialHash, lastSeen: Date.now() });
                 console.error(`[HTTP] Session initialized: ${id}`);
             },
         });
         const client = new BackendClient({ baseURL: BACKEND_URL, apiKey, jwt });
         const analyticsId = distinctIdFor(apiKey ?? jwt);
-        captureEvent("mcp_session_init", analyticsId, { auth: apiKey ? "api_key" : "oauth" });
-        const server = createMcpServer(analyticsId);
+        // Tool surface is fixed for the life of the session: we do not declare
+        // `tools.listChanged`, so a host has no obligation to re-fetch the list.
+        // Opt into the full surface with `?profile=full` on the connector URL, or
+        // an `X-OE-Tool-Surface: full` header where the host allows custom headers.
+        const surface = parseToolSurface(req.query.profile ?? req.headers["x-oe-tool-surface"]);
+        const server = createMcpServer(analyticsId, surface);
+        // Fire session_init after the handshake so getClientVersion() is populated
+        // — without this the connecting host is unknown and we cannot tell which
+        // clients the remote server is actually serving.
+        server.oninitialized = () => {
+            captureEvent("mcp_session_init", analyticsId, {
+                auth: apiKey ? "api_key" : "oauth",
+                ...transportProps(server, surface),
+            });
+        };
         transport.onclose = () => {
             if (transport.sessionId) {
                 httpSessions.delete(transport.sessionId);
@@ -801,6 +876,27 @@ export async function createSseApp() {
             });
             return;
         }
+        // The SSE leg is an authenticated attach, not an open pipe keyed only by a
+        // session id: a leaked id previously let anyone attach to another user's
+        // event stream. Require a credential (same gate as POST resume) and, once
+        // the session is found, the same credential-binding match.
+        const attachAuth = extractAuth(req);
+        if (!attachAuth.apiKey && !attachAuth.jwt) {
+            res.set("WWW-Authenticate", `Bearer realm="OpenEphemeris MCP", resource_metadata="${PROTECTED_RESOURCE_METADATA_URL}"`);
+            res.status(401).json({
+                error: "auth_required",
+                message: "Authentication required. Pass an API key via X-API-Key header, or a Bearer token via Authorization header.",
+            });
+            return;
+        }
+        if (attachAuth.jwt && isJwtExpired(attachAuth.jwt)) {
+            res.set("WWW-Authenticate", `Bearer realm="OpenEphemeris MCP", error="invalid_token", error_description="The access token expired", resource_metadata="${PROTECTED_RESOURCE_METADATA_URL}"`);
+            res.status(401).json({
+                error: "invalid_token",
+                message: "Your session token has expired. Re-authorize to continue.",
+            });
+            return;
+        }
         const session = httpSessions.get(sessionId);
         if (!session) {
             // Cross-machine replay for the SSE leg (same scheme as POST /mcp resume).
@@ -818,6 +914,10 @@ export async function createSseApp() {
             });
             return;
         }
+        if (!bindingHashMatches(session.credentialHash, credentialBindingHash(attachAuth))) {
+            rejectCredentialMismatch(res);
+            return;
+        }
         session.lastSeen = Date.now();
         // The SSE leg stays open indefinitely — keep it alive through proxies.
         startSseKeepalive(res);

package/dist/tools/apps/bazi-app.js

@@ -22,6 +22,10 @@ import { fileURLToPath } from "node:url";
 import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+// One BaZi component parser, shared with the specialized tools. The local copy
+// this replaces used `new Date(naive)`, which resolves in the host process's
+// timezone and silently shifted the hour pillar on any non-UTC server.
+import { parseBaziArgs } from "../specialized/bazi.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const BAZI_RESOURCE_URI = "ui://openephemeris/bazi";
 export const BAZI_MIME_TYPE = "text/html;profile=mcp-app";
@@ -56,30 +60,6 @@ export function getBaziBundle() {
 export function clearBaziBundleCache() {
     cachedBundle = null;
 }
-function parseBaziArgs(args) {
-    let year = args.year;
-    let month = args.month;
-    let day = args.day;
-    let hour = args.hour;
-    if (args.datetime && (!year || !month || !day)) {
-        const dt = new Date(String(args.datetime));
-        if (!isNaN(dt.getTime())) {
-            year = dt.getUTCFullYear();
-            month = dt.getUTCMonth() + 1;
-            day = dt.getUTCDate();
-            if (hour == null)
-                hour = dt.getUTCHours();
-        }
-    }
-    if (!year || !month || !day) {
-        throw new Error("Provide year/month/day fields, or a datetime ISO string. " +
-            "Example: year=1987, month=7, day=15 OR datetime='1987-07-15T14:00:00'");
-    }
-    const out = { year, month, day };
-    if (hour != null)
-        out.hour = hour;
-    return out;
-}
 /**
  * Fetch the BaZi chart via the include_visual intercept — one call returns
  * both the structured pillar data (year/month/day/hour/day_master) and the
@@ -135,8 +115,9 @@ registerTool({
         "(Year = ancestry/early life, Month = parents/career, Day = self/spouse, Hour = children/later life).\n\n" +
         "CREDIT COST: 3 credits per call (1 base + 2 visual render).\n\n" +
         "Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude Desktop). " +
-        "Falls back to a text summary in other hosts. For non-visual data lookups, use the dedicated " +
-        "chinese_bazi / bazi_ten_gods / bazi_element_balance / bazi_luck_pillars tools instead.",
+        "Falls back to a text summary in other hosts. For non-visual data lookups, use chinese_bazi " +
+        "instead; deeper derivations (Ten Gods, element balance, luck pillars) have dedicated tools " +
+        "on the full tool surface (`?profile=full`).",
     inputSchema: {
         type: "object",
         properties: {
@@ -150,8 +131,14 @@ registerTool({
             },
             datetime: {
                 type: "string",
-                description: "Alternative to year/month/day: ISO 8601 datetime (e.g. '1987-07-15T14:00:00'). " +
-                    "year/month/day/hour are extracted automatically. Use this OR the individual fields.",
+                description: "Alternative to year/month/day: ISO 8601 datetime read as LOCAL wall-clock time at the " +
+                    "birth place — BaZi pillars are local by definition, so a zone-less value is correct " +
+                    "here and is NOT converted to UTC. If it carries a 'Z' or offset, also pass timezone.",
+            },
+            timezone: {
+                type: "string",
+                description: "IANA timezone name for the birth place, e.g. 'Asia/Shanghai'. Only needed when " +
+                    "datetime carries a 'Z' or ±HH:MM offset.",
             },
         },
         additionalProperties: false,