@openephemeris/mcp-server 3.13.9 → 3.13.10

package/dist/server-sse.js

@@ -27,6 +27,15 @@ 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";
+import { TRANSIT_TIMELINE_RESOURCE_URI, TRANSIT_TIMELINE_MIME_TYPE, getTransitTimelineBundle, } from "./tools/apps/transit-timeline-app.js";
+import { MOON_PHASE_RESOURCE_URI, MOON_PHASE_MIME_TYPE, getMoonPhaseBundle, } from "./tools/apps/moon-phase-app.js";
+import { BAZI_RESOURCE_URI, BAZI_MIME_TYPE, getBaziBundle, } from "./tools/apps/bazi-app.js";
+import { VEDIC_CHART_RESOURCE_URI, VEDIC_CHART_MIME_TYPE, getVedicChartBundle, } from "./tools/apps/vedic-chart-app.js";
+import { oauthDiscoveryRouter } 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 +91,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
@@ -282,6 +304,38 @@ function createMcpServer() {
                 mimeType: BI_WHEEL_MIME_TYPE,
             });
         }
+        if (getTransitTimelineBundle()) {
+            resources.push({
+                uri: TRANSIT_TIMELINE_RESOURCE_URI,
+                name: "Transit Timeline Explorer",
+                description: "Interactive Gantt-style transit timeline showing planetary aspects over time.",
+                mimeType: TRANSIT_TIMELINE_MIME_TYPE,
+            });
+        }
+        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,
+            });
+        }
+        if (getBaziBundle()) {
+            resources.push({
+                uri: BAZI_RESOURCE_URI,
+                name: "BaZi Four Pillars Explorer",
+                description: "Interactive BaZi chart with pillars, Ten Gods, hidden stems, and Wu Xing balance.",
+                mimeType: BAZI_MIME_TYPE,
+            });
+        }
+        if (getVedicChartBundle()) {
+            resources.push({
+                uri: VEDIC_CHART_RESOURCE_URI,
+                name: "Vedic Jyotish Chart",
+                description: "Interactive South Indian Rashi grid with planet placements, Lagna marker, and Nakshatra detail.",
+                mimeType: VEDIC_CHART_MIME_TYPE,
+            });
+        }
         return { resources };
     });
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
@@ -304,6 +358,30 @@ 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 }] };
         }
+        if (uri === TRANSIT_TIMELINE_RESOURCE_URI) {
+            const bundle = getTransitTimelineBundle();
+            if (!bundle)
+                throw new Error("Transit Timeline UI bundle not found. Run `npm run build:ui` to build it.");
+            return { contents: [{ uri: TRANSIT_TIMELINE_RESOURCE_URI, mimeType: TRANSIT_TIMELINE_MIME_TYPE, text: bundle }] };
+        }
+        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 }] };
+        }
+        if (uri === BAZI_RESOURCE_URI) {
+            const bundle = getBaziBundle();
+            if (!bundle)
+                throw new Error("BaZi UI bundle not found. Run `npm run build:ui` to build it.");
+            return { contents: [{ uri: BAZI_RESOURCE_URI, mimeType: BAZI_MIME_TYPE, text: bundle }] };
+        }
+        if (uri === VEDIC_CHART_RESOURCE_URI) {
+            const bundle = getVedicChartBundle();
+            if (!bundle)
+                throw new Error("Vedic Chart UI bundle not found. Run `npm run build:ui` to build it.");
+            return { contents: [{ uri: VEDIC_CHART_RESOURCE_URI, mimeType: VEDIC_CHART_MIME_TYPE, text: bundle }] };
+        }
         throw new Error(`Unknown resource: ${uri}`);
     });
     return server;
@@ -330,6 +408,19 @@ 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,
+    });
+    app.use(oauthDiscoveryRouter);
+    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({
@@ -407,22 +498,26 @@ async function main() {
             });
             return;
         }
-        // Auth — required on Initialize
-        const apiKey = extractApiKey(req);
-        if (!apiKey) {
+        // Auth — required on Initialize (supports both API keys and OAuth JWTs)
+        const { apiKey, jwt } = extractAuth(req);
+        if (!apiKey && !jwt) {
             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",
+                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;
         }
-        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 are validated downstream
+        // by the Go sidecar's ValidateSupabaseJWT when tool calls are proxied.
+        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;
+            }
         }
         // Create per-session transport, server, and client
         const transport = new StreamableHTTPServerTransport({
@@ -432,7 +527,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 +606,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 +634,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,224 @@
+/**
+ * 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";
+// ── 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,
+    },
+    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;