@openephemeris/mcp-server 3.13.9 → 3.13.10

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

@@ -234,9 +234,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,

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,190 @@
+/**
+ * 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";
+// ── 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 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 isVoc = Boolean(voc?.is_void ?? voc?.is_void_of_course ?? false);
+    let summary = "**Moon Phase** — " + phaseName + "\n\n" +
+        "Illumination: **" + illumination + "%**\n";
+    if (moonSign) {
+        summary += "Moon Sign: **" + moonSign + "**\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,
+    },
+    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 and VOC in parallel
+        const [phase, voc] = await Promise.allSettled([
+            client.request("GET", "/ephemeris/moon/phase", { params }),
+            client.request("GET", "/ephemeris/moon/void-of-course", { 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 },
+        };
+        // Flatten for the UI — merge phase fields to top level
+        const phaseData = mergedData.phase;
+        const vocData = mergedData.void_of_course;
+        const uiPayload = {
+            phase_name: phaseData?.phase_name ?? phaseData?.name ?? "Unknown",
+            illumination: phaseData?.illumination ?? 0,
+            age_days: phaseData?.age_days ?? phaseData?.age ?? null,
+            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
+                        : 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,
+            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 }] };
+    },
+});

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 Explorer.
+ *
+ * Registers 1 tool:
+ *   • explore_transit_timeline — primary entry point, returns data + UI resource [model]
+ *
+ * The timeline is rendered client-side from structured JSON — the tool reuses
+ * the existing `ephemeris_transits` handler logic to compute natal chart positions
+ * and search for transit events, then returns the data with a UI resource link
+ * so the iframe can render a Gantt-style 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,243 @@
+/**
+ * transit-timeline-app.ts — MCP App tool registration for the Transit Timeline Explorer.
+ *
+ * Registers 1 tool:
+ *   • explore_transit_timeline — primary entry point, returns data + UI resource [model]
+ *
+ * The timeline is rendered client-side from structured JSON — the tool reuses
+ * the existing `ephemeris_transits` handler logic to compute natal chart positions
+ * and search for transit events, then returns the data with a UI resource link
+ * so the iframe can render a Gantt-style 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";
+// ── 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;
+}
+// ── Summary builder ──────────────────────────────────────────────────────────
+function buildTransitSummary(natalPositions, transitResult, aspectAngle, startDate, endDate) {
+    const transits = Array.isArray(transitResult)
+        ? transitResult
+        : (transitResult?.events ?? transitResult?.transits ?? transitResult?.results ?? []);
+    const count = transits.length;
+    const planets = [...new Set(transits.map((t) => String(t.planet ?? "")).filter(Boolean))];
+    const natalPoints = Object.keys(natalPositions);
+    const aspectLabel = aspectAngle === 0 ? "conjunction" : aspectAngle === 180 ? "opposition" : aspectAngle === 90 ? "square" : aspectAngle === 120 ? "trine" : aspectAngle + "°";
+    let summary = "**Transit Timeline — " + startDate + " to " + endDate + "**\n\n" +
+        count + " transit event" + (count !== 1 ? "s" : "") + " found";
+    if (aspectAngle !== 0) {
+        summary += " (" + aspectLabel + " aspect)";
+    }
+    summary += ".\n";
+    if (planets.length > 0) {
+        summary += "Transiting planets: " + planets.join(", ") + "\n";
+    }
+    if (natalPoints.length > 0) {
+        summary += "Natal points targeted: " + natalPoints.join(", ") + "\n";
+    }
+    summary += "\nClick any transit bar on the timeline for details and interpretation.";
+    return summary;
+}
+// ── Tool: explore_transit_timeline ────────────────────────────────────────────
+registerTool({
+    name: "explore_transit_timeline",
+    description: "Generate an interactive transit timeline visualization showing astrological transit events " +
+        "as a visual Gantt chart. Each transit appears as a colored bar on a time axis, grouped by " +
+        "transiting planet, with markers at exact aspect moments.\n\n" +
+        "This tool first calculates the natal chart to extract planetary longitudes, then searches " +
+        "for transiting planets crossing those degrees during the specified date range.\n\n" +
+        "SUPPORTED BODIES: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, " +
+        "Pluto, Chiron, Pholus, Ceres, Pallas, Juno, Vesta, MeanNode.\n\n" +
+        "ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine.\n\n" +
+        "Use this for a rich, interactive transit visualization 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.",
+            },
+            end_date: {
+                type: "string",
+                description: "End of the transit search window, ISO 8601 date or datetime.",
+            },
+            transiting_planets: {
+                type: "array",
+                items: { type: "string" },
+                description: "List of transiting planet IDs to search. Omit to search all outer planets.",
+            },
+            natal_points: {
+                type: "array",
+                items: { type: "string" },
+                description: "Natal point IDs whose longitudes should be targeted. Omit for all core points.",
+            },
+            aspect_angle: {
+                type: "number",
+                description: "Aspect angle in degrees. 0 = conjunction (default), 180 = opposition, 90 = square, 120 = trine.",
+            },
+        },
+        required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "Interactive Transit Timeline Explorer",
+        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: Compute natal chart to extract 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.request("POST", "/ephemeris/natal-chart", { data: natalBody });
+        const targetDegrees = [];
+        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()))
+            : null;
+        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 && !wantedPoints.has(name))
+                continue;
+            targetDegrees.push(Math.round(lon * 100) / 100);
+            natalPositionMap[name] = lon;
+        }
+        // Extract angles (ASC, MC)
+        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 && !wantedPoints.has(name))
+                    continue;
+                targetDegrees.push(Math.round(lon * 100) / 100);
+                natalPositionMap[name] = lon;
+            }
+        }
+        if (targetDegrees.length === 0) {
+            throw new Error("Could not extract natal planet longitudes. Verify natal_datetime, natal_latitude, and natal_longitude.");
+        }
+        // Step 2: 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: targetDegrees,
+        };
+        if (args.transiting_planets)
+            transitBody.planet_names = args.transiting_planets;
+        let effectiveTargets = targetDegrees;
+        const aspectAngle = typeof args.aspect_angle === "number" ? args.aspect_angle : 0;
+        if (aspectAngle !== 0) {
+            effectiveTargets = targetDegrees.map((deg) => ((deg + aspectAngle) % 360 + 360) % 360);
+            transitBody.target_degrees = effectiveTargets;
+            transitBody.search_criteria = { aspect_angle: aspectAngle };
+        }
+        const transitResult = await client.request("POST", "/predictive/transits/search", { data: transitBody });
+        // Build payload
+        const payload = {
+            natal_positions: natalPositionMap,
+            target_degrees_used: effectiveTargets,
+            aspect_angle: aspectAngle,
+            transit_results: transitResult,
+            search_window: { start_date: args.start_date, end_date: args.end_date },
+            server_version: SERVER_VERSION,
+        };
+        const summary = buildTransitSummary(natalPositionMap, transitResult, aspectAngle, args.start_date, args.end_date);
+        const bundleAvailable = Boolean(getTransitTimelineBundle());
+        if (bundleAvailable) {
+            return {
+                content: [
+                    { type: "text", text: summary },
+                    { type: "text", text: JSON.stringify(payload) },
+                ],
+                _meta: {
+                    "ui/resourceUri": TRANSIT_TIMELINE_RESOURCE_URI,
+                    ui: { resourceUri: TRANSIT_TIMELINE_RESOURCE_URI },
+                },
+            };
+        }
+        // Fallback: text summary only
+        return { content: [{ type: "text", text: summary }] };
+    },
+});

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

@@ -0,0 +1,17 @@
+/**
+ * vedic-chart-app.ts — MCP App tool registration for the Vedic Jyotish Chart Explorer.
+ *
+ * Registers 1 tool:
+ *   • explore_vedic_chart — primary entry point [model + app visible]
+ *     Calls POST /vedic/chart and returns a data payload + UI resource URI
+ *     so Claude Desktop can render the interactive South Indian Rashi grid.
+ *
+ * Also exports resource helpers (getVedicChartBundle, etc.) for use in
+ * server-sse.ts resource listing and reading.
+ */
+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;