@openephemeris/mcp-server 3.14.0 → 3.16.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.16.0] — 2026-07-05
+
+### Added
+- **`explore_human_design_transit`** — personalized Human Design transit overlay. Overlays a transiting moment on a person's natal bodygraph and highlights the channels the transit temporarily completes plus any newly-defined centers. Premium (Developer tier); renders an interactive overlay bodygraph in MCP Apps hosts.
+- **`explore_human_design_connection`** — two-person Human Design connection (synastry) overlay. Classifies every connected channel as electromagnetic / companionship / dominance / compromise and renders a two-person overlay bodygraph. Premium (Developer tier).
+
+### Changed
+- **`human_design_composite` is now Developer-tier** (was Explorer) and returns real connection-channel scoring — the previously-stubbed relationship endpoint (`/human-design/composite`) is now live end-to-end.
+
+---
+
+## [3.15.0] — 2026-06-15
+
+### Changed
+- **`dev_call` split into `dev_read_api` (GET) and `dev_write_api` (POST/PUT/PATCH/DELETE).** Read and write now live in separate tools so a safe read surface never shares a tool with state-changing calls — required for MCP connector-directory compliance. `dev_read_api` carries `readOnlyHint: true`; `dev_write_api` carries `readOnlyHint: false`. Both name their target API explicitly.
+
+### Fixed
+- **Brand-gold WCAG AA contrast pass** across the chart-wheel, bi-wheel, and bodygraph iframes — gold accents darkened to clear AA against their backgrounds; all three apps are axe-clean.
+- **Moon-phase color cue** now encodes speed/proximity, and aspect-label contrast corrected.
+
+### Added
+- **Collapsible glyph legend** in the interactive chart iframes — keeps the wheel uncluttered while remaining one tap from a full symbol key.
+
+---
+
 ## [3.14.0] — 2026-05-24
 
 ### Added

package/README.md

@@ -229,7 +229,9 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 | Station tracker | `electional_station_tracker` | Developer |
 | Aspect search | `electional_aspect_search` | Developer |
 | Human Design chart | `human_design_chart` | Explorer |
-| HD composite | `human_design_composite` | Explorer |
+| HD composite | `human_design_composite` | Developer |
+| HD transit overlay | `explore_human_design_transit` | Developer |
+| HD connection (synastry) | `explore_human_design_connection` | Developer |
 | HD penta | `human_design_penta` | Explorer |
 | HD return / opposition | `hd_planetary_return`, `hd_opposition` | Explorer |
 | Vedic chart | `vedic_chart` | Explorer |
@@ -251,15 +253,15 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 ## Tooling Model
 
 - Typed tools are preferred for common workflows (natal, transits, moon phase, eclipse, synastry, relocation, electional, Human Design).
-- Generic tools: `dev.list_allowed` returns all currently allowlisted operations, and `dev.call` invokes any allowlisted operation by `method + path`.
+- Generic tools: `dev_list_allowed` returns all currently allowlisted operations; `dev_read_api` invokes allowlisted **GET** (read) operations and `dev_write_api` invokes allowlisted **POST/PUT/PATCH/DELETE** (write/compute) operations, each by `method + path`. Read and write are kept as separate tools so a safe read surface never shares a tool with state-changing writes.
 - Security model: default-deny with explicit allowlist in `config/dev-allowlist.json`.
 - Deny prefixes block sensitive route families (`/auth`, `/billing`, `/admin`, etc.).
 
-### `dev.call` input
+### `dev_read_api` / `dev_write_api` input
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `method` | `GET\|POST\|PUT\|PATCH\|DELETE` | Yes | HTTP method |
+| `method` | `dev_read_api`: `GET` · `dev_write_api`: `POST\|PUT\|PATCH\|DELETE` | No | HTTP method (defaults to the tool's natural method) |
 | `path` | `string` | Yes | Absolute API path, e.g. `/ephemeris/natal-chart` |
 | `query` | `object` | No | Query parameters |
 | `body` | `object` | No | JSON body for non-GET requests |
@@ -355,8 +357,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`): **79**
-- 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_call`, `dev_list_allowed`, `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_moon_phase`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_gate_click`, `hd_on_planet_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`): **82**
+- 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_gate_click`, `hd_on_planet_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`
 - Generic tools: 
 
 ### Allowlist Families

package/dist/prompts.js

@@ -68,9 +68,9 @@ export const PROMPTS = [
             "   Default to Placidus if they're unsure.\n\n" +
             "## Step 2 — Resolve Coordinates and Timezone (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones from memory.** Use the API tools to resolve them:\n\n" +
-            "**A) Geocode** — call `dev_call` with `method: 'GET'`, `path: '/location/autocomplete'`, " +
+            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
             "`query: { q: 'City Name, Country' }`. This returns verified decimal lat/lon.\n\n" +
-            "**B) Timezone** — call `dev_call` with `method: 'POST'`, `path: '/timezone/lookup'`, " +
+            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
             "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`. " +
             "This returns the correct IANA timezone and UTC offset for the birth year, including historical DST.\n\n" +
             "- Format: pass `datetime` as local ISO 8601 (e.g. `1990-04-15T14:30:00`) " +
@@ -148,9 +148,9 @@ export const PROMPTS = [
             "4. **Any major events coming up** they already know about — reframes the transits around real context\n\n" +
             "## Step 2 — Resolve Coordinates and Timezone (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones from memory.** Use the API tools:\n\n" +
-            "**A) Geocode** — call `dev_call` with `method: 'GET'`, `path: '/location/autocomplete'`, " +
+            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
             "`query: { q: 'Birth City, Country' }`. Use the returned decimal lat/lon.\n\n" +
-            "**B) Timezone** — call `dev_call` with `method: 'POST'`, `path: '/timezone/lookup'`, " +
+            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
             "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
             "- Set `start_date` to today and `end_date` to the end of the forecast window\n\n" +
             "## Step 3 — Tool Call Sequence\n" +
@@ -211,9 +211,9 @@ export const PROMPTS = [
             "7. **House system**: Placidus (default), Whole Sign, Koch, Equal?\n\n" +
             "## Step 2 — Resolve Both Sets of Coordinates (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones.** For EACH person:\n\n" +
-            "**A) Geocode** — call `dev_call` with `method: 'GET'`, `path: '/location/autocomplete'`, " +
+            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
             "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_call` with `method: 'POST'`, `path: '/timezone/lookup'`, " +
+            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
             "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
             "- Format: local ISO 8601 datetime (no Z) + IANA timezone name separately for each person\n" +
             "- Note if either birth time is unknown — flag this upfront before running tools\n\n" +
@@ -283,9 +283,9 @@ export const PROMPTS = [
             "sometimes it explains why a place felt 'off'\n\n" +
             "## Step 2 — Resolve Coordinates (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones.** Use the API tools:\n\n" +
-            "**A) Geocode birth city** — call `dev_call` with `method: 'GET'`, `path: '/location/autocomplete'`, " +
+            "**A) Geocode birth city** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
             "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_call` with `method: 'POST'`, `path: '/timezone/lookup'`, " +
+            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
             "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
             "**C) Geocode each target city** — repeat the autocomplete call for each destination city.\n\n" +
             "- Format birth datetime as local ISO 8601 (no Z), pass IANA timezone separately\n\n" +
@@ -372,9 +372,9 @@ export const PROMPTS = [
             "4. **Birth city and country** — needed for timezone conversion\n\n" +
             "## Step 2 — CRITICAL: Convert to UTC\n" +
             "Human Design requires **UTC datetime**. The tool rejects local times without a UTC offset.\n\n" +
-            "**A) Geocode** — call `dev_call` with `method: 'GET'`, `path: '/location/autocomplete'`, " +
+            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
             "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_call` with `method: 'POST'`, `path: '/timezone/lookup'`, " +
+            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
             "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n" +
             "This returns the UTC offset for the birth year, including historical DST.\n\n" +
             "- Use the returned offset to convert local birth time → UTC\n" +
@@ -458,7 +458,7 @@ export const PROMPTS = [
             "5. **Any personal chart data?** If yes, run natal chart first and look for dates when the " +
             "moon triggers benefic natal planets.\n\n" +
             "## Step 1.5 — Resolve Event Location (MANDATORY)\n" +
-            "**Do NOT guess coordinates.** Call `dev_call` with `method: 'GET'`, `path: '/location/autocomplete'`, " +
+            "**Do NOT guess coordinates.** Call `dev_read_api` with `path: '/location/autocomplete'`, " +
             "`query: { q: 'Event City, Country' }` to get verified decimal lat/lon for the event location.\n\n" +
             "## Step 2 — Check the Planetary Weather First\n" +
             "Before scanning for windows:\n\n" +
@@ -545,9 +545,9 @@ export const PROMPTS = [
             "   Default to Lahiri if unsure.\n\n" +
             "## Step 2 — Convert to UTC (MANDATORY)\n" +
             "The `vedic_chart` tool requires a UTC datetime (with Z suffix):\n\n" +
-            "**A) Geocode** — call `dev_call` with `method: 'GET'`, `path: '/location/autocomplete'`, " +
+            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
             "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_call` with `method: 'POST'`, `path: '/timezone/lookup'`, " +
+            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
             "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n" +
             "This returns the correct IANA timezone and UTC offset for the birth year, including historical DST.\n\n" +
             "- Use the returned offset to convert local birth time → UTC\n" +
@@ -629,7 +629,7 @@ export const PROMPTS = [
             "this difference is small, but it can shift the hour animal by one block for cities far " +
             "from their timezone meridian (e.g. western Xinjiang in China UTC+8, western Spain in CET).\n" +
             "Pass individual date/time components — do NOT convert to UTC.\n\n" +
-            "**Geocode the birth city** — call `dev_call` with `method: 'GET'`, `path: '/location/autocomplete'`, " +
+            "**Geocode the birth city** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
             "`query: { q: 'Birth City, Country' }` to get verified coordinates for longitude offset calculation.\n\n" +
             "## Step 3 — Call the Tool\n" +
             "Call `chinese_bazi` with:\n" +
@@ -770,9 +770,9 @@ export const PROMPTS = [
             "4. **House system**: Placidus (default), Whole Sign, Koch, Equal?\n\n" +
             "## Step 2 — Resolve Data (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones.** Use the API tools:\n\n" +
-            "**A) Geocode birth city** — call `dev_call` with `method: 'GET'`, `path: '/location/autocomplete'`, " +
+            "**A) Geocode birth city** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
             "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_call` with `method: 'POST'`, `path: '/timezone/lookup'`, " +
+            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
             "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
             "- For `birth_datetime`, include the UTC offset from the timezone lookup: `1985-06-21T14:00:00-05:00`\n" +
             "  (or convert to UTC with Z: `1985-06-21T19:00:00Z`)\n\n" +

package/dist/server-sse.js

@@ -66,8 +66,10 @@ const BACKEND_URL = process.env.OPENEPHEMERIS_BACKEND_URL ||
     "https://api.openephemeris.com";
 const version = resolveServerVersion();
 /**
- * Validate a user-supplied API key by hitting an auth-gated endpoint on
- * the Go sidecar. Returns true if the key yields a 2xx, false on 401/403.
+ * Validate a user-supplied API key by hitting an auth-gated endpoint on the Go
+ * sidecar. Tri-state so callers can fail closed when validation is unavailable
+ * (APP-6): "valid" (2xx), "invalid" (401/403), or "unknown" (network error or
+ * non-auth status — could not confirm).
  */
 async function validateApiKey(apiKey) {
     try {
@@ -77,17 +79,26 @@ async function validateApiKey(apiKey) {
             timeout: 5_000,
             validateStatus: () => true, // don't throw on any status
         });
-        // 2xx = valid key, 401/403 = invalid key, anything else = let through
         if (resp.status === 401 || resp.status === 403)
-            return false;
-        return true;
+            return "invalid";
+        if (resp.status >= 200 && resp.status < 300)
+            return "valid";
+        return "unknown"; // 5xx etc. — can't confirm
     }
     catch {
-        // Network error — let them through; tool calls will fail if key is bad.
-        console.warn("Could not validate API key against backend, allowing connection.");
-        return true;
+        console.warn("Could not validate API key against backend.");
+        return "unknown";
     }
 }
+/**
+ * Browser-originated requests carry an Origin header (the MCP apps run in a
+ * cross-origin iframe). Server-to-server MCP clients generally do not. We use
+ * this to fail closed for browsers when key validation is unavailable, while
+ * still letting trusted server clients through (APP-6).
+ */
+function isBrowserOrigin(req) {
+    return typeof req.headers.origin === "string" && req.headers.origin.length > 0;
+}
 /**
  * Extract authentication from a request, distinguishing JWTs from API keys.
  *
@@ -212,8 +223,12 @@ function createMcpServer() {
             prompts: {},
             resources: {},
             experimental: {
-                // Declare MCP Apps extension (spec: io.modelcontextprotocol/ui, 2026-01-26)
-                "io.modelcontextprotocol/ui": {},
+                // Declare MCP Apps extension (spec: io.modelcontextprotocol/ui, 2026-01-26).
+                // Advertise the supported UI MIME type so Directory-compliant hosts know
+                // this server returns renderable HTML resources.
+                "io.modelcontextprotocol/ui": {
+                    mimeTypes: ["text/html;profile=mcp-app"],
+                },
             },
         },
         instructions: "Open Ephemeris is a precision astronomical computation engine. " +
@@ -421,6 +436,24 @@ async function main() {
     app.use(express.json({ limit: "1mb" }), oauthDcrRouter);
     app.use("/oauth/token", tokenRateLimiter);
     app.use(express.urlencoded({ extended: false }), oauthTokenRouter(oauthStore));
+    // Per-IP throttle on MCP session creation to bound unauthenticated session
+    // churn / volumetric abuse (APP-7). Only NEW sessions are limited — requests
+    // carrying an mcp-session-id are existing sessions (ongoing tool calls) and
+    // must never be throttled.
+    const sessionRateLimiter = createRateLimiter({
+        windowMs: 60_000,
+        maxRequests: 30,
+        trustProxy: true,
+    });
+    const throttleSessionCreation = (req, res, next) => {
+        if (req.headers["mcp-session-id"]) {
+            next();
+            return;
+        }
+        sessionRateLimiter(req, res, next);
+    };
+    app.use("/mcp", throttleSessionCreation);
+    app.use("/sse", sessionRateLimiter);
     // Health check
     app.get("/health", (_req, res) => {
         res.json({
@@ -508,8 +541,8 @@ async function main() {
         // Validate API keys against the Go backend; JWTs are validated downstream
         // by the Go sidecar's ValidateSupabaseJWT when tool calls are proxied.
         if (apiKey) {
-            const valid = await validateApiKey(apiKey);
-            if (!valid) {
+            const keyStatus = await validateApiKey(apiKey);
+            if (keyStatus === "invalid") {
                 res.set("WWW-Authenticate", `Bearer realm="OpenEphemeris MCP", error="invalid_token", resource_metadata="${PROTECTED_RESOURCE_METADATA_URL}"`);
                 res.status(401).json({
                     error: "invalid_api_key",
@@ -517,6 +550,15 @@ async function main() {
                 });
                 return;
             }
+            // Fail closed for browser clients when validation is unavailable (APP-6).
+            if (keyStatus === "unknown" && isBrowserOrigin(req)) {
+                res.set("Retry-After", "5");
+                res.status(503).json({
+                    error: "validation_unavailable",
+                    message: "Could not verify your API key right now. Please retry shortly.",
+                });
+                return;
+            }
         }
         // New session — must be an initialize request
         if (!isInitializeRequest(req.body)) {
@@ -624,14 +666,23 @@ async function main() {
         }
         // Validate API keys against the Go backend; JWTs validated downstream.
         if (apiKey) {
-            const valid = await validateApiKey(apiKey);
-            if (!valid) {
+            const keyStatus = await validateApiKey(apiKey);
+            if (keyStatus === "invalid") {
                 res.status(403).json({
                     error: "invalid_api_key",
                     message: "The provided API key is invalid or inactive. Check your key at https://openephemeris.com/dashboard?tab=apikeys",
                 });
                 return;
             }
+            // Fail closed for browser clients when validation is unavailable (APP-6).
+            if (keyStatus === "unknown" && isBrowserOrigin(req)) {
+                res.set("Retry-After", "5");
+                res.status(503).json({
+                    error: "validation_unavailable",
+                    message: "Could not verify your API key right now. Please retry shortly.",
+                });
+                return;
+            }
         }
         const transport = new SSEServerTransport("/message", res);
         const sessionId = transport.sessionId;

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

@@ -288,8 +288,12 @@ const CLASSICAL_PLANETS = new Set([
  */
 function canonicalizePlanetName(raw) {
     const lower = raw.toLowerCase();
-    // Various node/chiron aliases the Go PlanetName() function emits
-    if (lower === "north node (mean)" || lower === "north node (true)" || lower === "mean node" || lower === "true node")
+    // Various node/chiron aliases the Go PlanetName() function emits.
+    // Keep mean vs true DISTINCT so the UI can offer a node toggle; collapsing
+    // both to "north_node" (the old behaviour) produced two overlapping ☊ glyphs.
+    if (lower === "north node (true)" || lower === "true node")
+        return "true_node";
+    if (lower === "north node (mean)" || lower === "mean node" || lower === "north node")
         return "north_node";
     if (lower === "south node (mean)" || lower === "south node (true)")
         return "south_node";
@@ -491,11 +495,16 @@ registerTool({
         const payload = buildBiWheelPayload(innerData, outerData, mode, params1, params2);
         const bundleAvailable = Boolean(getBiWheelBundle());
         if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block. A URI-only
+            // `type: "resource"` block lacks the inline text/blob the base MCP schema
+            // requires and fails strict client validation. structuredContent
+            // preserves the full payload for hosts that don't render the iframe.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify({ ...payload, server_version: SERVER_VERSION }) },
                 ],
+                structuredContent: { ...payload, server_version: SERVER_VERSION },
                 _meta: {
                     "ui/resourceUri": BI_WHEEL_RESOURCE_URI,
                     ui: { resourceUri: BI_WHEEL_RESOURCE_URI },

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

@@ -1,11 +1,15 @@
 /**
  * bodygraph-app.ts — MCP App tool registration for the Human Design Bodygraph Explorer.
  *
- * Registers 4 tools:
- *   • explore_human_design      — primary entry point, returns data + UI resource [model]
- *   • hd_on_center_click        — center click handler [app-only]
- *   • hd_on_gate_click          — gate click handler [app-only]
- *   • hd_on_channel_click       — channel click handler [app-only]
+ * Entry tools [model + app]:
+ *   • explore_human_design             — natal bodygraph, data + UI resource
+ *   • explore_human_design_transit     — natal + transit overlay (premium)
+ *   • explore_human_design_connection  — two-person connection/synastry overlay (premium)
+ * Click handlers [app-only]: hd_on_center_click, hd_on_gate_click,
+ *   hd_on_channel_click, hd_on_planet_click, hd_on_variable_click.
+ * The transit + connection tools reuse this bodygraph iframe resource; their
+ * overlay SVG is returned inline by /human-design/transit-chart and
+ * /human-design/composite (include_visual) rather than a separate render call.
  *
  * The bodygraph is rendered client-side from structured JSON — no SVG endpoint
  * is called, keeping latency at zero and the architecture consistent with