@openephemeris/mcp-server 3.23.1 → 4.0.0

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/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
@@ -150,8 +130,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,

package/dist/tools/apps/bi-wheel-app.js

@@ -427,7 +427,7 @@ registerTool({
                 type: "string",
                 description: "ISO 8601 datetime for Person 1 / Natal chart (e.g. '1990-04-15T14:30:00-05:00').",
             },
-            person1_latitude: { type: "number", description: "Birth latitude for Person 1 (decimal degrees, positive = North)." },
+            person1_latitude: { type: "number", description: "Birth latitude for Person 1 (decimal degrees, positive = North). Resolve from a place name with location_search; never recall coordinates from memory." },
             person1_longitude: { type: "number", description: "Birth longitude for Person 1 (decimal degrees, positive = East)." },
             person1_timezone: { type: "string", description: "IANA timezone for Person 1 (e.g. 'America/New_York')." },
             person1_name: {
@@ -449,7 +449,7 @@ registerTool({
             },
             location: {
                 type: "string",
-                description: "Label for Person 1 / Natal location (display only, e.g. 'New York, NY').",
+                description: "Label for Person 1 / Natal location (display only, e.g. 'New York, NY'). This is a caption, NOT a geocoder — it does not set the chart location. Supply latitude/longitude too (resolve them with location_search), or the chart is computed at 0N 0E.",
             },
             mode: {
                 type: "string",

package/dist/tools/apps/bodygraph-app.d.ts

@@ -1,10 +1,10 @@
 /**
- * bodygraph-app.ts — MCP App tool registration for the Human Design Bodygraph Explorer.
+ * bodygraph-app.ts — MCP App tool registration for the Human Design Bodygraph Explorer.
  *
  * Entry tools [model + app]:
- *   • explore_human_design             — natal bodygraph, data + UI resource
- *   • explore_human_design_transit     — natal + transit overlay (premium)
- *   • explore_human_design_connection  — two-person connection/synastry overlay (premium)
+ *   • explore_human_design             — natal bodygraph, data + UI resource
+ *   • explore_human_design_transit     — natal + transit overlay (premium)
+ *   • explore_human_design_connection  — two-person connection/synastry overlay (premium)
  * Click handlers [app-only]: hd_on_center_click, hd_on_gate_click,
  *   hd_on_channel_click, hd_on_planet_click, hd_on_variable_click,
  *   hd_on_connection_channel_click, hd_on_transit_channel_click (overlay, Phase 5).
@@ -12,7 +12,7 @@
  * overlay SVG is returned inline by /human-design/transit-chart and
  * /human-design/composite (include_visual) rather than a separate render call.
  *
- * The bodygraph is rendered client-side from structured JSON — no SVG endpoint
+ * The bodygraph is rendered client-side from structured JSON — no SVG endpoint
  * is called, keeping latency at zero and the architecture consistent with
  * the chart-wheel-app approach.
  *