@openephemeris/mcp-server 3.21.1 → 3.23.0

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;

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'",