@openephemeris/mcp-server 3.16.0 → 3.19.0

package/dist/server-sse.js

@@ -22,7 +22,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
-import { initTools, toolRegistry, formatToolResponse, modelVisibleTools } from "./tools/index.js";
+import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools } 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";
@@ -34,6 +34,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";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -73,9 +74,14 @@ const version = resolveServerVersion();
  */
 async function validateApiKey(apiKey) {
     try {
-        const resp = await axios.get(`${BACKEND_URL}/ephemeris/moon/phase`, {
+        // Use a genuinely free, auth-gated endpoint. /catalogs/bodies is metered at
+        // 0 credits (usage_meter.go EstimateUsageUnits) yet still requires auth (NOT
+        // in middleware.go IsPublicPath), so an invalid key returns 401/403 while a
+        // valid key is validated without charging a credit on every session init.
+        // (The previous /ephemeris/moon/phase probe fell through to the default
+        // 1-credit charge — connecting cost the user a credit.)
+        const resp = await axios.get(`${BACKEND_URL}/catalogs/bodies`, {
             headers: { "X-API-Key": apiKey },
-            params: { datetime: new Date().toISOString() }, // required param per OpenAPI spec
             timeout: 5_000,
             validateStatus: () => true, // don't throw on any status
         });
@@ -279,25 +285,22 @@ function createMcpServer() {
         try {
             const startTime = Date.now();
             console.error(`[MCP] Executing tool: ${toolName}`);
-            const result = await tool.handler(request.params.arguments ?? {});
+            // Bound execution so a hung backend request can't pin the session forever.
+            // 120s comfortably covers the slowest known endpoint (cold heatmap
+            // 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;
             return formatToolResponse(toolName, result, durationMs);
         }
         catch (error) {
-            const startTime = Date.now(); // Not strictly accurate for errors but acceptable for logging structure if needed
-            const durationMs = Date.now() - startTime;
             const errorMessage = error instanceof Error ? error.message : String(error);
-            const isRetryable = error.retryable === true || error.status === 401 || error.code === "auth_required";
-            console.error(`[MCP] ❌ Failed: ${toolName} (${durationMs}ms) - ${errorMessage}`);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Tool execution failed:\n\n${errorMessage}\n\nPlease read the error above carefully and assist the user (e.g. by providing them the auth link or explaining the issue).`,
-                    },
-                ],
-                isError: !isRetryable,
-            };
+            console.error(`[MCP] ❌ Failed: ${toolName} - ${errorMessage}`);
+            // 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
+            // (including the "disconnect and reconnect" message) renders as a real
+            // error and prompts the host's OAuth refresh.
+            return formatToolError(error);
         }
     });
     // --- Resource handlers ---
@@ -370,6 +373,51 @@ function createMcpServer() {
     return server;
 }
 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
+// otherwise leak sessions until process restart, so reap anything idle past
+// the TTL. A reaped session 404s on its next request and the client
+// re-initializes per the MCP spec.
+const SESSION_IDLE_TTL_MS = 2 * 60 * 60 * 1000; // 2h
+const TOOL_CALL_TIMEOUT_MS = 120_000;
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Tool '${label}' timed out after ${ms / 1000}s`)), ms);
+        promise.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+function reapIdleSessions() {
+    const cutoff = Date.now() - SESSION_IDLE_TTL_MS;
+    for (const [id, session] of httpSessions) {
+        if (session.lastSeen < cutoff) {
+            httpSessions.delete(id);
+            session.server.close().catch(() => { });
+            console.error(`[HTTP] Session reaped (idle > ${SESSION_IDLE_TTL_MS / 60000}m): ${id}`);
+        }
+    }
+}
+/**
+ * Keep a long-lived SSE response alive through Fly's proxy and any
+ * intermediaries: disable the socket idle timeout and emit an SSE comment
+ * frame every 25s (comment frames are ignored by EventSource parsers).
+ * Call only after the transport has sent the SSE headers.
+ */
+function startSseKeepalive(res) {
+    res.socket?.setTimeout(0);
+    const ping = setInterval(() => {
+        if (res.writableEnded || res.destroyed) {
+            clearInterval(ping);
+            return;
+        }
+        try {
+            res.write(":ping\n\n");
+        }
+        catch {
+            clearInterval(ping);
+        }
+    }, 25_000);
+    res.on("close", () => clearInterval(ping));
+}
 async function main() {
     await initTools();
     const app = express();
@@ -391,6 +439,36 @@ async function main() {
     function isOriginAllowed(origin) {
         return ORIGIN_ALLOWLIST.some((m) => typeof m === "string" ? m === origin : m.test(origin));
     }
+    // DNS-rebinding defense: Origin validation alone doesn't cover the Host
+    // header, which is the vector rebinding attacks use. Restrict the MCP
+    // endpoints to the hosts we actually serve. Override/extend with
+    // MCP_ALLOWED_HOSTS (comma-separated) if the deployment hostname changes.
+    const HOST_ALLOWLIST = [
+        /^mcp\.openephemeris\.com$/i,
+        /^oe-mcp-live\.fly\.dev$/i,
+        /^localhost(:\d+)?$/i,
+        /^127\.0\.0\.1(:\d+)?$/i,
+        /^\[::1\](:\d+)?$/i,
+        ...(process.env.MCP_ALLOWED_HOSTS ?? "")
+            .split(",")
+            .map((h) => h.trim())
+            .filter(Boolean)
+            .map((h) => new RegExp(`^${h.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(:\\d+)?$`, "i")),
+    ];
+    const MCP_ROUTES = new Set(["/mcp", "/sse", "/message"]);
+    app.use((req, res, next) => {
+        if (MCP_ROUTES.has(req.path)) {
+            const host = req.headers.host;
+            if (host && !HOST_ALLOWLIST.some((m) => m.test(host))) {
+                res.status(403).json({
+                    error: "host_not_allowed",
+                    error_description: `Host '${host}' is not permitted.`,
+                });
+                return;
+            }
+        }
+        next();
+    });
     app.use((req, res, next) => {
         const origin = req.headers.origin;
         // Browser request → must match allowlist. Native client (no Origin) → allow.
@@ -515,12 +593,53 @@ async function main() {
         if (sessionId) {
             const session = httpSessions.get(sessionId);
             if (!session) {
+                // Cross-machine session recovery (Fly): min_machines_running >= 2 but
+                // httpSessions is per-process. If the session id encodes a DIFFERENT
+                // machine, ask Fly's proxy to replay this request to the owning machine
+                // — unless it was already replayed once (loop guard), in which case we
+                // fall through to 404 so the client re-initializes per the MCP spec.
+                const target = replayTargetMachine(sessionId, {
+                    alreadyReplayed: typeof req.headers["fly-replay-src"] === "string",
+                });
+                if (target) {
+                    res.set("fly-replay", `instance=${target}`);
+                    res.status(307).end();
+                    return;
+                }
                 res.status(404).json({
                     error: "session_not_found",
                     message: "Unknown or expired MCP session. Re-initialize to start a new one.",
                 });
                 return;
             }
+            // A session id alone is not a credential: require the caller to still
+            // present a key/JWT on every resume, and reject an expired JWT with the
+            // OAuth-refresh signal (same semantics as the init gate below).
+            const resumedAuth = extractAuth(req);
+            if (!resumedAuth.apiKey && !resumedAuth.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 on every request. Pass an API key via X-API-Key header, or a Bearer token via Authorization header.",
+                });
+                return;
+            }
+            if (resumedAuth.jwt && isJwtExpired(resumedAuth.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;
+            }
+            // 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
+            // forever. Re-read the header and push the fresh token into the client.
+            if (resumedAuth.jwt) {
+                session.client.setJwt(resumedAuth.jwt);
+            }
+            session.lastSeen = Date.now();
             await runWithClient(session.client, () => session.transport.handleRequest(req, res, req.body));
             return;
         }
@@ -538,6 +657,19 @@ async function main() {
             });
             return;
         }
+        // Reject already-expired JWTs at the gate with an OAuth-refresh signal.
+        // Signature is validated downstream by the Go API — here we only decode the
+        // `exp` claim (no verification) so an expired token triggers the host's
+        // token refresh (401 invalid_token) instead of dying as a confusing tool
+        // error mid-session.
+        if (jwt && isJwtExpired(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;
+        }
         // Validate API keys against the Go backend; JWTs are validated downstream
         // by the Go sidecar's ValidateSupabaseJWT when tool calls are proxied.
         if (apiKey) {
@@ -570,9 +702,12 @@ async function main() {
         }
         // Create per-session transport, server, and client
         const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: randomUUID,
+            // Embed the Fly machine id so a resume request landing on another machine
+            // can be replayed to the owner (see the resume branch above). No-op off
+            // Fly (FLY_MACHINE_ID unset) — the raw UUID is used unchanged.
+            sessionIdGenerator: () => encodeSessionId(randomUUID()),
             onsessioninitialized: (id) => {
-                httpSessions.set(id, { server, transport, client });
+                httpSessions.set(id, { server, transport, client, lastSeen: Date.now() });
                 console.error(`[HTTP] Session initialized: ${id}`);
             },
         });
@@ -599,12 +734,24 @@ async function main() {
         }
         const session = httpSessions.get(sessionId);
         if (!session) {
+            // Cross-machine replay for the SSE leg (same scheme as POST /mcp resume).
+            const target = replayTargetMachine(sessionId, {
+                alreadyReplayed: typeof req.headers["fly-replay-src"] === "string",
+            });
+            if (target) {
+                res.set("fly-replay", `instance=${target}`);
+                res.status(307).end();
+                return;
+            }
             res.status(404).json({
                 error: "session_not_found",
                 message: "Unknown or expired MCP session.",
             });
             return;
         }
+        session.lastSeen = Date.now();
+        // The SSE leg stays open indefinitely — keep it alive through proxies.
+        startSseKeepalive(res);
         await session.transport.handleRequest(req, res);
     });
     // DELETE /mcp — client-initiated session teardown
@@ -715,6 +862,8 @@ async function main() {
         try {
             // server.connect() calls transport.start() internally in SDK v1.27+
             await server.connect(transport);
+            // Stream is established — keep it alive through Fly's proxy.
+            startSseKeepalive(res);
         }
         catch (err) {
             console.error(`SSE session ${sessionId} failed to start:`, err);
@@ -742,9 +891,17 @@ async function main() {
             await transport.handlePostMessage(req, res);
         }
     });
-    app.listen(PORT, "0.0.0.0", () => {
+    // Reap abandoned sessions (no DELETE, no transport close) every 10 minutes.
+    setInterval(reapIdleSessions, 10 * 60 * 1000).unref();
+    const httpServer = app.listen(PORT, "0.0.0.0", () => {
         console.log(`OpenEphemeris MCP SSE server v${version} listening on port ${PORT}`);
     });
+    // SSE streams are long-lived by design; Node 18+ closes idle connections
+    // after 5s keep-alive by default at the server level — the per-response
+    // socket timeout is disabled in startSseKeepalive, but also raise the
+    // server-wide headers/request timeouts so slow proxies don't get cut.
+    httpServer.keepAliveTimeout = 65_000;
+    httpServer.headersTimeout = 70_000;
 }
 // Prevent SDK recursive close bugs from crashing the process
 process.on("uncaughtException", (err) => {
@@ -755,6 +912,13 @@ process.on("uncaughtException", (err) => {
     console.error("Uncaught exception:", err);
     process.exit(1);
 });
+// Log-and-continue on unhandled promise rejections. A rejected promise from a
+// single request (e.g. a client that disconnected mid-stream) must never take
+// down the whole server and kill every other live session. Log for triage and
+// keep serving.
+process.on("unhandledRejection", (reason) => {
+    console.error("Unhandled promise rejection:", reason);
+});
 main().catch((error) => {
     console.error("Fatal error:", error);
     process.exit(1);

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

@@ -6,7 +6,8 @@
  *   • 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_channel_click, hd_on_planet_click, hd_on_variable_click,
+ *   hd_on_connection_channel_click, hd_on_transit_channel_click (overlay, Phase 5).
  * The transit + connection tools reuse this bodygraph iframe resource; their
  * overlay SVG is returned inline by /human-design/transit-chart and
  * /human-design/composite (include_visual) rather than a separate render call.

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

@@ -6,7 +6,8 @@
  *   • 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_channel_click, hd_on_planet_click, hd_on_variable_click,
+ *   hd_on_connection_channel_click, hd_on_transit_channel_click (overlay, Phase 5).
  * The transit + connection tools reuse this bodygraph iframe resource; their
  * overlay SVG is returned inline by /human-design/transit-chart and
  * /human-design/composite (include_visual) rather than a separate render call.
@@ -704,6 +705,148 @@ registerTool({
         };
     },
 });
+const CONNECTION_TYPE_DATA = {
+    electromagnetic: {
+        label: "Electromagnetic",
+        tagline: "attraction — opposites complete the channel",
+        body: "Each of you holds one different gate of this channel; together you complete a current neither runs alone. This is the classic draw — and, on the same wiring, the friction. What the channel does comes alive only in the meeting; apart, each of you is back to half. The gift is chemistry and mutual completion. The edge is that the completeness depends on the other, and the same difference that pulls you together can push you apart. Each of you stays with your own strategy and inner authority — the connection is information about the interplay, not an instruction.",
+    },
+    companionship: {
+        label: "Companionship",
+        tagline: "sameness — you both already run the whole channel",
+        body: "You each already define this whole channel on your own, so meeting here is recognition rather than completion. Nothing has to be negotiated; you simply operate the same way. Friendship and ease live here. The edge is that there is no charge to cross — sameness can go flat, or become the place you take each other for granted. Ease is not the same as aliveness.",
+    },
+    dominance: {
+        label: "Dominance",
+        tagline: "one defines the whole channel, the other is fully open here",
+        body: "One of you defines this entire channel; the other holds neither gate and is completely open here. The defined partner conditions the open one steadily and consistently, and the open partner takes the current in fully, unfiltered by any definition of their own — seeing the defined one clearly, for exactly who they are. It is meant to be accepted and surrendered to, not fixed or matched. The gift is consistency and clear sight. The edge is the not-self reading of \"I always have to do it your way\": the open partner can lose themselves to the steady conditioning if they drift from their own authority. Surrender here is a choice made from authority, not a disappearance.",
+    },
+    compromise: {
+        label: "Compromise",
+        tagline: "one defines the whole channel, the other holds a single gate",
+        body: "One of you defines this whole channel; the other holds exactly one of its two gates. Push and pull land on that shared gate — the half-definition keeps getting overridden by the full one, so the single-gate partner is consistently compromised here. This is the spot where \"you do it your way, I do it mine\" surfaces most. Met consciously, the recurring friction on that one gate names exactly where the work is and can sharpen both of you. Unwatched, it calcifies into a standing grievance instead of a workable edge.",
+    },
+};
+const TRANSIT_CLASS_DATA = {
+    transit_completed: {
+        label: "Transit completes this channel",
+        body: "For a window, a passing transit completes this channel: one of its gates is defined in your own design, the other is switched on by the sky. While that holds, the current runs in you the way it does for someone built this way full-time — except you are not, and that is the whole point. It is a gift on loan: a real taste of standing definition here, without your having become someone else for it. The pull is to grab it and decide this is now who you are; when the transit separates and the channel opens back up, that reading only leaves you grieving. Nothing about your type, strategy, or authority has changed. Use the borrowed current while it lasts, keep deciding from your own authority, and let it go cleanly when the sky moves on.",
+    },
+    transit_only: {
+        label: "Transit defines this channel on its own",
+        body: "For a window, a passing transit lights both gates of this channel — neither is yours natally. The channel runs entirely on borrowed weather; it is not part of your design at all, and it switches off completely when the transit moves on. Notice the temporary current for what it is, and keep deciding from your own authority rather than mistaking it for a new capacity.",
+    },
+    reinforced: {
+        label: "Transit reinforces your definition here",
+        body: "You already define this channel, and a passing transit also lands on one of its gates today — your standing definition, amplified for a window. Nothing new is added; the current you already run simply gets louder. When the transit moves on, it settles back to its usual level.",
+    },
+    natal: {
+        label: "Your standing definition",
+        body: "Both gates of this channel are defined in your own design. This is part of your fixed wiring, not transit weather — the passing sky does not change it. It reads here for context alongside the temporary activations.",
+    },
+};
+// ── Tool: hd_on_connection_channel_click [app-only] ────────────────────────
+// Fired when the user clicks a connection (synastry) channel in the overlay
+// bodygraph. Serves the connection-type dynamic for that specific channel.
+registerTool({
+    name: "hd_on_connection_channel_click",
+    description: "Event handler called when the user clicks a connected channel in a Human Design connection (synastry) overlay bodygraph. " +
+        "Returns the channel identity and the relationship dynamic for its connection type " +
+        "(electromagnetic / companionship / dominance / compromise). " +
+        "This tool is called automatically by the bodygraph UI; you do not need to call it directly.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            channel: { type: "string", description: "Channel identifier string (e.g. '1-8', '20-34')." },
+            connection_type: {
+                type: "string",
+                description: "Connection type: electromagnetic | companionship | dominance | compromise.",
+            },
+            gate1: { type: "number", description: "First gate number." },
+            gate2: { type: "number", description: "Second gate number." },
+        },
+        required: ["channel"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Connection Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
+    handler: async (args) => {
+        const channelStr = String(args.channel ?? "");
+        const g1 = args.gate1 != null ? Number(args.gate1) : null;
+        const g2 = args.gate2 != null ? Number(args.gate2) : null;
+        const typeKey = String(args.connection_type ?? "").toLowerCase();
+        const key = channelStr.includes("-") ? channelStr : g1 != null && g2 != null ? `${g1}-${g2}` : channelStr;
+        const chan = HD_CHANNEL_DATA[key] ?? HD_CHANNEL_DATA[key.split("-").reverse().join("-")];
+        const conn = CONNECTION_TYPE_DATA[typeKey];
+        const chanName = chan?.name ?? "this channel";
+        const gatesLine = `**Gates:** ${g1 ?? channelStr.split("-")[0] ?? "?"} ↔ ${g2 ?? channelStr.split("-")[1] ?? "?"}`;
+        if (!conn) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `**Channel ${channelStr} — ${chanName}**\n\n${gatesLine}\n\n` +
+                            `This channel is defined across both people. ${chan?.description ?? ""}`.trim(),
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: `**${conn.label} Connection — Channel of ${chanName} (${channelStr})**\n\n` +
+                        `${gatesLine}\n\n` +
+                        `*${conn.tagline}*\n\n` +
+                        `${conn.body}` +
+                        (chan?.description ? `\n\n**This channel:** ${chan.description}` : ""),
+                }],
+        };
+    },
+});
+// ── Tool: hd_on_transit_channel_click [app-only] ──────────────────────────
+// Fired when the user clicks a channel in a transit overlay bodygraph. Serves
+// the meaning of the channel's transit class (esp. transit_completed).
+registerTool({
+    name: "hd_on_transit_channel_click",
+    description: "Event handler called when the user clicks a channel in a Human Design transit overlay bodygraph. " +
+        "Returns the channel identity and what its transit class means — especially transit_completed, where a transit " +
+        "temporarily completes a channel (one natal gate + one transit gate). " +
+        "This tool is called automatically by the bodygraph UI; you do not need to call it directly.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            channel: { type: "string", description: "Channel identifier string (e.g. '64-47')." },
+            transit_class: {
+                type: "string",
+                description: "Transit class: natal | reinforced | transit_completed | transit_only.",
+            },
+            gate1: { type: "number", description: "First gate number." },
+            gate2: { type: "number", description: "Second gate number." },
+        },
+        required: ["channel"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Transit Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
+    handler: async (args) => {
+        const channelStr = String(args.channel ?? "");
+        const g1 = args.gate1 != null ? Number(args.gate1) : null;
+        const g2 = args.gate2 != null ? Number(args.gate2) : null;
+        const cls = String(args.transit_class ?? "transit_completed").toLowerCase();
+        const key = channelStr.includes("-") ? channelStr : g1 != null && g2 != null ? `${g1}-${g2}` : channelStr;
+        const chan = HD_CHANNEL_DATA[key] ?? HD_CHANNEL_DATA[key.split("-").reverse().join("-")];
+        const info = TRANSIT_CLASS_DATA[cls] ?? TRANSIT_CLASS_DATA.transit_completed;
+        const chanName = chan?.name ?? "this channel";
+        const gatesLine = `**Gates:** ${g1 ?? channelStr.split("-")[0] ?? "?"} ↔ ${g2 ?? channelStr.split("-")[1] ?? "?"}`;
+        return {
+            content: [{
+                    type: "text",
+                    text: `**Channel of ${chanName} (${channelStr}) — ${info.label}**\n\n` +
+                        `${gatesLine}\n\n` +
+                        `${info.body}` +
+                        (chan?.description ? `\n\n**This channel:** ${chan.description}` : ""),
+                }],
+        };
+    },
+});
 const HD_CENTER_DATA = {
     Head: {
         keynote: "Inspiration, mental pressure, questioning",

package/dist/tools/dev.js

@@ -73,7 +73,7 @@ const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.open
     "  POST /acg/power-lines                 — Astrocartography power lines (lat/lon GeoJSON)\n" +
     "  POST /acg/hits                         — ACG power at a specific location\n" +
     "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
-    "  GET  /location/autocomplete            — Geocode a place name (query: q=City Name)\n" +
+    "  GET  /location/autocomplete            — Geocode a place name (query: query=City Name)\n" +
     "  POST /timezone/lookup                  — Resolve timezone + UTC offset for a location\n" +
     "  POST /chinese/bazi                     — Chinese Ba Zi (Four Pillars) chart (body: {year, month, day, hour})\n" +
     "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +

package/dist/tools/index.d.ts

@@ -73,3 +73,28 @@ export declare function validateCoordinates(args: any, latKey: string, lonKey: s
  * Applies a safety limit to JSON payloads to prevent crashing LLM contexts.
  */
 export declare function formatToolResponse(toolName: string, result: any, durationMs: number): any;
+/**
+ * Decide whether a thrown tool error is the stdio device-auth-pending case,
+ * which must NOT be flagged isError so the model relays the verification link.
+ *
+ * Everything else — 429, 5xx, network, plain auth failures — is a real error
+ * and MUST report isError: true so the host recovers (retry / OAuth refresh)
+ * instead of treating a failure as a silent success.
+ *
+ * Device-auth-pending is uniquely identified by a BackendError with
+ * code === "auth_required" AND retryable === true (set only when the background
+ * device-auth flow is live and its message carries a verification link). The
+ * plain "disconnect and reconnect" 401 is retryable === false → a real error.
+ */
+export declare function isDeviceAuthPendingError(error: unknown): boolean;
+/**
+ * Build the MCP error content block for a failed tool call. Shared by the stdio
+ * and SSE/HTTP CallTool handlers so the isError policy stays consistent.
+ */
+export declare function formatToolError(error: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};

package/dist/tools/index.js

@@ -216,3 +216,36 @@ export function formatToolResponse(toolName, result, durationMs) {
         ],
     };
 }
+/**
+ * Decide whether a thrown tool error is the stdio device-auth-pending case,
+ * which must NOT be flagged isError so the model relays the verification link.
+ *
+ * Everything else — 429, 5xx, network, plain auth failures — is a real error
+ * and MUST report isError: true so the host recovers (retry / OAuth refresh)
+ * instead of treating a failure as a silent success.
+ *
+ * Device-auth-pending is uniquely identified by a BackendError with
+ * code === "auth_required" AND retryable === true (set only when the background
+ * device-auth flow is live and its message carries a verification link). The
+ * plain "disconnect and reconnect" 401 is retryable === false → a real error.
+ */
+export function isDeviceAuthPendingError(error) {
+    const e = error;
+    return !!e && e.code === "auth_required" && e.retryable === true;
+}
+/**
+ * Build the MCP error content block for a failed tool call. Shared by the stdio
+ * and SSE/HTTP CallTool handlers so the isError policy stays consistent.
+ */
+export function formatToolError(error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Tool execution failed:\n\n${errorMessage}\n\nPlease read the error above carefully and assist the user (e.g. by providing them the auth link or explaining the issue).`,
+            },
+        ],
+        isError: !isDeviceAuthPendingError(error),
+    };
+}

package/dist/tools/output-schemas.d.ts

@@ -2,7 +2,7 @@
  * output-schemas.ts — Shared JSON Schema output schema definitions for MCP tools.
  *
  * MCP spec 2025-11-25 supports `outputSchema` on tool definitions. Smithery
- * uses this field to score the "Output schemas" quality criterion (10.37pt / 57 tools).
+ * uses this field to score the "Output schemas" quality criterion (scored per registered tool; count guarded by test/allowlist-and-tools.test.ts).
  *
  * All tools return an MCP content block response. Most return a single JSON text
  * block; visual tools return an image block or an image + text block.

package/dist/tools/output-schemas.js

@@ -2,7 +2,7 @@
  * output-schemas.ts — Shared JSON Schema output schema definitions for MCP tools.
  *
  * MCP spec 2025-11-25 supports `outputSchema` on tool definitions. Smithery
- * uses this field to score the "Output schemas" quality criterion (10.37pt / 57 tools).
+ * uses this field to score the "Output schemas" quality criterion (scored per registered tool; count guarded by test/allowlist-and-tools.test.ts).
  *
  * All tools return an MCP content block response. Most return a single JSON text
  * block; visual tools return an image block or an image + text block.

package/dist/tools/specialized/acg.js

@@ -24,7 +24,9 @@ registerTool({
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 natal birth date/time.",
+                description: "ISO 8601 natal birth date/time. MUST include a UTC offset (or 'Z'), " +
+                    "e.g. '1990-05-15T14:30:00-05:00'. A naive datetime (no offset) is " +
+                    "interpreted as UTC and will place the ACG lines in the wrong location.",
             },
             birth_latitude: {
                 type: "number",
@@ -114,7 +116,9 @@ registerTool({
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 natal birth date/time.",
+                description: "ISO 8601 natal birth date/time. MUST include a UTC offset (or 'Z'), " +
+                    "e.g. '1990-05-15T14:30:00-05:00'. A naive datetime (no offset) is " +
+                    "interpreted as UTC and will place the ACG lines in the wrong location.",
             },
             birth_latitude: {
                 type: "number",

package/dist/tools/specialized/progressed.js

@@ -15,7 +15,9 @@ registerTool({
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 natal birth date/time.",
+                description: "ISO 8601 natal birth date/time. MUST include a UTC offset (or 'Z'), " +
+                    "e.g. '1990-05-15T14:30:00-05:00'. A naive datetime (no offset) is " +
+                    "interpreted as UTC and will shift the progressed positions.",
             },
             birth_latitude: {
                 type: "number",