@openephemeris/mcp-server 3.10.3 → 3.12.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.10.4] — 2026-04-24
+
+### Changed
+- `ephemeris_transits` tool description updated with compute surcharge and search range limit documentation
+- `dev_call` credit cost reference now includes compute surcharge information
+- Tier-based compute timeouts: Explorer 30s, Developer 120s, Startup 5m, Scale 10m for compute-heavy endpoints
+- Search range caps: `/predictive/transits/search` limited to 1y (Explorer), 5y (Developer), 10y (Startup)
+- Compute surcharges: requests exceeding 30s incur 1 additional credit per 30s of wall-clock compute
+- Daily credit caps now persistent across server restarts (PostgreSQL-backed)
+
+---
+
 ## [3.10.0] — 2026-04-23
 
 ### Added

package/README.md

@@ -353,8 +353,8 @@ When you update the MCP server logic (handlers, bug fixes, hardening), you shoul
 
 Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live tool registry.
 
-- Allowlisted operations: **23**
-- Methods: `GET=4`, `POST=19`, `PUT=0`, `PATCH=0`, `DELETE=0`
+- Allowlisted operations: **28**
+- Methods: `GET=4`, `POST=24`, `PUT=0`, `PATCH=0`, `DELETE=0`
 - Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **57**
 - Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `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_natal_chart`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
@@ -364,6 +364,7 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 | Family | Operations | Example |
 |---|---:|---|
 | `acg` | 4 | `POST /acg/ccg`, `POST /acg/hits` |
+| `chinese` | 5 | `POST /chinese/bazi/compatibility`, `POST /chinese/bazi/element-balance` |
 | `comparative` | 5 | `POST /comparative/composite`, `POST /comparative/composite/midpoint` |
 | `electional` | 4 | `GET /electional/aspect-search`, `GET /electional/find-window` |
 | `ephemeris` | 1 | `POST /ephemeris/relocation` |

package/config/dev-allowlist.json

@@ -31,6 +31,26 @@
       "method": "POST",
       "path": "/acg/power-lines"
     },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/compatibility"
+    },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/element-balance"
+    },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/luck-pillars"
+    },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/solar-terms"
+    },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/ten-gods"
+    },
     {
       "method": "POST",
       "path": "/comparative/composite/midpoint"
@@ -108,8 +128,8 @@
       "path": "/visualization/chart-wheel"
     }
   ],
-  "last_generated_at": "2026-04-22T15:19:21.508Z",
-  "openapi_sha256": "0c29ad2e37fd08d48800ec54059e262fbbdb681b844e00fed9274611bae678ac",
+  "last_generated_at": "2026-04-25T17:47:00.681Z",
+  "openapi_sha256": "9b2a79811fef658557233fc649b598178488985708b3ad10f252be598567080a",
   "candidates_get": [
     {
       "method": "GET",
@@ -391,6 +411,14 @@
       ],
       "operationId": "reverse_geocode_location_reverse_get"
     },
+    {
+      "method": "GET",
+      "path": "/tidal/forcing/deep-time",
+      "tags": [
+        "tidal"
+      ],
+      "operationId": "get_tidal_forcing_deep_time_endpoint_tidal_forcing_deep_time_get"
+    },
     {
       "method": "GET",
       "path": "/tidal/forcing",
@@ -521,6 +549,54 @@
       ],
       "operationId": "power_lines_acg_power_lines_post"
     },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/annual-pillar",
+      "tags": [
+        "chinese"
+      ],
+      "operationId": "bazi_annual_pillar_chinese_bazi_annual_pillar_post"
+    },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/compatibility",
+      "tags": [
+        "chinese"
+      ],
+      "operationId": "bazi_compatibility_chinese_bazi_compatibility_post"
+    },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/element-balance",
+      "tags": [
+        "chinese"
+      ],
+      "operationId": "bazi_element_balance_chinese_bazi_element_balance_post"
+    },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/luck-pillars",
+      "tags": [
+        "chinese"
+      ],
+      "operationId": "bazi_luck_pillars_chinese_bazi_luck_pillars_post"
+    },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/solar-terms",
+      "tags": [
+        "chinese"
+      ],
+      "operationId": "bazi_solar_terms_chinese_bazi_solar_terms_post"
+    },
+    {
+      "method": "POST",
+      "path": "/chinese/bazi/ten-gods",
+      "tags": [
+        "chinese"
+      ],
+      "operationId": "bazi_ten_gods_chinese_bazi_ten_gods_post"
+    },
     {
       "method": "POST",
       "path": "/chinese/bazi",
@@ -994,6 +1070,11 @@
       "Non-GET allowlisted: POST /acg/hits",
       "Non-GET allowlisted: POST /acg/local-space",
       "Non-GET allowlisted: POST /acg/power-lines",
+      "Non-GET allowlisted: POST /chinese/bazi/compatibility",
+      "Non-GET allowlisted: POST /chinese/bazi/element-balance",
+      "Non-GET allowlisted: POST /chinese/bazi/luck-pillars",
+      "Non-GET allowlisted: POST /chinese/bazi/solar-terms",
+      "Non-GET allowlisted: POST /chinese/bazi/ten-gods",
       "Non-GET allowlisted: POST /comparative/composite/midpoint",
       "Non-GET allowlisted: POST /comparative/composite",
       "Non-GET allowlisted: POST /comparative/natal-transits",

package/dist/index.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { initTools, toolRegistry, formatToolResponse } from "./tools/index.js";
+import { initTools, toolRegistry, formatToolResponse, modelVisibleTools } from "./tools/index.js";
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
 function resolveServerVersion() {
     try {
@@ -41,7 +41,7 @@ const server = new Server({
 // List available tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
-        tools: Object.values(toolRegistry).map((tool) => ({
+        tools: modelVisibleTools().map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,

package/dist/server-sse.js

@@ -22,7 +22,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
-import { initTools, toolRegistry, formatToolResponse } from "./tools/index.js";
+import { initTools, toolRegistry, formatToolResponse, modelVisibleTools } from "./tools/index.js";
 import { BackendClient, runWithClient } from "./backend/client.js";
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
 // ---------------------------------------------------------------------------
@@ -193,7 +193,7 @@ function createMcpServer() {
     });
     // --- Tool handlers ---
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: Object.values(toolRegistry).map((tool) => ({
+        tools: modelVisibleTools().map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -315,7 +315,7 @@ async function main() {
     // Spec: https://smithery.ai/docs/build/publish#server-scanning
     // ---------------------------------------------------------------------------
     app.get("/.well-known/mcp/server-card.json", (_req, res) => {
-        const tools = Object.values(toolRegistry).map((tool) => ({
+        const tools = modelVisibleTools().map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,

package/dist/tools/apps/chart-wheel-app.d.ts

@@ -1,12 +1,16 @@
 /**
  * chart-wheel-app.ts — MCP App tool registration for the Chart Wheel Explorer.
  *
- * Registers 5 tools:
- *   • explore_natal_chart         — primary entry point, returns data + UI resource
- *   • chart_wheel_on_planet_click — event handler for planet clicks
- *   • chart_wheel_on_house_click  — event handler for house clicks
- *   • chart_wheel_on_aspect_click — event handler for aspect clicks
- *   • chart_wheel_recalculate     — recalculates with a different house system
+ * Registers 7 tools:
+ *   • explore_natal_chart          — primary entry point, returns data + UI resource [model]
+ *   • chart_wheel_fetch_svg        — lazy SVG fetcher called by UI on first render [app-only]
+ *   • chart_wheel_on_planet_click  — planet click handler [app-only]
+ *   • chart_wheel_on_house_click   — house click handler [app-only]
+ *   • chart_wheel_on_aspect_click  — aspect click handler [app-only]
+ *   • chart_wheel_recalculate      — house-system switcher [app-only]
+ *
+ * SVG payloads are NEVER embedded in model-facing text blocks. The UI calls
+ * chart_wheel_fetch_svg lazily to keep Claude's context lean.
  *
  * Also exports resource helpers (getChartWheelBundle, etc.) for use in
  * index.ts and server-sse.ts.

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

@@ -1,12 +1,16 @@
 /**
  * chart-wheel-app.ts — MCP App tool registration for the Chart Wheel Explorer.
  *
- * Registers 5 tools:
- *   • explore_natal_chart         — primary entry point, returns data + UI resource
- *   • chart_wheel_on_planet_click — event handler for planet clicks
- *   • chart_wheel_on_house_click  — event handler for house clicks
- *   • chart_wheel_on_aspect_click — event handler for aspect clicks
- *   • chart_wheel_recalculate     — recalculates with a different house system
+ * Registers 7 tools:
+ *   • explore_natal_chart          — primary entry point, returns data + UI resource [model]
+ *   • chart_wheel_fetch_svg        — lazy SVG fetcher called by UI on first render [app-only]
+ *   • chart_wheel_on_planet_click  — planet click handler [app-only]
+ *   • chart_wheel_on_house_click   — house click handler [app-only]
+ *   • chart_wheel_on_aspect_click  — aspect click handler [app-only]
+ *   • chart_wheel_recalculate      — house-system switcher [app-only]
+ *
+ * SVG payloads are NEVER embedded in model-facing text blocks. The UI calls
+ * chart_wheel_fetch_svg lazily to keep Claude's context lean.
  *
  * Also exports resource helpers (getChartWheelBundle, etc.) for use in
  * index.ts and server-sse.ts.
@@ -55,6 +59,22 @@ export function getChartWheelBundle() {
 export function clearBundleCache() {
     cachedBundle = null;
 }
+// ── Per-request SVG cache (serves chart_wheel_fetch_svg lazily) ────────────
+// Keyed by "datetime|lat|lon|houseSystem". Bounded to last 50 renders.
+const SVG_CACHE_MAX = 50;
+const cachedSvgMap = new Map();
+function buildSvgCacheKey(datetime, lat, lon, houseSystem) {
+    return `${datetime}|${lat ?? 0}|${lon ?? 0}|${houseSystem}`;
+}
+function cacheSetSvg(key, svg) {
+    if (cachedSvgMap.size >= SVG_CACHE_MAX) {
+        // Evict oldest entry
+        const first = cachedSvgMap.keys().next().value;
+        if (first !== undefined)
+            cachedSvgMap.delete(first);
+    }
+    cachedSvgMap.set(key, svg);
+}
 // ── House system helpers ───────────────────────────────────────────────────
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
@@ -136,39 +156,26 @@ registerTool({
         const lat = args.latitude;
         const lon = args.longitude;
         const natalBody = buildNatalBody(datetime, lat, lon, houseSystem, args.timezone);
-        // Parallel: fetch JSON data + SVG visual
-        const [chartData, svgBinary] = await Promise.all([
-            client.post("/ephemeris/natal-chart", natalBody),
-            client.post(`/visualization/chart-wheel?format=svg&size=800`, { ...natalBody, style: "light" }).catch(() => null),
-        ]);
-        // Decode SVG from binary response (base64 → UTF-8 string)
-        let svgString = null;
-        if (svgBinary && typeof svgBinary === "object" && svgBinary.encoding === "base64" && svgBinary.data_base64) {
-            svgString = Buffer.from(svgBinary.data_base64, "base64").toString("utf-8");
-        }
-        // Build the enriched chart payload for the UI
-        const uiPayload = {
-            ...chartData,
-            _svg_base: svgString,
-            _birth_params: {
-                datetime,
-                timezone: args.timezone ?? null,
-                latitude: lat ?? null,
-                longitude: lon ?? null,
-                location: args.location ?? null,
-            },
-            house_system: houseSystem,
-        };
-        // Build human-readable summary for the LLM context / fallback text
+        // Fetch natal chart JSON. The chart is rendered client-side in the UI iframe,
+        // so we do NOT call the /visualization/chart-wheel endpoint — that was the
+        // source of the ~90 second blocking delay.
+        const chartData = await client.post("/ephemeris/natal-chart", natalBody);
+        // Build human-readable summary for the LLM context
         const summary = buildChartSummary(chartData, String(args.location ?? `${lat}, ${lon}`));
-        // Check if the UI bundle is available
+        // Build the UI payload (planets normalised to array, aspects computed)
+        const modelPayload = buildModelPayload(chartData, {
+            datetime,
+            timezone: args.timezone ?? null,
+            latitude: lat ?? null,
+            longitude: lon ?? null,
+            location: args.location ?? null,
+        }, houseSystem);
         const bundleAvailable = Boolean(getChartWheelBundle());
         if (bundleAvailable) {
-            // Return: text fallback + JSON payload + resource reference
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify(uiPayload) },
+                    { type: "text", text: JSON.stringify(modelPayload) },
                     {
                         type: "resource",
                         resource: {
@@ -183,17 +190,14 @@ registerTool({
                 },
             };
         }
-        // Fallback: text summary + static SVG image block
-        const content = [
-            { type: "text", text: summary },
-        ];
-        if (svgString) {
-            const b64 = Buffer.from(svgString).toString("base64");
-            content.push({ type: "image", data: b64, mimeType: "image/svg+xml" });
-        }
-        return { content };
+        // Fallback: text summary only (non-App hosts; no SVG available here)
+        return { content: [{ type: "text", text: summary }] };
     },
 });
+// ── chart_wheel_fetch_svg removed ────────────────────────────────────────────
+// SVG is now embedded inline in the explore_natal_chart payload (_svg_base).
+// The UI fast-path in main.ts checks _svg_base first and skips the tool call.
+// The SVG cache is retained for chart_wheel_recalculate house system switches.
 // ── Tool: chart_wheel_on_planet_click ──────────────────────────────────────
 registerTool({
     name: "chart_wheel_on_planet_click",
@@ -214,6 +218,7 @@ registerTool({
         required: ["planet", "longitude"],
     },
     annotations: { title: "Planet Interpretation", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const planet = String(args.planet);
         const sign = args.sign ? String(args.sign) : zodSignFromLon(Number(args.longitude));
@@ -247,6 +252,7 @@ registerTool({
         required: ["house_number"],
     },
     annotations: { title: "House Interpretation", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const num = Number(args.house_number);
         const sign = args.sign ? String(args.sign) : "";
@@ -281,6 +287,7 @@ registerTool({
         required: ["planet1", "planet2"],
     },
     annotations: { title: "Aspect Interpretation", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const p1 = capitalize(String(args.planet1));
         const p2 = capitalize(String(args.planet2));
@@ -319,6 +326,7 @@ registerTool({
         required: ["datetime", "latitude", "longitude", "house_system"],
     },
     annotations: { title: "Recalculate Chart", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
         const houseSystem = String(args.house_system);
@@ -326,17 +334,11 @@ registerTool({
         const lat = args.latitude;
         const lon = args.longitude;
         const natalBody = buildNatalBody(datetime, lat, lon, houseSystem, args.timezone);
-        const [chartData, svgBinary] = await Promise.all([
-            client.post("/ephemeris/natal-chart", natalBody),
-            client.post(`/visualization/chart-wheel?format=svg&size=800`, { ...natalBody, style: "light" }).catch(() => null),
-        ]);
-        let svgString = null;
-        if (svgBinary && typeof svgBinary === "object" && svgBinary.encoding === "base64" && svgBinary.data_base64) {
-            svgString = Buffer.from(svgBinary.data_base64, "base64").toString("utf-8");
-        }
-        const uiPayload = {
+        // Fetch updated chart JSON only — chart renders client-side in the iframe
+        const chartData = await client.post("/ephemeris/natal-chart", natalBody);
+        // Return only chart data (no SVG) — the UI calls chart_wheel_fetch_svg
+        const payload = {
             ...chartData,
-            _svg_base: svgString,
             _birth_params: {
                 datetime,
                 timezone: args.timezone ?? null,
@@ -347,7 +349,7 @@ registerTool({
             house_system: houseSystem,
         };
         return {
-            content: [{ type: "text", text: JSON.stringify(uiPayload) }],
+            content: [{ type: "text", text: JSON.stringify(payload) }],
         };
     },
 });
@@ -365,6 +367,97 @@ function zodSignFromLon(lon) {
         "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"];
     return signs[Math.floor(((lon % 360) + 360) % 360 / 30)];
 }
+const CLASSICAL_PLANETS = new Set([
+    "sun", "moon", "mercury", "venus", "mars",
+    "jupiter", "saturn", "uranus", "neptune", "pluto",
+    "chiron", "north_node", "south_node", "true_node", "asc", "mc",
+]);
+/**
+ * Build a lean, SVG-free payload for Claude's text context.
+ * Strips SVG, filters to classical planets only, and packages birth params.
+ * Tokens saved vs. full uiPayload: ~85–95% reduction (no 100KB SVG, no asteroid flood).
+ */
+/**
+ * Compute major aspects between a set of planets.
+ * Returns a structured AspectData[] array — the natal chart API does not
+ * include aspects in its JSON response; we derive them from longitude data.
+ */
+function computeAspects(planets) {
+    const ASPECTS = [
+        { type: "conjunction", angle: 0, orb: 8 },
+        { type: "opposition", angle: 180, orb: 8 },
+        { type: "trine", angle: 120, orb: 8 },
+        { type: "square", angle: 90, orb: 7 },
+        { type: "sextile", angle: 60, orb: 6 },
+        { type: "quincunx", angle: 150, orb: 3 },
+        { type: "semisquare", angle: 45, orb: 2 },
+    ];
+    const results = [];
+    for (let i = 0; i < planets.length; i++) {
+        for (let j = i + 1; j < planets.length; j++) {
+            const p1 = planets[i];
+            const p2 = planets[j];
+            // Angular separation: shortest arc (0–180)
+            let diff = Math.abs(p1.longitude - p2.longitude) % 360;
+            if (diff > 180)
+                diff = 360 - diff;
+            for (const asp of ASPECTS) {
+                const orb = Math.abs(diff - asp.angle);
+                if (orb <= asp.orb) {
+                    // Applying: combined longitudinal speed closing the orb
+                    const applying = ((p1.speed ?? 1) - (p2.speed ?? 0)) < 0 ? diff < asp.angle : diff > asp.angle;
+                    results.push({
+                        planet1: p1.name,
+                        planet2: p2.name,
+                        type: asp.type,
+                        angle: asp.angle,
+                        orb: Math.round(orb * 100) / 100,
+                        applying,
+                    });
+                    break; // Each pair only matches one aspect type
+                }
+            }
+        }
+    }
+    return results;
+}
+function buildModelPayload(chartData, birthParams, houseSystem, svgBase) {
+    // ── 1. Normalize planets: keyed object → typed PlanetData array ──────────
+    // The natal API returns { sun: { longitude, sign_name, is_retrograde, ... }, moon: {...} }.
+    // The chart wheel UI expects PlanetData[] with canonical field names.
+    const rawPlanets = chartData.planets;
+    let planetsArray = [];
+    if (rawPlanets && typeof rawPlanets === "object" && !Array.isArray(rawPlanets)) {
+        planetsArray = Object.entries(rawPlanets)
+            .filter(([k]) => CLASSICAL_PLANETS.has(k.toLowerCase()))
+            .map(([name, p]) => ({
+            name: name.toLowerCase(),
+            longitude: (p.longitude ?? p.lon ?? 0),
+            latitude: (p.latitude ?? p.lat),
+            speed: (p.longitude_speed ?? p.speed),
+            retrograde: Boolean(p.is_retrograde ?? p.retrograde),
+            sign: (p.sign_name ?? p.sign),
+            house: (p.house),
+        }));
+    }
+    else if (Array.isArray(chartData.planets)) {
+        // Already normalised (e.g. house system recalculate path)
+        planetsArray = chartData.planets;
+    }
+    // ── 2. Compute aspects from longitude data (API doesn't return them) ──────
+    const aspects = computeAspects(planetsArray);
+    return {
+        ...chartData,
+        // Typed array replaces the keyed object — the renderer can now iterate it
+        planets: planetsArray,
+        // Structured aspect array — powers highlighting and info panel
+        aspects,
+        // Embed SVG for fast first-render in the iframe.
+        _svg_base: svgBase ?? undefined,
+        _birth_params: birthParams,
+        house_system: houseSystem,
+    };
+}
 function buildChartSummary(data, location) {
     // The natal API returns planets as a keyed object { sun: {...}, moon: {...} }.
     // Normalise to an array before processing.
@@ -373,12 +466,65 @@ function buildChartSummary(data, location) {
         ? raw
         : Object.entries(raw).map(([name, p]) => ({
             name,
-            sign: p.sign,
+            sign: (p.sign_name ?? p.sign),
             house: p.house,
-            retrograde: Boolean(p.retrograde),
+            retrograde: Boolean(p.is_retrograde ?? p.retrograde),
+            longitude: p.longitude,
+            longitude_speed: p.longitude_speed,
         }));
-    const lines = planetsArray.slice(0, 10).map((p) => `• **${capitalize(p.name)}** in ${p.sign ?? "?"} (H${p.house ?? "?"})${p.retrograde ? " ℞" : ""}`);
+    const CLASSICAL_ORDER = [
+        "sun", "moon", "mercury", "venus", "mars",
+        "jupiter", "saturn", "uranus", "neptune", "pluto",
+        "chiron", "north_node", "south_node", "true_node", "asc", "mc",
+    ];
+    planetsArray.sort((a, b) => {
+        const ai = CLASSICAL_ORDER.indexOf(a.name.toLowerCase());
+        const bi = CLASSICAL_ORDER.indexOf(b.name.toLowerCase());
+        if (ai !== -1 && bi !== -1)
+            return ai - bi;
+        if (ai !== -1)
+            return -1;
+        if (bi !== -1)
+            return 1;
+        return a.name.localeCompare(b.name);
+    });
+    const lines = planetsArray.slice(0, 12).map((p) => `• **${capitalize(p.name)}** in ${p.sign ?? "?"} (H${p.house ?? "?"})${p.retrograde ? " ℞" : ""}`);
+    // ── Enrichment: sect, element tally, strongest aspect ──────────────────
+    const sun = planetsArray.find((p) => p.name.toLowerCase() === "sun");
+    const ascLon = data.ascendant;
+    const sunLon = sun?.longitude;
+    let sectNote = "";
+    if (sunLon != null && ascLon != null) {
+        // Day chart: Sun above horizon (houses 7–12, i.e. longitude within 180° of ASC going upper half)
+        const sunRelative = ((sunLon - ascLon) + 360) % 360;
+        sectNote = sunRelative < 180 ? "Day chart ☀️" : "Night chart 🌙";
+    }
+    const ELEMENT_MAP = {
+        aries: "fire", leo: "fire", sagittarius: "fire",
+        taurus: "earth", virgo: "earth", capricorn: "earth",
+        gemini: "air", libra: "air", aquarius: "air",
+        cancer: "water", scorpio: "water", pisces: "water",
+    };
+    const elementCount = { fire: 0, earth: 0, air: 0, water: 0 };
+    for (const p of planetsArray.slice(0, 10)) {
+        const sign = (p.sign ?? "").toLowerCase();
+        const el = ELEMENT_MAP[sign];
+        if (el)
+            elementCount[el]++;
+    }
+    const domElement = Object.entries(elementCount).sort((a, b) => b[1] - a[1])[0];
+    // Strongest aspect by tightest orb (use computed aspects from planetsArray)
+    const aspects = computeAspects(planetsArray
+        .filter((p) => p.longitude != null)
+        .map((p) => ({ name: p.name, longitude: p.longitude, speed: p.longitude_speed })));
+    const strongest = aspects.sort((a, b) => a.orb - b.orb)[0];
+    const strongestNote = strongest
+        ? `Closest aspect: ${capitalize(strongest.planet1)} ${strongest.type} ${capitalize(strongest.planet2)} (${strongest.orb.toFixed(1)}° orb)`
+        : "";
+    const enrichment = [sectNote, domElement ? `Dominant element: ${domElement[0]} (${domElement[1]})` : "", strongestNote]
+        .filter(Boolean).join(" · ");
     return (`**Natal Chart — ${location}**\n\n` +
+        (enrichment ? `${enrichment}\n\n` : "") +
         `Key Placements:\n${lines.join("\n")}\n\n` +
         "Click any planet, house, or aspect line for interpretation.");
 }

package/dist/tools/dev.js

@@ -47,6 +47,7 @@ registerTool({
         "  • ACG / astrocartography: 10 credits (acg/hits: 15 credits)\n" +
         "  • Calendar endpoints: 10 credits\n" +
         "  • Catalog / metadata / health endpoints: 0 credits\n" +
+        "  • Compute surcharge: requests > 30s add 1 credit per 30s (predictive, acg, calendar, electional)\n" +
         "  • format=llm (token-optimized output): available on all tiers\n\n" +
         "COMMON CALLS:\n" +
         "  POST /ephemeris/natal-chart            — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}})\n" +

package/dist/tools/index.d.ts

@@ -10,8 +10,25 @@ export interface ToolDefinition {
         idempotentHint?: boolean;
         openWorldHint?: boolean;
     };
+    /**
+     * UI metadata — mirrors the ext-apps SDK _meta.ui shape.
+     * When visibility includes "app" only (not "model"), the tool is hidden from
+     * Claude's tool list (ListTools) but remains callable by the UI via callServerTool().
+     */
+    _meta?: {
+        ui?: {
+            resourceUri?: string;
+            /** SDK visibility array — use ["app"] to hide from model, ["model"] for model-only. */
+            visibility?: Array<"app" | "model">;
+        };
+    };
     handler: (args: any) => Promise<any>;
 }
+/**
+ * Returns tools that should be exposed to Claude in the ListTools response.
+ * Filters out tools that have visibility restricted to the UI (app-only).
+ */
+export declare function modelVisibleTools(): ToolDefinition[];
 export declare const toolRegistry: Record<string, ToolDefinition>;
 export declare function registerTool(tool: ToolDefinition): void;
 export type ToolProfile = "dev" | "legacy";

package/dist/tools/index.js

@@ -1,3 +1,16 @@
+/**
+ * Returns tools that should be exposed to Claude in the ListTools response.
+ * Filters out tools that have visibility restricted to the UI (app-only).
+ */
+export function modelVisibleTools() {
+    return Object.values(toolRegistry).filter((t) => {
+        const vis = t._meta?.ui?.visibility;
+        // If visibility is explicitly ["app"] (no "model"), hide from model
+        if (vis && !vis.includes("model") && vis.includes("app"))
+            return false;
+        return true;
+    });
+}
 export const toolRegistry = {};
 export function registerTool(tool) {
     toolRegistry[tool.name] = tool;

package/dist/tools/specialized/transits.js

@@ -15,7 +15,10 @@ registerTool({
         "  Example: Chiron Return → transiting_planets=['chiron'], natal_points=['chiron'], aspect_angle=0\n\n" +
         "SUPPORTED BODIES: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, " +
         "Pluto, Chiron, Pholus, Ceres, Pallas, Juno, Vesta, MeanNode.\n\n" +
-        "CREDIT COST: 6 credits per call (1 for natal + 5 for transit search).\n\n" +
+        "CREDIT COST: 6 credits per call (1 for natal + 5 for transit search). " +
+        "Requests exceeding 30 seconds incur 1 additional credit per 30s of compute time.\n\n" +
+        "SEARCH RANGE LIMITS: Explorer tier is limited to 1-year windows; Developer to 5 years. " +
+        "Ranges exceeding the limit are silently clamped.\n\n" +
         "EXAMPLE: Find all Saturn transits to the natal Sun/Moon for the next 6 months:\n" +
         "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
         "  start_date='2026-01-01', end_date='2026-06-30', transiting_planets=['saturn']",