@openephemeris/mcp-server 4.17.0 → 4.19.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.19.0] — 2026-09-27
+
+### Changed
+- **The Human Design bodygraph is easier to read.** Gate numbers use a clean sans-serif and are
+  noticeably larger at chat width; the Design and Personality planet columns sit close to the body
+  under their own headings; open centres use the theme's colour instead of glaring white; channels
+  defined from both sides are drawn as two parallel stripes (Design red beside Personality); the
+  mandala's body is about 1.3× larger inside its rings.
+- **Select a single activation.** Clicking a planet row (for example Personality Moon) highlights
+  only that activation's gate, stub and channel, never its Design twin. The rendered SVG tags every
+  element by side and activation, so your own CSS can do the same.
+- **Every chart widget fits the chat better.** Widgets size themselves from the host; scrolling the
+  conversation past a chart scrolls instead of zooming (zoom with Ctrl/Cmd + scroll or a pinch); the
+  fullscreen button only appears where the host supports fullscreen; moon phase and transit timeline
+  support picture-in-picture; fullscreen uses one shared layout that stacks into a single column on
+  phones; all seven widgets share one colour and font set, and the host draws the card border.
+
+### Fixed
+- Changing theme no longer drops a widget out of fullscreen.
+- On moon phase and transit timeline, the info button no longer covers the fullscreen button.
+- Bodygraph hover highlights work again.
+- Widget resources are versioned, so hosts that cache them (such as ChatGPT) pick up new widget
+  versions after an update without reinstalling the app.
+
+## [4.18.0] — 2026-09-26
+
+### Fixed
+- **`explore_bi_wheel` progressed, solar return and lunar return modes work again.** They sent
+  requests the API rejected ("Validation failed" / "birth_datetime is required"); all six modes now
+  return a chart.
+- **Solar arc directions are exact.** `explore_bi_wheel` mode `solar_arc` used a flat ~1°-per-year
+  estimate and left the houses at their birth positions. It now uses the Sun's real arc from the API:
+  every planet, angle and house cusp is directed by the same arc, with correct signs and houses.
+  `ephemeris_progressed_chart` with `method: "solar_arc"` directs the angles and house cusps too.
+- **Every lunar node is named Mean or True.** The charts show "North Node (Mean)", "North Node
+  (True)", "South Node (Mean)" and "South Node (True)" as four separate points. The two South Nodes
+  used to merge into one, and the mean North Node was shown as a bare "North Node". The Mean/True
+  toggle now applies to the South Node as well.
+- **Bi-wheel recalculation keeps the house system you choose** for the outer chart too (it was always
+  Placidus).
+- **Black Moon Lilith appears on the chart wheel, named Mean, True or Interpolated.** Asking
+  `explore_natal_chart` for `lilith` or `lilith_true` returned the chart without it. The three Liliths
+  are now shown as "Lilith (Mean)", "Lilith (True)" and "Lilith (Interpolated)" (new slug
+  `lilith_interpolated`), never merged into one.
+- **`explore_natal_chart` with `bodies: ["all"]` works.** It was rejected because it asked for Vertex and
+  Part of Fortune as extra bodies; "all" now covers every body the chart can add.
+
+### Removed
+- **`include_visual` on `ephemeris_progressed_chart`.** The API never draws a progressed chart
+  image, so the option returned no picture. It was never charged. To see progressions over the natal
+  chart, use `explore_bi_wheel` with mode `progressed`.
+
 ## [4.17.0] — 2026-09-24
 
 ### Added

package/README.md

@@ -212,7 +212,7 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 
 - Missing/invalid credentials (`401`): tool call fails with a message that points users to sign up/sign in at `https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount`, then create/manage keys in `https://openephemeris.com/dashboard?tab=account`.
 - Tier-gated endpoint (`403`): tool call returns an upgrade-required message with `https://openephemeris.com/pay` and dashboard billing/key management link.
-- Monthly quota exhausted (`402`): tool call returns usage quota guidance with both dashboard (`/dashboard?tab=account`) and upgrade (`/pay`) links.
+- Out of credits (`402`): tool call returns a one-tap top-up link (Explorer's 150 free credits are one-time and do not reset; plan allowances renew each billing period) plus the dashboard usage link. Failed calls (any `4xx`/`5xx`) are refunded.
 - Burst/rate limit (`429`): tool call returns retry guidance and links to dashboard usage monitoring.
 
 ## What You Can Ask
@@ -256,13 +256,13 @@ instead of the picture, so nothing breaks, you just don't get the wheel.
 | Tool | What opens | What you can click | Credits |
 |---|---|---|---|
 | `explore_natal_chart` | Natal wheel — planets, houses, aspects, angles | Planets, houses, aspect lines; recalculate with new settings | 1 |
-| `explore_bi_wheel` | Two charts on one wheel: transits, synastry, progressions | Either wheel's planets, houses, and the aspects between them | 2 |
-| `explore_human_design` | Human Design bodygraph, with a mandala view toggle | Centers, gates, channels, planets, variables | 2 |
-| `explore_human_design_transit` | Today's planets laid over a natal bodygraph | Transit-activated channels | 3 |
-| `explore_human_design_connection` | Two bodygraphs combined, every shared channel classified | Connection channels by type | 3 |
+| `explore_bi_wheel` | Two charts on one wheel: transits, synastry, progressions | Either wheel's planets, houses, and the aspects between them | 2 (6 for solar/lunar return) |
+| `explore_human_design` | Human Design bodygraph, with a mandala view toggle | Centers, gates, channels, planets, variables | 4 |
+| `explore_human_design_transit` | Today's planets laid over a natal bodygraph | Transit-activated channels | 5 |
+| `explore_human_design_connection` | Two bodygraphs combined, every shared channel classified | Connection channels by type | 5 |
 | `explore_vedic_chart` | South Indian Rashi grid — sidereal placements and Lagna | Each rashi, for its placements and nakshatras | 3 |
 | `explore_bazi_chart` | Four Pillars (四柱命盘) — Year, Month, Day, Hour | Each pillar | 3 |
-| `explore_transit_timeline` | Upcoming transit hits in date order | Individual hits | 6 |
+| `explore_transit_timeline` | Upcoming transit hits in date order | Individual hits | 6 for up to 1 year (priced by span) |
 | `explore_moon_phase` | Moon dial — illumination, phase, sign, void-of-course | Recalculate for another moment | 3 |
 
 Ask for these the way you'd ask a person: *"show me my chart"*, *"put today's transits over my Human Design"*, *"what's the moon doing right now"*. The model picks the app.
@@ -300,10 +300,10 @@ Screenshots of each are on the way.
 | Lunar return | `ephemeris_lunar_return` | Explorer |
 | Planetary return | `ephemeris_planetary_return` | Explorer |
 | Astrocartography lines | `acg_power_lines` | Developer |
-| ACG hits at location | `acg_hits` | Scale |
+| ACG hits at location | `acg_hits` | Developer |
 | Venus Star Points | `venus_star_points` + 4 more | Explorer |
-| Chart wheel image | `ephemeris_chart_wheel` | Developer |
-| Bi-wheel image | `ephemeris_bi_wheel` | Developer |
+| Chart wheel image | `ephemeris_chart_wheel` | Explorer |
+| Bi-wheel image | `ephemeris_bi_wheel` | Explorer |
 | Dignities / Midpoints / Fixed stars | `ephemeris_dignities`, `ephemeris_midpoints`, `ephemeris_fixed_stars` | Explorer |
 
 ## Tooling Model
@@ -335,7 +335,7 @@ Screenshots of each are on the way.
 | `OPENEPHEMERIS_PROFILE` | No | `dev` by default |
 | `OPENEPHEMERIS_TOOLS` | No | `core` (default) advertises a focused everyday tool set; `full` advertises every tool. See [Tool surface](#tool-surface) |
 | `OPENEPHEMERIS_TELEMETRY` | No | Set to `0`/`false`/`off` to disable anonymous usage reporting. `DO_NOT_TRACK=1` also works. See [Telemetry](#telemetry) |
-| `OPENEPHEMERIS_SERVICE_KEY` | No | Internal service auth |
+| `OPENEPHEMERIS_SERVICE_KEY` | No | Internal service auth (stdio only; the hosted server refuses to start with one and always authenticates as the signed-in user) |
 | `OPENEPHEMERIS_JWT` | No | Bearer token auth |
 | `OPENEPHEMERIS_DEV_ALLOWLIST_PATH` | No | Override allowlist file path |
 | `MCP_USER_ID` | No | Per-instance user identifier |

package/dist/backend/client.d.ts

@@ -6,7 +6,29 @@ export interface BackendConfig {
     apiKey?: string;
     /** Back-compat: previous name for JWT token (Bearer). */
     authToken?: string;
+    /**
+     * When false, the client uses ONLY the credentials passed in this config and
+     * never falls back to the process environment (OPENEPHEMERIS_SERVICE_KEY,
+     * OPENEPHEMERIS_API_KEY, OPENEPHEMERIS_JWT and their legacy aliases).
+     *
+     * The hosted HTTP server builds one client per user session and MUST pass
+     * false: the interceptor sends X-Service-Key ahead of the user's own key, so
+     * an env credential inherited by a per-session client would make every
+     * user's calls unmetered (service key) or billed to one account (API key /
+     * JWT). Defaults to true so the stdio/local server keeps reading its config
+     * from the environment exactly as before.
+     */
+    inheritEnvCredentials?: boolean;
 }
+/** Env vars holding a service key — bypasses metering; never valid on the hosted server. */
+export declare const SERVICE_KEY_ENV_VARS: readonly ["OPENEPHEMERIS_SERVICE_KEY", "ASTROMCP_SERVICE_KEY", "MERIDIAN_SERVICE_KEY"];
+/** Env vars holding one user's credential — on the hosted server they would bill every session to one account. */
+export declare const USER_CREDENTIAL_ENV_VARS: readonly ["OPENEPHEMERIS_API_KEY", "ASTROMCP_API_KEY", "MERIDIAN_API_KEY", "OPENEPHEMERIS_JWT", "ASTROMCP_JWT", "MERIDIAN_AUTH_TOKEN"];
+/** Names of the credential env vars that are set (non-empty) in `env`. */
+export declare function presentCredentialEnvVars(env?: NodeJS.ProcessEnv): {
+    serviceKeys: string[];
+    userCredentials: string[];
+};
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 export interface BackendRequestOptions {
     params?: Record<string, unknown>;
@@ -25,8 +47,33 @@ export declare const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboar
 export declare const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
 export declare const UPGRADE_URL = "https://openephemeris.com/pricing";
 /** One-tap $5 → 150-credit top-up (signs the user in if needed, then redirects to the prefilled Stripe Payment Link). */
-export declare const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5";
+export declare const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5&src=mcp_402";
+/**
+ * The API's 402 carries `upgrade.topup_url`: the same /topup link, signed with
+ * the caller's account so it opens Stripe checkout without a sign-in step
+ * (most people hitting the wall are in ChatGPT/Claude and not signed in on the
+ * site). Use it when present, re-tagged src=mcp_402 so the funnel can tell MCP
+ * clicks from raw API ones; otherwise fall back to the unsigned link.
+ */
+export declare function resolveTopupUrl(apiTopupUrl: unknown): string;
 export declare const WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
+/**
+ * Whether an error body (typically a 422) is really the credit wall: the
+ * detail / type / field codes mention insufficient credits or an exceeded
+ * quota. Checked over the whole serialized body because the signal can sit in
+ * `detail`, `type`, or a nested `errors[].code`.
+ */
+export declare function looksLikeCreditExhaustion(data: unknown, msg?: string): boolean;
+/**
+ * True for errors that mean "this account cannot be charged / is not allowed"
+ * — the credit wall (402), missing auth (401), or a tier gate (403). Tools
+ * that fan out or degrade gracefully must rethrow these instead of swallowing
+ * them: a placeholder result at zero credits hides the paywall (and its
+ * top-up link) from the assistant and reads as real data.
+ */
+export declare function isBillingOrAuthError(err: unknown): err is BackendError;
+/** Rethrows the first billing/auth BackendError among settled results, if any. */
+export declare function rethrowBillingOrAuth(results: PromiseSettledResult<unknown>[]): void;
 export declare class BackendError extends Error {
     readonly status: number;
     readonly code: string;
@@ -59,6 +106,15 @@ export declare class BackendClient {
      * (JWT is the lowest-priority credential in the interceptor).
      */
     setJwt(jwt: string): void;
+    /**
+     * Drop every credential this client holds (service key, API key, JWT). The
+     * hosted HTTP server calls this on the module singleton at startup: the
+     * singleton is what getActiveClient() falls back to outside a session
+     * context, and it was built from the environment at import time.
+     */
+    clearCredentials(): void;
+    /** Which configured credential the interceptor will send (diagnostics/tests). */
+    credentialKind(): "service_key" | "api_key" | "jwt" | null;
     /**
      * Start the device auth flow in the background if not already running.
      * Called automatically when no credentials are found in the interceptor.

package/dist/backend/client.js

@@ -2,6 +2,29 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import axios, { AxiosError } from "axios";
 import { CredentialManager } from "../auth/credentials.js";
 import { DeviceAuthFlow } from "../auth/device-auth.js";
+/** Env vars holding a service key — bypasses metering; never valid on the hosted server. */
+export const SERVICE_KEY_ENV_VARS = [
+    "OPENEPHEMERIS_SERVICE_KEY",
+    "ASTROMCP_SERVICE_KEY",
+    "MERIDIAN_SERVICE_KEY",
+];
+/** Env vars holding one user's credential — on the hosted server they would bill every session to one account. */
+export const USER_CREDENTIAL_ENV_VARS = [
+    "OPENEPHEMERIS_API_KEY",
+    "ASTROMCP_API_KEY",
+    "MERIDIAN_API_KEY",
+    "OPENEPHEMERIS_JWT",
+    "ASTROMCP_JWT",
+    "MERIDIAN_AUTH_TOKEN",
+];
+/** Names of the credential env vars that are set (non-empty) in `env`. */
+export function presentCredentialEnvVars(env = process.env) {
+    const isSet = (name) => typeof env[name] === "string" && env[name].trim() !== "";
+    return {
+        serviceKeys: SERVICE_KEY_ENV_VARS.filter(isSet),
+        userCredentials: USER_CREDENTIAL_ENV_VARS.filter(isSet),
+    };
+}
 const DEFAULT_TIMEOUT_MS = 45_000;
 const RETRY_DELAYS_MS = [1_000, 2_000, 4_000]; // Three retries with backoff
 // NOTE: 429 is intentionally NOT retryable. Every expensive compute endpoint is
@@ -23,8 +46,64 @@ export const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=ac
 export const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
 export const UPGRADE_URL = "https://openephemeris.com/pricing";
 /** One-tap $5 → 150-credit top-up (signs the user in if needed, then redirects to the prefilled Stripe Payment Link). */
-export const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5";
+export const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5&src=mcp_402";
+/**
+ * The API's 402 carries `upgrade.topup_url`: the same /topup link, signed with
+ * the caller's account so it opens Stripe checkout without a sign-in step
+ * (most people hitting the wall are in ChatGPT/Claude and not signed in on the
+ * site). Use it when present, re-tagged src=mcp_402 so the funnel can tell MCP
+ * clicks from raw API ones; otherwise fall back to the unsigned link.
+ */
+export function resolveTopupUrl(apiTopupUrl) {
+    if (typeof apiTopupUrl !== "string")
+        return TOPUP_URL;
+    try {
+        const url = new URL(apiTopupUrl);
+        if (url.protocol !== "https:" || url.hostname !== "openephemeris.com" || url.pathname !== "/topup") {
+            return TOPUP_URL;
+        }
+        url.searchParams.set("src", "mcp_402");
+        return url.toString();
+    }
+    catch {
+        return TOPUP_URL;
+    }
+}
 export const WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
+const CREDIT_EXHAUSTION_RE = /credits?_insufficient|insufficient[ _-]?credits?|not enough credits|out of credits|credits?[ _-]exhausted|quota[ _-]exceeded|usage_quota|requires \d+ credits/i;
+/**
+ * Whether an error body (typically a 422) is really the credit wall: the
+ * detail / type / field codes mention insufficient credits or an exceeded
+ * quota. Checked over the whole serialized body because the signal can sit in
+ * `detail`, `type`, or a nested `errors[].code`.
+ */
+export function looksLikeCreditExhaustion(data, msg) {
+    let text = msg ?? "";
+    try {
+        text += " " + (typeof data === "string" ? data : JSON.stringify(data ?? ""));
+    }
+    catch {
+        // unserializable body — fall back to the message alone
+    }
+    return CREDIT_EXHAUSTION_RE.test(text);
+}
+/**
+ * True for errors that mean "this account cannot be charged / is not allowed"
+ * — the credit wall (402), missing auth (401), or a tier gate (403). Tools
+ * that fan out or degrade gracefully must rethrow these instead of swallowing
+ * them: a placeholder result at zero credits hides the paywall (and its
+ * top-up link) from the assistant and reads as real data.
+ */
+export function isBillingOrAuthError(err) {
+    return err instanceof BackendError && (err.status === 402 || err.status === 401 || err.status === 403);
+}
+/** Rethrows the first billing/auth BackendError among settled results, if any. */
+export function rethrowBillingOrAuth(results) {
+    for (const r of results) {
+        if (r.status === "rejected" && isBillingOrAuthError(r.reason))
+            throw r.reason;
+    }
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -53,22 +132,24 @@ export class BackendClient {
     _authFlowResult = null;
     constructor(config) {
         this.userId = config.userId || "anonymous";
+        // See BackendConfig.inheritEnvCredentials — per-session hosted clients opt out.
+        const env = config.inheritEnvCredentials === false ? {} : process.env;
         this.jwt =
             config.jwt ||
                 config.authToken ||
-                process.env.OPENEPHEMERIS_JWT ||
-                process.env.ASTROMCP_JWT ||
-                process.env.MERIDIAN_AUTH_TOKEN;
+                env.OPENEPHEMERIS_JWT ||
+                env.ASTROMCP_JWT ||
+                env.MERIDIAN_AUTH_TOKEN;
         this.serviceKey =
             config.serviceKey ||
-                process.env.OPENEPHEMERIS_SERVICE_KEY ||
-                process.env.ASTROMCP_SERVICE_KEY ||
-                process.env.MERIDIAN_SERVICE_KEY;
+                env.OPENEPHEMERIS_SERVICE_KEY ||
+                env.ASTROMCP_SERVICE_KEY ||
+                env.MERIDIAN_SERVICE_KEY;
         this.apiKey =
             config.apiKey ||
-                process.env.OPENEPHEMERIS_API_KEY ||
-                process.env.ASTROMCP_API_KEY ||
-                process.env.MERIDIAN_API_KEY;
+                env.OPENEPHEMERIS_API_KEY ||
+                env.ASTROMCP_API_KEY ||
+                env.MERIDIAN_API_KEY;
         this.credentialManager = new CredentialManager();
         this.client = axios.create({
             baseURL: config.baseURL ||
@@ -138,6 +219,27 @@ export class BackendClient {
     setJwt(jwt) {
         this.jwt = jwt;
     }
+    /**
+     * Drop every credential this client holds (service key, API key, JWT). The
+     * hosted HTTP server calls this on the module singleton at startup: the
+     * singleton is what getActiveClient() falls back to outside a session
+     * context, and it was built from the environment at import time.
+     */
+    clearCredentials() {
+        this.serviceKey = undefined;
+        this.apiKey = undefined;
+        this.jwt = undefined;
+    }
+    /** Which configured credential the interceptor will send (diagnostics/tests). */
+    credentialKind() {
+        if (this.serviceKey)
+            return "service_key";
+        if (this.apiKey)
+            return "api_key";
+        if (this.jwt)
+            return "jwt";
+        return null;
+    }
     /**
      * Start the device auth flow in the background if not already running.
      * Called automatically when no credentials are found in the interceptor.
@@ -270,7 +372,12 @@ export class BackendClient {
                     `through Claude's connector settings, your session expired: in Claude's connector ` +
                     `settings, toggle OpenEphemeris off and on to reconnect — this only takes a moment.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
             }
-            if (status === 402) {
+            // A 422 whose body says the caller ran out of credits is the credit wall
+            // wearing a validation status (the Go visual add-on reservation returned
+            // 422 `credits_insufficient` before it moved to 402). Route it through
+            // the same 402 path so the assistant gets the one credit-wall message
+            // and top-up link, not "Validation error: ...".
+            if (status === 402 || (status === 422 && looksLikeCreditExhaustion(data, msg))) {
                 // PRICING SSOT: apps/web/config/billing-plans.ts — Explorer grant
                 // (EXPLORER.creditsNumeric = 150, one-time), Pro/`developer`
                 // (monthlyPrice = 29, credits = 75,000), and CREDIT_TOPUPS
@@ -289,18 +396,21 @@ export class BackendClient {
                 // One direct link, not a dashboard tab: /topup?pack=payg_5 signs the
                 // user in if needed and redirects straight to the prefilled Stripe
                 // Payment Link for the $5 → 150-credit pack.
+                const topupUrl = resolveTopupUrl(dataObj.upgrade?.topup_url);
                 let upsellMsg = "";
-                let actionUrl = TOPUP_URL;
+                let actionUrl = topupUrl;
                 if (currentTier === 'explorer') {
                     upsellMsg =
-                        `Let the user know warmly: Their 150 free credits are used up. ` +
-                            `$5 gets 150 more — one tap: ${TOPUP_URL}. ` +
+                        `Let the user know warmly: Their 150 free credits are used up (they do not reset). ` +
+                            `$5 gets 150 more — one tap, no sign-in, opens checkout directly: ${topupUrl} ` +
+                            `(show this exact link to the user as a clickable link). ` +
                             `Or Pro ($29/mo, 75,000 credits): ${UPGRADE_URL}?plan=developer`;
                 }
                 else if (currentTier === 'payg') {
                     upsellMsg =
                         `Let the user know warmly: Their wallet balance is empty. ` +
-                            `$5 gets 150 more credits — one tap: ${TOPUP_URL}. ` +
+                            `$5 gets 150 more credits — one tap, no sign-in, opens checkout directly: ${topupUrl} ` +
+                            `(show this exact link to the user as a clickable link). ` +
                             `Or Pro ($29/mo, 75,000 credits): ${UPGRADE_URL}?plan=developer`;
                 }
                 else {

package/dist/index.js

@@ -10,14 +10,8 @@ import { buildUiMeta } from "./tools/ui-meta.js";
 import { SERVER_INSTRUCTIONS } from "./instructions.js";
 import { captureEvent, captureFirstToolCallOnce, distinctIdFor } from "./analytics.js";
 import { listPrompts, getPromptContent } from "./prompts.js";
-// ── MCP App resource imports ────────────────────────────────────────────────
-import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
-import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
-import { BI_WHEEL_RESOURCE_URI, BI_WHEEL_MIME_TYPE, getBiWheelBundle, } from "./tools/apps/bi-wheel-app.js";
-import { MOON_PHASE_RESOURCE_URI, MOON_PHASE_MIME_TYPE, getMoonPhaseBundle, } from "./tools/apps/moon-phase-app.js";
-import { TRANSIT_TIMELINE_RESOURCE_URI, TRANSIT_TIMELINE_MIME_TYPE, getTransitTimelineBundle, } from "./tools/apps/transit-timeline-app.js";
-import { VEDIC_CHART_RESOURCE_URI, VEDIC_CHART_MIME_TYPE, getVedicChartBundle, } from "./tools/apps/vedic-chart-app.js";
-import { BAZI_RESOURCE_URI, BAZI_MIME_TYPE, getBaziBundle, } from "./tools/apps/bazi-app.js";
+// ── MCP App resources (list/read registry shared with server-sse.ts) ────────
+import { listUiResources, readUiResource } from "./tools/apps/ui-resources.js";
 // ─────────────────────────────────────────────────────────────────────────────
 function resolveServerVersion() {
     try {
@@ -157,112 +151,16 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
         ],
     };
 });
-// List available resources
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
-    const resources = [];
-    if (getChartWheelBundle()) {
-        resources.push({
-            uri: CHART_WHEEL_RESOURCE_URI,
-            name: "Chart Wheel Explorer",
-            description: "Interactive natal chart wheel with clickable planets, houses, and aspects.",
-            mimeType: CHART_WHEEL_MIME_TYPE,
-        });
-    }
-    if (getBodygraphBundle()) {
-        resources.push({
-            uri: BODYGRAPH_RESOURCE_URI,
-            name: "Human Design Bodygraph Explorer",
-            description: "Interactive Human Design Bodygraph with clickable centers, gates, and channels.",
-            mimeType: BODYGRAPH_MIME_TYPE,
-        });
-    }
-    if (getBiWheelBundle()) {
-        resources.push({
-            uri: BI_WHEEL_RESOURCE_URI,
-            name: "Bi-Wheel Explorer",
-            description: "Interactive synastry or transit bi-wheel with cross-aspect lines and clickable planets.",
-            mimeType: BI_WHEEL_MIME_TYPE,
-        });
-    }
-    if (getMoonPhaseBundle()) {
-        resources.push({
-            uri: MOON_PHASE_RESOURCE_URI,
-            name: "Moon Phase Explorer",
-            description: "Interactive lunar phase dial showing illumination, sign, and void-of-course status.",
-            mimeType: MOON_PHASE_MIME_TYPE,
-        });
-    }
-    if (getTransitTimelineBundle()) {
-        resources.push({
-            uri: TRANSIT_TIMELINE_RESOURCE_URI,
-            name: "Transit Timeline Explorer",
-            description: "Interactive vertical timeline of upcoming transit hits grouped by month, with clickable events.",
-            mimeType: TRANSIT_TIMELINE_MIME_TYPE,
-        });
-    }
-    if (getVedicChartBundle()) {
-        resources.push({
-            uri: VEDIC_CHART_RESOURCE_URI,
-            name: "Vedic Chart Explorer",
-            description: "Interactive Vedic (Jyotish) South Indian Rashi grid with clickable sign placements.",
-            mimeType: VEDIC_CHART_MIME_TYPE,
-        });
-    }
-    if (getBaziBundle()) {
-        resources.push({
-            uri: BAZI_RESOURCE_URI,
-            name: "BaZi Four Pillars Explorer",
-            description: "Interactive BaZi (Four Pillars of Destiny) chart with clickable Year/Month/Day/Hour pillars.",
-            mimeType: BAZI_MIME_TYPE,
-        });
-    }
-    return { resources };
+    // One registry for both transports: versioned ui:// URIs + resource _meta
+    // (prefersBorder, CSP, widgetDescription). See tools/apps/ui-resources.ts.
+    return { resources: listUiResources() };
 });
-// Read resource
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const uri = request.params.uri;
-    if (uri === CHART_WHEEL_RESOURCE_URI) {
-        const bundle = getChartWheelBundle();
-        if (!bundle)
-            throw new Error("Chart Wheel UI bundle not found. Run `npm run build:ui` to build it.");
-        return { contents: [{ uri: CHART_WHEEL_RESOURCE_URI, mimeType: CHART_WHEEL_MIME_TYPE, text: bundle }] };
-    }
-    if (uri === BODYGRAPH_RESOURCE_URI) {
-        const bundle = getBodygraphBundle();
-        if (!bundle)
-            throw new Error("Bodygraph UI bundle not found. Run `npm run build:ui` to build it.");
-        return { contents: [{ uri: BODYGRAPH_RESOURCE_URI, mimeType: BODYGRAPH_MIME_TYPE, text: bundle }] };
-    }
-    if (uri === BI_WHEEL_RESOURCE_URI) {
-        const bundle = getBiWheelBundle();
-        if (!bundle)
-            throw new Error("Bi-Wheel UI bundle not found. Run `npm run build:ui` to build it.");
-        return { contents: [{ uri: BI_WHEEL_RESOURCE_URI, mimeType: BI_WHEEL_MIME_TYPE, text: bundle }] };
-    }
-    if (uri === MOON_PHASE_RESOURCE_URI) {
-        const bundle = getMoonPhaseBundle();
-        if (!bundle)
-            throw new Error("Moon Phase UI bundle not found. Run `npm run build:ui` to build it.");
-        return { contents: [{ uri: MOON_PHASE_RESOURCE_URI, mimeType: MOON_PHASE_MIME_TYPE, text: bundle }] };
-    }
-    if (uri === TRANSIT_TIMELINE_RESOURCE_URI) {
-        const bundle = getTransitTimelineBundle();
-        if (!bundle)
-            throw new Error("Transit Timeline UI bundle not found. Run `npm run build:ui` to build it.");
-        return { contents: [{ uri: TRANSIT_TIMELINE_RESOURCE_URI, mimeType: TRANSIT_TIMELINE_MIME_TYPE, text: bundle }] };
-    }
-    if (uri === VEDIC_CHART_RESOURCE_URI) {
-        const bundle = getVedicChartBundle();
-        if (!bundle)
-            throw new Error("Vedic Chart UI bundle not found. Run `npm run build:ui` to build it.");
-        return { contents: [{ uri: VEDIC_CHART_RESOURCE_URI, mimeType: VEDIC_CHART_MIME_TYPE, text: bundle }] };
-    }
-    if (uri === BAZI_RESOURCE_URI) {
-        const bundle = getBaziBundle();
-        if (!bundle)
-            throw new Error("BaZi UI bundle not found. Run `npm run build:ui` to build it.");
-        return { contents: [{ uri: BAZI_RESOURCE_URI, mimeType: BAZI_MIME_TYPE, text: bundle }] };
-    }
+    const result = readUiResource(uri);
+    if (result)
+        return result;
     throw new Error(`Unknown resource: ${uri}`);
 });
 // Handle tool calls

package/dist/prompts.js

@@ -36,8 +36,8 @@ export const PROMPTS = [
             "| `solar_return_year_ahead` | Annual Solar Return chart — themes for the coming birthday year |\n" +
             "| `developer_api_integration` | Help a dev integrate the Open Ephemeris API into their app |\n\n" +
             "## Before Calling Any Tool — Three Rules\n" +
-            "1. **Coordinates first**: Convert city names to decimal lat/lon before calling tools " +
-            "(e.g. Chicago → 41.8781, -87.6298). Positive = North/East; negative = South/West.\n" +
+            "1. **Coordinates first**: Resolve place names with `location_search` — never recall " +
+            "coordinates from memory. Positive = North/East; negative = South/West.\n" +
             "2. **Datetime format**: Pass birth times as local ISO 8601 + separate `timezone` IANA name " +
             "(e.g. `America/Chicago`), OR as a UTC-offset datetime `1990-04-15T14:30:00-05:00`. " +
             "Never append `Z` to a local birth time — `Z` means UTC.\n" +
@@ -870,7 +870,7 @@ export const PROMPTS = [
             "| Feature | MCP Tool | REST Endpoint | Credits |\n" +
             "|---------|----------|---------------|---------|\n" +
             "| Natal chart | `ephemeris_natal_chart` | `POST /ephemeris/natal-chart` | 1 |\n" +
-            "| Natal batch (up to 100) | `ephemeris_natal_batch` | `POST /ephemeris/natal/batch` | 1/subject |\n" +
+            "| Natal batch (up to 100, Startup+) | `ephemeris_natal_batch` | `POST /ephemeris/natal/batch` | 1/subject |\n" +
             "| Vedic / Jyotish chart | `vedic_chart` | `POST /vedic/chart` | 1 |\n" +
             "| Human Design | `human_design_chart` | `POST /human-design/chart` | 2 |\n" +
             "| BaZi Four Pillars | `chinese_bazi` | `POST /chinese/bazi` | 1 |\n" +
@@ -879,38 +879,39 @@ export const PROMPTS = [
             "| Midpoint composite | `ephemeris_composite_midpoint` | `POST /comparative/composite/midpoint` | 3 |\n" +
             "| House overlay | `ephemeris_overlay` | `POST /comparative/overlay` | 3 |\n" +
             "| Natal transits (now) | `ephemeris_natal_transits` | `POST /comparative/natal-transits` | 3 |\n" +
-            "| Transit search (range) | `ephemeris_transits` | `POST /predictive/transits/search` | 6 |\n" +
+            "| Transit search (range) | `ephemeris_transits` | `POST /predictive/transits/search` | 5–70 by span (≤1y 5 … ≤40y 70); tool +1 for the natal chart |\n" +
             "| Relocation chart | `ephemeris_relocation` | `POST /ephemeris/relocation` | 1 |\n" +
             "| Solar return | `ephemeris_solar_return` | `POST /predictive/returns/solar` | 5 |\n" +
             "| Lunar return | `ephemeris_lunar_return` | `POST /predictive/returns/lunar` | 5 |\n" +
             "| Progressions | `ephemeris_progressed_chart` | `POST /ephemeris/progressed` | 1 |\n" +
-            "| ACG power lines | `acg_power_lines` | `POST /acg/power-lines` | 10 |\n" +
-            "| ACG city hits | `acg_hits` | `POST /acg/hits` | 15 |\n" +
+            "| ACG power lines (Pro+) | `acg_power_lines` | `POST /acg/power-lines` | 10 |\n" +
+            "| ACG city hits (Pro+) | `acg_hits` | `POST /acg/hits` | 10 |\n" +
             "| Eclipse finder | `ephemeris_next_eclipse` | `GET /eclipse/next-visible` | 1 |\n" +
-            "| Moon phase (current) | `ephemeris_moon_phase` | `GET /ephemeris/moon/phase` | 1 |\n" +
-            "| Next lunar phase | `ephemeris_next_lunar_phase` | `GET /calendar/astrology/moon-phases` | 1 |\n" +
-            "| Electional windows | `ephemeris_electional` | `GET /electional/find-window` | 5 |\n" +
-            "| Electional score | `electional_moment_analysis` | `GET /electional/moment-analysis` | 1 |\n" +
+            "| Moon phase (current) | `ephemeris_moon_phase` | `GET /ephemeris/moon/phase` + `/void-of-course` | 2 |\n" +
+            "| Next lunar phase | `ephemeris_next_lunar_phase` | `GET /calendar/astrology/moon-phases` | 2 per occurrence |\n" +
+            "| Electional windows (Pro+) | `ephemeris_electional` | `GET /electional/find-window` | 5 / 8 / 12 for ≤30 / 60 / 120 days |\n" +
+            "| Electional score | `electional_moment_analysis` | `GET /electional/moment-analysis` | 5 |\n" +
             "| Dignities | `ephemeris_dignities` | `POST /ephemeris/dignities` | 1 |\n" +
             "| Hermetic lots | `ephemeris_hermetic_lots` | `POST /ephemeris/hermetic-lots` | 1 |\n" +
             "| Midpoints | `ephemeris_midpoints` | `POST /ephemeris/midpoints` | 1 |\n\n" +
             "## Step 3 — Critical Implementation Patterns\n\n" +
             "### ⚠️ Datetime Handling — Most Common Source of Bugs\n" +
             "```\n" +
-            "# CORRECT — Local birth time + IANA timezone (Western astrology)\n" +
+            "# CORRECT — local wall-clock time + IANA zone (server applies historical DST)\n" +
             "POST /ephemeris/natal-chart\n" +
-            "{ \"datetime\": \"1990-04-15T14:30:00\", \"timezone\": \"America/Chicago\" }\n\n" +
-            "# ALSO CORRECT — Local time with UTC offset embedded\n" +
-            "{ \"datetime\": \"1990-04-15T14:30:00-05:00\" }\n\n" +
-            "# CORRECT — UTC required for HD and Vedic\n" +
+            "{ \"subject\": { \"name\": \"A\", \"birth_datetime\": { \"iso\": \"1990-04-15T14:30:00\" },\n" +
+            "  \"birth_location\": { \"latitude\": { \"decimal\": 41.88 }, \"longitude\": { \"decimal\": -87.63 },\n" +
+            "    \"timezone\": { \"iana_name\": \"America/Chicago\" } } } }\n\n" +
             "POST /human-design/chart\n" +
-            "{ \"datetime\": \"1990-04-15T19:30:00Z\" }  // Z = UTC\n\n" +
-            "# WRONG — Never append Z to a local time\n" +
-            "{ \"datetime\": \"1990-04-15T14:30:00Z\" }  // ❌ reads as UTC 2:30pm, not Central 2:30pm\n" +
+            "{ \"birth_datetime_local\": \"1990-04-15T14:30:00\", \"timezone\": { \"iana_name\": \"America/Chicago\" },\n" +
+            "  \"latitude\": 41.88, \"longitude\": -87.63 }\n\n" +
+            "# ALSO CORRECT — an explicit instant (offset or Z): trusted as-is\n" +
+            "\"1990-04-15T14:30:00-05:00\"   or   \"1990-04-15T19:30:00Z\"\n\n" +
+            "# WRONG — Z on a local time reads as UTC 2:30pm, not Central 2:30pm (no error raised)\n" +
+            "\"1990-04-15T14:30:00Z\"\n" +
             "```\n\n" +
-            "**Rule of thumb**:\n" +
-            "- Natal charts (Western, BaZi, electional): local time + `timezone` IANA name\n" +
-            "- Human Design, Vedic: always UTC with Z\n\n" +
+            "**Rule of thumb**: on every endpoint, prefer local time + IANA zone. A zone-less clock time " +
+            "with no zone is a hard 400; a bare date resolves to 12:00 UTC.\n\n" +
             "### Coordinates\n" +
             "- Decimal degrees, at least 4 decimal places\n" +
             "- Positive = North/East; Negative = South/West\n" +
@@ -938,9 +939,10 @@ export const PROMPTS = [
             "### Credit Optimization\n" +
             "- **Batch natal charts**: use `POST /ephemeris/natal/batch` for multi-user onboarding (1 credit/subject vs N calls)\n" +
             "- **Current transits**: prefer `ephemeris_natal_transits` (3 credits) over " +
-            "`ephemeris_transits` (6 credits) when you only need right-now, not a date range\n" +
-            "- **ACG**: call `acg_hits` (city-level, 15 credits) only for specific targets; " +
-            "use `acg_power_lines` (10 credits) for global maps\n" +
+            "`ephemeris_transits` (6+ credits, priced by span) when you only need right-now, not a date range\n" +
+            "- **Range searches**: priced by the span you ask for, before compute; a span over the plan cap " +
+            "(transit search: Explorer/PAYG 1y, Pro 5y, Startup 10y, Scale 40y) is a 400 `search_span_limit` — split it\n" +
+            "- **Failed calls are free**: every 4xx/5xx response is refunded\n" +
             "- **Format matters**: `format: 'llm'` reduces token usage in your LLM calls significantly\n\n" +
             "## Step 4 — Generate a Code Scaffold\n" +
             "Ask: 'What language would you like the scaffold in? And what is the first feature you want to implement?'\n\n" +