@openephemeris/mcp-server 4.17.0 → 4.18.0

package/CHANGELOG.md

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

package/dist/server-sse.d.ts

@@ -1,4 +1,22 @@
 import express from "express";
+/**
+ * The hosted server is multi-tenant: every tool call must be authenticated
+ * and metered as the connecting user. A credential in the process environment
+ * breaks that — the client interceptor sends X-Service-Key ahead of the user's
+ * key (every user unmetered), and an env API key / JWT would bill every
+ * session to one account.
+ *
+ * - A service key in the environment is a hard startup failure: there is no
+ *   safe way to run with it present.
+ * - A user API key / JWT in the environment is logged loudly and ignored.
+ * - The module singleton (built from the environment at import, and what
+ *   getActiveClient() falls back to outside a session context) is stripped of
+ *   every credential either way; per-session clients are built with
+ *   `inheritEnvCredentials: false`.
+ *
+ * Exported for tests. stdio mode never calls this.
+ */
+export declare function enforceHostedCredentialPolicy(env?: NodeJS.ProcessEnv): void;
 /**
  * Build the full Express app (auth gate, OAuth routes, /mcp Streamable HTTP,
  * health, resources). Exported so tests can drive the REAL handlers with

package/dist/server-sse.js

@@ -8,7 +8,8 @@
  * Architecture:
  *   - The SSE server validates the user's API key at connection time by
  *     making a lightweight call to the Go backend.
- *   - The validated key is injected into the singleton BackendClient so
+ *   - Each session gets its own BackendClient built from the validated key
+ *     (never from env credentials — see enforceHostedCredentialPolicy), so
  *     all subsequent tool calls authenticate as the connecting user.
  *   - Usage credits are metered against the user's account and tier.
  */
@@ -26,7 +27,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema
 import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface, describeSurface } from "./tools/index.js";
 import { buildUiMeta } from "./tools/ui-meta.js";
 import { SERVER_INSTRUCTIONS } from "./instructions.js";
-import { BackendClient, runWithClient } from "./backend/client.js";
+import { BackendClient, backendClient, presentCredentialEnvVars, runWithClient } from "./backend/client.js";
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
 import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
 import { BI_WHEEL_RESOURCE_URI, BI_WHEEL_MIME_TYPE, getBiWheelBundle, } from "./tools/apps/bi-wheel-app.js";
@@ -557,12 +558,43 @@ function startSseKeepalive(res) {
     }, 25_000);
     res.on("close", () => clearInterval(ping));
 }
+/**
+ * The hosted server is multi-tenant: every tool call must be authenticated
+ * and metered as the connecting user. A credential in the process environment
+ * breaks that — the client interceptor sends X-Service-Key ahead of the user's
+ * key (every user unmetered), and an env API key / JWT would bill every
+ * session to one account.
+ *
+ * - A service key in the environment is a hard startup failure: there is no
+ *   safe way to run with it present.
+ * - A user API key / JWT in the environment is logged loudly and ignored.
+ * - The module singleton (built from the environment at import, and what
+ *   getActiveClient() falls back to outside a session context) is stripped of
+ *   every credential either way; per-session clients are built with
+ *   `inheritEnvCredentials: false`.
+ *
+ * Exported for tests. stdio mode never calls this.
+ */
+export function enforceHostedCredentialPolicy(env = process.env) {
+    const { serviceKeys, userCredentials } = presentCredentialEnvVars(env);
+    if (serviceKeys.length > 0) {
+        throw new Error(`Refusing to start the hosted MCP HTTP server: ${serviceKeys.join(", ")} is set. ` +
+            `A service key bypasses per-user metering for every session. Unset it — the ` +
+            `hosted server authenticates each session with the user's own API key or OAuth token.`);
+    }
+    if (userCredentials.length > 0) {
+        console.error(`[SECURITY] ${userCredentials.join(", ")} is set in the hosted MCP server environment. ` +
+            `IGNORING it — sessions authenticate only with their own credential. Remove it from the deployment.`);
+    }
+    backendClient.clearCredentials();
+}
 /**
  * Build the full Express app (auth gate, OAuth routes, /mcp Streamable HTTP,
  * health, resources). Exported so tests can drive the REAL handlers with
  * supertest instead of a re-implemented stub. Does not listen.
  */
 export async function createSseApp() {
+    enforceHostedCredentialPolicy();
     await initTools();
     const app = express();
     // NOTE: express.json() is applied per-route (jsonParser on /mcp POST), not
@@ -700,18 +732,19 @@ export async function createSseApp() {
             serverInfo: {
                 name: "Open Ephemeris",
                 version,
-                description: "NASA JPL DE440-backed astronomical computation engine for AI agents. 90+ typed tools covering " +
+                description: `NASA JPL DE440-backed astronomical computation engine for AI agents. ${tools.length} typed tools covering ` +
                     "natal charts, transit forecasting, Human Design bodygraphs, eclipses, astrocartography " +
                     "power lines, Venus Star Points, electional timing, synastry, composite charts, Vedic/Jyotish, " +
                     "Chinese BaZi, and more — powered by JPL DE440 ephemerides for sub-arcsecond " +
-                    "zero-hallucination accuracy. Free Explorer tier available.",
+                    "zero-hallucination accuracy. Free Explorer tier: 150 one-time credits.",
                 iconUrl: "https://mcp.openephemeris.com/icon.png",
                 homepage: "https://openephemeris.com",
             },
             authentication: {
                 required: true,
                 schemes: ["apiKey"],
-                instructions: "Pass your Open Ephemeris API key via the X-API-Key header. " +
+                instructions: "Sign in with OAuth 2.1 (PKCE, dynamic client registration), or pass your Open Ephemeris API key " +
+                    "via the X-API-Key header (or Authorization: Bearer opene-…). Every call is metered to that user. " +
                     "Get a free Explorer key at https://openephemeris.com/dashboard — no credit card required.",
             },
             tools,
@@ -871,7 +904,9 @@ export async function createSseApp() {
                 console.error(`[HTTP] Session initialized: ${id}`);
             },
         });
-        const client = new BackendClient({ baseURL: BACKEND_URL, apiKey, jwt });
+        // inheritEnvCredentials:false — this client must authenticate as THIS
+        // session's user only, never as an env service key / API key / JWT.
+        const client = new BackendClient({ baseURL: BACKEND_URL, apiKey, jwt, inheritEnvCredentials: false });
         const analyticsId = distinctIdFor(apiKey ?? jwt);
         // Tool surface is fixed for the life of the session: we do not declare
         // `tools.listChanged`, so a host has no obligation to re-fetch the list.

package/dist/tools/apps/_render-token.d.ts

@@ -0,0 +1,34 @@
+/**
+ * _render-token.ts — plumbing for the API's server-issued render token.
+ *
+ * The Go API stamps every charged visual on a render-family route
+ * (/human-design/chart + /visualization/bodygraph, /human-design/transit-chart,
+ * /human-design/composite, /chinese/bazi, /vedic/chart) with a short-lived
+ * token bound to the account and the chart-defining inputs
+ * (auth/render_token.go). Presenting it on a re-render of the SAME chart —
+ * the iframe's host light/dark reconciliation, a layout flip — makes that
+ * re-render free (base charge and visual surcharge). Anything else is charged
+ * normally, so passing a stale or foreign token is harmless.
+ *
+ * Flow: explore_* puts the token on the payload as `_render_token`; the iframe
+ * hands it back as the `render_token` argument of its recalc / refetch call;
+ * the tool sends it in the X-OE-Render-Token header.
+ */
+export declare const RENDER_TOKEN_HEADER = "X-OE-Render-Token";
+/** Input-schema property for the app-only recalc args. Never set by the model. */
+export declare const RENDER_TOKEN_PROPERTY: {
+    readonly type: "string";
+    readonly description: string;
+};
+/** Request headers presenting `token`, or undefined when there is none. */
+export declare function renderTokenHeaders(token: unknown): Record<string, string> | undefined;
+/**
+ * The token the API injected on the root <svg> of a /visualization/bodygraph
+ * response (a binary route, whose response headers the backend client does
+ * not surface).
+ */
+export declare function renderTokenFromSvg(svg: string | null | undefined): string | undefined;
+/** `visual.render_token` from an include_visual JSON response. */
+export declare function renderTokenFromVisual(visual: unknown): string | undefined;
+/** Copy of tool args with the per-call token removed (for `_refetch.args`). */
+export declare function withoutRenderToken<T extends Record<string, unknown>>(args: T): T;