@openephemeris/mcp-server 3.22.0 → 3.23.0

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

@@ -86,6 +86,106 @@ function buildMoonSummary(data) {
     summary += "\nClick cards on the dial for details and interpretation.";
     return summary;
 }
+// ── Shared payload builder ────────────────────────────────────────────────────
+/**
+ * Fetch phase + void-of-course + aspects for the given args and build the
+ * flattened UI payload and human summary. Shared by explore_moon_phase and
+ * moon_phase_recalculate so both return an identical structuredContent shape.
+ */
+async function computeMoonData(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);
+    return { summary, uiPayload };
+}
 // ── Tool: explore_moon_phase ─────────────────────────────────────────────────
 registerTool({
     name: "explore_moon_phase",
@@ -99,8 +199,8 @@ registerTool({
         "  • Lunar age (days in the synodic cycle)\n" +
         "  • Upcoming New Moon and Full Moon dates\n\n" +
         "CREDIT COST: 3 credits per call (phase + void-of-course + aspects, 1 each).\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.",
+        "Use this instead of ephemeris_moon_phase 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: {
@@ -135,97 +235,7 @@ registerTool({
         },
     },
     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 { summary, uiPayload } = await computeMoonData(args);
         const bundleAvailable = Boolean(getMoonPhaseBundle());
         if (bundleAvailable) {
             // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
@@ -249,3 +259,41 @@ registerTool({
         return { content: [{ type: "text", text: summary }] };
     },
 });
+// ── Tool: moon_phase_recalculate ─────────────────────────────────────────────
+// App-only. Fired by the Moon Phase iframe's date control to recompute the dial
+// for a chosen datetime. Mirrors bodygraph_recalculate: same endpoint set, same
+// structuredContent shape as explore_moon_phase, returned directly to the iframe
+// (ontoolresult does not fire for in-app tool calls).
+registerTool({
+    name: "moon_phase_recalculate",
+    description: "Recalculates the Moon Phase dial for a new datetime.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: "ISO 8601 datetime to query. If omitted, uses 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: "Recalculate Moon Phase", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: MOON_PHASE_RESOURCE_URI, visibility: ["app"] } },
+    handler: async (args) => {
+        const { summary, uiPayload } = await computeMoonData(args);
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: uiPayload,
+        };
+    },
+});

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

@@ -0,0 +1,20 @@
+/**
+ * transit-timeline-app.ts — MCP App tool registration for the Transit Timeline.
+ *
+ * Registers 1 tool:
+ *   • explore_transit_timeline — primary entry point, returns data + UI resource.
+ *
+ * The tool mirrors the `ephemeris_transits` plumbing: it computes the natal
+ * chart to extract real planetary longitudes, searches predictive transits
+ * against those targets, then flattens the (planet@target → hits) result map
+ * into a single chronological array the iframe renders as a vertical timeline.
+ *
+ * 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_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;
+/** Reset cache (useful in dev watch mode or tests). */
+export declare function clearTransitTimelineBundleCache(): void;

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

@@ -0,0 +1,302 @@
+/**
+ * transit-timeline-app.ts — MCP App tool registration for the Transit Timeline.
+ *
+ * Registers 1 tool:
+ *   • explore_transit_timeline — primary entry point, returns data + UI resource.
+ *
+ * The tool mirrors the `ephemeris_transits` plumbing: it computes the natal
+ * chart to extract real planetary longitudes, searches predictive transits
+ * against those targets, then flattens the (planet@target → hits) result map
+ * into a single chronological array the iframe renders as a vertical timeline.
+ *
+ * Also exports resource helpers (getTransitTimelineBundle, 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, validateRequired, SERVER_VERSION } from "../index.js";
+import { getActiveClient } from "../../backend/client.js";
+import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+export const TRANSIT_TIMELINE_RESOURCE_URI = "ui://openephemeris/transit-timeline";
+export const TRANSIT_TIMELINE_MIME_TYPE = "text/html;profile=mcp-app";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLE_PATHS = [
+    path.resolve(here, "..", "..", "..", "dist", "ui", "transit-timeline.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 getTransitTimelineBundle() {
+    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 clearTransitTimelineBundleCache() {
+    cachedBundle = null;
+}
+// ── Aspect labels ──────────────────────────────────────────────────────────────
+const ASPECT_LABELS = {
+    0: "conjunction", 60: "sextile", 90: "square", 120: "trine", 180: "opposition",
+};
+function aspectLabelFor(angle) {
+    return ASPECT_LABELS[angle] ?? angle + "°";
+}
+const CORE_BODIES_DEFAULT = new Set([
+    "sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn",
+]);
+function normDeg(d) {
+    return ((d % 360) + 360) % 360;
+}
+// ── Summary builder ──────────────────────────────────────────────────────────
+function buildSummary(transits, aspectLabel, win) {
+    if (transits.length === 0) {
+        return "**Transit Timeline** — no exact transit hits matched the search window and criteria.";
+    }
+    const planets = [...new Set(transits.map((t) => t.planet_name).filter(Boolean))];
+    const lines = transits.slice(0, 8).map((t) => {
+        const asp = t.aspect ?? aspectLabel;
+        const natal = t.natal_point ? " natal " + t.natal_point : "";
+        const when = new Date(t.date).toISOString().slice(0, 10);
+        return "  • " + when + " — " + t.planet_name + " " + asp + natal +
+            (t.zodiac_sign ? " (" + (t.zodiac_degree ?? 0) + "° " + t.zodiac_sign + ")" : "") +
+            (t.is_retrograde ? " ℞" : "");
+    });
+    let summary = "**Transit Timeline** — " + transits.length + (transits.length === 1 ? " event" : " events") +
+        " from " + win.start_date + " to " + win.end_date +
+        (planets.length ? " (" + planets.join(", ") + ")" : "") + "\n\n" +
+        lines.join("\n");
+    if (transits.length > 8)
+        summary += "\n  … and " + (transits.length - 8) + " more.";
+    summary += "\n\nClick any transit for details and interpretation.";
+    return summary;
+}
+// ── Tool: explore_transit_timeline ───────────────────────────────────────────
+registerTool({
+    name: "explore_transit_timeline",
+    description: "Generate an interactive Transit Timeline — a vertical, date-ordered list of " +
+        "upcoming transit hits (transiting planets forming a chosen aspect to natal " +
+        "chart positions) over a date range.\n\n" +
+        "Returns a visual timeline with:\n" +
+        "  • Exact crossing dates grouped by month\n" +
+        "  • Transiting planet glyph, the natal point it contacts, and the aspect\n" +
+        "  • Zodiac position of each crossing and retrograde markers\n" +
+        "  • Click any transit for a focused interpretation\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" +
+        "Use this for a rich, interactive transit-forecast experience in MCP Apps-capable hosts " +
+        "(Claude Desktop). Falls back to a text summary in other hosts.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            natal_datetime: { type: "string", description: "ISO 8601 birth datetime for the natal chart." },
+            natal_latitude: { type: "number", description: "Latitude of birth location in decimal degrees." },
+            natal_longitude: { type: "number", description: "Longitude of birth location in decimal degrees." },
+            start_date: { type: "string", description: "Start of the transit search window, ISO 8601 date or datetime (e.g. '2026-01-01')." },
+            end_date: { type: "string", description: "End of the transit search window, ISO 8601 date or datetime (e.g. '2026-12-31')." },
+            transiting_planets: {
+                type: "array", items: { type: "string" },
+                description: "Transiting planet IDs to search, e.g. ['saturn','jupiter','uranus','pluto','chiron']. Omit to search all outer planets.",
+            },
+            natal_points: {
+                type: "array", items: { type: "string" },
+                description: "Natal point IDs to target, e.g. ['sun','moon','asc','mc','saturn']. Omit for the 7 classical bodies.",
+            },
+            aspect_angle: {
+                type: "number",
+                description: "Aspect angle in degrees. 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile.",
+            },
+        },
+        required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: {
+        title: "Interactive Transit Timeline",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    _meta: {
+        ui: {
+            resourceUri: TRANSIT_TIMELINE_RESOURCE_URI,
+            visibility: ["model", "app"],
+        },
+    },
+    handler: async (args) => {
+        validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"]);
+        const client = getActiveClient();
+        // ── Step 1: natal chart → real planetary longitudes ──────────────────────
+        const natalBody = {
+            subject: {
+                name: "Transit Natal Subject",
+                birth_datetime: { iso: args.natal_datetime },
+                birth_location: {
+                    latitude: { decimal: args.natal_latitude },
+                    longitude: { decimal: args.natal_longitude },
+                },
+            },
+        };
+        const natalResult = await client.post("/ephemeris/natal-chart", natalBody);
+        const natalPositionMap = {};
+        const planets = natalResult?.planets || natalResult?.data?.planets || [];
+        const planetArray = Array.isArray(planets) ? planets : Object.values(planets);
+        const wantedPoints = args.natal_points
+            ? new Set(args.natal_points.map((p) => p.toLowerCase()))
+            : CORE_BODIES_DEFAULT;
+        for (const planet of planetArray) {
+            const name = (planet.name || planet.id || "").toLowerCase();
+            const lon = planet.longitude ?? planet.ecliptic_longitude ?? planet.lon;
+            if (typeof lon !== "number" || !isFinite(lon))
+                continue;
+            if (!wantedPoints.has(name))
+                continue;
+            natalPositionMap[name] = lon;
+        }
+        // Angles (ASC/MC) only when explicitly requested.
+        if (args.natal_points) {
+            const angles = natalResult?.angles || natalResult?.data?.angles;
+            if (angles) {
+                const angleEntries = Array.isArray(angles)
+                    ? angles
+                    : Object.entries(angles).map(([k, v]) => ({ name: k, ...(typeof v === "object" ? v : { longitude: v }) }));
+                for (const angle of angleEntries) {
+                    const name = (angle.name || angle.id || "").toLowerCase();
+                    const lon = angle.longitude ?? angle.ecliptic_longitude ?? angle.lon;
+                    if (typeof lon !== "number" || !isFinite(lon))
+                        continue;
+                    if (!wantedPoints.has(name))
+                        continue;
+                    natalPositionMap[name] = lon;
+                }
+            }
+        }
+        const pointNames = Object.keys(natalPositionMap);
+        if (pointNames.length === 0) {
+            throw new Error("Could not extract natal planet longitudes from the natal chart calculation. " +
+                "Please verify natal_datetime, natal_latitude, and natal_longitude are correct.");
+        }
+        // ── Step 2: build effective targets + reverse-map (target → natal point) ──
+        const aspectAngle = typeof args.aspect_angle === "number" ? args.aspect_angle : 0;
+        const aspectLabel = aspectLabelFor(aspectAngle);
+        // Cap targets (matches ephemeris_transits: never send more than 12).
+        const cappedNames = pointNames.slice(0, 12);
+        const targetToPoint = new Map();
+        const effectiveTargets = [];
+        for (const name of cappedNames) {
+            const eff = Math.round(normDeg(natalPositionMap[name] + aspectAngle) * 100) / 100;
+            effectiveTargets.push(eff);
+            targetToPoint.set(eff, name);
+        }
+        // ── Step 3: search transits ──────────────────────────────────────────────
+        let startStr = args.start_date;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(startStr))
+            startStr += "T00:00:00Z";
+        let endStr = args.end_date;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(endStr))
+            endStr += "T23:59:59Z";
+        const transitBody = {
+            start_date: startStr,
+            end_date: endStr,
+            target_degrees: effectiveTargets,
+        };
+        if (args.transiting_planets)
+            transitBody.planet_names = args.transiting_planets;
+        if (aspectAngle !== 0)
+            transitBody.search_criteria = { aspect_angle: aspectAngle };
+        const transitResult = await client.request("POST", "/predictive/transits/search", {
+            data: transitBody,
+            timeoutMs: 90_000,
+        });
+        // ── Step 4: flatten results map → chronological transit array ─────────────
+        const nearestPoint = (targetLon) => {
+            let best = "";
+            let bestDelta = 0.06; // ~3.6 arc-minutes tolerance
+            for (const [tgt, name] of targetToPoint) {
+                const delta = Math.abs(normDeg(targetLon - tgt));
+                const wrapped = Math.min(delta, 360 - delta);
+                if (wrapped <= bestDelta) {
+                    bestDelta = wrapped;
+                    best = name;
+                }
+            }
+            return best;
+        };
+        const resultsMap = (transitResult?.results ?? {});
+        const transits = [];
+        for (const hits of Object.values(resultsMap)) {
+            if (!Array.isArray(hits))
+                continue;
+            for (const hit of hits) {
+                const date = hit?.exact_time;
+                if (!date)
+                    continue;
+                const pname = String(hit?.planet_name ?? "");
+                const targetLon = typeof hit?.target_longitude === "number" ? hit.target_longitude : null;
+                const metaAsp = hit?.metadata?.aspect_type;
+                transits.push({
+                    planet: pname.toLowerCase(),
+                    planet_name: pname,
+                    planet_id: hit?.planet_id ?? null,
+                    date,
+                    aspect: typeof metaAsp === "string" ? metaAsp : aspectLabel,
+                    aspect_angle: aspectAngle,
+                    natal_point: targetLon != null ? nearestPoint(targetLon) : "",
+                    target_longitude: targetLon,
+                    zodiac_sign: hit?.zodiac_sign ?? null,
+                    zodiac_degree: hit?.zodiac_degree ?? null,
+                    zodiac_minute: hit?.zodiac_minute ?? null,
+                    is_retrograde: Boolean(hit?.is_retrograde),
+                });
+            }
+        }
+        transits.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+        const win = { start_date: startStr.slice(0, 10), end_date: endStr.slice(0, 10) };
+        const summary = buildSummary(transits, aspectLabel, win);
+        const uiPayload = {
+            transits,
+            natal_positions: natalPositionMap,
+            aspect_angle: aspectAngle,
+            aspect_label: aspectLabel,
+            search_window: win,
+            count: transits.length,
+            server_version: SERVER_VERSION,
+        };
+        const bundleAvailable = Boolean(getTransitTimelineBundle());
+        if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block.
+            // structuredContent carries the data payload for non-rendering hosts.
+            return {
+                content: [{ type: "text", text: summary }],
+                structuredContent: uiPayload,
+                _meta: {
+                    "ui/resourceUri": TRANSIT_TIMELINE_RESOURCE_URI,
+                    ui: { resourceUri: TRANSIT_TIMELINE_RESOURCE_URI },
+                },
+            };
+        }
+        return { content: [{ type: "text", text: summary }] };
+    },
+});

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

@@ -0,0 +1,25 @@
+/**
+ * vedic-chart-app.ts — MCP App tool registration for the Vedic Chart Explorer.
+ *
+ * Entry tool [model + app]:
+ *   • explore_vedic_chart — natal Vedic (Jyotish) chart, data + UI resource
+ * App-only tool:
+ *   • vedic_chart_recalculate — re-fetch with a different theme (dark/light
+ *     reconciliation, mirrors bodygraph_recalculate) — no client-side param
+ *     controls in v1, just the theme round-trip main.ts needs on mount.
+ *
+ * The South Indian Rashi grid is rendered server-side by the Go engine
+ * (handler_vedic_visual.go via POST /vedic/chart?include_visual=true) and
+ * inlined by the iframe — same Phase 4 "Go SVG is the source of truth"
+ * pattern as bodygraph-app.ts. /vedic/chart is not a binary endpoint, so the
+ * visual.data field is already a raw SVG string (no base64 decode needed).
+ *
+ * Also exports resource helpers (getVedicChartBundle, etc.) for use in
+ * index.ts and server-sse.ts.
+ */
+export declare const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
+export declare const VEDIC_CHART_MIME_TYPE = "text/html;profile=mcp-app";
+/** Read the pre-built HTML bundle. Returns null if not yet built. */
+export declare function getVedicChartBundle(): string | null;
+/** Reset cache (useful in dev watch mode or tests). */
+export declare function clearVedicChartBundleCache(): void;