@openephemeris/mcp-server 4.17.0 → 4.19.0

package/dist/server-sse.d.ts

@@ -1,4 +1,22 @@
 import express from "express";
+/**
+ * The hosted server is multi-tenant: every tool call must be authenticated
+ * and metered as the connecting user. A credential in the process environment
+ * breaks that — the client interceptor sends X-Service-Key ahead of the user's
+ * key (every user unmetered), and an env API key / JWT would bill every
+ * session to one account.
+ *
+ * - A service key in the environment is a hard startup failure: there is no
+ *   safe way to run with it present.
+ * - A user API key / JWT in the environment is logged loudly and ignored.
+ * - The module singleton (built from the environment at import, and what
+ *   getActiveClient() falls back to outside a session context) is stripped of
+ *   every credential either way; per-session clients are built with
+ *   `inheritEnvCredentials: false`.
+ *
+ * Exported for tests. stdio mode never calls this.
+ */
+export declare function enforceHostedCredentialPolicy(env?: NodeJS.ProcessEnv): void;
 /**
  * Build the full Express app (auth gate, OAuth routes, /mcp Streamable HTTP,
  * health, resources). Exported so tests can drive the REAL handlers with

package/dist/server-sse.js

@@ -8,7 +8,8 @@
  * Architecture:
  *   - The SSE server validates the user's API key at connection time by
  *     making a lightweight call to the Go backend.
- *   - The validated key is injected into the singleton BackendClient so
+ *   - Each session gets its own BackendClient built from the validated key
+ *     (never from env credentials — see enforceHostedCredentialPolicy), so
  *     all subsequent tool calls authenticate as the connecting user.
  *   - Usage credits are metered against the user's account and tier.
  */
@@ -26,17 +27,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema
 import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface, describeSurface } from "./tools/index.js";
 import { buildUiMeta } from "./tools/ui-meta.js";
 import { SERVER_INSTRUCTIONS } from "./instructions.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";
-import { BI_WHEEL_RESOURCE_URI, BI_WHEEL_MIME_TYPE, getBiWheelBundle, } from "./tools/apps/bi-wheel-app.js";
-// NOTE: bazi, vedic-chart imports removed — tools disabled.
-// NOTE: transit-timeline, bazi imports removed — tools disabled.
-// NOTE: transit-timeline, vedic-chart imports removed — tools disabled.
-import { MOON_PHASE_RESOURCE_URI, MOON_PHASE_MIME_TYPE, getMoonPhaseBundle, } from "./tools/apps/moon-phase-app.js";
-import { TRANSIT_TIMELINE_RESOURCE_URI, TRANSIT_TIMELINE_MIME_TYPE, getTransitTimelineBundle, } from "./tools/apps/transit-timeline-app.js";
-import { VEDIC_CHART_RESOURCE_URI, VEDIC_CHART_MIME_TYPE, getVedicChartBundle, } from "./tools/apps/vedic-chart-app.js";
-import { BAZI_RESOURCE_URI, BAZI_MIME_TYPE, getBaziBundle, } from "./tools/apps/bazi-app.js";
+import { BackendClient, backendClient, presentCredentialEnvVars, runWithClient } from "./backend/client.js";
+import { listUiResources, readUiResource } from "./tools/apps/ui-resources.js";
 import { oauthDiscoveryRouter, PROTECTED_RESOURCE_METADATA_URL } from "./oauth/discovery.js";
 import { oauthDcrRouter } from "./oauth/dcr.js";
 import { oauthTokenRouter } from "./oauth/token.js";
@@ -386,113 +378,15 @@ function createMcpServer(analyticsId = "anonymous", surface = "core", activity =
     });
     // --- Resource handlers ---
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
-        const resources = [];
-        if (getChartWheelBundle()) {
-            resources.push({
-                uri: CHART_WHEEL_RESOURCE_URI,
-                name: "Chart Wheel Explorer",
-                description: "Interactive natal chart wheel with clickable planets, houses, and aspects.",
-                mimeType: CHART_WHEEL_MIME_TYPE,
-            });
-        }
-        if (getBodygraphBundle()) {
-            resources.push({
-                uri: BODYGRAPH_RESOURCE_URI,
-                name: "Human Design Bodygraph Explorer",
-                description: "Interactive Human Design Bodygraph with clickable centers, gates, and channels.",
-                mimeType: BODYGRAPH_MIME_TYPE,
-            });
-        }
-        if (getBiWheelBundle()) {
-            resources.push({
-                uri: BI_WHEEL_RESOURCE_URI,
-                name: "Bi-Wheel Explorer",
-                description: "Interactive synastry or transit bi-wheel with cross-aspect lines and clickable planets.",
-                mimeType: BI_WHEEL_MIME_TYPE,
-            });
-        }
-        // NOTE: bazi resources omitted — tools disabled.
-        // NOTE: transit-timeline, 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,
-            });
-        }
-        if (getTransitTimelineBundle()) {
-            resources.push({
-                uri: TRANSIT_TIMELINE_RESOURCE_URI,
-                name: "Transit Timeline Explorer",
-                description: "Interactive vertical timeline of upcoming transit hits grouped by month, with clickable events.",
-                mimeType: TRANSIT_TIMELINE_MIME_TYPE,
-            });
-        }
-        if (getVedicChartBundle()) {
-            resources.push({
-                uri: VEDIC_CHART_RESOURCE_URI,
-                name: "Vedic Chart Explorer",
-                description: "Interactive Vedic (Jyotish) South Indian Rashi grid with clickable sign placements.",
-                mimeType: VEDIC_CHART_MIME_TYPE,
-            });
-        }
-        if (getBaziBundle()) {
-            resources.push({
-                uri: BAZI_RESOURCE_URI,
-                name: "BaZi Four Pillars Explorer",
-                description: "Interactive BaZi (Four Pillars of Destiny) chart with clickable Year/Month/Day/Hour pillars.",
-                mimeType: BAZI_MIME_TYPE,
-            });
-        }
-        return { resources };
+        // One registry for both transports: versioned ui:// URIs + resource _meta
+        // (prefersBorder, CSP, widgetDescription). See tools/apps/ui-resources.ts.
+        return { resources: listUiResources() };
     });
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const uri = request.params.uri;
-        if (uri === CHART_WHEEL_RESOURCE_URI) {
-            const bundle = getChartWheelBundle();
-            if (!bundle)
-                throw new Error("Chart Wheel UI bundle not found. Run `npm run build:ui` to build it.");
-            return { contents: [{ uri: CHART_WHEEL_RESOURCE_URI, mimeType: CHART_WHEEL_MIME_TYPE, text: bundle }] };
-        }
-        if (uri === BODYGRAPH_RESOURCE_URI) {
-            const bundle = getBodygraphBundle();
-            if (!bundle)
-                throw new Error("Bodygraph UI bundle not found. Run `npm run build:ui` to build it.");
-            return { contents: [{ uri: BODYGRAPH_RESOURCE_URI, mimeType: BODYGRAPH_MIME_TYPE, text: bundle }] };
-        }
-        if (uri === BI_WHEEL_RESOURCE_URI) {
-            const bundle = getBiWheelBundle();
-            if (!bundle)
-                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: bazi resources omitted — tools disabled.
-        // NOTE: transit-timeline, 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 }] };
-        }
-        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 === 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 }] };
-        }
-        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 }] };
-        }
+        const result = readUiResource(uri);
+        if (result)
+            return result;
         throw new Error(`Unknown resource: ${uri}`);
     });
     return server;
@@ -557,12 +451,43 @@ function startSseKeepalive(res) {
     }, 25_000);
     res.on("close", () => clearInterval(ping));
 }
+/**
+ * The hosted server is multi-tenant: every tool call must be authenticated
+ * and metered as the connecting user. A credential in the process environment
+ * breaks that — the client interceptor sends X-Service-Key ahead of the user's
+ * key (every user unmetered), and an env API key / JWT would bill every
+ * session to one account.
+ *
+ * - A service key in the environment is a hard startup failure: there is no
+ *   safe way to run with it present.
+ * - A user API key / JWT in the environment is logged loudly and ignored.
+ * - The module singleton (built from the environment at import, and what
+ *   getActiveClient() falls back to outside a session context) is stripped of
+ *   every credential either way; per-session clients are built with
+ *   `inheritEnvCredentials: false`.
+ *
+ * Exported for tests. stdio mode never calls this.
+ */
+export function enforceHostedCredentialPolicy(env = process.env) {
+    const { serviceKeys, userCredentials } = presentCredentialEnvVars(env);
+    if (serviceKeys.length > 0) {
+        throw new Error(`Refusing to start the hosted MCP HTTP server: ${serviceKeys.join(", ")} is set. ` +
+            `A service key bypasses per-user metering for every session. Unset it — the ` +
+            `hosted server authenticates each session with the user's own API key or OAuth token.`);
+    }
+    if (userCredentials.length > 0) {
+        console.error(`[SECURITY] ${userCredentials.join(", ")} is set in the hosted MCP server environment. ` +
+            `IGNORING it — sessions authenticate only with their own credential. Remove it from the deployment.`);
+    }
+    backendClient.clearCredentials();
+}
 /**
  * Build the full Express app (auth gate, OAuth routes, /mcp Streamable HTTP,
  * health, resources). Exported so tests can drive the REAL handlers with
  * supertest instead of a re-implemented stub. Does not listen.
  */
 export async function createSseApp() {
+    enforceHostedCredentialPolicy();
     await initTools();
     const app = express();
     // NOTE: express.json() is applied per-route (jsonParser on /mcp POST), not
@@ -700,18 +625,19 @@ export async function createSseApp() {
             serverInfo: {
                 name: "Open Ephemeris",
                 version,
-                description: "NASA JPL DE440-backed astronomical computation engine for AI agents. 90+ typed tools covering " +
+                description: `NASA JPL DE440-backed astronomical computation engine for AI agents. ${tools.length} 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 " +
-                    "zero-hallucination accuracy. Free Explorer tier available.",
+                    "zero-hallucination accuracy. Free Explorer tier: 150 one-time credits.",
                 iconUrl: "https://mcp.openephemeris.com/icon.png",
                 homepage: "https://openephemeris.com",
             },
             authentication: {
                 required: true,
                 schemes: ["apiKey"],
-                instructions: "Pass your Open Ephemeris API key via the X-API-Key header. " +
+                instructions: "Sign in with OAuth 2.1 (PKCE, dynamic client registration), or pass your Open Ephemeris API key " +
+                    "via the X-API-Key header (or Authorization: Bearer opene-…). Every call is metered to that user. " +
                     "Get a free Explorer key at https://openephemeris.com/dashboard — no credit card required.",
             },
             tools,
@@ -871,7 +797,9 @@ export async function createSseApp() {
                 console.error(`[HTTP] Session initialized: ${id}`);
             },
         });
-        const client = new BackendClient({ baseURL: BACKEND_URL, apiKey, jwt });
+        // inheritEnvCredentials:false — this client must authenticate as THIS
+        // session's user only, never as an env service key / API key / JWT.
+        const client = new BackendClient({ baseURL: BACKEND_URL, apiKey, jwt, inheritEnvCredentials: false });
         const analyticsId = distinctIdFor(apiKey ?? jwt);
         // 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.

package/dist/tools/apps/_render-token.d.ts

@@ -0,0 +1,34 @@
+/**
+ * _render-token.ts — plumbing for the API's server-issued render token.
+ *
+ * The Go API stamps every charged visual on a render-family route
+ * (/human-design/chart + /visualization/bodygraph, /human-design/transit-chart,
+ * /human-design/composite, /chinese/bazi, /vedic/chart) with a short-lived
+ * token bound to the account and the chart-defining inputs
+ * (auth/render_token.go). Presenting it on a re-render of the SAME chart —
+ * the iframe's host light/dark reconciliation, a layout flip — makes that
+ * re-render free (base charge and visual surcharge). Anything else is charged
+ * normally, so passing a stale or foreign token is harmless.
+ *
+ * Flow: explore_* puts the token on the payload as `_render_token`; the iframe
+ * hands it back as the `render_token` argument of its recalc / refetch call;
+ * the tool sends it in the X-OE-Render-Token header.
+ */
+export declare const RENDER_TOKEN_HEADER = "X-OE-Render-Token";
+/** Input-schema property for the app-only recalc args. Never set by the model. */
+export declare const RENDER_TOKEN_PROPERTY: {
+    readonly type: "string";
+    readonly description: string;
+};
+/** Request headers presenting `token`, or undefined when there is none. */
+export declare function renderTokenHeaders(token: unknown): Record<string, string> | undefined;
+/**
+ * The token the API injected on the root <svg> of a /visualization/bodygraph
+ * response (a binary route, whose response headers the backend client does
+ * not surface).
+ */
+export declare function renderTokenFromSvg(svg: string | null | undefined): string | undefined;
+/** `visual.render_token` from an include_visual JSON response. */
+export declare function renderTokenFromVisual(visual: unknown): string | undefined;
+/** Copy of tool args with the per-call token removed (for `_refetch.args`). */
+export declare function withoutRenderToken<T extends Record<string, unknown>>(args: T): T;

package/dist/tools/apps/_render-token.js

@@ -0,0 +1,50 @@
+/**
+ * _render-token.ts — plumbing for the API's server-issued render token.
+ *
+ * The Go API stamps every charged visual on a render-family route
+ * (/human-design/chart + /visualization/bodygraph, /human-design/transit-chart,
+ * /human-design/composite, /chinese/bazi, /vedic/chart) with a short-lived
+ * token bound to the account and the chart-defining inputs
+ * (auth/render_token.go). Presenting it on a re-render of the SAME chart —
+ * the iframe's host light/dark reconciliation, a layout flip — makes that
+ * re-render free (base charge and visual surcharge). Anything else is charged
+ * normally, so passing a stale or foreign token is harmless.
+ *
+ * Flow: explore_* puts the token on the payload as `_render_token`; the iframe
+ * hands it back as the `render_token` argument of its recalc / refetch call;
+ * the tool sends it in the X-OE-Render-Token header.
+ */
+export const RENDER_TOKEN_HEADER = "X-OE-Render-Token";
+/** Input-schema property for the app-only recalc args. Never set by the model. */
+export const RENDER_TOKEN_PROPERTY = {
+    type: "string",
+    description: "Set automatically by the embedded app when it re-renders a chart it already paid for " +
+        "(e.g. to match the host's light/dark theme). Never pass this yourself.",
+};
+/** Request headers presenting `token`, or undefined when there is none. */
+export function renderTokenHeaders(token) {
+    return typeof token === "string" && token.trim() !== ""
+        ? { [RENDER_TOKEN_HEADER]: token.trim() }
+        : undefined;
+}
+/**
+ * The token the API injected on the root <svg> of a /visualization/bodygraph
+ * response (a binary route, whose response headers the backend client does
+ * not surface).
+ */
+export function renderTokenFromSvg(svg) {
+    if (!svg)
+        return undefined;
+    const m = /<svg\b[^>]*\sdata-oe-render-token="([A-Za-z0-9._-]+)"/.exec(svg);
+    return m ? m[1] : undefined;
+}
+/** `visual.render_token` from an include_visual JSON response. */
+export function renderTokenFromVisual(visual) {
+    const t = visual?.render_token;
+    return typeof t === "string" && t !== "" ? t : undefined;
+}
+/** Copy of tool args with the per-call token removed (for `_refetch.args`). */
+export function withoutRenderToken(args) {
+    const { render_token: _drop, ...rest } = args;
+    return rest;
+}

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

@@ -16,7 +16,7 @@
  * bazi_annual_pillar, bazi_compatibility, bazi_chart) already exist in
  * ../specialized/bazi.ts — this file is purely the interactive visual entry point.
  */
-export declare const BAZI_RESOURCE_URI = "ui://openephemeris/bazi";
+export declare const BAZI_RESOURCE_URI: string;
 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;

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

@@ -20,15 +20,17 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { registerTool, SERVER_VERSION } from "../index.js";
+import { UI_RESOURCE_MIME_TYPE, uiResourceUri } from "./ui-resource.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, buildBaziConventionFields, CONVENTION_PROPERTIES } from "../specialized/bazi.js";
+import { RENDER_TOKEN_PROPERTY, renderTokenFromVisual, renderTokenHeaders } from "./_render-token.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
-export const BAZI_RESOURCE_URI = "ui://openephemeris/bazi";
-export const BAZI_MIME_TYPE = "text/html;profile=mcp-app";
+export const BAZI_RESOURCE_URI = uiResourceUri("bazi");
+export const BAZI_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 const here = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLE_PATHS = [
     path.resolve(here, "..", "..", "..", "dist", "ui", "bazi.html"),
@@ -60,26 +62,39 @@ export function getBaziBundle() {
 export function clearBaziBundleCache() {
     cachedBundle = null;
 }
+const CONVENTION_ARG_KEYS = ["year_boundary", "day_boundary", "true_solar_time", "latitude", "longitude", "timezone"];
+function pickConventionArgs(args) {
+    const out = {};
+    for (const k of CONVENTION_ARG_KEYS) {
+        if (args?.[k] != null && args[k] !== "")
+            out[k] = args[k];
+    }
+    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
  * Go-rendered SVG (bazi.RenderBaziChartSVG), same shape the strict
  * /chinese/bazi handler returns with a `visual` key attached.
  */
-async function fetchBaziChart(components, theme = "dark", conventionFields = {}, reconcile = false) {
+async function fetchBaziChart(components, theme = "dark", conventionFields = {}, renderToken) {
     const client = getActiveClient();
     const body = {
         ...components,
         ...conventionFields,
         include_visual: true,
         visual_config: { format: "svg", theme, size: 800 },
-        // Set only by bazi_recalculate's theme-reconcile path below — waives the
-        // visual surcharge server-side for a same-birth-data re-render (#551).
-        ...(reconcile ? { _visual_reconcile: true } : {}),
     };
-    return await client.request("POST", "/chinese/bazi", { data: body });
+    // bazi_recalculate's theme reconcile presents the token the first render
+    // was issued; the API waives the whole re-render only when it verifies for
+    // this account and these exact inputs (the old self-serve
+    // `_visual_reconcile` flag is gone).
+    return await client.request("POST", "/chinese/bazi", {
+        data: body,
+        headers: renderTokenHeaders(renderToken),
+    });
 }
-function buildModelPayload(data, components, theme) {
+function buildModelPayload(data, components, theme, conventionArgs = {}) {
     return {
         year: data.year,
         month: data.month,
@@ -88,7 +103,9 @@ function buildModelPayload(data, components, theme) {
         day_master: data.day_master,
         _svg: data.visual?.data,
         _birth_params: components,
+        ...(Object.keys(conventionArgs).length ? { _convention_args: conventionArgs } : {}),
         _theme: theme,
+        ...(renderTokenFromVisual(data.visual) ? { _render_token: renderTokenFromVisual(data.visual) } : {}),
     };
 }
 function buildSummary(payload) {
@@ -180,7 +197,7 @@ registerTool({
             return { content: [{ type: "text", text: buildSummary(payload) }] };
         }
         const data = await fetchBaziChart(components, theme, conventionFields);
-        const payload = buildModelPayload(data, components, theme);
+        const payload = buildModelPayload(data, components, theme, pickConventionArgs(args));
         const summary = buildSummary(payload);
         // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
         // delivered through resources/read — NOT as a content block.
@@ -199,9 +216,9 @@ registerTool({
     name: "bazi_recalculate",
     description: "Recalculates a BaZi Four Pillars chart with new birth data or theme. " +
         "App-only: called by the embedded chart itself to reconcile the initial " +
-        "server-rendered SVG to the host's actual light/dark theme. Billed at 1 " +
-        "credit (base only) — the visual-render surcharge is waived because this " +
-        "re-renders already-computed data, not a new chart.",
+        "server-rendered SVG to the host's actual light/dark theme. Free when it " +
+        "presents the render_token of the chart it re-renders (same birth data and " +
+        "conventions); otherwise billed like a new chart (3 credits).",
     inputSchema: {
         type: "object",
         properties: {
@@ -209,11 +226,15 @@ registerTool({
             month: { type: "integer" },
             day: { type: "integer" },
             hour: { type: "integer" },
+            minute: { type: "integer" },
+            ...CONVENTION_PROPERTIES,
+            timezone: { type: "string", description: "IANA timezone name the chart was cast in." },
             theme: {
                 type: "string",
                 enum: ["light", "dark"],
                 description: "Render palette for the BaZi SVG. Mirrors the MCP host's light/dark color scheme.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["year", "month", "day"],
     },
@@ -223,8 +244,12 @@ registerTool({
     handler: async (args) => {
         const components = parseBaziArgs(args);
         const theme = args.theme === "light" ? "light" : "dark";
-        const data = await fetchBaziChart(components, theme, {}, true);
-        const payload = buildModelPayload(data, components, theme);
+        // Re-cast under the SAME conventions as the original chart — dropping them
+        // (as this tool used to) rendered a different chart on any non-default
+        // year/day boundary, and would not match the render token either.
+        const conventionArgs = pickConventionArgs(args);
+        const data = await fetchBaziChart(components, theme, buildBaziConventionFields(conventionArgs), args.render_token);
+        const payload = buildModelPayload(data, components, theme, conventionArgs);
         return {
             content: [{ type: "text", text: JSON.stringify({ ...payload, server_version: SERVER_VERSION }) }],
         };

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

@@ -12,20 +12,27 @@
  * 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)
+ *   progressed   — natal inner + secondary progressions outer  (POST /ephemeris/progressed, method=secondary)
  *   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)
+ *   solar_arc    — natal inner + solar arc directions outer    (POST /ephemeris/progressed, method=solar_arc)
  *
  * 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.
  */
-export declare const BI_WHEEL_RESOURCE_URI = "ui://openephemeris/bi-wheel";
+import { getActiveClient } from "../../backend/client.js";
+export declare const BI_WHEEL_RESOURCE_URI: string;
 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";
+/**
+ * Route outer-wheel fetch to the correct API endpoint based on mode, and hand
+ * back a chart in the natal-chart shape (top-level planets/houses/angles):
+ * /ephemeris/progressed nests it under `data`, the return endpoints under `chart`.
+ */
+export declare function fetchOuterChart(client: Pick<ReturnType<typeof getActiveClient>, "post">, mode: BiWheelMode, dt1: string, lat1: number | undefined, lon1: number | undefined, tz1: string | undefined, dt2: string, lat2: number | undefined, lon2: number | undefined, tz2: string | undefined, houseSystem?: string): Promise<Record<string, unknown>>;
 interface PlanetPoint {
     name: string;
     longitude: number;