@openephemeris/mcp-server 3.13.10 → 3.15.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,45 @@ 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, theme = "dark") {
+    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.
+        //
+        // style=light|dark drives the Go renderer's palette. The endpoint defaults
+        // to "light" when style is omitted, which mismatches dark MCP hosts — so we
+        // always pass an explicit theme (default "dark" to match the app shell; the
+        // iframe re-fetches with the host-detected theme on load / theme change).
+        const resp = await client.post(`/visualization/bodygraph?format=svg&size=800&style=${theme}`, 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 +389,7 @@ registerTool({
         },
         required: ["datetime"],
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
         title: "Interactive Human Design Bodygraph Explorer",
         readOnlyHint: true,
@@ -376,9 +417,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,14 +439,20 @@ registerTool({
             latitude: lat ?? null,
             longitude: lon ?? null,
         });
+        if (svg)
+            modelPayload._svg = svg;
         const summary = buildHdSummary(modelPayload, location);
-        const bundleAvailable = Boolean(getBodygraphBundle());
         if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block. A URI-only
+            // `type: "resource"` block lacks the inline text/blob the base MCP schema
+            // requires and fails strict client validation. structuredContent carries
+            // the data for non-rendering hosts.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) },
                 ],
+                structuredContent: { ...modelPayload, server_version: SERVER_VERSION },
                 _meta: {
                     "ui/resourceUri": BODYGRAPH_RESOURCE_URI,
                     ui: { resourceUri: BODYGRAPH_RESOURCE_URI },
@@ -422,9 +478,15 @@ registerTool({
                 type: "string",
                 description: "IANA timezone name (e.g. 'America/New_York') for accurate UTC conversion.",
             },
+            theme: {
+                type: "string",
+                enum: ["light", "dark"],
+                description: "Render palette for the bodygraph SVG. Mirrors the MCP host's light/dark color scheme.",
+            },
         },
         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) => {
@@ -434,6 +496,7 @@ registerTool({
         const datetime = localToUtcIso(String(args.datetime), timezone);
         const lat = args.latitude;
         const lon = args.longitude;
+        const theme = args.theme === "light" ? "light" : "dark";
         const body = {
             birth_datetime_utc: datetime,
         };
@@ -441,9 +504,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, theme),
+        ]);
         const chart = chartData.chart ?? chartData;
         const modelPayload = buildHdModelPayload(chart, {
             datetime,
@@ -452,6 +519,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 +547,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 +605,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 +660,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 +806,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 +920,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 +1004,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 +1073,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,14 +196,20 @@ registerTool({
             latitude: lat ?? null,
             longitude: lon ?? null,
             location: args.location ?? null,
-        }, houseSystem);
+        }, houseSystem, undefined, requestedBodies);
         const bundleAvailable = Boolean(getChartWheelBundle());
         if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block. A URI-only
+            // `type: "resource"` block lacks the inline text/blob the base MCP schema
+            // requires and fails strict client validation. Keep `structuredContent`
+            // so non-rendering hosts still get the data, and a text summary so chat
+            // transcripts read coherently.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) },
                 ],
+                structuredContent: { ...modelPayload, server_version: SERVER_VERSION },
                 _meta: {
                     "ui/resourceUri": CHART_WHEEL_RESOURCE_URI,
                     ui: { resourceUri: CHART_WHEEL_RESOURCE_URI },
@@ -216,6 +243,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 +278,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 +314,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 +363,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) => {
@@ -389,8 +420,33 @@ function zodSignFromLon(lon) {
 const CLASSICAL_PLANETS = new Set([
     "sun", "moon", "mercury", "venus", "mars",
     "jupiter", "saturn", "uranus", "neptune", "pluto",
-    "chiron", "north_node", "south_node", "true_node", "asc", "mc",
+    // Nodes use space form to match the renderer's glyph table (chart-renderer.ts).
+    "chiron", "north node", "south node", "true node", "asc", "mc",
+]);
+/**
+ * Canonicalise the Go backend's verbose node keys ("North Node (Mean)" /
+ * "North Node (True)") to the space-form names the renderer expects, keeping
+ * mean vs true DISTINCT. Without this the natal wheel dropped the nodes entirely
+ * (the raw key never matched the classical-planet set). All other body names are
+ * returned lowercased and otherwise unchanged.
+ */
+function canonicalizeBodyName(raw) {
+    const lower = raw.toLowerCase().trim();
+    if (lower === "north node (true)" || lower === "true node")
+        return "true node";
+    if (lower === "north node (mean)" || lower === "mean node" || lower === "north node")
+        return "north node";
+    if (lower === "south node (mean)" || lower === "south node (true)" || lower === "south node")
+        return "south node";
+    return lower;
+}
+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 +478,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 +502,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,9 +510,20 @@ 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 = canonicalizeBodyName(k);
+            // 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 => canonicalizeBodyName(b) === key);
+            }
+            // Default: classical planets only
+            return CLASSICAL_PLANETS.has(key);
+        })
             .map(([name, p]) => ({
-            name: name.toLowerCase(),
+            name: canonicalizeBodyName(name),
             longitude: (p.longitude ?? p.lon ?? 0),
             latitude: (p.latitude ?? p.lat),
             speed: (p.longitude_speed ?? p.speed),

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

@@ -1,19 +1,37 @@
 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.",
+    description: "App-only tool for getting location autocomplete suggestions. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Optional bias params (country/region/near) improve ranking; a trailing \"City, ST\" qualifier in the query is also honored.",
     inputSchema: {
         type: "object",
         properties: {
             query: {
                 type: "string",
-                description: "Search query for location, e.g. 'Los Angeles'",
+                description: "Search query for location, e.g. 'Los Angeles' or 'Wakefield, MI'",
+            },
+            country: {
+                type: "string",
+                description: "Optional ISO 3166-1 alpha-2 country code (e.g. 'US') to bias ranking. Boost, not filter.",
+            },
+            region: {
+                type: "string",
+                description: "Optional admin1 (state/province) qualifier to bias ranking — full name ('Michigan'), ASCII name, or code ('MI'). Boost, not filter.",
+            },
+            admin1: {
+                type: "string",
+                description: "Alias for region (region wins if both supplied).",
+            },
+            near: {
+                type: "string",
+                description: "Optional 'lat,lon' proximity hint (e.g. '37.77,-122.42') to bias ranking toward nearby places.",
             },
         },
         required: ["query"],
         additionalProperties: false,
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     _meta: {
         ui: {
             visibility: ["app"],
@@ -21,9 +39,26 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["query"]);
-        return await getActiveClient().request("GET", "/location/autocomplete", {
-            params: { q: args.query },
-        });
+        // NB: the endpoint param is `query` (only /geocode/search reads `q`).
+        const params = { query: args.query };
+        for (const k of ["country", "region", "admin1", "near"]) {
+            if (args[k] != null && String(args[k]).trim() !== "")
+                params[k] = String(args[k]);
+        }
+        const raw = (await getActiveClient().request("GET", "/location/autocomplete", { params }));
+        // Map the API's snake_case response to the camelCase shape the app UI consumes.
+        const list = Array.isArray(raw?.suggestions) ? raw.suggestions : [];
+        const suggestions = list.map((s) => ({
+            displayName: s.display_name,
+            shortName: s.short_name,
+            region: s.region,
+            countryCode: s.country_code,
+            placeId: s.place_id,
+            latitude: s.latitude,
+            longitude: s.longitude,
+            timezone: s.timezone,
+        }));
+        return { suggestions };
     },
 });
 registerTool({
@@ -38,6 +73,7 @@ registerTool({
         required: ["latitude", "longitude"],
         additionalProperties: false,
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     _meta: {
         ui: {
             visibility: ["app"],

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

@@ -16,6 +16,7 @@ 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";
@@ -54,15 +55,26 @@ export function clearMoonPhaseBundleCache() {
 function buildMoonSummary(data) {
     const phase = data.phase;
     const voc = data.void_of_course;
-    const phaseName = String(phase?.phase_name ?? phase?.name ?? "Unknown");
-    const illumination = typeof phase?.illumination === "number" ? Math.round(phase.illumination * 100) : "?";
-    const moonSign = String(phase?.moon_sign ?? phase?.sign ?? "");
+    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)
@@ -107,6 +119,7 @@ registerTool({
         required: [],
         additionalProperties: false,
     },
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
         title: "Interactive Moon Phase Explorer",
         readOnlyHint: true,
@@ -129,38 +142,79 @@ registerTool({
             params.latitude = args.latitude;
         if (args.longitude != null)
             params.longitude = args.longitude;
-        // Fetch phase and VOC in parallel
-        const [phase, voc] = await Promise.allSettled([
+        // 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: phaseData?.phase_name ?? phaseData?.name ?? "Unknown",
-            illumination: phaseData?.illumination ?? 0,
-            age_days: phaseData?.age_days ?? phaseData?.age ?? null,
+            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.
-                // Never use illumination alone — it's identical for mirror-symmetric waxing/waning phases.
-                (typeof phaseData?.elongation === "number"
-                    ? phaseData.elongation < 180
-                    : typeof phaseData?.age_days === "number"
-                        ? phaseData.age_days < 14.75
+                (typeof phaseData?.phase_angle === "number"
+                    ? phaseData.phase_angle < 180
+                    : typeof ageDays === "number"
+                        ? ageDays < 14.75
                         : true), // safe default: assume waxing
-            moon_sign: phaseData?.moon_sign ?? phaseData?.sign ?? "",
-            moon_longitude: phaseData?.moon_longitude ?? phaseData?.longitude ?? null,
-            sun_longitude: phaseData?.sun_longitude ?? null,
-            elongation: phaseData?.elongation ?? null,
-            moon_latitude: phaseData?.moon_latitude ?? null,
-            moon_distance_km: phaseData?.moon_distance_km ?? phaseData?.distance_km ?? null,
-            next_new_moon: phaseData?.next_new_moon ?? null,
-            next_full_moon: phaseData?.next_full_moon ?? null,
+            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,
@@ -173,11 +227,17 @@ registerTool({
         const summary = buildMoonSummary(mergedData);
         const bundleAvailable = Boolean(getMoonPhaseBundle());
         if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block. An embedded
+            // `type: "resource"` block must carry inline text/blob per the base MCP
+            // schema, so a URI-only reference fails strict client validation; the
+            // _meta keys below are what the host uses to render the iframe.
+            // structuredContent carries the data payload for non-rendering hosts.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify(uiPayload) },
                 ],
+                structuredContent: uiPayload,
                 _meta: {
                     "ui/resourceUri": MOON_PHASE_RESOURCE_URI,
                     ui: { resourceUri: MOON_PHASE_RESOURCE_URI },