@openephemeris/mcp-server 3.21.1 → 3.23.0

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

@@ -27,6 +27,8 @@ import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const BODYGRAPH_RESOURCE_URI = "ui://openephemeris/bodygraph";
+// Appended to every model-visible HD tool description — trademark hygiene.
+const HD_DISCLAIMER = " Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.";
 export const BODYGRAPH_MIME_TYPE = "text/html;profile=mcp-app";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLE_PATHS = [
@@ -346,11 +348,13 @@ function buildHdModelPayload(data, birthParams) {
 function buildHdSummary(payload, location) {
     const definedList = payload.centers.filter((c) => c.defined).map((c) => c.name);
     const undefinedList = payload.centers.filter((c) => !c.defined).map((c) => c.name);
+    const channelList = payload.active_channels.length > 0 ? payload.active_channels.join(", ") : "None";
     return (`**Human Design Chart \u2014 ${location}**\n\n` +
         `Type: **${payload.type}**  |  Profile: **${payload.profile}**  |  Authority: **${payload.authority}**\n` +
         `Definition: ${payload.definition}  |  Cross: ${payload.incarnation_cross}\n\n` +
         `Defined Centers: ${definedList.length > 0 ? definedList.join(", ") : "None"}\n` +
-        `Undefined Centers: ${undefinedList.length > 0 ? undefinedList.join(", ") : "None"}\n\n` +
+        `Undefined Centers: ${undefinedList.length > 0 ? undefinedList.join(", ") : "None"}\n` +
+        `Channels (${payload.active_channels.length}): ${channelList}\n\n` +
         "Click any center, gate, or channel on the bodygraph for interpretation.");
 }
 // ── Tool: explore_human_design ────────────────────────────────────────────
@@ -363,8 +367,10 @@ registerTool({
         "Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, " +
         "and Incarnation Cross. " +
         "The chart is calculated using NASA JPL DE440 ephemerides for both Personality and Design positions. " +
-        "Use this for a rich, interactive HD experience in MCP Apps-capable hosts (Claude Desktop). " +
-        "Falls back to a text summary in other hosts.",
+        "Use this instead of human_design_chart or human_design_bodygraph for a richer, interactive HD " +
+        "experience in MCP Apps-capable hosts (Claude Desktop). " +
+        "Falls back to a text summary in other hosts." +
+        HD_DISCLAIMER,
     inputSchema: {
         type: "object",
         properties: {
@@ -1331,7 +1337,8 @@ registerTool({
         "Highlights the channels a transit temporarily COMPLETES with the natal chart and any centers it " +
         "newly defines — the core of a Human Design transit reading. " +
         "Returns an interactive overlay bodygraph in MCP Apps-capable hosts (Claude Desktop), with a text " +
-        "summary fallback elsewhere. Premium (Pro tier). Calculated with NASA JPL DE440 ephemerides.",
+        "summary fallback elsewhere. Premium (Pro tier). Calculated with NASA JPL DE440 ephemerides." +
+        HD_DISCLAIMER,
     inputSchema: {
         type: "object",
         properties: {
@@ -1348,6 +1355,12 @@ registerTool({
                 type: "string",
                 description: "Transit moment, ISO 8601. Defaults to now (UTC) when omitted.",
             },
+            theme: {
+                type: "string",
+                enum: ["light", "dark"],
+                description: "Visual theme for the overlay bodygraph. Set automatically by the embedded app to match " +
+                    "the host; defaults to dark. You normally never need to pass this.",
+            },
         },
         required: ["datetime"],
     },
@@ -1384,8 +1397,14 @@ registerTool({
             body.transit_datetime = { iso: ensureTimezone(String(args.transit_datetime)) };
         }
         const bundleAvailable = Boolean(getBodygraphBundle());
-        if (bundleAvailable)
+        // The Go endpoint defaults visual_config.theme to "light", which mismatches
+        // dark MCP hosts — mirror the natal path's explicit dark default. The
+        // iframe re-calls this tool with theme once it detects the host theme.
+        const theme = args.theme === "light" ? "light" : "dark";
+        if (bundleAvailable) {
             body.include_visual = true;
+            body.visual_config = { theme };
+        }
         const resp = await client.request("POST", "/human-design/transit-chart", { data: body });
         const transit = (resp?.transit ?? {});
         const completed = Array.isArray(transit.completed_channels) ? transit.completed_channels : [];
@@ -1400,7 +1419,14 @@ registerTool({
             (newCenters.length
                 ? `\n\nNewly-defined center${newCenters.length === 1 ? "" : "s"}: **${newCenters.join(", ")}** — a temporary shift while the transit holds.`
                 : "");
-        const payload = { ...resp, _svg: svg, server_version: SERVER_VERSION };
+        const payload = {
+            ...resp,
+            _svg: svg,
+            _theme: theme,
+            // Lets the iframe re-request this overlay in the host's theme.
+            _refetch: { tool: "explore_human_design_transit", args: { ...args } },
+            server_version: SERVER_VERSION,
+        };
         if (bundleAvailable && svg) {
             return {
                 content: [{ type: "text", text: summary }],
@@ -1417,10 +1443,13 @@ registerTool({
 registerTool({
     name: "explore_human_design_connection",
     description: "Compare two people's Human Design charts and classify every connected channel by HD connection " +
-        "theory. CREDIT COST: 3 credits per call. Classifications: " +
+        "theory.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
+        "Classifications: " +
         "electromagnetic (attraction), companionship (sameness), dominance (one defines), and " +
         "compromise (friction). Returns an interactive two-person overlay bodygraph in MCP Apps-capable " +
-        "hosts, with a text summary fallback elsewhere. Premium (Pro tier). NASA JPL DE440 ephemerides.",
+        "hosts, with a text summary fallback elsewhere. Premium (Pro tier). NASA JPL DE440 ephemerides." +
+        HD_DISCLAIMER,
     inputSchema: {
         type: "object",
         properties: {
@@ -1446,6 +1475,12 @@ registerTool({
                 },
                 required: ["datetime"],
             },
+            theme: {
+                type: "string",
+                enum: ["light", "dark"],
+                description: "Visual theme for the overlay bodygraph. Set automatically by the embedded app to match " +
+                    "the host; defaults to dark. You normally never need to pass this.",
+            },
         },
         required: ["person_a", "person_b"],
     },
@@ -1473,8 +1508,12 @@ registerTool({
             subject_2: toSubject(args.person_b),
         };
         const bundleAvailable = Boolean(getBodygraphBundle());
-        if (bundleAvailable)
+        // Mirror the transit tool: explicit dark default, host-theme refetch.
+        const theme = args.theme === "light" ? "light" : "dark";
+        if (bundleAvailable) {
             body.include_visual = true;
+            body.visual_config = { theme };
+        }
         const resp = await client.request("POST", "/human-design/composite", { data: body });
         const connections = Array.isArray(resp?.connections) ? resp.connections : [];
         const svg = resp?.visual?.data;
@@ -1490,7 +1529,13 @@ registerTool({
             line("Dominance — one defines", "dominance") +
             line("Compromise — friction", "compromise") +
             (connections.length ? "" : " none.");
-        const payload = { ...resp, _svg: svg, server_version: SERVER_VERSION };
+        const payload = {
+            ...resp,
+            _svg: svg,
+            _theme: theme,
+            _refetch: { tool: "explore_human_design_connection", args: { ...args } },
+            server_version: SERVER_VERSION,
+        };
         if (bundleAvailable && svg) {
             return {
                 content: [{ type: "text", text: summary }],

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;