@openephemeris/mcp-server 3.14.0 → 3.15.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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

@@ -251,15 +251,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 +355,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`): **80**
+- 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_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.js

@@ -78,13 +78,18 @@ function ensureTimezone(dt) {
  * renderer in bodygraph-renderer.ts. Non-fatal: a missing SVG should never
  * block the tool result.
  */
-async function fetchGoBodygraphSVG(body) {
+async function fetchGoBodygraphSVG(body, theme = "dark") {
     try {
         const client = getActiveClient();
         // /visualization/bodygraph is registered as binary in BINARY_ENDPOINT_PREFIXES.
         // The client wraps it as { content_type, encoding: "base64", data_base64 } —
         // we decode back to UTF-8 SVG text for inlining.
-        const resp = await client.post("/visualization/bodygraph?format=svg&size=800", body);
+        //
+        // style=light|dark drives the Go renderer's palette. The endpoint defaults
+        // to "light" when style is omitted, which mismatches dark MCP hosts — so we
+        // always pass an explicit theme (default "dark" to match the app shell; the
+        // iframe re-fetches with the host-detected theme on load / theme change).
+        const resp = await client.post(`/visualization/bodygraph?format=svg&size=800&style=${theme}`, body);
         if (typeof resp === "string")
             return resp;
         if (resp && typeof resp === "object") {
@@ -438,11 +443,16 @@ registerTool({
             modelPayload._svg = svg;
         const summary = buildHdSummary(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. A URI-only
+            // `type: "resource"` block lacks the inline text/blob the base MCP schema
+            // requires and fails strict client validation. structuredContent carries
+            // the data for non-rendering hosts.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) },
                 ],
+                structuredContent: { ...modelPayload, server_version: SERVER_VERSION },
                 _meta: {
                     "ui/resourceUri": BODYGRAPH_RESOURCE_URI,
                     ui: { resourceUri: BODYGRAPH_RESOURCE_URI },
@@ -468,6 +478,11 @@ registerTool({
                 type: "string",
                 description: "IANA timezone name (e.g. 'America/New_York') for accurate UTC conversion.",
             },
+            theme: {
+                type: "string",
+                enum: ["light", "dark"],
+                description: "Render palette for the bodygraph SVG. Mirrors the MCP host's light/dark color scheme.",
+            },
         },
         required: ["datetime"],
     },
@@ -481,6 +496,7 @@ registerTool({
         const datetime = localToUtcIso(String(args.datetime), timezone);
         const lat = args.latitude;
         const lon = args.longitude;
+        const theme = args.theme === "light" ? "light" : "dark";
         const body = {
             birth_datetime_utc: datetime,
         };
@@ -493,7 +509,7 @@ registerTool({
             client.request("POST", "/human-design/chart", {
                 data: body,
             }),
-            fetchGoBodygraphSVG(body),
+            fetchGoBodygraphSVG(body, theme),
         ]);
         const chart = chartData.chart ?? chartData;
         const modelPayload = buildHdModelPayload(chart, {

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

@@ -199,11 +199,17 @@ registerTool({
         }, houseSystem, undefined, requestedBodies);
         const bundleAvailable = Boolean(getChartWheelBundle());
         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. Keep `structuredContent`
+            // so non-rendering hosts still get the data, and a text summary so chat
+            // transcripts read coherently.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) },
                 ],
+                structuredContent: { ...modelPayload, server_version: SERVER_VERSION },
                 _meta: {
                     "ui/resourceUri": CHART_WHEEL_RESOURCE_URI,
                     ui: { resourceUri: CHART_WHEEL_RESOURCE_URI },
@@ -414,8 +420,26 @@ function zodSignFromLon(lon) {
 const CLASSICAL_PLANETS = new Set([
     "sun", "moon", "mercury", "venus", "mars",
     "jupiter", "saturn", "uranus", "neptune", "pluto",
-    "chiron", "north_node", "south_node", "true_node", "asc", "mc",
+    // Nodes use space form to match the renderer's glyph table (chart-renderer.ts).
+    "chiron", "north node", "south node", "true node", "asc", "mc",
 ]);
+/**
+ * Canonicalise the Go backend's verbose node keys ("North Node (Mean)" /
+ * "North Node (True)") to the space-form names the renderer expects, keeping
+ * mean vs true DISTINCT. Without this the natal wheel dropped the nodes entirely
+ * (the raw key never matched the classical-planet set). All other body names are
+ * returned lowercased and otherwise unchanged.
+ */
+function canonicalizeBodyName(raw) {
+    const lower = raw.toLowerCase().trim();
+    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)" || lower === "south node")
+        return "south node";
+    return lower;
+}
 const EXTENDED_BODIES = new Set([
     "mean_lilith", "lilith", "true_lilith",
     "ceres", "juno", "vesta", "pallas", "pholus",
@@ -487,19 +511,19 @@ function buildModelPayload(chartData, birthParams, houseSystem, svgBase, bodyFil
     if (rawPlanets && typeof rawPlanets === "object" && !Array.isArray(rawPlanets)) {
         planetsArray = Object.entries(rawPlanets)
             .filter(([k]) => {
-            const key = k.toLowerCase();
+            const key = canonicalizeBodyName(k);
             // If specific bodies were requested, use that filter
             if (bodyFilter) {
                 const wantsAll = bodyFilter.some(b => b.toLowerCase() === "all");
                 if (wantsAll)
                     return ALL_KNOWN_BODIES.has(key);
-                return bodyFilter.some(b => b.toLowerCase() === key);
+                return bodyFilter.some(b => canonicalizeBodyName(b) === key);
             }
             // Default: classical planets only
             return CLASSICAL_PLANETS.has(key);
         })
             .map(([name, p]) => ({
-            name: name.toLowerCase(),
+            name: canonicalizeBodyName(name),
             longitude: (p.longitude ?? p.lon ?? 0),
             latitude: (p.latitude ?? p.lat),
             speed: (p.longitude_speed ?? p.speed),

package/dist/tools/apps/location-tools.js

@@ -3,13 +3,29 @@ import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 registerTool({
     name: "location_search",
-    description: "App-only tool for getting location autocomplete suggestions. Returns latitude, longitude, and IANA timezone.",
+    description: "App-only tool for getting location autocomplete suggestions. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Optional bias params (country/region/near) improve ranking; a trailing \"City, ST\" qualifier in the query is also honored.",
     inputSchema: {
         type: "object",
         properties: {
             query: {
                 type: "string",
-                description: "Search query for location, e.g. 'Los Angeles'",
+                description: "Search query for location, e.g. 'Los Angeles' or 'Wakefield, MI'",
+            },
+            country: {
+                type: "string",
+                description: "Optional ISO 3166-1 alpha-2 country code (e.g. 'US') to bias ranking. Boost, not filter.",
+            },
+            region: {
+                type: "string",
+                description: "Optional admin1 (state/province) qualifier to bias ranking — full name ('Michigan'), ASCII name, or code ('MI'). Boost, not filter.",
+            },
+            admin1: {
+                type: "string",
+                description: "Alias for region (region wins if both supplied).",
+            },
+            near: {
+                type: "string",
+                description: "Optional 'lat,lon' proximity hint (e.g. '37.77,-122.42') to bias ranking toward nearby places.",
             },
         },
         required: ["query"],
@@ -23,9 +39,26 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["query"]);
-        return await getActiveClient().request("GET", "/location/autocomplete", {
-            params: { q: args.query },
-        });
+        // NB: the endpoint param is `query` (only /geocode/search reads `q`).
+        const params = { query: args.query };
+        for (const k of ["country", "region", "admin1", "near"]) {
+            if (args[k] != null && String(args[k]).trim() !== "")
+                params[k] = String(args[k]);
+        }
+        const raw = (await getActiveClient().request("GET", "/location/autocomplete", { params }));
+        // Map the API's snake_case response to the camelCase shape the app UI consumes.
+        const list = Array.isArray(raw?.suggestions) ? raw.suggestions : [];
+        const suggestions = list.map((s) => ({
+            displayName: s.display_name,
+            shortName: s.short_name,
+            region: s.region,
+            countryCode: s.country_code,
+            placeId: s.place_id,
+            latitude: s.latitude,
+            longitude: s.longitude,
+            timezone: s.timezone,
+        }));
+        return { suggestions };
     },
 });
 registerTool({

package/dist/tools/apps/moon-phase-app.js

@@ -227,11 +227,17 @@ registerTool({
         const summary = buildMoonSummary(mergedData);
         const bundleAvailable = Boolean(getMoonPhaseBundle());
         if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block. An embedded
+            // `type: "resource"` block must carry inline text/blob per the base MCP
+            // schema, so a URI-only reference fails strict client validation; the
+            // _meta keys below are what the host uses to render the iframe.
+            // structuredContent carries the data payload for non-rendering hosts.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify(uiPayload) },
                 ],
+                structuredContent: uiPayload,
                 _meta: {
                     "ui/resourceUri": MOON_PHASE_RESOURCE_URI,
                     ui: { resourceUri: MOON_PHASE_RESOURCE_URI },