@openephemeris/mcp-server 3.22.0 → 3.23.0

package/dist/tools/apps/vedic-chart-app.js

@@ -0,0 +1,297 @@
+/**
+ * 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.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { registerTool, validateRequired, validateCoordinates, SERVER_VERSION } from "../index.js";
+import { getActiveClient } from "../../backend/client.js";
+import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+export const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
+export const VEDIC_CHART_MIME_TYPE = "text/html;profile=mcp-app";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLE_PATHS = [
+    path.resolve(here, "..", "..", "..", "dist", "ui", "vedic-chart.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 getVedicChartBundle() {
+    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 clearVedicChartBundleCache() {
+    cachedBundle = null;
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/** Ensure datetime has a UTC offset for Go time.Time parsing. */
+function ensureTimezone(dt) {
+    if (!dt)
+        return dt;
+    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt))
+        return dt;
+    return dt + "Z";
+}
+/**
+ * Convert a local datetime string (no offset) to a UTC ISO 8601 string using
+ * the IANA timezone. Mirrors bodygraph-app.ts's localToUtcIso.
+ */
+function localToUtcIso(dt, tz) {
+    if (!dt || /[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt))
+        return ensureTimezone(dt);
+    if (!tz)
+        return dt + "Z";
+    try {
+        const [datePart, timePart = "00:00:00"] = dt.split("T");
+        const [year, month, day] = datePart.split("-").map(Number);
+        const [hour, min, sec = 0] = timePart.split(":").map(Number);
+        const candidateUtcMs = Date.UTC(year, month - 1, day, hour, min, sec);
+        const getOffsetMs = (utcMs) => {
+            const fmtParts = new Intl.DateTimeFormat("en-US", {
+                timeZone: tz,
+                year: "numeric", month: "2-digit", day: "2-digit",
+                hour: "2-digit", minute: "2-digit", second: "2-digit",
+                hour12: false,
+            }).formatToParts(new Date(utcMs));
+            const get = (t) => Number(fmtParts.find((p) => p.type === t)?.value ?? 0);
+            const localizedUtcMs = Date.UTC(get("year"), get("month") - 1, get("day"), get("hour") % 24, get("minute"), get("second"));
+            return utcMs - localizedUtcMs;
+        };
+        const offsetMs1 = getOffsetMs(candidateUtcMs);
+        const correctedUtcMs1 = candidateUtcMs + offsetMs1;
+        const offsetMs2 = getOffsetMs(correctedUtcMs1);
+        const finalUtcMs = candidateUtcMs + offsetMs2;
+        return new Date(finalUtcMs).toISOString();
+    }
+    catch {
+        return dt + "Z";
+    }
+}
+/**
+ * Build the compact iframe model from the raw Go /vedic/chart response.
+ * The Go response nests ayanamsha/lagna under `metadata` (radians→degrees
+ * already applied) and carries `visual.data` as the raw SVG when
+ * include_visual was requested.
+ */
+function buildVedicModelPayload(chartData, birthParams, theme) {
+    const meta = (chartData.metadata ?? {});
+    const lagnaLon = typeof meta.lagna === "number" ? meta.lagna : 0;
+    const lagnaSign = ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"][Math.floor((((lagnaLon % 360) + 360) % 360) / 30)];
+    const retrogradeSet = new Set(meta.retrograde_planets ?? []);
+    const planets = (chartData.planets ?? []).map((p) => ({
+        ...p,
+        is_retrograde: retrogradeSet.has(String(p.planet ?? "")),
+    }));
+    const visual = chartData.visual;
+    return {
+        ayanamsa: String(meta.ayanamsha ?? "lahiri").replace(/\b\w/g, (c) => c.toUpperCase()),
+        lagna: lagnaSign,
+        planets,
+        _svg: visual?.data,
+        _theme: theme,
+        _birth_params: birthParams,
+    };
+}
+function buildVedicSummary(payload, location) {
+    const planetLines = payload.planets
+        .map((p) => `${p.planet} in ${p.rashi_western} ${Number(p.rashi_degree ?? 0).toFixed(1)}°${p.is_retrograde ? " ℞" : ""}`)
+        .join(", ");
+    return (`**Vedic (Jyotish) Chart — ${location}**\n\n` +
+        `Ayanamsa: **${payload.ayanamsa}**  |  Lagna: **${payload.lagna}**\n\n` +
+        `Planets: ${planetLines}\n\n` +
+        "Click any rashi in the grid for its themes and interpretation.");
+}
+// ── Tool: explore_vedic_chart ────────────────────────────────────────────────
+registerTool({
+    name: "explore_vedic_chart",
+    description: "Generate an interactive Vedic (Jyotish) birth chart as a South Indian fixed-sign Rashi grid, " +
+        "with clickable rashis showing sidereal placements, nakshatras, and the Lagna.\n\n" +
+        "CREDIT COST: 3 credits per call (chart calculation + visual render).\n\n" +
+        "Returns an embedded visual explorer that lets you click any rashi cell for its themes and " +
+        "any planets placed there. Shows sidereal (Lahiri by default) planet placements, nakshatra with " +
+        "pada, navamsa, and the Lagna (Ascendant) rashi. Uses NASA JPL DE440 ephemerides. " +
+        "Use this for a rich, interactive Jyotish 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 birth datetime in UTC, e.g. '1990-06-15T14:30:00Z'. Include 'Z' or a timezone offset.",
+            },
+            latitude: {
+                type: "number",
+                description: "Birth latitude in decimal degrees (positive = North).",
+            },
+            longitude: {
+                type: "number",
+                description: "Birth longitude in decimal degrees (positive = East).",
+            },
+            location: {
+                type: "string",
+                description: "Location name for display only (e.g. 'Mumbai, India').",
+            },
+            timezone: {
+                type: "string",
+                description: "IANA timezone name for the birth location (e.g. 'Asia/Kolkata'). " +
+                    "Recommended for accuracy if providing local birth time without a UTC offset.",
+            },
+            ayanamsa: {
+                type: "string",
+                enum: ["lahiri", "fagan_bradley", "krishnamurti", "raman", "yukteshwar"],
+                description: "Ayanamsa system for sidereal conversion. Defaults to 'lahiri'.",
+            },
+        },
+        required: ["datetime", "latitude", "longitude"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: {
+        title: "Interactive Vedic Chart Explorer",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    _meta: {
+        ui: {
+            resourceUri: VEDIC_CHART_RESOURCE_URI,
+            visibility: ["model", "app"],
+        },
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        validateCoordinates(args, "latitude", "longitude");
+        const client = getActiveClient();
+        const timezone = args.timezone;
+        const datetime = localToUtcIso(String(args.datetime), timezone);
+        const lat = Number(args.latitude);
+        const lon = Number(args.longitude);
+        const ayanamsa = args.ayanamsa;
+        const location = String(args.location ?? `${lat}, ${lon}`).slice(0, 120);
+        const bundleAvailable = Boolean(getVedicChartBundle());
+        const theme = "dark"; // app shell default; iframe reconciles to host theme on load
+        const body = {
+            datetime_utc: datetime,
+            latitude: lat,
+            longitude: lon,
+        };
+        if (ayanamsa)
+            body.ayanamsa = ayanamsa;
+        if (bundleAvailable) {
+            body.include_visual = true;
+            body.visual_config = { theme, format: "svg", size: 640 };
+        }
+        const chartData = await client.request("POST", "/vedic/chart", { data: body });
+        const modelPayload = buildVedicModelPayload(chartData, {
+            datetime,
+            location: args.location ?? null,
+            timezone: timezone ?? null,
+            latitude: lat,
+            longitude: lon,
+            ayanamsa: ayanamsa ?? "lahiri",
+        }, theme);
+        const summary = buildVedicSummary(modelPayload, location);
+        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: { ...modelPayload, server_version: SERVER_VERSION },
+                _meta: {
+                    "ui/resourceUri": VEDIC_CHART_RESOURCE_URI,
+                    ui: { resourceUri: VEDIC_CHART_RESOURCE_URI },
+                },
+            };
+        }
+        return { content: [{ type: "text", text: summary }] };
+    },
+});
+// ── Tool: vedic_chart_recalculate [app-only] ─────────────────────────────────
+// Fired by main.ts's applyTheme() to reconcile the server-default-dark SVG
+// with the host's actual theme. No client-side param controls in v1.
+registerTool({
+    name: "vedic_chart_recalculate",
+    description: "Re-renders a Vedic chart with a different theme (light/dark).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: { type: "string" },
+            latitude: { type: "number" },
+            longitude: { type: "number" },
+            ayanamsa: { type: "string" },
+            theme: {
+                type: "string",
+                enum: ["light", "dark"],
+                description: "Render palette for the Rashi grid SVG. Mirrors the MCP host's light/dark color scheme.",
+            },
+        },
+        required: ["datetime"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Recalculate Vedic Chart", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: VEDIC_CHART_RESOURCE_URI, visibility: ["app"] } },
+    handler: async (args) => {
+        const client = getActiveClient();
+        const datetime = ensureTimezone(String(args.datetime));
+        const lat = args.latitude != null ? Number(args.latitude) : undefined;
+        const lon = args.longitude != null ? Number(args.longitude) : undefined;
+        const ayanamsa = args.ayanamsa;
+        const theme = args.theme === "light" ? "light" : "dark";
+        const body = {
+            datetime_utc: datetime,
+            latitude: lat,
+            longitude: lon,
+            include_visual: true,
+            visual_config: { theme, format: "svg", size: 640 },
+        };
+        if (ayanamsa)
+            body.ayanamsa = ayanamsa;
+        const chartData = await client.request("POST", "/vedic/chart", { data: body });
+        const modelPayload = buildVedicModelPayload(chartData, {
+            datetime,
+            location: null,
+            timezone: null,
+            latitude: lat ?? null,
+            longitude: lon ?? null,
+            ayanamsa: ayanamsa ?? "lahiri",
+        }, theme);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) }],
+        };
+    },
+});

package/dist/tools/index.js

@@ -83,6 +83,9 @@ export async function initTools(profile) {
         await import("./apps/bi-wheel-app.js");
         await import("./apps/bodygraph-app.js");
         await import("./apps/moon-phase-app.js");
+        await import("./apps/transit-timeline-app.js");
+        await import("./apps/vedic-chart-app.js");
+        await import("./apps/bazi-app.js");
     }
 }
 /**

package/dist/tools/specialized/bi_wheel.js

@@ -11,6 +11,7 @@ const HOUSE_SYSTEM_MAP = {
 registerTool({
     name: "ephemeris_bi_wheel",
     description: "Generate a Bi-Wheel (Synastry/Transit) image (SVG) comparing two charts. Draws Subject A's planets on the inside wheel and Subject B's on the outside wheel. Returns a native SVG that Claude displays inline in the conversation.\n\n" +
+        "For a user-facing interactive bi-wheel, use explore_bi_wheel instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "EXAMPLE: Compare someone born April 15, 1990 (A) to someone born June 10, 1992 (B):\n" +
         "  datetime_a='...', latitude_a=..., longitude_a=..., datetime_b='...', latitude_b=..., longitude_b=...",

package/dist/tools/specialized/chart_wheel.js

@@ -11,6 +11,7 @@ const HOUSE_SYSTEM_MAP = {
 registerTool({
     name: "ephemeris_chart_wheel",
     description: "Generate a classic astrological Chart Wheel image (SVG) for a person/event. This draws a standard circular chart wheel with planets, aspects, and house cusps. The tool returns a native SVG image that Claude displays inline in the conversation — no external tools needed.\n\n" +
+        "For a user-facing interactive chart wheel, use explore_natal_chart instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "EXAMPLE: Generate a natal chart wheel for someone born April 15, 1990 in Chicago:\n" +
         "  datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298",

package/dist/tools/specialized/hd_bodygraph.js

@@ -14,6 +14,7 @@ registerTool({
         "with Personality (conscious) and Design (unconscious) activations color-coded. " +
         "Defined centers are filled with their HD doctrine color; open/undefined centers remain muted. " +
         "Returns a native SVG that Claude displays inline. Use format='png' to opt into raster output (requires server-side rasterizer).\n\n" +
+        "For a user-facing interactive bodygraph explorer, use explore_human_design instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "EXAMPLE: Generate a bodygraph for someone born April 15, 1990 at 19:30 UTC:\n" +
         "  datetime='1990-04-15T19:30:00Z'",

package/dist/tools/specialized/human_design.js

@@ -19,6 +19,7 @@ registerTool({
         "(Generator, Manifesting Generator, Projector, Manifestor, Reflector), Strategy, Authority, " +
         "Profile (e.g. 1/3, 2/4), defined and undefined Centers, activated Gates and Channels, " +
         "Incarnation Cross, and both Personality (conscious) and Design (unconscious) planetary positions.\n\n" +
+        "Returns raw JSON. For a user-facing interactive bodygraph, use explore_human_design instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion " +
         "before birth (~3 months prior, the Design calculation). The API handles this automatically.\n\n" +

package/dist/tools/specialized/moon.js

@@ -9,6 +9,7 @@ registerTool({
         "⚠️  THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?'\n" +
         "❌  THIS TOOL DOES NOT ANSWER: 'When is the next new moon / full moon?'\n" +
         "→   For upcoming phase DATES use ephemeris_next_lunar_phase instead.\n\n" +
+        "For a user-facing interactive moon-phase dial, use explore_moon_phase instead.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "If no datetime is provided, returns the current (live) moon phase.\n\n" +
         "EXAMPLE: Get moon phase for a specific date/time:\n" +

package/dist/tools/specialized/natal.js

@@ -87,7 +87,11 @@ registerTool({
                     latitude: { decimal: args.latitude },
                     longitude: { decimal: args.longitude }
                 },
-            }
+            },
+            // The Go endpoint computes the aspect grid only when asked. The tool
+            // documents a "major aspect grid" as core output, so always opt in —
+            // otherwise the response comes back with `"aspects": []`.
+            options: { include_aspects: true },
         };
         if (args.timezone) {
             body.subject.birth_location.timezone = { iana_name: args.timezone };
@@ -104,6 +108,7 @@ registerTool({
         }
         if (args.include_arabic_parts) {
             body.options = {
+                ...body.options,
                 include_hermetic_lots: true,
             };
         }