@openephemeris/mcp-server 4.17.0 → 4.19.0

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

@@ -12,9 +12,12 @@
  * overlay SVG is returned inline by /human-design/transit-chart and
  * /human-design/composite (include_visual) rather than a separate render call.
  *
- * The bodygraph is rendered client-side from structured JSON — no SVG endpoint
- * is called, keeping latency at zero and the architecture consistent with
- * the chart-wheel-app approach.
+ * The bodygraph picture is the Go engine's SVG, rendered server-side
+ * (fetchGoBodygraphSVG, in parallel with the chart call; overlays inline as
+ * above) and returned as `_svg`.
+ * The iframe inlines that SVG and binds interactivity to its data-* attributes
+ * (packages/widget-ui/bodygraph/src/wire-go-svg.ts); it does not draw the
+ * graph itself.
  *
  * Also exports resource helpers (getBodygraphBundle, etc.) for use in
  * index.ts and server-sse.ts.
@@ -23,15 +26,17 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { registerTool, SERVER_VERSION } from "../index.js";
-import { getActiveClient } from "../../backend/client.js";
+import { UI_RESOURCE_MIME_TYPE, uiResourceUri } from "./ui-resource.js";
+import { getActiveClient, isBillingOrAuthError } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
+import { RENDER_TOKEN_PROPERTY, renderTokenFromSvg, renderTokenFromVisual, renderTokenHeaders, withoutRenderToken, } from "./_render-token.js";
 // ── Constants ─────────────────────────────────────────────────────────────
-export const BODYGRAPH_RESOURCE_URI = "ui://openephemeris/bodygraph";
+export const BODYGRAPH_RESOURCE_URI = uiResourceUri("bodygraph");
 // Appended to every model-visible HD tool description — trademark hygiene.
 const HD_DISCLAIMER = " Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.";
-export const BODYGRAPH_MIME_TYPE = "text/html;profile=mcp-app";
+export const BODYGRAPH_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 const here = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLE_PATHS = [
     path.resolve(here, "..", "..", "..", "dist", "ui", "bodygraph.html"),
@@ -67,7 +72,7 @@ export function clearBodygraphBundleCache() {
 function capitalize(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
 }
-async function fetchGoBodygraphSVG(body, theme = "dark", view) {
+async function fetchGoBodygraphSVG(body, theme = "dark", view, renderToken) {
     try {
         const client = getActiveClient();
         // /visualization/bodygraph is registered as binary in BINARY_ENDPOINT_PREFIXES.
@@ -83,13 +88,24 @@ async function fetchGoBodygraphSVG(body, theme = "dark", view) {
         // (handler_bodygraph.go) — only appended when the caller (the in-iframe
         // layout toggle) actually requests the mandala view.
         let qs = `format=svg&size=800&style=${theme}`;
+        // Planet columns stay ON (renderer default): they are the chart's
+        // activation list and are clickable in the iframe. The same variant serves
+        // inline AND fullscreen, so a display-mode switch never re-renders (the
+        // render-token waiver is 15 min / 12 uses, so a re-render is not always free).
         if (view?.layout)
             qs += `&layout=${encodeURIComponent(view.layout)}`;
         if (view?.rings !== undefined)
             qs += `&rings=${encodeURIComponent(view.rings)}`;
         if (view?.houseSystem)
             qs += `&house_system=${encodeURIComponent(view.houseSystem)}`;
-        const resp = await client.post(`/visualization/bodygraph?${qs}`, body);
+        // A re-render of a chart this account already paid for presents its render
+        // token; the API waives the charge only if it verifies for these inputs.
+        // The API returns the (new or echoed) token as data-oe-render-token on the
+        // root <svg> — read it back with renderTokenFromSvg.
+        const resp = await client.request("POST", `/visualization/bodygraph?${qs}`, {
+            data: body,
+            headers: renderTokenHeaders(renderToken),
+        });
         if (typeof resp === "string")
             return resp;
         if (resp && typeof resp === "object") {
@@ -101,6 +117,10 @@ async function fetchGoBodygraphSVG(body, theme = "dark", view) {
         return null;
     }
     catch (err) {
+        // Out of credits / signed out must reach the assistant with the credit-wall
+        // message and top-up link — never be papered over by the client render.
+        if (isBillingOrAuthError(err))
+            throw err;
         console.warn("[bodygraph] Go SVG fetch failed, will fall back to client render:", err);
         return null;
     }
@@ -413,6 +433,9 @@ registerTool({
         });
         if (svg)
             modelPayload._svg = svg;
+        const renderToken = renderTokenFromSvg(svg);
+        if (renderToken)
+            modelPayload._render_token = renderToken;
         const summary = buildHdSummary(modelPayload, location);
         if (bundleAvailable) {
             // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
@@ -468,6 +491,7 @@ registerTool({
                 type: "string",
                 description: "House system for the mandala house ring. Only used when layout=mandala and rings includes 'houses' with a birth location. Adds 1 credit when the house ring renders.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["datetime"],
     },
@@ -494,11 +518,15 @@ registerTool({
         if (lon != null)
             body.longitude = lon;
         // Recalculate is iframe-only (visibility: ["app"]) — always co-fetch the SVG.
+        // Both halves present the render token: a theme / layout flip of the chart
+        // already on screen is then free (the house ring's 1-credit surcharge still
+        // applies when it renders); new birth data is charged as a new chart.
         const [chartData, svg] = await Promise.all([
             client.request("POST", "/human-design/chart", {
                 data: body,
+                headers: renderTokenHeaders(args.render_token),
             }),
-            fetchGoBodygraphSVG(body, theme, { layout, rings, houseSystem }),
+            fetchGoBodygraphSVG(body, theme, { layout, rings, houseSystem }, args.render_token),
         ]);
         const chart = chartData.chart ?? chartData;
         const modelPayload = buildHdModelPayload(chart, {
@@ -510,6 +538,11 @@ registerTool({
         });
         if (svg)
             modelPayload._svg = svg;
+        // The API echoes the presented token on a waived re-render, or mints a new
+        // one when this was charged as a new chart (e.g. edited birth data).
+        const renderToken = renderTokenFromSvg(svg);
+        if (renderToken)
+            modelPayload._render_token = renderToken;
         return {
             content: [{ type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) }],
         };
@@ -1176,9 +1209,8 @@ registerTool({
         "The Variable describes the four arrow directions attached to the Personality Sun/Earth " +
         "and Design Sun/Earth positions, encoding the PHS (Primary Health System) — the optimal conditions " +
         "for the body-mind to receive information and make decisions. " +
-        "Returns an interpretation of Digestion (right/left Personality Sun arrow), " +
-        "Perspective (right/left Personality Earth arrow), " +
-        "Environment (right/left Design Sun arrow), and Motivation (right/left Design Earth arrow). " +
+        "Returns an interpretation of Motivation (Personality Sun), Digestion (Design Sun), " +
+        "Perspective (Personality Node) and Environment (Design Node). " +
         "This tool is called automatically by the bodygraph UI; you do not need to call it directly.",
     inputSchema: {
         type: "object",
@@ -1224,13 +1256,13 @@ registerTool({
                     "and being drawn by appetite and desire rather than routine. " +
                     "Left Digestion types often thrive with more novelty, conversation, and engagement at the table — " +
                     "your body needs to be activated, not passively nourished.",
-                tones: {
-                    1: "Tone 1 — Consecutive: best with orderly, sequential eating — simple and unvaried meals in a fixed rhythm.",
-                    2: "Tone 2 — Alternating: eat a variety of foods but alternate types — not all mixed together.",
-                    3: "Tone 3 — Cyclic: allow the body to cycle through periods of different dietary focuses.",
-                    4: "Tone 4 — Calm: eat only when the emotional atmosphere is calm and undisturbed.",
-                    5: "Tone 5 — Open: eat in open spaces or with good air circulation; avoid enclosed or stagnant settings.",
-                    6: "Tone 6 — Closed: eat in private, quiet, familiar environments — protected from public exposure.",
+                colors: {
+                    1: { left: "Appetite, Consecutive: orderly, one-at-a-time eating at regular times.", right: "Appetite, Alternating: grazing and switching between kinds of food across the day." },
+                    2: { left: "Taste, Open: sampling first; a bite tells the body what fits today.", right: "Taste, Closed: knowing what fits by sight or smell, without needing to try it." },
+                    3: { left: "Thirst, Hot: warm food, warm drinks, warm settings.", right: "Thirst, Cold: cool food, cool drinks, calm and cool settings." },
+                    4: { left: "Touch, Calm: eating in a quiet, settled atmosphere, often alone.", right: "Touch, Nervous: eating with some activity or buzz around." },
+                    5: { left: "Sound, High: eating with conversation, music or background sound.", right: "Sound, Low: eating in quiet." },
+                    6: { left: "Light, Direct: eating in daylight, earlier in the day.", right: "Light, Indirect: eating in softer light or later in the day." },
                 },
             },
             perspective: {
@@ -1251,13 +1283,13 @@ registerTool({
                     "stimulating environments. This is an Active environment variable: you are designed to encounter " +
                     "variety, new places, and fresh stimulation. Being too long in the same environment can lead to " +
                     "stagnation, restlessness, or decreased vitality.",
-                tones: {
-                    1: "Tone 1 — Caves: you do best in enclosed, cozy, cave-like environments with shelter overhead.",
-                    2: "Tone 2 — Markets: you thrive in places of exchange and activity — social, commercial, varied.",
-                    3: "Tone 3 — Kitchens: hearth-centered environments — where nourishment and community gather.",
-                    4: "Tone 4 — Mountains: elevated, expansive, airy environments with altitude and horizon.",
-                    5: "Tone 5 — Valleys: sheltered, low, protected geographies — river valleys, low land, sheltered bays.",
-                    6: "Tone 6 — Shores: boundary environments — coast, lakeside, edge-of-land — where elements meet.",
+                colors: {
+                    1: { left: "Caves, Exclusive: enclosed, protected spaces with few people.", right: "Caves, Blending: sheltered spaces shared with a trusted group." },
+                    2: { left: "Markets, Internal: places of exchange where you have a clear role inside.", right: "Markets, External: open places of exchange you move through." },
+                    3: { left: "Kitchens, Wet: hearth and gathering places with moisture and life.", right: "Kitchens, Dry: hearth and gathering places that are dry and warm." },
+                    4: { left: "Mountains, Active: high, open ground with movement.", right: "Mountains, Passive: high, open ground to rest in and overlook." },
+                    5: { left: "Valleys, Narrow: sheltered low ground with a close view.", right: "Valleys, Wide: sheltered low ground with a wide view." },
+                    6: { left: "Shores, Natural: edges where land meets water, in nature.", right: "Shores, Artificial: edges and thresholds in built places." },
                 },
             },
             motivation: {
@@ -1267,13 +1299,13 @@ registerTool({
                 left: "**Left Motivation** (Active) \u2014 Your decision-making is best guided by active, intentional pursuit " +
                     "of what aligns with your values and strategy. You are designed to initiate and drive toward what matters to you — " +
                     "though always filtered through your Authority to ensure the body’s wisdom is guiding the mind.",
-                tones: {
-                    1: "Tone 1 — Fear: the motivation to move away from what limits or threatens, turning fear into healthy caution.",
-                    2: "Tone 2 — Hope: the motivation toward a better, more expanded future possibility.",
-                    3: "Tone 3 — Desire: the motivation driven by genuine wanting and attraction.",
-                    4: "Tone 4 — Need: the motivation arising from a felt sense of lack or necessity.",
-                    5: "Tone 5 — Guilt: the motivation arising from responsibility to others and the tribe.",
-                    6: "Tone 6 — Innocence: the motivation of pure openness, not knowing, and beginner’s mind.",
+                colors: {
+                    1: { left: "Fear: the drive to understand the unknown and stay safe.", right: "Fear: the drive to understand the unknown and stay safe." },
+                    2: { left: "Hope: trust in a better possible outcome.", right: "Hope: trust in a better possible outcome." },
+                    3: { left: "Desire: the push to change or affect the world.", right: "Desire: the push to change or affect the world." },
+                    4: { left: "Need: identifying what is necessary.", right: "Need: identifying what is necessary." },
+                    5: { left: "Guilt: the drive to fix and improve.", right: "Guilt: the drive to fix and improve." },
+                    6: { left: "Innocence: acting without a personal agenda.", right: "Innocence: acting without a personal agenda." },
                 },
             },
         };
@@ -1284,11 +1316,8 @@ registerTool({
             };
         }
         const main = direction === "right" ? info.right : info.left;
-        const toneNote = tone != null && info.tones?.[tone]
-            ? `\n\n**Your Specific Tone (${tone}):** ${info.tones[tone]}`
-            : "";
-        const colorNote = color != null
-            ? `\n\n**Color ${color}** subtly modulates this Variable's expression — these nuances are covered in advanced PHS reading.`
+        const colorNote = color != null && info.colors?.[color]
+            ? `\n\n**Your Color ${color}${tone != null ? `, Tone ${tone}` : ""}:** ${info.colors[color][direction]}`
             : "";
         const label = `${capitalize(variable)} Arrow — ${capitalize(direction)} Variable`;
         const icon = variable === "digestion" ? "🔵" : variable === "perspective" ? "🟢" : variable === "environment" ? "⚪" : "🔴";
@@ -1296,7 +1325,7 @@ registerTool({
             content: [{
                     type: "text",
                     text: `**${label}** ${icon}\n\n` +
-                        main + toneNote + colorNote +
+                        main + colorNote +
                         "\n\n*The Variable is a refinement layer within the Primary Health System (PHS). " +
                         "It describes the optimal conditions for the body-brain to receive and process information correctly. " +
                         "Living according to your Variable is an advanced practice that supports deeper health, clarity, and cognitive accuracy.*",
@@ -1315,7 +1344,7 @@ registerTool({
         "(inline in Claude and ChatGPT; text summary elsewhere) highlighting the channels the transit " +
         "temporarily COMPLETES with the natal chart and any centers it newly defines, for now or a chosen " +
         "datetime. Birthplace may be a place name (`location`).\n\n" +
-        "CREDIT COST: 3 credits per call (+1 to resolve a place name).\n\n" +
+        "CREDIT COST: 5 credits per call (chart 3 + render 2; +1 per place name).\n\n" +
         "Do not use for the person's own natal bodygraph — use explore_human_design; for another person's " +
         "chart overlaid on theirs use explore_human_design_connection." +
         HD_DISCLAIMER,
@@ -1349,6 +1378,7 @@ registerTool({
                     "concentric ring set the natal chart uses. Set by the in-iframe layout toggle, never by " +
                     "the model.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["datetime"],
     },
@@ -1410,7 +1440,12 @@ registerTool({
             body.include_visual = true;
             body.visual_config = { theme, ...(layout ? { layout } : {}) };
         }
-        const resp = await client.request("POST", "/human-design/transit-chart", { data: body });
+        // The iframe's theme / layout refetch presents the token of the overlay it
+        // is showing; the API waives it only for the same account + inputs.
+        const resp = await client.request("POST", "/human-design/transit-chart", {
+            data: body,
+            headers: renderTokenHeaders(args.render_token),
+        });
         const transit = (resp?.transit ?? {});
         const completed = Array.isArray(transit.completed_channels) ? transit.completed_channels : [];
         const newCenters = Array.isArray(transit.newly_defined_centers) ? transit.newly_defined_centers : [];
@@ -1428,8 +1463,15 @@ registerTool({
             ...resp,
             _svg: svg,
             _theme: theme,
-            // Lets the iframe re-request this overlay in the host's theme.
-            _refetch: { tool: "explore_human_design_transit", args: { ...args } },
+            ...(renderTokenFromVisual(resp?.visual) ? { _render_token: renderTokenFromVisual(resp?.visual) } : {}),
+            // Lets the iframe re-request this overlay in the host's theme. The
+            // resolved coordinates/zone/name are pinned so the refetch neither
+            // re-geocodes (another credit) nor drifts to a different request body,
+            // which would no longer match the render token.
+            _refetch: {
+                tool: "explore_human_design_transit",
+                args: { ...withoutRenderToken(args), latitude: lat, longitude: lon, location, ...(timezone ? { timezone } : {}) },
+            },
             server_version: SERVER_VERSION,
         };
         if (bundleAvailable && svg) {
@@ -1453,7 +1495,7 @@ registerTool({
         "text summary elsewhere) with every connected channel classified by HD connection theory: " +
         "electromagnetic (attraction), companionship (sameness), dominance (one defines), compromise " +
         "(friction).\n\n" +
-        "CREDIT COST: 3 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call (composite 3 + render 2).\n\n" +
         "Do not use for one person's chart — use explore_human_design; for the sky's transit on one chart " +
         "use explore_human_design_transit; for Western compatibility use explore_bi_wheel." +
         HD_DISCLAIMER,
@@ -1498,6 +1540,7 @@ registerTool({
                     "concentric ring set the natal chart uses. Set by the in-iframe layout toggle, never by " +
                     "the model.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["person_a", "person_b"],
     },
@@ -1529,12 +1572,15 @@ registerTool({
                 throw new Error(`${label} requires either \`latitude\` + \`longitude\` or a resolvable \`location\` name. ` +
                     "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
             }
+            // Pin the resolved coordinates for the iframe's refetch (see _refetch).
+            pinned[label] = { ...(p ?? {}), latitude: lat, longitude: lon, ...(tz ? { timezone: tz } : {}) };
             return {
                 birth_datetime_utc: await localToUtcIsoHistorical(`${label}.datetime`, String(p?.datetime), tz, { latitude: lat, longitude: lon }, `${label}.timezone`),
                 latitude: lat,
                 longitude: lon,
             };
         };
+        const pinned = {};
         const body = {
             subject_1: await toSubject(args.person_a, "person_a"),
             subject_2: await toSubject(args.person_b, "person_b"),
@@ -1547,7 +1593,10 @@ registerTool({
             body.include_visual = true;
             body.visual_config = { theme, ...(layout ? { layout } : {}) };
         }
-        const resp = await client.request("POST", "/human-design/composite", { data: body });
+        const resp = await client.request("POST", "/human-design/composite", {
+            data: body,
+            headers: renderTokenHeaders(args.render_token),
+        });
         const connections = Array.isArray(resp?.connections) ? resp.connections : [];
         const svg = resp?.visual?.data;
         const byType = (t) => connections.filter((c) => c?.type === t).map((c) => c.id);
@@ -1566,7 +1615,13 @@ registerTool({
             ...resp,
             _svg: svg,
             _theme: theme,
-            _refetch: { tool: "explore_human_design_connection", args: { ...args } },
+            ...(renderTokenFromVisual(resp?.visual) ? { _render_token: renderTokenFromVisual(resp?.visual) } : {}),
+            // Resolved coordinates pinned so the refetch neither re-geocodes nor
+            // drifts from the request the render token was issued for.
+            _refetch: {
+                tool: "explore_human_design_connection",
+                args: { ...withoutRenderToken(args), person_a: pinned.person_a, person_b: pinned.person_b },
+            },
             server_version: SERVER_VERSION,
         };
         if (bundleAvailable && svg) {

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

@@ -15,7 +15,7 @@
  * Also exports resource helpers (getChartWheelBundle, etc.) for use in
  * index.ts and server-sse.ts.
  */
-export declare const CHART_WHEEL_RESOURCE_URI = "ui://openephemeris/chart-wheel";
+export declare const CHART_WHEEL_RESOURCE_URI: string;
 export declare const CHART_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
 /** Read the pre-built HTML bundle. Returns null if not yet built. */
 export declare function getChartWheelBundle(): string | null;

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

@@ -19,13 +19,14 @@ 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";
-import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, toDateTimeInputBody } from "../datetime.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────
-export const CHART_WHEEL_RESOURCE_URI = "ui://openephemeris/chart-wheel";
-export const CHART_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
+export const CHART_WHEEL_RESOURCE_URI = uiResourceUri("chart-wheel");
+export const CHART_WHEEL_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 // Bundle path: at runtime (compiled), __dirname = dist/tools/apps/
 //   so ../../../dist/ui/ = dist/ui/  ✓
 // In dev (tsx),            __dirname = src/tools/apps/
@@ -159,9 +160,10 @@ registerTool({
                 items: { type: "string" },
                 description: "Optional list of body names to include. " +
                     "Defaults to 13 classical bodies (Sun through Pluto + Chiron + Nodes). " +
-                    "Use 'all' as a single item to include every available body (Lilith, Ceres, Juno, Vesta, Pallas, Vertex, " +
+                    "Use 'all' as a single item to include every available body (the three Liliths — mean, true and interpolated — Ceres, Juno, Vesta, Pallas, Pholus, " +
                     "the 8 trans-Neptunian objects — eris, sedna, makemake, haumea, quaoar, orcus, ixion, varuna — and the " +
                     "8 Uranian/Hamburg-School points — cupido, hades, zeus, kronos, apollon, admetos, vulkanus, poseidon). " +
+                    "Lilith slugs: 'lilith' (mean), 'lilith_true', 'lilith_interpolated'. " +
                     "Example: ['sun','moon','lilith','sedna'].",
             },
         },
@@ -410,19 +412,40 @@ registerTool({
         const baseBody = buildNatalBody(datetime, lat, lon, houseSystem, args.timezone);
         let endpoint = "/ephemeris/natal-chart";
         let requestBody = baseBody;
+        // Where the chart sits in the reply: natal-chart returns it top-level,
+        // /ephemeris/progressed under `data`, the return endpoints under `chart`.
+        let chartKey = null;
+        const target = toDateTimeInputBody("target_datetime", String(args.target_datetime ?? datetime), args.timezone);
         if (chartType === "solar_return") {
+            // SolarReturnRequest is flat — birth_datetime at the top level, no `subject`.
             endpoint = "/predictive/returns/solar";
-            requestBody.configuration.target_datetime = { iso: args.target_datetime ?? datetime };
+            const subject = baseBody.subject;
+            requestBody = {
+                birth_datetime: toDateTimeInputBody("datetime", datetime, args.timezone),
+                birth_location: subject.birth_location,
+                target_datetime: target,
+                house_system: baseBody.configuration.house_system,
+            };
+            chartKey = "chart";
         }
         else if (chartType === "progressed") {
             // openapi.json exposes /ephemeris/progressed — /predictive/progressed
             // does not exist and 404'd every progressed recalculate in the iframe.
             endpoint = "/ephemeris/progressed";
-            requestBody.configuration.target_datetime = { iso: args.target_datetime ?? datetime };
-            requestBody.configuration.method = "secondary";
+            requestBody = {
+                subject: baseBody.subject,
+                configuration: { house_system: baseBody.configuration.house_system },
+                target_datetime: target,
+                progression_options: { method: "secondary" },
+            };
+            chartKey = "data";
         }
         // Fetch updated chart JSON only — chart renders client-side in the iframe
-        const chartData = await client.post(endpoint, requestBody);
+        const reply = await client.post(endpoint, requestBody);
+        const chartData = chartKey ? reply[chartKey] : reply;
+        if (!chartData || typeof chartData !== "object") {
+            throw new Error(`Unexpected ${chartType} response: no \`${chartKey}\` chart in the API reply.`);
+        }
         // Normalise through buildModelPayload so house-switch results use the same
         // format as the initial response.
         const payload = buildModelPayload(chartData, {
@@ -457,7 +480,10 @@ const CLASSICAL_PLANETS = new Set([
     "sun", "moon", "mercury", "venus", "mars",
     "jupiter", "saturn", "uranus", "neptune", "pluto",
     // Nodes use space form to match the renderer's glyph table (chart-renderer.ts).
-    "chiron", "north node", "south node", "true node", "asc", "mc",
+    "chiron", "asc", "mc",
+    // The four lunar nodes keep the API's own names (lowercased): Mean and True
+    // are different points and never share a name.
+    "north node (mean)", "north node (true)", "south node (mean)", "south node (true)",
 ]);
 /**
  * Canonicalise the Go backend's verbose node keys ("North Node (Mean)" /
@@ -469,25 +495,40 @@ const CLASSICAL_PLANETS = new Set([
 function canonicalizeBodyName(raw) {
     const lower = raw.toLowerCase().trim();
     if (lower === "north node (true)" || lower === "true node")
-        return "true node";
+        return "north node (true)";
     if (lower === "north node (mean)" || lower === "mean node" || lower === "north node")
-        return "north node";
-    if (lower === "south node (mean)" || lower === "south node (true)" || lower === "south node")
-        return "south node";
+        return "north node (mean)";
+    if (lower === "south node (true)" || lower === "true south node")
+        return "south node (true)";
+    if (lower === "south node (mean)" || lower === "south node")
+        return "south node (mean)";
+    // Lilith: three different points (mean apogee 12, osculating 13, interpolated
+    // 40), each kept under the API's own name — never merged into one "lilith".
+    if (lower === "lilith (true)" || lower === "lilith_true" || lower === "true_lilith" || lower === "osculating apogee")
+        return "lilith (true)";
+    if (lower === "lilith (interpolated)" || lower === "lilith_interpolated" || lower === "lilith_natural" || lower === "interpolated apogee")
+        return "lilith (interpolated)";
+    if (lower === "lilith (mean)" || lower === "lilith" || lower === "mean_lilith" || lower === "mean apogee" || lower === "black moon lilith")
+        return "lilith (mean)";
     return lower;
 }
 const EXTENDED_BODIES = new Set([
     // Slugs match the Go API's ephemerisIDForSlug (handler_wheel_resolver.go) so
-    // additional_objects entries actually resolve server-side.
-    "mean_lilith", "lilith", "lilith_true",
+    // additional_objects entries actually resolve server-side. Only ephemeris
+    // bodies belong here: vertex / part_of_fortune are not additional_objects and
+    // made the API reject every bodies:["all"] request.
+    "lilith", "mean_lilith", "lilith_true", "lilith_interpolated",
     "ceres", "juno", "vesta", "pallas", "pholus",
-    "vertex", "part_of_fortune",
     // Trans-Neptunian objects (all 8 — #603 catalog expansion)
     "eris", "sedna", "makemake", "haumea", "quaoar", "orcus", "ixion", "varuna",
     // Uranian / Hamburg School hypothetical points (all 8 — #603 catalog expansion)
     "cupido", "hades", "zeus", "kronos", "apollon", "admetos", "vulkanus", "poseidon",
 ]);
-const ALL_KNOWN_BODIES = new Set([...CLASSICAL_PLANETS, ...EXTENDED_BODIES]);
+// Names as they come back from the API (canonicalised), for display filtering.
+const ALL_KNOWN_BODIES = new Set([
+    ...CLASSICAL_PLANETS, ...EXTENDED_BODIES,
+    "lilith (mean)", "lilith (true)", "lilith (interpolated)",
+]);
 /**
  * Build a lean, SVG-free payload for Claude's text context.
  * Strips SVG, filters to classical planets only, and packages birth params.
@@ -617,7 +658,7 @@ function buildChartSummary(data, location, houseSystem) {
     const CLASSICAL_ORDER = [
         "sun", "moon", "mercury", "venus", "mars",
         "jupiter", "saturn", "uranus", "neptune", "pluto",
-        "chiron", "north_node", "south_node", "true_node", "asc", "mc",
+        "chiron", "north node (mean)", "north node (true)", "south node (mean)", "south node (true)", "asc", "mc",
     ];
     planetsArray.sort((a, b) => {
         const ai = CLASSICAL_ORDER.indexOf(a.name.toLowerCase());

package/dist/tools/apps/location-tools.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { getActiveClient } from "../../backend/client.js";
+import { getActiveClient, isBillingOrAuthError } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { TZDATA_AUTHORITATIVE_FROM_YEAR } from "../datetime-historical.js";
 import { isQualifiedForTopHit } from "./_location-resolver.js";
@@ -245,7 +245,11 @@ registerTool({
                     });
                 }
             }
-            catch {
+            catch (err) {
+                // The credit wall / auth / tier gate is not "server unavailable":
+                // surface it with its top-up link instead of a quiet estimate.
+                if (isBillingOrAuthError(err))
+                    throw err;
                 // Server path unavailable — the tzdata estimate stands, still
                 // labelled historical_estimate. Degrading to a labelled
                 // estimate is acceptable; failing the whole search is not.
@@ -349,7 +353,10 @@ registerTool({
                         };
                     }
                 }
-                catch {
+                catch (err) {
+                    // Credit wall / auth / tier gate: surface it, don't degrade.
+                    if (isBillingOrAuthError(err))
+                        throw err;
                     // Server path unavailable — fall through to the local
                     // tzdata estimate below, flagged as such.
                 }

package/dist/tools/apps/moon-phase-app.d.ts

@@ -11,7 +11,7 @@
  * Also exports resource helpers (getMoonPhaseBundle, etc.) for use in
  * index.ts and server-sse.ts.
  */
-export declare const MOON_PHASE_RESOURCE_URI = "ui://openephemeris/moon-phase";
+export declare const MOON_PHASE_RESOURCE_URI: string;
 export declare const MOON_PHASE_MIME_TYPE = "text/html;profile=mcp-app";
 /** Read the pre-built HTML bundle. Returns null if not yet built. */
 export declare function getMoonPhaseBundle(): string | null;

package/dist/tools/apps/moon-phase-app.js

@@ -15,13 +15,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { registerTool, validateCoordinates, SERVER_VERSION } from "../index.js";
-import { getActiveClient } from "../../backend/client.js";
+import { UI_RESOURCE_MIME_TYPE, uiResourceUri } from "./ui-resource.js";
+import { getActiveClient, rethrowBillingOrAuth } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { TIMEZONE_PROPERTY } from "../datetime.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
-export const MOON_PHASE_RESOURCE_URI = "ui://openephemeris/moon-phase";
-export const MOON_PHASE_MIME_TYPE = "text/html;profile=mcp-app";
+export const MOON_PHASE_RESOURCE_URI = uiResourceUri("moon-phase");
+export const MOON_PHASE_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 const here = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLE_PATHS = [
     path.resolve(here, "..", "..", "..", "dist", "ui", "moon-phase.html"),
@@ -111,8 +112,16 @@ async function computeMoonData(args) {
         client.request("GET", "/ephemeris/moon/void-of-course", { params }),
         client.request("GET", "/ephemeris/moon/aspects", { params }),
     ]);
+    // A credit wall (402), expired auth (401) or tier gate (403) on ANY of the
+    // three calls must surface as the thrown error — with its top-up / sign-in
+    // link — not as an "Unknown ?%" dial that reads like real data. Only
+    // non-billing partial failures (VOC or aspects down) degrade gracefully.
+    rethrowBillingOrAuth([phase, voc, aspects]);
+    // Without the phase there is no dial to draw; fail rather than render "Unknown".
+    if (phase.status === "rejected")
+        throw phase.reason;
     const mergedData = {
-        phase: phase.status === "fulfilled" ? phase.value : { error: phase.reason?.message },
+        phase: phase.value,
         void_of_course: voc.status === "fulfilled" ? voc.value : { error: voc.reason?.message },
         aspects: aspects.status === "fulfilled" ? aspects.value : null,
     };

package/dist/tools/apps/transit-timeline-app.d.ts

@@ -15,7 +15,7 @@
  * Also exports resource helpers (getTransitTimelineBundle, etc.) for use in
  * index.ts and server-sse.ts.
  */
-export declare const TRANSIT_TIMELINE_RESOURCE_URI = "ui://openephemeris/transit-timeline";
+export declare const TRANSIT_TIMELINE_RESOURCE_URI: string;
 export declare const TRANSIT_TIMELINE_MIME_TYPE = "text/html;profile=mcp-app";
 /** Read the pre-built HTML bundle. Returns null if not yet built. */
 export declare function getTransitTimelineBundle(): string | null;

package/dist/tools/apps/transit-timeline-app.js

@@ -19,12 +19,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, 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";
 import { DATETIME_DESC, WINDOW_DATE_DESC, timezoneProperty, toDateTimeInputBody } from "../datetime.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
-export const TRANSIT_TIMELINE_RESOURCE_URI = "ui://openephemeris/transit-timeline";
-export const TRANSIT_TIMELINE_MIME_TYPE = "text/html;profile=mcp-app";
+export const TRANSIT_TIMELINE_RESOURCE_URI = uiResourceUri("transit-timeline");
+export const TRANSIT_TIMELINE_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 const here = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLE_PATHS = [
     path.resolve(here, "..", "..", "..", "dist", "ui", "transit-timeline.html"),
@@ -119,10 +120,9 @@ registerTool({
         "in-orb window (when the transit starts and ends, and which pass it is when a retrograde repeats it), " +
         "and transits already in orb at the start are listed with applying/separating.\n\n" +
         "ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 " +
-        "= sextile. EFFICIENCY: specify transiting_planets and natal_points to keep compute fast. DEFAULT " +
-        "natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. SEARCH RANGE LIMITS: " +
-        "Explorer/PayG → 1 year; Pro → 5 years; Startup → 10 years.\n\n" +
-        "CREDIT COST: 6 credits per call (natal chart + predictive transit search).\n\n" +
+        "= sextile. EFFICIENCY: specify transiting_planets and natal_points to keep compute fast. " +
+        "MAX SPAN and CREDIT COST as " +
+        "ephemeris_transits (6 for ≤1 year).\n\n" +
         "Do not use for transit data as JSON — use ephemeris_transits; for the sky today with no birth " +
         "data use electional_moment_analysis; to see one date's transits drawn around the natal wheel use " +
         "explore_bi_wheel (mode='transit').",