@openephemeris/mcp-server 3.21.1 → 3.23.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.23.0] — 2026-07-19
+
+Coverage build-out (4 → 7 live iframe apps), tool-data bug fixes from live probing, and Human Design trademark hygiene. Registered tool count: 84 → 90.
+
+### Added
+- **Three revived iframe apps** (all following current conventions — structuredContent, shared error/first-run/fullscreen chrome, theme reconciliation, harness + visual-check gated):
+  - **`explore_transit_timeline`** — vertical timeline of upcoming transit hits grouped by month, with retrograde markers and clickable events.
+  - **`explore_vedic_chart`** + `vedic_chart_recalculate` (app-only) — interactive Vedic (Jyotish) chart as a South Indian fixed-sign Rashi grid; Go renders the SVG server-side (`handler_vedic_visual.go`, now emitting `data-sign`/`data-lagna`/`data-planets` groups), iframe binds interactivity.
+  - **`explore_bazi_chart`** + `bazi_recalculate` (app-only) — BaZi Four Pillars grid from the Go visual renderer, with element coloring, Wu Xing balance bar, and click-to-explain pillars.
+- **Moon-phase app grew up**: date control (`moon_phase_recalculate`, app-only), fullscreen toggle, and first-run coaching — it is no longer frozen on "now".
+- **Copy-positions button** on the chart-wheel planet table (Markdown to clipboard, graceful fallback when the host denies clipboard access).
+- **Credit-cost hints** on the iframe Recalculate controls, and per-theme SVG caching in the bodygraph so light↔dark host toggles no longer re-bill on every flip.
+- **Go: Pholus rides a real kernel** — `pholus.bsp` fetched at build time (mirrors the Chiron pattern), boot self-test vs JPL Horizons truth, `BootFatal` in prod on mismatch. No body is served from silent Keplerian fallback.
+
+### Fixed
+- **`ephemeris_natal_chart` now returns its promised aspect grid** (the tool omitted the endpoint's opt-in `include_aspects`).
+- **`format=llm` `summary_lines` house annotations repaired** — a union-type formatting bug printed raw JSON bytes (`H{[56]}`) instead of the house number (`H8`).
+- **`electional_moment_analysis` `format=llm`** top-level fields (aspects, day ruler, dignity, VOC, lunar phase) are now populated instead of `null`-with-values-hidden-under-`score_detail`.
+- **Bi-wheel provenance dates render in the chart's timezone**, not the viewer's browser timezone.
+- Cross-references added between every `explore_*` tool and its raw data sibling; credit-cost disclosure normalized to one consistent line per metered tool.
+
+### Changed
+- **Human Design trademark hygiene**: affiliation disclaimers ("not affiliated with Jovian Archive") added to the HD marketing pages, the bodygraph iframe footer (with the AUP informational/entertainment line), and the `explore_human_design*` tool descriptions; the one "Rave I Ching" usage replaced with generic phrasing.
+
+## [3.22.0] — 2026-07-19
+
+Mobile/dark QA sweep across the four live iframe apps (chart-wheel, bi-wheel, bodygraph, moon-phase), plus a design-parity pass bringing the wheels' colors in line with the web app's #239 engine redesign.
+
+### Added
+- **Pinch-to-zoom + reliable touch pan** on chart-wheel, bi-wheel, and bodygraph — `touch-action: none` on the chart SVG stops mobile browsers from claiming drags for page scroll and pinches for page zoom; two-finger pinch zooms anchored at the gesture midpoint with simultaneous pan.
+- **Midpoint aspect-type glyphs** on the natal chart wheel — every aspect line now shows its symbol (☌ ☍ △ □ ⚹) on a backing disc, matching the bi-wheel app and the Go engine's design.
+- **Theme-aware HD transit/connection overlays** — `explore_human_design_transit` and `explore_human_design_connection` now pass `visual_config.theme` (previously always defaulted to light server-side) and re-fetch in the host's detected theme via the embedded app.
+
+### Fixed
+- **HD transit/connection overlays no longer error-card** in MCP Apps hosts — both tools' payloads nest the chart under `natal` / `composite_chart` (with a `centers` map shape the app didn't handle), which the bodygraph app's validity gate rejected outright.
+- **Chart-wheel and bi-wheel color palette** now matches the web app's #239 wheel redesign (element remap, vibrant dark-mode zodiac tints, warm/cool aspect semantics) — the iframe wheels had never received that pass and read muddy by comparison.
+- Zodiac sign glyphs no longer occasionally render as the wrong emoji-presentation glyph (missing `U+FE0E` variation selector).
+- Light-host theme detection no longer misreads as dark in some hosts (background-luminance probe used the wrong color space).
+- **ASC/DSC angle labels** no longer clip at the edge of the wheel on full-bleed mobile hosts (a `viewBox` overflow needing container padding that phones don't provide) — coordinates are now clamped inside the frame.
+- Mobile pan/zoom controls shrink to 32px with a translucent, blurred background and an icon-only Reset button, so the control stack stops covering the chart at phone widths.
+
 ## [3.21.1] — 2026-07-12
 
 ### Changed

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-2026 Open Ephemeris
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025-2026 Open Ephemeris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -359,8 +359,8 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 - Allowlisted operations: **28**
 - Methods: `GET=4`, `POST=24`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **84**
-- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bazi_annual_pillar`, `bazi_chart`, `bazi_compatibility`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_ten_gods`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_list_allowed`, `dev_read_api`, `dev_write_api`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bi_wheel`, `explore_human_design`, `explore_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_connection_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_transit_channel_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `timezone_resolve`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **90**
+- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bazi_annual_pillar`, `bazi_chart`, `bazi_compatibility`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_recalculate`, `bazi_ten_gods`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_list_allowed`, `dev_read_api`, `dev_write_api`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bazi_chart`, `explore_bi_wheel`, `explore_human_design`, `explore_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `explore_transit_timeline`, `explore_vedic_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_connection_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_transit_channel_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `moon_phase_recalculate`, `timezone_resolve`, `vedic_chart`, `vedic_chart_recalculate`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
 
 ### Allowlist Families

package/dist/index.js

@@ -12,6 +12,9 @@ import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, }
 import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
 import { BI_WHEEL_RESOURCE_URI, BI_WHEEL_MIME_TYPE, getBiWheelBundle, } from "./tools/apps/bi-wheel-app.js";
 import { MOON_PHASE_RESOURCE_URI, MOON_PHASE_MIME_TYPE, getMoonPhaseBundle, } from "./tools/apps/moon-phase-app.js";
+import { TRANSIT_TIMELINE_RESOURCE_URI, TRANSIT_TIMELINE_MIME_TYPE, getTransitTimelineBundle, } from "./tools/apps/transit-timeline-app.js";
+import { VEDIC_CHART_RESOURCE_URI, VEDIC_CHART_MIME_TYPE, getVedicChartBundle, } from "./tools/apps/vedic-chart-app.js";
+import { BAZI_RESOURCE_URI, BAZI_MIME_TYPE, getBaziBundle, } from "./tools/apps/bazi-app.js";
 // ─────────────────────────────────────────────────────────────────────────────
 function resolveServerVersion() {
     try {
@@ -136,6 +139,30 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
             mimeType: MOON_PHASE_MIME_TYPE,
         });
     }
+    if (getTransitTimelineBundle()) {
+        resources.push({
+            uri: TRANSIT_TIMELINE_RESOURCE_URI,
+            name: "Transit Timeline Explorer",
+            description: "Interactive vertical timeline of upcoming transit hits grouped by month, with clickable events.",
+            mimeType: TRANSIT_TIMELINE_MIME_TYPE,
+        });
+    }
+    if (getVedicChartBundle()) {
+        resources.push({
+            uri: VEDIC_CHART_RESOURCE_URI,
+            name: "Vedic Chart Explorer",
+            description: "Interactive Vedic (Jyotish) South Indian Rashi grid with clickable sign placements.",
+            mimeType: VEDIC_CHART_MIME_TYPE,
+        });
+    }
+    if (getBaziBundle()) {
+        resources.push({
+            uri: BAZI_RESOURCE_URI,
+            name: "BaZi Four Pillars Explorer",
+            description: "Interactive BaZi (Four Pillars of Destiny) chart with clickable Year/Month/Day/Hour pillars.",
+            mimeType: BAZI_MIME_TYPE,
+        });
+    }
     return { resources };
 });
 // Read resource
@@ -165,6 +192,24 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             throw new Error("Moon Phase UI bundle not found. Run `npm run build:ui` to build it.");
         return { contents: [{ uri: MOON_PHASE_RESOURCE_URI, mimeType: MOON_PHASE_MIME_TYPE, text: bundle }] };
     }
+    if (uri === TRANSIT_TIMELINE_RESOURCE_URI) {
+        const bundle = getTransitTimelineBundle();
+        if (!bundle)
+            throw new Error("Transit Timeline UI bundle not found. Run `npm run build:ui` to build it.");
+        return { contents: [{ uri: TRANSIT_TIMELINE_RESOURCE_URI, mimeType: TRANSIT_TIMELINE_MIME_TYPE, text: bundle }] };
+    }
+    if (uri === VEDIC_CHART_RESOURCE_URI) {
+        const bundle = getVedicChartBundle();
+        if (!bundle)
+            throw new Error("Vedic Chart UI bundle not found. Run `npm run build:ui` to build it.");
+        return { contents: [{ uri: VEDIC_CHART_RESOURCE_URI, mimeType: VEDIC_CHART_MIME_TYPE, text: bundle }] };
+    }
+    if (uri === BAZI_RESOURCE_URI) {
+        const bundle = getBaziBundle();
+        if (!bundle)
+            throw new Error("BaZi UI bundle not found. Run `npm run build:ui` to build it.");
+        return { contents: [{ uri: BAZI_RESOURCE_URI, mimeType: BAZI_MIME_TYPE, text: bundle }] };
+    }
     throw new Error(`Unknown resource: ${uri}`);
 });
 // Handle tool calls

package/dist/server-sse.js

@@ -28,8 +28,13 @@ import { BackendClient, runWithClient } from "./backend/client.js";
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
 import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
 import { BI_WHEEL_RESOURCE_URI, BI_WHEEL_MIME_TYPE, getBiWheelBundle, } from "./tools/apps/bi-wheel-app.js";
-// NOTE: transit-timeline, bazi, vedic-chart imports removed — tools disabled.
+// NOTE: bazi, vedic-chart imports removed — tools disabled.
+// NOTE: transit-timeline, bazi imports removed — tools disabled.
+// NOTE: transit-timeline, vedic-chart imports removed — tools disabled.
 import { MOON_PHASE_RESOURCE_URI, MOON_PHASE_MIME_TYPE, getMoonPhaseBundle, } from "./tools/apps/moon-phase-app.js";
+import { TRANSIT_TIMELINE_RESOURCE_URI, TRANSIT_TIMELINE_MIME_TYPE, getTransitTimelineBundle, } from "./tools/apps/transit-timeline-app.js";
+import { VEDIC_CHART_RESOURCE_URI, VEDIC_CHART_MIME_TYPE, getVedicChartBundle, } from "./tools/apps/vedic-chart-app.js";
+import { BAZI_RESOURCE_URI, BAZI_MIME_TYPE, getBaziBundle, } from "./tools/apps/bazi-app.js";
 import { oauthDiscoveryRouter, PROTECTED_RESOURCE_METADATA_URL } from "./oauth/discovery.js";
 import { oauthDcrRouter } from "./oauth/dcr.js";
 import { oauthTokenRouter } from "./oauth/token.js";
@@ -337,7 +342,8 @@ function createMcpServer(analyticsId = "anonymous") {
                 mimeType: BI_WHEEL_MIME_TYPE,
             });
         }
-        // NOTE: transit-timeline, bazi, vedic-chart resources omitted — tools disabled.
+        // NOTE: bazi resources omitted — tools disabled.
+        // NOTE: transit-timeline, vedic-chart resources omitted — tools disabled.
         if (getMoonPhaseBundle()) {
             resources.push({
                 uri: MOON_PHASE_RESOURCE_URI,
@@ -346,6 +352,30 @@ function createMcpServer(analyticsId = "anonymous") {
                 mimeType: MOON_PHASE_MIME_TYPE,
             });
         }
+        if (getTransitTimelineBundle()) {
+            resources.push({
+                uri: TRANSIT_TIMELINE_RESOURCE_URI,
+                name: "Transit Timeline Explorer",
+                description: "Interactive vertical timeline of upcoming transit hits grouped by month, with clickable events.",
+                mimeType: TRANSIT_TIMELINE_MIME_TYPE,
+            });
+        }
+        if (getVedicChartBundle()) {
+            resources.push({
+                uri: VEDIC_CHART_RESOURCE_URI,
+                name: "Vedic Chart Explorer",
+                description: "Interactive Vedic (Jyotish) South Indian Rashi grid with clickable sign placements.",
+                mimeType: VEDIC_CHART_MIME_TYPE,
+            });
+        }
+        if (getBaziBundle()) {
+            resources.push({
+                uri: BAZI_RESOURCE_URI,
+                name: "BaZi Four Pillars Explorer",
+                description: "Interactive BaZi (Four Pillars of Destiny) chart with clickable Year/Month/Day/Hour pillars.",
+                mimeType: BAZI_MIME_TYPE,
+            });
+        }
         return { resources };
     });
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
@@ -368,13 +398,32 @@ function createMcpServer(analyticsId = "anonymous") {
                 throw new Error("Bi-Wheel UI bundle not found. Run `npm run build:ui` to build it.");
             return { contents: [{ uri: BI_WHEEL_RESOURCE_URI, mimeType: BI_WHEEL_MIME_TYPE, text: bundle }] };
         }
-        // NOTE: transit-timeline, bazi, vedic-chart ReadResource handlers removed.
+        // NOTE: bazi resources omitted — tools disabled.
+        // NOTE: transit-timeline, vedic-chart ReadResource handlers removed.
         if (uri === MOON_PHASE_RESOURCE_URI) {
             const bundle = getMoonPhaseBundle();
             if (!bundle)
                 throw new Error("Moon Phase UI bundle not found. Run `npm run build:ui` to build it.");
             return { contents: [{ uri: MOON_PHASE_RESOURCE_URI, mimeType: MOON_PHASE_MIME_TYPE, text: bundle }] };
         }
+        if (uri === TRANSIT_TIMELINE_RESOURCE_URI) {
+            const bundle = getTransitTimelineBundle();
+            if (!bundle)
+                throw new Error("Transit Timeline UI bundle not found. Run `npm run build:ui` to build it.");
+            return { contents: [{ uri: TRANSIT_TIMELINE_RESOURCE_URI, mimeType: TRANSIT_TIMELINE_MIME_TYPE, text: bundle }] };
+        }
+        if (uri === VEDIC_CHART_RESOURCE_URI) {
+            const bundle = getVedicChartBundle();
+            if (!bundle)
+                throw new Error("Vedic Chart UI bundle not found. Run `npm run build:ui` to build it.");
+            return { contents: [{ uri: VEDIC_CHART_RESOURCE_URI, mimeType: VEDIC_CHART_MIME_TYPE, text: bundle }] };
+        }
+        if (uri === BAZI_RESOURCE_URI) {
+            const bundle = getBaziBundle();
+            if (!bundle)
+                throw new Error("BaZi UI bundle not found. Run `npm run build:ui` to build it.");
+            return { contents: [{ uri: BAZI_RESOURCE_URI, mimeType: BAZI_MIME_TYPE, text: bundle }] };
+        }
         throw new Error(`Unknown resource: ${uri}`);
     });
     return server;

package/dist/tools/apps/bazi-app.d.ts

@@ -0,0 +1,24 @@
+/**
+ * bazi-app.ts — MCP App tool registration for the BaZi Four Pillars Explorer.
+ *
+ * Registers 2 tools:
+ *   • explore_bazi_chart  — primary entry point, returns data + UI resource [model + app]
+ *   • bazi_recalculate    — re-render with new birth data or theme [app-only]
+ *
+ * The Go engine (internal/rendering/bazi) is the single source of truth for
+ * the visual — same pattern as bodygraph-app.ts (Phase 4 SVG unification).
+ * The include_visual intercept on POST /chinese/bazi (handler_bazi_visual_wrap.go)
+ * returns the structured pillar data AND the rendered SVG in one call, so a
+ * single request builds the whole model payload — no separate visualization
+ * fetch needed.
+ *
+ * Data tools (chinese_bazi, bazi_ten_gods, bazi_element_balance, bazi_luck_pillars,
+ * bazi_annual_pillar, bazi_compatibility, bazi_chart) already exist in
+ * ../specialized/bazi.ts — this file is purely the interactive visual entry point.
+ */
+export declare const BAZI_RESOURCE_URI = "ui://openephemeris/bazi";
+export declare const BAZI_MIME_TYPE = "text/html;profile=mcp-app";
+/** Read the pre-built HTML bundle. Returns null if not yet built. */
+export declare function getBaziBundle(): string | null;
+/** Reset cache (useful in dev watch mode or tests). */
+export declare function clearBaziBundleCache(): void;

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

@@ -0,0 +1,231 @@
+/**
+ * bazi-app.ts — MCP App tool registration for the BaZi Four Pillars Explorer.
+ *
+ * Registers 2 tools:
+ *   • explore_bazi_chart  — primary entry point, returns data + UI resource [model + app]
+ *   • bazi_recalculate    — re-render with new birth data or theme [app-only]
+ *
+ * The Go engine (internal/rendering/bazi) is the single source of truth for
+ * the visual — same pattern as bodygraph-app.ts (Phase 4 SVG unification).
+ * The include_visual intercept on POST /chinese/bazi (handler_bazi_visual_wrap.go)
+ * returns the structured pillar data AND the rendered SVG in one call, so a
+ * single request builds the whole model payload — no separate visualization
+ * fetch needed.
+ *
+ * Data tools (chinese_bazi, bazi_ten_gods, bazi_element_balance, bazi_luck_pillars,
+ * bazi_annual_pillar, bazi_compatibility, bazi_chart) already exist in
+ * ../specialized/bazi.ts — this file is purely the interactive visual entry point.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { registerTool, SERVER_VERSION } from "../index.js";
+import { getActiveClient } from "../../backend/client.js";
+import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+export const BAZI_RESOURCE_URI = "ui://openephemeris/bazi";
+export const BAZI_MIME_TYPE = "text/html;profile=mcp-app";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLE_PATHS = [
+    path.resolve(here, "..", "..", "..", "dist", "ui", "bazi.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 getBaziBundle() {
+    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 clearBaziBundleCache() {
+    cachedBundle = null;
+}
+function parseBaziArgs(args) {
+    let year = args.year;
+    let month = args.month;
+    let day = args.day;
+    let hour = args.hour;
+    if (args.datetime && (!year || !month || !day)) {
+        const dt = new Date(String(args.datetime));
+        if (!isNaN(dt.getTime())) {
+            year = dt.getUTCFullYear();
+            month = dt.getUTCMonth() + 1;
+            day = dt.getUTCDate();
+            if (hour == null)
+                hour = dt.getUTCHours();
+        }
+    }
+    if (!year || !month || !day) {
+        throw new Error("Provide year/month/day fields, or a datetime ISO string. " +
+            "Example: year=1987, month=7, day=15 OR datetime='1987-07-15T14:00:00'");
+    }
+    const out = { year, month, day };
+    if (hour != null)
+        out.hour = hour;
+    return out;
+}
+/**
+ * Fetch the BaZi chart via the include_visual intercept — one call returns
+ * both the structured pillar data (year/month/day/hour/day_master) and the
+ * Go-rendered SVG (bazi.RenderBaziChartSVG), same shape the strict
+ * /chinese/bazi handler returns with a `visual` key attached.
+ */
+async function fetchBaziChart(components, theme = "dark") {
+    const client = getActiveClient();
+    const body = {
+        ...components,
+        include_visual: true,
+        visual_config: { format: "svg", theme, size: 800 },
+    };
+    return await client.request("POST", "/chinese/bazi", { data: body });
+}
+function buildModelPayload(data, components, theme) {
+    return {
+        year: data.year,
+        month: data.month,
+        day: data.day,
+        hour: data.hour,
+        day_master: data.day_master,
+        _svg: data.visual?.data,
+        _birth_params: components,
+        _theme: theme,
+    };
+}
+function buildSummary(payload) {
+    const dm = payload.day_master;
+    const dmLine = dm ? `Day Master: **${dm.stem} ${dm.element}**` : "";
+    const rows = ["year", "month", "day", "hour"]
+        .map((k) => {
+        const p = payload[k];
+        if (!p?.stem || !p?.branch)
+            return null;
+        const label = k.charAt(0).toUpperCase() + k.slice(1);
+        return `${label}: ${p.stem.name} ${p.stem.element} / ${p.branch.name} (${p.branch.animal})`;
+    })
+        .filter(Boolean)
+        .join("\n");
+    return ("**BaZi Four Pillars (四柱命盘)**\n\n" +
+        `${dmLine}\n\n${rows}\n\n` +
+        "Click any pillar on the chart for its interpretation.");
+}
+// ── Tool: explore_bazi_chart ─────────────────────────────────────────────────
+registerTool({
+    name: "explore_bazi_chart",
+    description: "Generate an interactive BaZi (四柱命盘 Four Pillars of Destiny) chart with clickable pillars.\n\n" +
+        "Returns an embedded visual Four Pillars explorer showing the Year, Month, Day, and Hour " +
+        "pillars — each with its Heavenly Stem (天干) and Earthly Branch (地支), Ten God label, and " +
+        "element color — plus the Day Master identity and a Wu Xing (五行) element balance bar. " +
+        "Click any pillar for an instant interpretation of what it reveals about that life domain " +
+        "(Year = ancestry/early life, Month = parents/career, Day = self/spouse, Hour = children/later life).\n\n" +
+        "CREDIT COST: 3 credits per call (1 base + 2 visual render).\n\n" +
+        "Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude Desktop). " +
+        "Falls back to a text summary in other hosts. For non-visual data lookups, use the dedicated " +
+        "chinese_bazi / bazi_ten_gods / bazi_element_balance / bazi_luck_pillars tools instead.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            year: { type: "integer", description: "Gregorian birth year, e.g. 1987." },
+            month: { type: "integer", description: "Birth month (1–12)." },
+            day: { type: "integer", description: "Birth day of month (1–31)." },
+            hour: {
+                type: "integer",
+                description: "Birth hour (0–23). Optional, defaults to 12 (noon). " +
+                    "Chinese shí hours are 2-hour blocks — precision within a 2-hour window is sufficient.",
+            },
+            datetime: {
+                type: "string",
+                description: "Alternative to year/month/day: ISO 8601 datetime (e.g. '1987-07-15T14:00:00'). " +
+                    "year/month/day/hour are extracted automatically. Use this OR the individual fields.",
+            },
+        },
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: {
+        title: "Interactive BaZi Four Pillars Explorer",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    _meta: {
+        ui: {
+            resourceUri: BAZI_RESOURCE_URI,
+            visibility: ["model", "app"],
+        },
+    },
+    handler: async (args) => {
+        const components = parseBaziArgs(args);
+        const bundleAvailable = Boolean(getBaziBundle());
+        const theme = "dark";
+        if (!bundleAvailable) {
+            // Text-fallback hosts have no use for the SVG — skip the visual surcharge.
+            const data = await getActiveClient().request("POST", "/chinese/bazi", {
+                data: components,
+            });
+            const payload = buildModelPayload(data, components, theme);
+            return { content: [{ type: "text", text: buildSummary(payload) }] };
+        }
+        const data = await fetchBaziChart(components, theme);
+        const payload = buildModelPayload(data, components, theme);
+        const summary = buildSummary(payload);
+        // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+        // delivered through resources/read — NOT as a content block.
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: { ...payload, server_version: SERVER_VERSION },
+            _meta: {
+                "ui/resourceUri": BAZI_RESOURCE_URI,
+                ui: { resourceUri: BAZI_RESOURCE_URI },
+            },
+        };
+    },
+});
+// ── Tool: bazi_recalculate [app-only] ────────────────────────────────────────
+registerTool({
+    name: "bazi_recalculate",
+    description: "Recalculates a BaZi Four Pillars chart with new birth data or theme.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            year: { type: "integer" },
+            month: { type: "integer" },
+            day: { type: "integer" },
+            hour: { type: "integer" },
+            theme: {
+                type: "string",
+                enum: ["light", "dark"],
+                description: "Render palette for the BaZi SVG. Mirrors the MCP host's light/dark color scheme.",
+            },
+        },
+        required: ["year", "month", "day"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Recalculate BaZi Chart", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: BAZI_RESOURCE_URI, visibility: ["app"] } },
+    handler: async (args) => {
+        const components = parseBaziArgs(args);
+        const theme = args.theme === "light" ? "light" : "dark";
+        const data = await fetchBaziChart(components, theme);
+        const payload = buildModelPayload(data, components, theme);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ...payload, server_version: SERVER_VERSION }) }],
+        };
+    },
+});

package/dist/tools/apps/bi-wheel-app.js

@@ -417,7 +417,9 @@ registerTool({
         "• lunar_return — Nearest lunar return chart (person2_datetime = target month). 5 credits.\n" +
         "• solar_arc    — Solar arc directed positions (person2_datetime = target date). 1 credit.\n" +
         "Cross-aspects between both wheels are computed and displayed as coloured dashed lines. " +
-        "Click any planet, aspect line, or house cusp for interpretation.",
+        "Click any planet, aspect line, or house cusp for interpretation. " +
+        "Use this instead of ephemeris_bi_wheel for a richer, interactive experience in " +
+        "MCP Apps-capable hosts (Claude Desktop). Falls back to static SVG in other hosts.",
     inputSchema: {
         type: "object",
         properties: {