@openephemeris/mcp-server 3.13.9 → 3.14.0

package/dist/server-sse.js

@@ -27,6 +27,13 @@ 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";
 import { BI_WHEEL_RESOURCE_URI, BI_WHEEL_MIME_TYPE, getBiWheelBundle, } from "./tools/apps/bi-wheel-app.js";
+// NOTE: transit-timeline, bazi, vedic-chart imports removed — tools disabled.
+import { MOON_PHASE_RESOURCE_URI, MOON_PHASE_MIME_TYPE, getMoonPhaseBundle, } from "./tools/apps/moon-phase-app.js";
+import { oauthDiscoveryRouter, PROTECTED_RESOURCE_METADATA_URL } from "./oauth/discovery.js";
+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";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -82,18 +89,31 @@ async function validateApiKey(apiKey) {
     }
 }
 /**
- * Extract an API key from a request using priority order:
- *   1. X-API-Key header
- *   2. X-OpenEphemeris-API-Key header
- *   3. Authorization: Bearer <token>
- *   4. ?apiKey query param
+ * Extract authentication from a request, distinguishing JWTs from API keys.
+ *
+ * Detection heuristic:
+ *   - Bearer tokens starting with "eyJ" → Supabase JWT (from OAuth flow)
+ *   - Bearer tokens starting with "opene-" → API key
+ *   - X-API-Key / X-OpenEphemeris-API-Key headers → API key
+ *   - ?apiKey query param → API key
+ *
+ * Returns { apiKey?, jwt? } — at most one will be set.
  */
-function extractApiKey(req) {
-    return (req.headers["x-api-key"] ||
+function extractAuth(req) {
+    // Explicit API key headers take precedence
+    const explicitKey = req.headers["x-api-key"] ||
         req.headers["x-openephemeris-api-key"] ||
-        req.headers["authorization"]?.replace(/^Bearer\s+/i, "") ||
-        req.query.apiKey ||
-        undefined);
+        req.query.apiKey;
+    if (explicitKey)
+        return { apiKey: explicitKey };
+    // Bearer token — distinguish JWT from API key by prefix
+    const bearer = req.headers["authorization"]?.replace(/^Bearer\s+/i, "");
+    if (bearer) {
+        if (bearer.startsWith("eyJ"))
+            return { jwt: bearer }; // Supabase JWT
+        return { apiKey: bearer }; // API key
+    }
+    return {};
 }
 // ---------------------------------------------------------------------------
 // Helpers
@@ -210,7 +230,15 @@ function createMcpServer() {
             annotations: buildAnnotations(tool),
             // Expose MCP Apps UI linkage so Claude Desktop can prefetch the resource
             ...(tool._meta?.ui?.resourceUri
-                ? { _meta: { ui: { resourceUri: tool._meta.ui.resourceUri, visibility: tool._meta.ui.visibility ?? ["model", "app"] } } }
+                ? {
+                    _meta: {
+                        "ui/resourceUri": tool._meta.ui.resourceUri,
+                        ui: {
+                            resourceUri: tool._meta.ui.resourceUri,
+                            visibility: tool._meta.ui.visibility ?? ["model", "app"],
+                        },
+                    },
+                }
                 : {}),
         })),
     }));
@@ -242,16 +270,18 @@ function createMcpServer() {
         }
         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);
-            console.error(`[MCP] \u274c Failed: ${toolName} - ${errorMessage}`);
+            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: JSON.stringify({ success: false, error: "TOOL_EXECUTION_ERROR", message: errorMessage }, null, 2),
+                        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: true,
+                isError: !isRetryable,
             };
         }
     });
@@ -282,6 +312,15 @@ function createMcpServer() {
                 mimeType: BI_WHEEL_MIME_TYPE,
             });
         }
+        // NOTE: transit-timeline, bazi, vedic-chart resources omitted — tools disabled.
+        if (getMoonPhaseBundle()) {
+            resources.push({
+                uri: MOON_PHASE_RESOURCE_URI,
+                name: "Moon Phase Explorer",
+                description: "Interactive lunar phase dial showing illumination, sign, and void-of-course status.",
+                mimeType: MOON_PHASE_MIME_TYPE,
+            });
+        }
         return { resources };
     });
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
@@ -304,6 +343,13 @@ function createMcpServer() {
                 throw new Error("Bi-Wheel UI bundle not found. Run `npm run build:ui` to build it.");
             return { contents: [{ uri: BI_WHEEL_RESOURCE_URI, mimeType: BI_WHEEL_MIME_TYPE, text: bundle }] };
         }
+        // NOTE: transit-timeline, bazi, vedic-chart ReadResource handlers removed.
+        if (uri === MOON_PHASE_RESOURCE_URI) {
+            const bundle = getMoonPhaseBundle();
+            if (!bundle)
+                throw new Error("Moon Phase UI bundle not found. Run `npm run build:ui` to build it.");
+            return { contents: [{ uri: MOON_PHASE_RESOURCE_URI, mimeType: MOON_PHASE_MIME_TYPE, text: bundle }] };
+        }
         throw new Error(`Unknown resource: ${uri}`);
     });
     return server;
@@ -315,12 +361,38 @@ async function main() {
     // NOTE: Do NOT use express.json() globally — SSEServerTransport.handlePostMessage
     // reads the raw request stream itself. Pre-parsing with express.json() consumes it,
     // causing "stream is not readable" errors.
-    // CORS — required for Claude Web cross-origin SSE connections
-    app.use((_req, res, next) => {
-        res.setHeader("Access-Control-Allow-Origin", "*");
+    // CORS + Origin allowlist
+    // Per Anthropic remote-MCP review criteria, browser-originated requests must
+    // be validated against an allowlist. Native (no-Origin) clients like Claude
+    // Desktop and CLI tooling are permitted; unknown browser origins are rejected.
+    const ORIGIN_ALLOWLIST = [
+        /^https:\/\/([a-z0-9-]+\.)*claude\.ai$/i,
+        /^https:\/\/([a-z0-9-]+\.)*claude\.com$/i,
+        /^https:\/\/([a-z0-9-]+\.)*anthropic\.com$/i,
+        /^https:\/\/([a-z0-9-]+\.)*openephemeris\.com$/i,
+        /^http:\/\/localhost(:\d+)?$/i,
+        /^http:\/\/127\.0\.0\.1(:\d+)?$/i,
+    ];
+    function isOriginAllowed(origin) {
+        return ORIGIN_ALLOWLIST.some((m) => typeof m === "string" ? m === origin : m.test(origin));
+    }
+    app.use((req, res, next) => {
+        const origin = req.headers.origin;
+        // Browser request → must match allowlist. Native client (no Origin) → allow.
+        if (origin) {
+            if (!isOriginAllowed(origin)) {
+                res.status(403).json({
+                    error: "origin_not_allowed",
+                    error_description: `Origin '${origin}' is not permitted.`,
+                });
+                return;
+            }
+            res.setHeader("Access-Control-Allow-Origin", origin);
+            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");
-        if (_req.method === "OPTIONS") {
+        if (req.method === "OPTIONS") {
             res.status(204).end();
             return;
         }
@@ -330,6 +402,25 @@ async function main() {
     const transports = new Map();
     // Per-session BackendClient — each connection authenticates independently.
     const sessionClients = new Map();
+    // ---------------------------------------------------------------------------
+    // OAuth 2.1 routes — must be mounted BEFORE JSON body parser
+    // ---------------------------------------------------------------------------
+    const oauthStore = new OAuthStore();
+    const tokenRateLimiter = createRateLimiter({
+        windowMs: 60_000,
+        maxRequests: 10,
+        trustProxy: true,
+    });
+    const dcrRateLimiter = createRateLimiter({
+        windowMs: 60_000,
+        maxRequests: 5,
+        trustProxy: true,
+    });
+    app.use(oauthDiscoveryRouter);
+    app.use("/oauth/register", dcrRateLimiter);
+    app.use(express.json({ limit: "1mb" }), oauthDcrRouter);
+    app.use("/oauth/token", tokenRateLimiter);
+    app.use(express.urlencoded({ extended: false }), oauthTokenRouter(oauthStore));
     // Health check
     app.get("/health", (_req, res) => {
         res.json({
@@ -350,6 +441,7 @@ async function main() {
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
             annotations: buildAnnotations(tool),
         }));
         res.json({
@@ -399,6 +491,33 @@ async function main() {
             await runWithClient(session.client, () => session.transport.handleRequest(req, res, req.body));
             return;
         }
+        // Auth check FIRST — before validating request shape. RFC 9728 requires
+        // any unauthenticated POST to /mcp (even a probe with an empty/invalid
+        // body) to return 401 + WWW-Authenticate so OAuth clients (Claude Web)
+        // can bootstrap discovery. Returning 400 before auth causes the ofid_
+        // "Authorization with MCP server failed" error in Claude's connector UI.
+        const { apiKey, jwt } = extractAuth(req);
+        if (!apiKey && !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. Get a free key at https://openephemeris.com/dashboard",
+            });
+            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) {
+            const valid = await validateApiKey(apiKey);
+            if (!valid) {
+                res.set("WWW-Authenticate", `Bearer realm="OpenEphemeris MCP", error="invalid_token", resource_metadata="${PROTECTED_RESOURCE_METADATA_URL}"`);
+                res.status(401).json({
+                    error: "invalid_api_key",
+                    message: "The provided API key is invalid or inactive. Check your key at https://openephemeris.com/dashboard?tab=apikeys",
+                });
+                return;
+            }
+        }
         // New session — must be an initialize request
         if (!isInitializeRequest(req.body)) {
             res.status(400).json({
@@ -407,23 +526,6 @@ async function main() {
             });
             return;
         }
-        // Auth — required on Initialize
-        const apiKey = extractApiKey(req);
-        if (!apiKey) {
-            res.status(401).json({
-                error: "api_key_required",
-                message: "An Open Ephemeris API key is required. Pass it via X-API-Key header or Authorization: Bearer. Get a free key at https://openephemeris.com/dashboard",
-            });
-            return;
-        }
-        const valid = await validateApiKey(apiKey);
-        if (!valid) {
-            res.status(403).json({
-                error: "invalid_api_key",
-                message: "The provided API key is invalid or inactive. Check your key at https://openephemeris.com/dashboard?tab=apikeys",
-            });
-            return;
-        }
         // Create per-session transport, server, and client
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: randomUUID,
@@ -432,7 +534,7 @@ async function main() {
                 console.error(`[HTTP] Session initialized: ${id}`);
             },
         });
-        const client = new BackendClient({ baseURL: BACKEND_URL, apiKey });
+        const client = new BackendClient({ baseURL: BACKEND_URL, apiKey, jwt });
         const server = createMcpServer();
         transport.onclose = () => {
             if (transport.sessionId) {
@@ -511,23 +613,25 @@ async function main() {
     // ---------------------------------------------------------------------------
     // SSE endpoint — clients GET /sse to establish a stream
     app.get("/sse", async (req, res) => {
-        // Extract API key from query param or header
-        const apiKey = extractApiKey(req);
-        if (!apiKey) {
+        // Extract auth from query param or header (supports API keys + OAuth JWTs)
+        const { apiKey, jwt } = extractAuth(req);
+        if (!apiKey && !jwt) {
             res.status(401).json({
-                error: "api_key_required",
-                message: "An OpenEphemeris API key is required. Generate one at https://openephemeris.com/dashboard?tab=apikeys",
+                error: "auth_required",
+                message: "Authentication required. Pass an API key via X-API-Key header or query param, or a Bearer JWT via Authorization header. Get a free key at https://openephemeris.com/dashboard?tab=apikeys",
             });
             return;
         }
-        // Validate the user's key against the Go backend
-        const valid = await validateApiKey(apiKey);
-        if (!valid) {
-            res.status(403).json({
-                error: "invalid_api_key",
-                message: "The provided API key is invalid or inactive. Check your key at https://openephemeris.com/dashboard?tab=apikeys",
-            });
-            return;
+        // Validate API keys against the Go backend; JWTs validated downstream.
+        if (apiKey) {
+            const valid = await validateApiKey(apiKey);
+            if (!valid) {
+                res.status(403).json({
+                    error: "invalid_api_key",
+                    message: "The provided API key is invalid or inactive. Check your key at https://openephemeris.com/dashboard?tab=apikeys",
+                });
+                return;
+            }
         }
         const transport = new SSEServerTransport("/message", res);
         const sessionId = transport.sessionId;
@@ -537,6 +641,7 @@ async function main() {
         const sessionClient = new BackendClient({
             baseURL: BACKEND_URL,
             apiKey,
+            jwt,
         });
         sessionClients.set(sessionId, sessionClient);
         const server = createMcpServer();

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

@@ -0,0 +1,23 @@
+/**
+ * bazi-app.ts — MCP App tool registration for the BaZi Four Pillars Explorer.
+ *
+ * Registers 1 tool:
+ *   • explore_bazi_chart — primary entry point, returns data + UI resource [model]
+ *
+ * Batches three backend API calls in parallel:
+ *   POST /chinese/bazi              → four pillars
+ *   POST /chinese/bazi/ten-gods     → ten gods + hidden stems
+ *   POST /chinese/bazi/element-balance → wu xing balance + yong shen
+ *
+ * Merges results into a single UI payload and returns it with a resource URI
+ * so the iframe can render the interactive Four Pillars visualization.
+ *
+ * Also exports resource helpers (getBaziBundle, etc.) for use in
+ * index.ts and server-sse.ts.
+ */
+export declare const BAZI_RESOURCE_URI = "ui://openephemeris/bazi";
+export declare const BAZI_MIME_TYPE = "text/html;profile=mcp-app";
+/** Read the pre-built HTML bundle. Returns null if not yet built. */
+export declare function getBaziBundle(): string | null;
+/** Reset cache (useful in dev watch mode or tests). */
+export declare function clearBaziBundleCache(): void;

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

@@ -0,0 +1,226 @@
+/**
+ * bazi-app.ts — MCP App tool registration for the BaZi Four Pillars Explorer.
+ *
+ * Registers 1 tool:
+ *   • explore_bazi_chart — primary entry point, returns data + UI resource [model]
+ *
+ * Batches three backend API calls in parallel:
+ *   POST /chinese/bazi              → four pillars
+ *   POST /chinese/bazi/ten-gods     → ten gods + hidden stems
+ *   POST /chinese/bazi/element-balance → wu xing balance + yong shen
+ *
+ * Merges results into a single UI payload and returns it with a resource URI
+ * so the iframe can render the interactive Four Pillars visualization.
+ *
+ * Also exports resource helpers (getBaziBundle, etc.) for use in
+ * index.ts and server-sse.ts.
+ */
+import fs from "node:fs";
+import path from "node:path";
+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";
+// ── Constants ─────────────────────────────────────────────────────────────────
+export const BAZI_RESOURCE_URI = "ui://openephemeris/bazi";
+export const BAZI_MIME_TYPE = "text/html;profile=mcp-app";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLE_PATHS = [
+    path.resolve(here, "..", "..", "..", "dist", "ui", "bazi.html"),
+];
+function findBundlePath() {
+    for (const p of BUNDLE_PATHS) {
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+let cachedBundle = null;
+/** Read the pre-built HTML bundle. Returns null if not yet built. */
+export function getBaziBundle() {
+    if (cachedBundle)
+        return cachedBundle;
+    const bundlePath = findBundlePath();
+    if (!bundlePath)
+        return null;
+    try {
+        cachedBundle = fs.readFileSync(bundlePath, "utf-8");
+        return cachedBundle;
+    }
+    catch {
+        return null;
+    }
+}
+/** Reset cache (useful in dev watch mode or tests). */
+export function clearBaziBundleCache() {
+    cachedBundle = null;
+}
+function parseBaziArgs(args) {
+    let { year, month, day, hour } = args;
+    if (args.datetime && (!year || !month || !day)) {
+        const dt = new Date(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:00Z'");
+    }
+    const out = { year, month, day };
+    if (hour != null)
+        out.hour = hour;
+    return out;
+}
+// ── Summary builder ──────────────────────────────────────────────────────────
+function buildBaziSummary(data) {
+    const chart = data.chart;
+    const balance = data.element_balance;
+    const tenGods = data.ten_gods;
+    const dm = chart?.day_master;
+    const dmStr = dm ? (dm.stem || "?") + " " + (dm.element || "?") : "Unknown";
+    let summary = "**BaZi Four Pillars** — Day Master: **" + dmStr + "**\n\n";
+    // Pillars summary
+    const keys = ["year", "month", "day", "hour"];
+    const labels = ["Year", "Month", "Day", "Hour"];
+    if (chart) {
+        summary += "| Pillar | Stem | Branch | Animal |\n|--------|------|--------|--------|\n";
+        for (let i = 0; i < keys.length; i++) {
+            const p = chart[keys[i]];
+            if (p) {
+                summary +=
+                    "| " + labels[i] +
+                        " | " + (p.stem?.name || "?") +
+                        " (" + (p.stem?.element || "") + ")" +
+                        " | " + (p.branch?.name || "?") +
+                        " | " + (p.branch?.animal || "") +
+                        " |\n";
+            }
+        }
+        summary += "\n";
+    }
+    // Element balance
+    if (balance?.elements) {
+        const strength = balance.day_master_strength || "unknown";
+        summary += "**Day Master Strength**: " + strength + "\n";
+        if (balance.yong_shen_element) {
+            summary += "**Useful God (用神)**: " + balance.yong_shen_element + "\n";
+        }
+        summary += "\n";
+    }
+    summary += "Click pillars on the chart for Ten Gods detail and interpretation.";
+    return summary;
+}
+// ── Tool: explore_bazi_chart ─────────────────────────────────────────────────
+registerTool({
+    name: "explore_bazi_chart",
+    description: "Generate an interactive BaZi Four Pillars (四柱命盘) visualization. " +
+        "Displays the Year, Month, Day, and Hour pillars with Heavenly Stems, " +
+        "Earthly Branches, Hidden Stems, Ten Gods analysis, and a weighted " +
+        "Wu Xing (Five Elements) balance bar.\n\n" +
+        "Returns a rich interactive chart with:\n" +
+        "  • Four-column pillar grid with Chinese characters and element colours\n" +
+        "  • Day Master emphasis and badge\n" +
+        "  • Hidden Stems with strength indicators (main/secondary/residual)\n" +
+        "  • Ten Gods classification for each pillar\n" +
+        "  • Wu Xing balance bar with percentages and Yong Shen (Useful God)\n" +
+        "  • Click pillars for detailed Ten Gods drawer\n\n" +
+        "CREDIT COST: 3 credits (batches three BaZi endpoints).\n\n" +
+        "Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude Desktop). " +
+        "Falls back to a markdown table summary in other hosts.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            year: {
+                type: "integer",
+                description: "Gregorian birth year, e.g. 1987.",
+            },
+            month: {
+                type: "integer",
+                description: "Birth month (1–12).",
+            },
+            day: {
+                type: "integer",
+                description: "Birth day of month (1–31).",
+            },
+            hour: {
+                type: "integer",
+                description: "Birth hour (0–23). Optional, defaults to 12 (noon). " +
+                    "Chinese shí hours are 2-hour blocks — precision within a 2-hour window is sufficient.",
+            },
+            datetime: {
+                type: "string",
+                description: "Alternative to year/month/day: ISO 8601 datetime (e.g. '1987-07-15T14:00:00Z'). " +
+                    "year/month/day/hour are extracted automatically.",
+            },
+        },
+        required: [],
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: {
+        title: "Interactive BaZi Four Pillars Explorer",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    _meta: {
+        ui: {
+            resourceUri: BAZI_RESOURCE_URI,
+            visibility: ["model", "app"],
+        },
+    },
+    handler: async (args) => {
+        const components = parseBaziArgs(args);
+        const client = getActiveClient();
+        const body = {
+            year: components.year,
+            month: components.month,
+            day: components.day,
+        };
+        if (components.hour != null)
+            body.hour = components.hour;
+        // Batch all three BaZi endpoints in parallel
+        const [chartResult, tenGodsResult, balanceResult] = await Promise.allSettled([
+            client.request("POST", "/chinese/bazi", { data: body }),
+            client.request("POST", "/chinese/bazi/ten-gods", { data: body }),
+            client.request("POST", "/chinese/bazi/element-balance", { data: body }),
+        ]);
+        const chartData = chartResult.status === "fulfilled"
+            ? chartResult.value
+            : { error: chartResult.reason?.message };
+        const tenGodsData = tenGodsResult.status === "fulfilled"
+            ? tenGodsResult.value
+            : { error: tenGodsResult.reason?.message };
+        const balanceData = balanceResult.status === "fulfilled"
+            ? balanceResult.value
+            : { error: balanceResult.reason?.message };
+        const uiPayload = {
+            chart: chartData,
+            ten_gods: tenGodsData,
+            element_balance: balanceData,
+            server_version: SERVER_VERSION,
+        };
+        const summary = buildBaziSummary(uiPayload);
+        const bundleAvailable = Boolean(getBaziBundle());
+        if (bundleAvailable) {
+            return {
+                content: [
+                    { type: "text", text: summary },
+                    { type: "text", text: JSON.stringify(uiPayload) },
+                ],
+                _meta: {
+                    "ui/resourceUri": BAZI_RESOURCE_URI,
+                    ui: { resourceUri: BAZI_RESOURCE_URI },
+                },
+            };
+        }
+        // Fallback: text summary only
+        return { content: [{ type: "text", text: summary }] };
+    },
+});

package/dist/tools/apps/bi-wheel-app.d.ts

@@ -1,15 +1,21 @@
 /**
  * bi-wheel-app.ts — MCP App tool registration for the Bi-Wheel Explorer.
  *
- * Registers 3 tools:
- *   • explore_bi_wheel               — primary entry point: fetches two charts, computes
- *                                      cross-aspects, returns data + UI resource [model]
+ * Registers 6 tools:
+ *   • explore_bi_wheel               — primary entry point [model + app]
+ *   • bi_wheel_recalculate           — re-fetch with new params [app-only]
  *   • bi_wheel_on_cross_aspect_click — cross-aspect click handler [app-only]
- *   • bi_wheel_on_planet_click       — planet click handler (inner or outer wheel) [app-only]
+ *   • bi_wheel_on_planet_click       — planet click handler [app-only]
+ *   • bi_wheel_on_house_click        — house cusp click handler [app-only]
+ *   • bi_wheel_synopsis              — full reading overview [model + app]
  *
- * Modes:
- *   synastry — fetch two natal charts in parallel (person1 inner, person2 outer)
- *   transit  — fetch one natal chart (inner) + one transit chart (outer)
+ * Supported modes (BiWheelMode):
+ *   synastry     — two natal charts (person1 inner, person2 outer)
+ *   transit      — natal inner + transiting planets outer
+ *   progressed   — natal inner + secondary progressions outer  (POST /ephemeris/progressed)
+ *   solar_return — natal inner + solar return chart outer      (POST /predictive/returns/solar)
+ *   lunar_return — natal inner + lunar return chart outer      (POST /predictive/returns/lunar)
+ *   solar_arc    — natal inner + solar arc directions outer    (client-side Naibod approximation)
  *
  * Cross-aspects are computed client-side (UI) AND server-side (for summary/fallback).
  * The payload cross_aspects array is capped at 30 tightest-orb aspects.
@@ -19,6 +25,7 @@ export declare const BI_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
 /** Read the pre-built HTML bundle. Returns null if not yet built. */
 export declare function getBiWheelBundle(): string | null;
 export declare function clearBiWheelBundleCache(): void;
+export type BiWheelMode = "synastry" | "transit" | "progressed" | "solar_return" | "lunar_return" | "solar_arc";
 interface PlanetPoint {
     name: string;
     longitude: number;