@openephemeris/mcp-server 3.13.10 → 3.15.0

package/dist/server-sse.js

@@ -27,11 +27,9 @@ 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";
+// 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 { 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 { 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";
@@ -68,8 +66,10 @@ const BACKEND_URL = process.env.OPENEPHEMERIS_BACKEND_URL ||
     "https://api.openephemeris.com";
 const version = resolveServerVersion();
 /**
- * Validate a user-supplied API key by hitting an auth-gated endpoint on
- * the Go sidecar. Returns true if the key yields a 2xx, false on 401/403.
+ * Validate a user-supplied API key by hitting an auth-gated endpoint on the Go
+ * sidecar. Tri-state so callers can fail closed when validation is unavailable
+ * (APP-6): "valid" (2xx), "invalid" (401/403), or "unknown" (network error or
+ * non-auth status — could not confirm).
  */
 async function validateApiKey(apiKey) {
     try {
@@ -79,17 +79,26 @@ async function validateApiKey(apiKey) {
             timeout: 5_000,
             validateStatus: () => true, // don't throw on any status
         });
-        // 2xx = valid key, 401/403 = invalid key, anything else = let through
         if (resp.status === 401 || resp.status === 403)
-            return false;
-        return true;
+            return "invalid";
+        if (resp.status >= 200 && resp.status < 300)
+            return "valid";
+        return "unknown"; // 5xx etc. — can't confirm
     }
     catch {
-        // Network error — let them through; tool calls will fail if key is bad.
-        console.warn("Could not validate API key against backend, allowing connection.");
-        return true;
+        console.warn("Could not validate API key against backend.");
+        return "unknown";
     }
 }
+/**
+ * Browser-originated requests carry an Origin header (the MCP apps run in a
+ * cross-origin iframe). Server-to-server MCP clients generally do not. We use
+ * this to fail closed for browsers when key validation is unavailable, while
+ * still letting trusted server clients through (APP-6).
+ */
+function isBrowserOrigin(req) {
+    return typeof req.headers.origin === "string" && req.headers.origin.length > 0;
+}
 /**
  * Extract authentication from a request, distinguishing JWTs from API keys.
  *
@@ -214,8 +223,12 @@ function createMcpServer() {
             prompts: {},
             resources: {},
             experimental: {
-                // Declare MCP Apps extension (spec: io.modelcontextprotocol/ui, 2026-01-26)
-                "io.modelcontextprotocol/ui": {},
+                // Declare MCP Apps extension (spec: io.modelcontextprotocol/ui, 2026-01-26).
+                // Advertise the supported UI MIME type so Directory-compliant hosts know
+                // this server returns renderable HTML resources.
+                "io.modelcontextprotocol/ui": {
+                    mimeTypes: ["text/html;profile=mcp-app"],
+                },
             },
         },
         instructions: "Open Ephemeris is a precision astronomical computation engine. " +
@@ -232,7 +245,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"],
+                        },
+                    },
+                }
                 : {}),
         })),
     }));
@@ -264,16 +285,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,
             };
         }
     });
@@ -304,14 +327,7 @@ 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,
-            });
-        }
+        // NOTE: transit-timeline, bazi, vedic-chart resources omitted — tools disabled.
         if (getMoonPhaseBundle()) {
             resources.push({
                 uri: MOON_PHASE_RESOURCE_URI,
@@ -320,22 +336,6 @@ function createMcpServer() {
                 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) => {
@@ -358,30 +358,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 }] };
         }
-        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 }] };
-        }
+        // 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 }] };
         }
-        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;
@@ -393,12 +376,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;
         }
@@ -417,10 +426,34 @@ async function main() {
         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));
+    // Per-IP throttle on MCP session creation to bound unauthenticated session
+    // churn / volumetric abuse (APP-7). Only NEW sessions are limited — requests
+    // carrying an mcp-session-id are existing sessions (ongoing tool calls) and
+    // must never be throttled.
+    const sessionRateLimiter = createRateLimiter({
+        windowMs: 60_000,
+        maxRequests: 30,
+        trustProxy: true,
+    });
+    const throttleSessionCreation = (req, res, next) => {
+        if (req.headers["mcp-session-id"]) {
+            next();
+            return;
+        }
+        sessionRateLimiter(req, res, next);
+    };
+    app.use("/mcp", throttleSessionCreation);
+    app.use("/sse", sessionRateLimiter);
     // Health check
     app.get("/health", (_req, res) => {
         res.json({
@@ -441,6 +474,7 @@ async function main() {
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
             annotations: buildAnnotations(tool),
         }));
         res.json({
@@ -490,17 +524,14 @@ async function main() {
             await runWithClient(session.client, () => session.transport.handleRequest(req, res, req.body));
             return;
         }
-        // New session — must be an initialize request
-        if (!isInitializeRequest(req.body)) {
-            res.status(400).json({
-                error: "expected_initialize",
-                message: "First request to /mcp must be an MCP Initialize request.",
-            });
-            return;
-        }
-        // Auth — required on Initialize (supports both API keys and OAuth JWTs)
+        // 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",
@@ -510,14 +541,32 @@ async function main() {
         // 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({
+            const keyStatus = await validateApiKey(apiKey);
+            if (keyStatus === "invalid") {
+                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;
             }
+            // Fail closed for browser clients when validation is unavailable (APP-6).
+            if (keyStatus === "unknown" && isBrowserOrigin(req)) {
+                res.set("Retry-After", "5");
+                res.status(503).json({
+                    error: "validation_unavailable",
+                    message: "Could not verify your API key right now. Please retry shortly.",
+                });
+                return;
+            }
+        }
+        // New session — must be an initialize request
+        if (!isInitializeRequest(req.body)) {
+            res.status(400).json({
+                error: "expected_initialize",
+                message: "First request to /mcp must be an MCP Initialize request.",
+            });
+            return;
         }
         // Create per-session transport, server, and client
         const transport = new StreamableHTTPServerTransport({
@@ -617,14 +666,23 @@ async function main() {
         }
         // Validate API keys against the Go backend; JWTs validated downstream.
         if (apiKey) {
-            const valid = await validateApiKey(apiKey);
-            if (!valid) {
+            const keyStatus = await validateApiKey(apiKey);
+            if (keyStatus === "invalid") {
                 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;
             }
+            // Fail closed for browser clients when validation is unavailable (APP-6).
+            if (keyStatus === "unknown" && isBrowserOrigin(req)) {
+                res.set("Retry-After", "5");
+                res.status(503).json({
+                    error: "validation_unavailable",
+                    message: "Could not verify your API key right now. Please retry shortly.",
+                });
+                return;
+            }
         }
         const transport = new SSEServerTransport("/message", res);
         const sessionId = transport.sessionId;

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

@@ -20,6 +20,7 @@ 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";
@@ -160,6 +161,7 @@ registerTool({
         required: [],
         additionalProperties: false,
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
         title: "Interactive BaZi Four Pillars Explorer",
         readOnlyHint: true,

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

@@ -25,6 +25,7 @@ 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 BI_WHEEL_RESOURCE_URI = "ui://openephemeris/bi-wheel";
 export const BI_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
@@ -100,7 +101,7 @@ const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R",
 };
-function buildNatalBody(datetime, lat, lon, timezone) {
+function buildNatalBody(datetime, lat, lon, timezone, houseSystem = "placidus") {
     const body = {
         subject: {
             name: "MCP Request",
@@ -111,7 +112,7 @@ function buildNatalBody(datetime, lat, lon, timezone) {
             },
         },
         configuration: {
-            house_system: HOUSE_SYSTEM_MAP["placidus"],
+            house_system: HOUSE_SYSTEM_MAP[houseSystem] ?? HOUSE_SYSTEM_MAP["placidus"],
         },
     };
     if (timezone) {
@@ -275,19 +276,43 @@ export function computeCrossAspects(planets1, planets2) {
     return results.sort((a, b) => a.orb - b.orb).slice(0, 30);
 }
 // ── Planet normalisation ───────────────────────────────────────────────────────
+// Canonical underscore names accepted by the renderer.
 const CLASSICAL_PLANETS = new Set([
     "sun", "moon", "mercury", "venus", "mars",
     "jupiter", "saturn", "uranus", "neptune", "pluto",
     "chiron", "north_node", "south_node", "true_node", "asc", "mc",
 ]);
+/**
+ * Normalise the Go backend's verbose planet key (e.g. "North Node (Mean)")
+ * to the canonical lowercase underscore form the renderer expects.
+ */
+function canonicalizePlanetName(raw) {
+    const lower = raw.toLowerCase();
+    // Various node/chiron aliases the Go PlanetName() function emits.
+    // Keep mean vs true DISTINCT so the UI can offer a node toggle; collapsing
+    // both to "north_node" (the old behaviour) produced two overlapping ☊ glyphs.
+    if (lower === "north node (true)" || lower === "true node")
+        return "true_node";
+    if (lower === "north node (mean)" || lower === "mean node" || lower === "north node")
+        return "north_node";
+    if (lower === "south node (mean)" || lower === "south node (true)")
+        return "south_node";
+    if (lower === "mean apogee" || lower === "black moon lilith" || lower === "lilith (mean)" || lower === "lilith (true)")
+        return "lilith";
+    // Strip parenthetical qualifiers for any other bodies just in case
+    return lower.replace(/\s*\(.*?\)/g, "").replace(/\s+/g, "_");
+}
 function normalizePlanets(raw) {
     if (Array.isArray(raw))
         return raw;
     if (raw && typeof raw === "object" && !Array.isArray(raw)) {
         return Object.entries(raw)
-            .filter(([k]) => CLASSICAL_PLANETS.has(k.toLowerCase()))
+            .filter(([k]) => {
+            const canonical = canonicalizePlanetName(k);
+            return CLASSICAL_PLANETS.has(canonical);
+        })
             .map(([name, p]) => ({
-            name: name.toLowerCase(),
+            name: canonicalizePlanetName(name),
             longitude: (p.longitude ?? p.lon ?? 0),
             speed: (p.longitude_speed ?? p.speed),
             retrograde: Boolean(p.is_retrograde ?? p.retrograde),
@@ -309,14 +334,30 @@ function normalizeHouses(raw) {
     return [];
 }
 // ── Payload builder ────────────────────────────────────────────────────────────
+function extractAngles(data) {
+    const rawAngles = data.angles;
+    const rawHouseObj = data.houses;
+    const ascendant = rawAngles?.ascendant ??
+        data.ascendant ??
+        rawHouseObj?.cusps?.[0] ??
+        0;
+    const midheaven = rawAngles?.midheaven ??
+        data.midheaven ??
+        rawHouseObj?.cusps?.[9] ??
+        0;
+    return { ascendant, midheaven };
+}
 function buildBiWheelPayload(innerData, outerData, mode, params1, params2) {
     const innerPlanets = normalizePlanets(innerData.planets);
     const outerPlanets = normalizePlanets(outerData.planets);
     const innerHouses = normalizeHouses(innerData.houses);
     const outerHouses = normalizeHouses(outerData.houses);
     const crossAspects = computeCrossAspects(innerPlanets, outerPlanets);
+    const { ascendant, midheaven } = extractAngles(innerData);
     return {
         mode,
+        ascendant,
+        midheaven,
         inner: innerPlanets,
         outer: outerPlanets,
         inner_houses: innerHouses,
@@ -413,6 +454,7 @@ registerTool({
         required: ["person1_datetime", "person2_datetime",
             "person1_latitude", "person1_longitude"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
         title: "Interactive Bi-Wheel Explorer",
         readOnlyHint: true,
@@ -453,11 +495,16 @@ registerTool({
         const payload = buildBiWheelPayload(innerData, outerData, mode, params1, params2);
         const bundleAvailable = Boolean(getBiWheelBundle());
         if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block. A URI-only
+            // `type: "resource"` block lacks the inline text/blob the base MCP schema
+            // requires and fails strict client validation. structuredContent
+            // preserves the full payload for hosts that don't render the iframe.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify({ ...payload, server_version: SERVER_VERSION }) },
                 ],
+                structuredContent: { ...payload, server_version: SERVER_VERSION },
                 _meta: {
                     "ui/resourceUri": BI_WHEEL_RESOURCE_URI,
                     ui: { resourceUri: BI_WHEEL_RESOURCE_URI },
@@ -487,14 +534,21 @@ registerTool({
             person2_timezone: { type: "string" },
             person2_name: { type: "string" },
             location: { type: "string" },
+            house_system: {
+                type: "string",
+                enum: Object.keys(HOUSE_SYSTEM_MAP),
+                description: "House system for the inner (natal) wheel. Defaults to placidus.",
+            },
         },
         required: ["mode", "person1_datetime", "person1_latitude", "person1_longitude", "person2_datetime"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Recalculate Bi-Wheel", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
         const mode = args.mode ?? "synastry";
+        const houseSystem = args.house_system ?? "placidus";
         const dt1 = String(args.person1_datetime);
         const lat1 = args.person1_latitude;
         const lon1 = args.person1_longitude;
@@ -506,14 +560,14 @@ registerTool({
         const loc1 = String(args.person1_name ?? args.location ?? `${lat1 ?? "?"},${lon1 ?? "?"}`);
         const loc2 = MODE_META[mode].outerLabel(dt2, args.person2_name);
         const [innerData, outerData] = await Promise.all([
-            client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1)),
+            client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1, houseSystem)),
             fetchOuterChart(client, mode, dt1, lat1, lon1, tz1, dt2, lat2, lon2, tz2),
         ]);
         const params1 = { datetime: dt1, timezone: tz1 ?? null, latitude: lat1 ?? null, longitude: lon1 ?? null, location: loc1 };
         const params2 = { datetime: dt2, timezone: tz2 ?? null, latitude: lat2 ?? null, longitude: lon2 ?? null, location: loc2 };
         const payload = buildBiWheelPayload(innerData, outerData, mode, params1, params2);
         return {
-            content: [{ type: "text", text: JSON.stringify({ ...payload, server_version: SERVER_VERSION }) }],
+            content: [{ type: "text", text: JSON.stringify({ ...payload, house_system: houseSystem, server_version: SERVER_VERSION }) }],
         };
     },
 });
@@ -537,6 +591,7 @@ registerTool({
         },
         required: ["planet1", "planet2", "aspect_type"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Cross-Aspect Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -575,6 +630,7 @@ registerTool({
         },
         required: ["planet", "wheel", "longitude"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Bi-Wheel Planet Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -775,6 +831,7 @@ registerTool({
         },
         required: ["house_number"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Bi-Wheel House Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -834,6 +891,7 @@ registerTool({
         },
         required: ["mode"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Bi-Wheel Synopsis", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app", "model"] } },
     handler: async (args) => {