@openephemeris/mcp-server 3.13.10 → 3.14.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";
@@ -232,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"],
+                        },
+                    },
+                }
                 : {}),
         })),
     }));
@@ -264,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,
             };
         }
     });
@@ -304,14 +312,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 +321,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 +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 }] };
         }
-        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 +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;
         }
@@ -417,7 +411,13 @@ 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));
@@ -441,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({
@@ -490,17 +491,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",
@@ -512,13 +510,22 @@ async function main() {
         if (apiKey) {
             const valid = await validateApiKey(apiKey);
             if (!valid) {
-                res.status(403).json({
+                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({
+                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({
             sessionIdGenerator: randomUUID,

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,39 @@ 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
+    if (lower === "north node (mean)" || lower === "north node (true)" || lower === "mean node" || lower === "true 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 +330,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 +450,7 @@ registerTool({
         required: ["person1_datetime", "person2_datetime",
             "person1_latitude", "person1_longitude"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
         title: "Interactive Bi-Wheel Explorer",
         readOnlyHint: true,
@@ -487,14 +525,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 +551,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 +582,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 +621,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 +822,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 +882,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) => {

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

@@ -19,6 +19,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 BODYGRAPH_RESOURCE_URI = "ui://openephemeris/bodygraph";
 export const BODYGRAPH_MIME_TYPE = "text/html;profile=mcp-app";
@@ -65,6 +66,40 @@ function ensureTimezone(dt) {
         return dt;
     return dt + "Z";
 }
+/**
+ * Fetch the canonical bodygraph SVG from the Go renderer.
+ *
+ * The Go engine is the source of truth for bodygraph visuals (Phase 4 of the
+ * renderer unification). This SVG is inlined directly into the iframe and
+ * bound to interaction handlers via its data-* attributes (data-center,
+ * data-gate, data-channel, data-hanging, data-highlighted, etc.).
+ *
+ * Returns null on failure so the caller can fall back to the legacy client-side
+ * renderer in bodygraph-renderer.ts. Non-fatal: a missing SVG should never
+ * block the tool result.
+ */
+async function fetchGoBodygraphSVG(body) {
+    try {
+        const client = getActiveClient();
+        // /visualization/bodygraph is registered as binary in BINARY_ENDPOINT_PREFIXES.
+        // The client wraps it as { content_type, encoding: "base64", data_base64 } —
+        // we decode back to UTF-8 SVG text for inlining.
+        const resp = await client.post("/visualization/bodygraph?format=svg&size=800", body);
+        if (typeof resp === "string")
+            return resp;
+        if (resp && typeof resp === "object") {
+            const r = resp;
+            if (typeof r.data_base64 === "string") {
+                return Buffer.from(r.data_base64, "base64").toString("utf-8");
+            }
+        }
+        return null;
+    }
+    catch (err) {
+        console.warn("[bodygraph] Go SVG fetch failed, will fall back to client render:", err);
+        return null;
+    }
+}
 /**
  * Convert a local datetime string (no offset) to a UTC ISO 8601 string.
  * Uses the IANA timezone to compute the correct UTC offset.
@@ -349,6 +384,7 @@ registerTool({
         },
         required: ["datetime"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
         title: "Interactive Human Design Bodygraph Explorer",
         readOnlyHint: true,
@@ -376,9 +412,18 @@ registerTool({
             body.latitude = lat;
         if (lon != null)
             body.longitude = lon;
-        const chartData = await client.request("POST", "/human-design/chart", {
-            data: body,
-        });
+        const bundleAvailable = Boolean(getBodygraphBundle());
+        // Fetch chart data and Go-rendered SVG in parallel. SVG only fetched when
+        // the iframe bundle is available (text-fallback hosts have no use for it,
+        // and the visualization endpoint costs a credit reservation).
+        const [chartData, svg] = await Promise.all([
+            client.request("POST", "/human-design/chart", {
+                data: body,
+            }),
+            bundleAvailable
+                ? fetchGoBodygraphSVG(body)
+                : Promise.resolve(null),
+        ]);
         // API returns { chart: {...}, metadata: {...} } — unwrap the inner chart object
         const chart = chartData.chart ?? chartData;
         // Build payload once — summary and model data both derive from the same object
@@ -389,8 +434,9 @@ registerTool({
             latitude: lat ?? null,
             longitude: lon ?? null,
         });
+        if (svg)
+            modelPayload._svg = svg;
         const summary = buildHdSummary(modelPayload, location);
-        const bundleAvailable = Boolean(getBodygraphBundle());
         if (bundleAvailable) {
             return {
                 content: [
@@ -425,6 +471,7 @@ registerTool({
         },
         required: ["datetime"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Recalculate Bodygraph", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -441,9 +488,13 @@ registerTool({
             body.latitude = lat;
         if (lon != null)
             body.longitude = lon;
-        const chartData = await client.request("POST", "/human-design/chart", {
-            data: body,
-        });
+        // Recalculate is iframe-only (visibility: ["app"]) — always co-fetch the SVG.
+        const [chartData, svg] = await Promise.all([
+            client.request("POST", "/human-design/chart", {
+                data: body,
+            }),
+            fetchGoBodygraphSVG(body),
+        ]);
         const chart = chartData.chart ?? chartData;
         const modelPayload = buildHdModelPayload(chart, {
             datetime,
@@ -452,6 +503,8 @@ registerTool({
             latitude: lat ?? null,
             longitude: lon ?? null,
         });
+        if (svg)
+            modelPayload._svg = svg;
         return {
             content: [{ type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) }],
         };
@@ -478,6 +531,7 @@ registerTool({
         },
         required: ["center", "defined"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Center Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -535,6 +589,7 @@ registerTool({
         },
         required: ["gate"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Gate Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -589,6 +644,7 @@ registerTool({
         },
         required: ["channel"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Channel Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -734,7 +790,7 @@ const HD_GATE_DATA = {
     38: { name: "The Fighter", hexagram: "Hex 38 — Opposition", keynote: "Struggle in the search for purpose", gift: "Perseverance — fighting for what is meaningful", shadow: "Struggle — fighting against everything without purpose", circuit: "Individual (Knowing)" },
     39: { name: "Provocation", hexagram: "Hex 39 — Obstruction", keynote: "Freeing the spirit through provocation", gift: "Dynamism — provocateur that liberates", shadow: "Provocation — stirring trouble unconsciously", circuit: "Individual (Knowing)" },
     40: { name: "Aloneness", hexagram: "Hex 40 — Deliverance", keynote: "The demand for aloneness as restoration", gift: "Resolve — willpower renewed in solitude", shadow: "Exhaustion — depleted by giving without replenishment", circuit: "Tribal (Ego)" },
-    41: { name: "Contraction", hexagram: "Hex 41 — Decrease", keynote: "The beginning of all experience — fantasy and desire", gift: "Fantasy — imagination that seeds new experience", shadow: "Fantasy misused — escapism", circuit: "Collective (Abstract)" },
+    41: { name: "Contraction", hexagram: "Hex 41 — Decrease", keynote: "The beginning of all experience — fantasy and desire", gift: "Fantasy — imagination that seeds new experience", shadow: "Escapism — escapism", circuit: "Collective (Abstract)" },
     42: { name: "Growth", hexagram: "Hex 42 — Increase", keynote: "The ability to perpetuate and complete growth cycles", gift: "Detachment — completing cycles with grace", shadow: "Incompletion — abandoning cycles before they end", circuit: "Collective (Abstract)" },
     43: { name: "Insight", hexagram: "Hex 43 — Breakthrough", keynote: "Breakthrough from within", gift: "Insight — inner knowing that arrives as genius", shadow: "Deafness — genius unrecognised or unheard", circuit: "Individual (Knowing)" },
     44: { name: "Alertness", hexagram: "Hex 44 — Coming to Meet", keynote: "Instinctive memory and pattern recognition", gift: "Teamwork — bringing the right people together", shadow: "Interference — driven by karmic patterns from the past", circuit: "Tribal (Defence)" },
@@ -848,8 +904,8 @@ const HD_PLANET_HD_THEMES = {
             "to act before the mind has a chance to deliberate. This energy can surprise even yourself.",
     },
     Jupiter: {
-        conscious: "**Jupiter** represents the law of your Personality — the karmic gifts and the areas of life where " +
-            "higher wisdom, abundance, and justice flow. It shows where and how you expand beyond the self-limiting " +
+        conscious: "**Jupiter** represents the law of your Personality — the karmic gifts and the principled framework through which you expand beyond " +
+            "higher wisdom and justice flow. It shows where you move beyond the self-limiting " +
             "patterns of your conditioning.",
         unconscious: "**Design Jupiter** shows the unconscious grace embedded in your design — the karmic correction " +
             "your body naturally applies when you are living true to your nature.",
@@ -932,6 +988,7 @@ registerTool({
         },
         required: ["planet", "column"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Planet Sidebar Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -1000,6 +1057,7 @@ registerTool({
         },
         required: ["variable", "direction"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Variable Arrow Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {