@openephemeris/mcp-server 3.13.9 → 3.14.0

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.
@@ -234,9 +269,44 @@ function buildHdModelPayload(data, birthParams) {
     const dGateList = Array.isArray(rawD) ? rawD : Object.values(rawD);
     const personality_gates = [...new Set(extractGateNums(pGateList))].sort((a, b) => a - b);
     const design_gates = [...new Set(extractGateNums(dGateList))].sort((a, b) => a - b);
-    // keep the maps
-    const personality_activations = !Array.isArray(rawP) && typeof rawP === 'object' ? rawP : undefined;
-    const design_activations = !Array.isArray(rawD) && typeof rawD === 'object' ? rawD : undefined;
+    // Convert activation arrays or maps → planet-keyed Record<string, ActivationSummary>
+    // The Go API returns arrays like [{ planet: "Sun", gate: 62, line: 1, color: 3, tone: 4 }].
+    // The renderer needs a map keyed by planet name: { "Sun": { gate, line, color, tone } }.
+    function toActivationMap(raw) {
+        if (!raw || (typeof raw !== 'object'))
+            return undefined;
+        // Already a planet-keyed map (non-array object)
+        if (!Array.isArray(raw)) {
+            const obj = raw;
+            // Make sure it looks like planet-keyed (values have 'gate' property)
+            const first = Object.values(obj)[0];
+            if (first && typeof first === 'object' && 'gate' in first) {
+                return obj;
+            }
+            return undefined;
+        }
+        // Array of activation objects — key by the 'planet' field
+        const arr = raw;
+        if (arr.length === 0)
+            return undefined;
+        const map = {};
+        for (const item of arr) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const planetName = String(item.planet ?? item.name ?? '');
+            if (!planetName)
+                continue;
+            map[planetName] = {
+                gate: Number(item.gate ?? 0),
+                line: Number(item.line ?? 0),
+                color: Number(item.color ?? 0),
+                tone: Number(item.tone ?? 0),
+            };
+        }
+        return Object.keys(map).length > 0 ? map : undefined;
+    }
+    const personality_activations = toActivationMap(rawP);
+    const design_activations = toActivationMap(rawD);
     return {
         type,
         profile,
@@ -314,6 +384,7 @@ registerTool({
         },
         required: ["datetime"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
         title: "Interactive Human Design Bodygraph Explorer",
         readOnlyHint: true,
@@ -341,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
@@ -354,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: [
@@ -390,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) => {
@@ -406,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,
@@ -417,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 }) }],
         };
@@ -443,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) => {
@@ -500,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) => {
@@ -554,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) => {
@@ -699,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)" },
@@ -813,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.",
@@ -897,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) => {
@@ -965,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) => {

package/dist/tools/apps/chart-wheel-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 CHART_WHEEL_RESOURCE_URI = "ui://openephemeris/chart-wheel";
 export const CHART_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
@@ -139,9 +140,18 @@ registerTool({
                 enum: ["placidus", "whole_sign", "equal", "koch", "regiomontanus", "campanus"],
                 description: "House system to use (default: placidus).",
             },
+            bodies: {
+                type: "array",
+                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, etc.). " +
+                    "Example: ['sun','moon','lilith','vertex'].",
+            },
         },
         required: ["datetime", "latitude", "longitude"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
         title: "Interactive Chart Wheel Explorer",
         readOnlyHint: true,
@@ -162,6 +172,17 @@ registerTool({
         const lat = args.latitude;
         const lon = args.longitude;
         const natalBody = buildNatalBody(datetime, lat, lon, houseSystem, args.timezone);
+        // Determine which bodies are requested
+        const requestedBodies = args.bodies;
+        const wantsAll = requestedBodies?.some(b => b.toLowerCase() === "all");
+        const wantsExtended = wantsAll || requestedBodies?.some(b => EXTENDED_BODIES.has(b.toLowerCase()));
+        // Enable extended body computation on the API side when needed
+        if (wantsExtended) {
+            const config = natalBody.configuration;
+            config.include_asteroids = true;
+            config.include_lilith = true;
+            config.include_chiron = true;
+        }
         // Fetch natal chart JSON. The chart is rendered client-side in the UI iframe,
         // so we do NOT call the /visualization/chart-wheel endpoint — that was the
         // source of the ~90 second blocking delay.
@@ -175,7 +196,7 @@ registerTool({
             latitude: lat ?? null,
             longitude: lon ?? null,
             location: args.location ?? null,
-        }, houseSystem);
+        }, houseSystem, undefined, requestedBodies);
         const bundleAvailable = Boolean(getChartWheelBundle());
         if (bundleAvailable) {
             return {
@@ -216,6 +237,7 @@ registerTool({
         },
         required: ["planet", "longitude"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Planet Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -250,6 +272,7 @@ registerTool({
         },
         required: ["house_number"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "House Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -285,6 +308,7 @@ registerTool({
         },
         required: ["planet1", "planet2"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Aspect Interpretation", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -333,6 +357,7 @@ registerTool({
         },
         required: ["datetime", "latitude", "longitude", "house_system"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Recalculate Chart", readOnlyHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
@@ -391,6 +416,13 @@ const CLASSICAL_PLANETS = new Set([
     "jupiter", "saturn", "uranus", "neptune", "pluto",
     "chiron", "north_node", "south_node", "true_node", "asc", "mc",
 ]);
+const EXTENDED_BODIES = new Set([
+    "mean_lilith", "lilith", "true_lilith",
+    "ceres", "juno", "vesta", "pallas", "pholus",
+    "vertex", "part_of_fortune",
+    "eris", "sedna",
+]);
+const ALL_KNOWN_BODIES = new Set([...CLASSICAL_PLANETS, ...EXTENDED_BODIES]);
 /**
  * Build a lean, SVG-free payload for Claude's text context.
  * Strips SVG, filters to classical planets only, and packages birth params.
@@ -422,7 +454,13 @@ function computeAspects(planets) {
                 diff = 360 - diff;
             for (const asp of ASPECTS) {
                 const orb = Math.abs(diff - asp.angle);
-                if (orb <= asp.orb) {
+                // Tighten orbs when one or both bodies are extended (asteroids, etc.)
+                const p1Extended = EXTENDED_BODIES.has(p1.name.toLowerCase());
+                const p2Extended = EXTENDED_BODIES.has(p2.name.toLowerCase());
+                const effectiveOrb = (p1Extended || p2Extended)
+                    ? Math.min(asp.orb * 0.5, 3) // half standard, capped at 3°
+                    : asp.orb;
+                if (orb <= effectiveOrb) {
                     // Applying: combined longitudinal speed closing the orb
                     const applying = ((p1.speed ?? 1) - (p2.speed ?? 0)) < 0 ? diff < asp.angle : diff > asp.angle;
                     results.push({
@@ -440,7 +478,7 @@ function computeAspects(planets) {
     }
     return results;
 }
-function buildModelPayload(chartData, birthParams, houseSystem, svgBase) {
+function buildModelPayload(chartData, birthParams, houseSystem, svgBase, bodyFilter) {
     // ── 1. Normalize planets: keyed object → typed PlanetData array ──────────
     // The natal API returns { sun: { longitude, sign_name, is_retrograde, ... }, moon: {...} }.
     // The chart wheel UI expects PlanetData[] with canonical field names.
@@ -448,7 +486,18 @@ function buildModelPayload(chartData, birthParams, houseSystem, svgBase) {
     let planetsArray = [];
     if (rawPlanets && typeof rawPlanets === "object" && !Array.isArray(rawPlanets)) {
         planetsArray = Object.entries(rawPlanets)
-            .filter(([k]) => CLASSICAL_PLANETS.has(k.toLowerCase()))
+            .filter(([k]) => {
+            const key = k.toLowerCase();
+            // If specific bodies were requested, use that filter
+            if (bodyFilter) {
+                const wantsAll = bodyFilter.some(b => b.toLowerCase() === "all");
+                if (wantsAll)
+                    return ALL_KNOWN_BODIES.has(key);
+                return bodyFilter.some(b => b.toLowerCase() === key);
+            }
+            // Default: classical planets only
+            return CLASSICAL_PLANETS.has(key);
+        })
             .map(([name, p]) => ({
             name: name.toLowerCase(),
             longitude: (p.longitude ?? p.lon ?? 0),

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

@@ -1,5 +1,6 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
+import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 registerTool({
     name: "location_search",
     description: "App-only tool for getting location autocomplete suggestions. Returns latitude, longitude, and IANA timezone.",
@@ -14,6 +15,7 @@ registerTool({
         required: ["query"],
         additionalProperties: false,
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     _meta: {
         ui: {
             visibility: ["app"],
@@ -38,6 +40,7 @@ registerTool({
         required: ["latitude", "longitude"],
         additionalProperties: false,
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     _meta: {
         ui: {
             visibility: ["app"],

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

@@ -0,0 +1,19 @@
+/**
+ * moon-phase-app.ts — MCP App tool registration for the Moon Phase Explorer.
+ *
+ * Registers 1 tool:
+ *   • explore_moon_phase — primary entry point, returns data + UI resource [model]
+ *
+ * The dial is rendered client-side from structured JSON. The tool calls the
+ * existing moon phase and VOC endpoints, merges the results, and returns them
+ * with a UI resource link so the iframe can render a circular phase dial.
+ *
+ * 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_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;
+/** Reset cache (useful in dev watch mode or tests). */
+export declare function clearMoonPhaseBundleCache(): void;

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

@@ -0,0 +1,244 @@
+/**
+ * moon-phase-app.ts — MCP App tool registration for the Moon Phase Explorer.
+ *
+ * Registers 1 tool:
+ *   • explore_moon_phase — primary entry point, returns data + UI resource [model]
+ *
+ * The dial is rendered client-side from structured JSON. The tool calls the
+ * existing moon phase and VOC endpoints, merges the results, and returns them
+ * with a UI resource link so the iframe can render a circular phase dial.
+ *
+ * Also exports resource helpers (getMoonPhaseBundle, etc.) for use in
+ * index.ts and server-sse.ts.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { registerTool, validateCoordinates, SERVER_VERSION } from "../index.js";
+import { getActiveClient } from "../../backend/client.js";
+import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+export const MOON_PHASE_RESOURCE_URI = "ui://openephemeris/moon-phase";
+export const MOON_PHASE_MIME_TYPE = "text/html;profile=mcp-app";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLE_PATHS = [
+    path.resolve(here, "..", "..", "..", "dist", "ui", "moon-phase.html"),
+];
+function findBundlePath() {
+    for (const p of BUNDLE_PATHS) {
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+let cachedBundle = null;
+/** Read the pre-built HTML bundle. Returns null if not yet built. */
+export function getMoonPhaseBundle() {
+    if (cachedBundle)
+        return cachedBundle;
+    const bundlePath = findBundlePath();
+    if (!bundlePath)
+        return null;
+    try {
+        cachedBundle = fs.readFileSync(bundlePath, "utf-8");
+        return cachedBundle;
+    }
+    catch {
+        return null;
+    }
+}
+/** Reset cache (useful in dev watch mode or tests). */
+export function clearMoonPhaseBundleCache() {
+    cachedBundle = null;
+}
+// ── Summary builder ──────────────────────────────────────────────────────────
+function buildMoonSummary(data) {
+    const phase = data.phase;
+    const voc = data.void_of_course;
+    const meta = (phase?.metadata ?? {});
+    const phaseName = String(phase?.phase_name ?? phase?.name ?? "Unknown").replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase());
+    const illumination = typeof phase?.illumination === "number" ? Math.round(phase.illumination) : "?";
+    const moonSign = String(meta?.moon_sign ?? phase?.moon_sign ?? phase?.sign ?? voc?.current_sign ?? "");
+    const isVoc = Boolean(voc?.is_void ?? voc?.is_void_of_course ?? false);
+    const speed = typeof meta?.longitude_speed === "number" ? meta.longitude_speed : null;
+    const daysToFull = typeof meta?.days_to_full === "number" ? meta.days_to_full :
+        typeof phase?.days_to_full === "number" ? phase.days_to_full : null;
+    let summary = "**Moon Phase** — " + phaseName + "\n\n" +
+        "Illumination: **" + illumination + "%**\n";
+    if (moonSign) {
+        summary += "Moon Sign: **" + moonSign + "**\n";
+    }
+    if (speed !== null) {
+        const tempo = speed > 14.5 ? "fast" : speed < 12.0 ? "slow" : "average";
+        summary += "Speed: **" + speed.toFixed(2) + "°/day** (" + tempo + ")\n";
+    }
+    if (daysToFull !== null) {
+        summary += "Full Moon in: **" + daysToFull.toFixed(1) + " days**\n";
+    }
+    if (isVoc) {
+        summary += "\n⚠️ **Void of Course** — The Moon is currently VOC.";
+        if (voc?.ends)
+            summary += " Ends at " + String(voc.ends) + ".";
+        if (voc?.next_sign)
+            summary += " Next sign: " + String(voc.next_sign) + ".";
+        summary += "\n";
+    }
+    summary += "\nClick cards on the dial for details and interpretation.";
+    return summary;
+}
+// ── Tool: explore_moon_phase ─────────────────────────────────────────────────
+registerTool({
+    name: "explore_moon_phase",
+    description: "Generate an interactive Moon Phase dial showing the current lunar illumination, " +
+        "phase name, zodiac sign, and void-of-course status as a beautiful circular visualization.\n\n" +
+        "Returns a visual dial with:\n" +
+        "  • SVG crescent Moon showing real-time illumination percentage\n" +
+        "  • Phase name and waxing/waning indicator\n" +
+        "  • Current Moon sign with degree\n" +
+        "  • Void-of-Course status with timing details\n" +
+        "  • Lunar age (days in the synodic cycle)\n" +
+        "  • Upcoming New Moon and Full Moon dates\n\n" +
+        "Use this for a rich, interactive lunar phase experience in MCP Apps-capable hosts (Claude Desktop). " +
+        "Falls back to a text summary in other hosts.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: "ISO 8601 datetime to query. If omitted, returns the current live moon phase (UTC now).",
+            },
+            latitude: {
+                type: "number",
+                description: "Observer latitude (optional, used for local void-of-course calculations).",
+            },
+            longitude: {
+                type: "number",
+                description: "Observer longitude (optional, used for local void-of-course calculations).",
+            },
+        },
+        required: [],
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: {
+        title: "Interactive Moon Phase Explorer",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    _meta: {
+        ui: {
+            resourceUri: MOON_PHASE_RESOURCE_URI,
+            visibility: ["model", "app"],
+        },
+    },
+    handler: async (args) => {
+        validateCoordinates(args, "latitude", "longitude");
+        const client = getActiveClient();
+        const params = {};
+        params.datetime = args.datetime ?? new Date().toISOString();
+        if (args.latitude != null)
+            params.latitude = args.latitude;
+        if (args.longitude != null)
+            params.longitude = args.longitude;
+        // Fetch phase, VOC, and moon aspects in parallel
+        const [phase, voc, aspects] = await Promise.allSettled([
+            client.request("GET", "/ephemeris/moon/phase", { params }),
+            client.request("GET", "/ephemeris/moon/void-of-course", { params }),
+            client.request("GET", "/ephemeris/moon/aspects", { params }),
+        ]);
+        const mergedData = {
+            phase: phase.status === "fulfilled" ? phase.value : { error: phase.reason?.message },
+            void_of_course: voc.status === "fulfilled" ? voc.value : { error: voc.reason?.message },
+            aspects: aspects.status === "fulfilled" ? aspects.value : null,
+        };
+        // Flatten for the UI — merge phase fields to top level
+        const phaseData = mergedData.phase;
+        const vocData = mergedData.void_of_course;
+        const aspectsData = mergedData.aspects;
+        // Extract enriched metadata fields from the GET response
+        const meta = (phaseData?.metadata ?? {});
+        const moonSign = String(meta?.moon_sign ?? phaseData?.moon_sign ?? phaseData?.sign ?? vocData?.current_sign ?? "");
+        const moonSpeedRaw = meta?.longitude_speed;
+        const moonSpeed = typeof moonSpeedRaw === "number" ? moonSpeedRaw : null;
+        const angularDiameter = typeof meta?.angular_diameter === "number" ? meta.angular_diameter : null;
+        const distanceKm = typeof meta?.moon_distance_km === "number" ? meta.moon_distance_km : null;
+        const moonLat = typeof meta?.moon_lat === "number" ? meta.moon_lat : null;
+        const ageDays = typeof meta?.age_days === "number" ? meta.age_days :
+            (typeof phaseData?.age_days === "number" ? phaseData.age_days : null);
+        // days_to_new / days_to_full can come as the union value or from the top-level field
+        const extractDays = (field) => {
+            if (typeof field === "number")
+                return field;
+            if (field && typeof field === "object") {
+                const v = Object.values(field)[0];
+                if (typeof v === "number")
+                    return v;
+            }
+            return null;
+        };
+        const daysToNew = extractDays(phaseData?.days_to_new);
+        const daysToFull = extractDays(phaseData?.days_to_full);
+        // Top 3 applying aspects by tightest orb
+        const rawAspects = (aspectsData?.aspects ?? aspectsData?.data ?? []);
+        const applyingAspects = Array.isArray(rawAspects)
+            ? rawAspects
+                .filter((a) => a.applying === true || a.type === "applying")
+                .sort((a, b) => Math.abs(a.orb ?? 99) - Math.abs(b.orb ?? 99))
+                .slice(0, 3)
+                .map((a) => ({
+                planet: a.planet ?? a.body ?? a.planet_name ?? "",
+                aspect: a.aspect ?? a.aspect_name ?? a.type_name ?? "",
+                orb: typeof a.orb === "number" ? Math.abs(a.orb) : null,
+            }))
+            : [];
+        const uiPayload = {
+            phase_name: String(phaseData?.phase_name ?? phaseData?.name ?? "Unknown").replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase()),
+            illumination: typeof phaseData?.illumination === "number" ? phaseData.illumination / 100.0 : 0,
+            phase_angle: typeof phaseData?.phase_angle === "number" ? phaseData.phase_angle : null,
+            age_days: ageDays,
+            days_to_new: daysToNew,
+            days_to_full: daysToFull,
+            waxing: phaseData?.waxing ??
+                // Fallback chain: elongation < 180° = waxing, else age_days < 14.75 = waxing.
+                (typeof phaseData?.phase_angle === "number"
+                    ? phaseData.phase_angle < 180
+                    : typeof ageDays === "number"
+                        ? ageDays < 14.75
+                        : true), // safe default: assume waxing
+            moon_sign: moonSign,
+            moon_longitude: meta?.moon_lon ?? phaseData?.moon_longitude ?? phaseData?.longitude ?? null,
+            moon_latitude: moonLat,
+            moon_distance_km: distanceKm,
+            angular_diameter: angularDiameter,
+            moon_speed: moonSpeed,
+            sun_longitude: meta?.sun_lon ?? phaseData?.sun_longitude ?? null,
+            applying_aspects: applyingAspects,
+            voc_status: {
+                is_void: Boolean(vocData?.is_void ?? vocData?.is_void_of_course ?? false),
+                started: vocData?.started ?? vocData?.start ?? null,
+                ends: vocData?.ends ?? vocData?.end ?? null,
+                next_sign: vocData?.next_sign ?? null,
+            },
+            datetime: params.datetime,
+            server_version: SERVER_VERSION,
+        };
+        const summary = buildMoonSummary(mergedData);
+        const bundleAvailable = Boolean(getMoonPhaseBundle());
+        if (bundleAvailable) {
+            return {
+                content: [
+                    { type: "text", text: summary },
+                    { type: "text", text: JSON.stringify(uiPayload) },
+                ],
+                _meta: {
+                    "ui/resourceUri": MOON_PHASE_RESOURCE_URI,
+                    ui: { resourceUri: MOON_PHASE_RESOURCE_URI },
+                },
+            };
+        }
+        // Fallback: text summary only
+        return { content: [{ type: "text", text: summary }] };
+    },
+});