@openephemeris/mcp-server 3.17.0 → 3.19.0

package/CHANGELOG.md

@@ -7,6 +7,63 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.19.0] — 2026-07-09
+
+Transport hardening + E2E release verification, from a full review of the streaming HTTP transport and iframe app capability.
+
+### Fixed
+- **stdio missing the MCP Apps capability flag.** The stdio entry (`src/index.ts`) never advertised `experimental["io.modelcontextprotocol/ui"]` (the SSE server did), so hosts gating iframe rendering on that capability would not render apps from a local install. Now declared on both transports.
+- **Rotted integration scripts.** `scripts/test-client.ts` and `scripts/smoke-dev-profile.ts` still asserted pre-rename dotted tool names (`auth.login`, `dev.call`) and could never pass. Fixed and wired into CI so they can't rot silently again.
+
+### Added
+- **SSE keepalive.** Long-lived streams (`GET /mcp` leg and legacy `/sse`) now emit an SSE comment frame every 25s and disable the per-socket idle timeout, preventing silent drops through Fly's proxy on idle sessions.
+- **Idle session reaper.** In-memory HTTP sessions abandoned without a DELETE are reaped after 2h idle (they previously leaked until process restart); a reaped session 404s and the client re-initializes per spec.
+- **Tool-call timeout** (120s) so a hung backend request can't pin a session forever.
+- **Resume-path auth.** A session id alone is no longer sufficient to resume a Streamable HTTP session — every request must still carry a valid API key / non-expired JWT (expired JWTs get the standard 401 `invalid_token` refresh signal).
+- **Host-header allowlist** on `/mcp`, `/sse`, `/message` as DNS-rebinding defense (Origin was already validated; Host was not). Extend via `MCP_ALLOWED_HOSTS`.
+- **Fly HTTP health check** on `/health` (previously TCP-only, so a hung process stayed in rotation).
+- **E2E release verification:** `test:published` installs the packed/published tarball into a clean dir and drives `dist/index.js` over stdio (initialize → tools/list → UI resource read → tool call); `test:mcp-http` drives the live Streamable HTTP endpoint end to end including an MCP Apps `resources/read`. Wired into the validate workflow, as a post-publish gate in the npm workflow, and as a 6-hourly production canary.
+- **Tool-count regression test** (84) keeping the marketing SSOT honest.
+
+### Removed
+- **Dormant UI apps deleted** (transit-timeline, bazi, vedic-chart): never imported/registered, two never functional; their trees, tool files, per-app lockfiles, and `build:ui` steps are gone. BaZi/Vedic data still ships via the typed `bazi_*`/`vedic_chart` tools.
+- Leftover one-off codemods (`fix.cjs`, `fix.mjs`, `fix2.mjs`) and the empty `dev_card.json`.
+- 7 byte-identical copies of `singlefile-plugin.ts` (now shared from `src/ui/shared/`); debug `console.log` noise stripped from the chart-wheel bundle.
+
+### Changed
+- Runtime Docker image now prunes dev dependencies before the final stage.
+
+---
+
+## [3.18.0] — 2026-07-06
+
+Launch-reliability hardening for the remote SSE/HTTP server (`oe-mcp-live`).
+
+### Fixed
+- **Stale-JWT dead session.** Self-signed Supabase JWTs expire after 1h. A session's `BackendClient` captured the JWT once at init and the resume path never re-read it, so after the host refreshed the token every tool call kept sending the frozen expired JWT and 401'd forever (users were told to disconnect/reconnect). `BackendClient.setJwt()` now lets the resume branch push the freshly-rotated Bearer token into the session client. Additionally, the `/mcp` auth gate now decodes the JWT `exp` claim (no signature verification — the Go API is the trust boundary) and returns `401 invalid_token` + `WWW-Authenticate` for an already-expired token, triggering the host's OAuth refresh instead of a confusing downstream tool error.
+- **POST retry double-charge.** The axios retry loop retried every method — including POST — on transient failures, and every expensive compute endpoint is POST (e.g. `acg_hits` = 15 credits) metered at reservation time, so one dropped response could be billed up to 4×. Only idempotent GETs are auto-retried now; POST/PUT/PATCH/DELETE are never retried. `429` is no longer retried at all — the rate-limit message surfaces immediately instead of hammering the limiter.
+- **`isError` correctness.** Both CallTool handlers previously set `isError: !isRetryable`, so 429/5xx/network/auth failures arrived as `isError: false` "successes." All failures now report `isError: true` so hosts recover (retry / OAuth refresh), with the one exception of the stdio device-auth-pending case (whose message carries a verification link the model must relay). Extracted into a shared, unit-tested `formatToolError` helper.
+- **Cross-machine session 404s.** `min_machines_running = 2` but the session store is a per-process Map, so a resume request landing on the other machine 404'd. Streamable-HTTP session IDs now embed `FLY_MACHINE_ID`; a request whose session ID targets a different machine is re-routed via the `fly-replay` header (with a `fly-replay-src` loop guard that falls through to 404 so the client re-initializes). No-op locally when `FLY_MACHINE_ID` is unset.
+- **API-key validation no longer costs a credit.** Session-init key validation probed `/ephemeris/moon/phase`, which meters at 1 credit — so merely connecting charged the user. Switched to `/catalogs/bodies` (auth-gated but metered at 0 credits).
+- **ACG / progressed datetime descriptions** now require a UTC offset (e.g. `1990-05-15T14:30:00-05:00`); a naive datetime was silently interpreted as UTC and mislocated ACG lines / shifted progressions.
+- **`dev_read_api` reference text** corrected: `/location/autocomplete` takes `query=`, not `q=`.
+
+### Changed
+- Added a `process.on('unhandledRejection')` log-and-continue handler so a single rejected request can't take down every live session.
+- 402 credit-exhausted message annotated with a pointer to the pricing SSOT (`apps/web/config/billing-plans.ts`).
+- `fly.toml` VM memory raised 512MB → 1024MB for the launch window.
+
+---
+
+## [3.17.0] — 2026-07-06
+
+Docs-only release (this is the version live on npm while 3.18.0 awaited publish).
+
+### Changed
+- README: embedded the hero demo GIF and refreshed the quick-start copy for the launch window (PR #258). No runtime changes.
+
+---
+
 ## [3.16.0] — 2026-07-05
 
 ### Added

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-2026 Open Ephemeris
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025-2026 Open Ephemeris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/backend/client.d.ts

@@ -44,6 +44,15 @@ export declare class BackendClient {
      * metered against the correct user account.
      */
     setApiKey(key: string): void;
+    /**
+     * Override the stored JWT at runtime. Used by the SSE/HTTP server to refresh
+     * a session's Bearer token when the host (e.g. claude.ai) rotates it via
+     * /oauth/token. Self-signed Supabase JWTs expire after 1h, so without this a
+     * long-lived session would keep sending the frozen expired token and 401 on
+     * every tool call. Only takes effect when no API key / service key is set
+     * (JWT is the lowest-priority credential in the interceptor).
+     */
+    setJwt(jwt: string): void;
     /**
      * 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

@@ -4,7 +4,13 @@ import { CredentialManager } from "../auth/credentials.js";
 import { DeviceAuthFlow } from "../auth/device-auth.js";
 const DEFAULT_TIMEOUT_MS = 45_000;
 const RETRY_DELAYS_MS = [1_000, 2_000, 4_000]; // Three retries with backoff
-const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+// NOTE: 429 is intentionally NOT retryable. Every expensive compute endpoint is
+// POST and the Go API meters at reservation time, so retrying a rate-limited or
+// dropped POST double-charges the user (e.g. acg_hits = 15 credits × retries).
+// We only auto-retry idempotent GETs on transient transport/5xx failures; the
+// 429 message is surfaced immediately so the caller backs off instead of
+// hammering the limiter. See request() for the GET-only guard.
+const RETRYABLE_STATUSES = new Set([502, 503, 504]);
 const RETRYABLE_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "ENOTFOUND", "EAI_AGAIN"]);
 const BINARY_ENDPOINT_PREFIXES = [
     "/visualization/bi-wheel",
@@ -118,6 +124,17 @@ export class BackendClient {
         this.serviceKey = undefined;
         this.jwt = undefined;
     }
+    /**
+     * Override the stored JWT at runtime. Used by the SSE/HTTP server to refresh
+     * a session's Bearer token when the host (e.g. claude.ai) rotates it via
+     * /oauth/token. Self-signed Supabase JWTs expire after 1h, so without this a
+     * long-lived session would keep sending the frozen expired token and 401 on
+     * every tool call. Only takes effect when no API key / service key is set
+     * (JWT is the lowest-priority credential in the interceptor).
+     */
+    setJwt(jwt) {
+        this.jwt = jwt;
+    }
     /**
      * Start the device auth flow in the background if not already running.
      * Called automatically when no credentials are found in the interceptor.
@@ -253,14 +270,18 @@ export class BackendClient {
                     `OpenEphemeris connector to re-authorize.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
             }
             if (status === 402) {
+                // 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
+                // ($5→150, $10→350, $20→900). Keep every number below in sync with
+                // that file; do NOT hand-edit these figures independently.
                 const dataObj = data && typeof data === "object" ? data : {};
                 const walletUrl = dataObj.upgrade?.wallets_url || "https://openephemeris.com/wallet";
                 const currentTier = dataObj.upgrade?.current_tier || dataObj.tier || "explorer";
-                const isPro = currentTier === "developer" || currentTier === "pro" || currentTier === "startup" || currentTier === "scale";
                 let upsellMsg = "";
                 if (currentTier === 'explorer') {
                     upsellMsg =
-                        `Let the user know warmly: Their 150 free discovery credits are used up. ` +
+                        `Let the user know warmly: Their 150 free credits (one-time grant) are used up. ` +
                             `They can top up their wallet starting at $5 for 150 credits at ` +
                             `${walletUrl} — or upgrade to Pro ($29/mo) ` +
                             `for 75,000 credits/month at ${UPGRADE_URL}`;
@@ -361,8 +382,14 @@ export class BackendClient {
             }
             catch (err) {
                 if (err instanceof AxiosError) {
-                    const isRetryable = (err.response && RETRYABLE_STATUSES.has(err.response.status)) ||
-                        (!err.response && err.code && RETRYABLE_CODES.has(err.code));
+                    // Only idempotent GETs may be auto-retried. POST/PUT/PATCH/DELETE are
+                    // never retried: expensive compute endpoints are POST and the Go API
+                    // meters credits at reservation time, so a retried POST double-charges
+                    // even when the original response was merely lost in transit.
+                    const isIdempotent = method === "GET";
+                    const isRetryable = isIdempotent &&
+                        ((err.response && RETRYABLE_STATUSES.has(err.response.status)) ||
+                            (!err.response && !!err.code && RETRYABLE_CODES.has(err.code)));
                     if (isRetryable && attempt < RETRY_DELAYS_MS.length) {
                         const jitter = Math.random() * 500;
                         await sleep(RETRY_DELAYS_MS[attempt] + jitter);

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, modelVisibleTools } from "./tools/index.js";
+import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools } from "./tools/index.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";
@@ -42,6 +42,14 @@ const server = new Server({
         tools: {},
         prompts: {},
         resources: {},
+        experimental: {
+            // Declare MCP Apps extension (spec: io.modelcontextprotocol/ui, 2026-01-26).
+            // Must match the SSE server's capability block so stdio hosts (Claude
+            // Desktop) also know this server returns renderable HTML resources.
+            "io.modelcontextprotocol/ui": {
+                mimeTypes: ["text/html;profile=mcp-app"],
+            },
+        },
     },
 });
 // List available tools
@@ -176,17 +184,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     catch (error) {
         const durationMs = Date.now() - startTime;
         const errorMessage = error instanceof Error ? error.message : String(error);
-        const isRetryable = error.retryable === true || error.status === 401 || error.code === "auth_required";
         console.error(`[MCP] ❌ Failed: ${toolName} (${durationMs}ms) - ${errorMessage}`);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Tool execution failed:\n\n${errorMessage}\n\nPlease read the error above carefully and assist the user (e.g. by providing them the auth link or explaining the issue).`,
-                },
-            ],
-            isError: !isRetryable,
-        };
+        // isError: true for every failure so the host recovers, EXCEPT the stdio
+        // device-auth-pending case (model must relay the verification link).
+        return formatToolError(error);
     }
 });
 // Start server

package/dist/oauth/session-utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * src/oauth/session-utils.ts — Pure helpers for session reliability.
+ *
+ * Two concerns live here so they can be unit-tested without spinning up the
+ * full SSE server:
+ *
+ *   1. JWT expiry decoding — read the `exp` claim WITHOUT signature
+ *      verification. The signature is validated downstream by the Go API's
+ *      ValidateSupabaseJWT; here we only need to know whether a token is
+ *      already expired so the /mcp gate can trigger the host's OAuth refresh
+ *      (401 invalid_token) instead of letting it die as a confusing tool error.
+ *
+ *   2. Machine-scoped session IDs — Fly runs min_machines_running >= 2, but the
+ *      HTTP/SSE session store is a per-process Map. A resume request can land on
+ *      a different machine and 404. We embed the FLY_MACHINE_ID into generated
+ *      session IDs so an incoming request can be re-routed to the owning machine
+ *      via the `fly-replay` header. Local/dev (no FLY_MACHINE_ID) is a no-op.
+ */
+/**
+ * Decode a JWT's payload without verifying the signature and return its `exp`
+ * claim (seconds since epoch), or null if the token is malformed / has no exp.
+ *
+ * Signature verification is intentionally skipped — the Go API is the trust
+ * boundary. This is only used to decide whether to prompt the host to refresh.
+ */
+export declare function decodeJwtExp(token: string): number | null;
+/**
+ * Returns true when the JWT is expired (or expires within `skewSeconds`).
+ * A token we cannot decode (or that carries no exp) is treated as NOT expired
+ * so we never block a token the Go API might still accept — the downstream
+ * validator remains the source of truth.
+ */
+export declare function isJwtExpired(token: string, skewSeconds?: number, nowMs?: number): boolean;
+/** The current Fly machine id, or "" when running locally / outside Fly. */
+export declare function currentMachineId(): string;
+/**
+ * Wrap a raw session ID with the current machine id when running on Fly.
+ * Local/dev (no FLY_MACHINE_ID) returns the raw id unchanged so behavior and
+ * existing session-id shapes are preserved off-platform.
+ */
+export declare function encodeSessionId(rawId: string, machineId?: string): string;
+/**
+ * Extract the machine id embedded in a session ID, or "" if none is present
+ * (locally-minted id, or a legacy id from before this scheme).
+ */
+export declare function machineIdFromSessionId(sessionId: string): string;
+/**
+ * Decide whether an incoming request for `sessionId` should be replayed to a
+ * different Fly machine.
+ *
+ * Returns the target machine id to replay to, or null to handle locally.
+ * Guards against replay loops: if the request was already replayed
+ * (fly-replay-src header present) we never replay again — the caller falls
+ * through to its normal 404 so the client re-initializes per the MCP spec.
+ */
+export declare function replayTargetMachine(sessionId: string, opts: {
+    selfMachineId?: string;
+    alreadyReplayed: boolean;
+}): string | null;

package/dist/oauth/session-utils.js

@@ -0,0 +1,110 @@
+/**
+ * src/oauth/session-utils.ts — Pure helpers for session reliability.
+ *
+ * Two concerns live here so they can be unit-tested without spinning up the
+ * full SSE server:
+ *
+ *   1. JWT expiry decoding — read the `exp` claim WITHOUT signature
+ *      verification. The signature is validated downstream by the Go API's
+ *      ValidateSupabaseJWT; here we only need to know whether a token is
+ *      already expired so the /mcp gate can trigger the host's OAuth refresh
+ *      (401 invalid_token) instead of letting it die as a confusing tool error.
+ *
+ *   2. Machine-scoped session IDs — Fly runs min_machines_running >= 2, but the
+ *      HTTP/SSE session store is a per-process Map. A resume request can land on
+ *      a different machine and 404. We embed the FLY_MACHINE_ID into generated
+ *      session IDs so an incoming request can be re-routed to the owning machine
+ *      via the `fly-replay` header. Local/dev (no FLY_MACHINE_ID) is a no-op.
+ */
+/**
+ * Decode a JWT's payload without verifying the signature and return its `exp`
+ * claim (seconds since epoch), or null if the token is malformed / has no exp.
+ *
+ * Signature verification is intentionally skipped — the Go API is the trust
+ * boundary. This is only used to decide whether to prompt the host to refresh.
+ */
+export function decodeJwtExp(token) {
+    if (typeof token !== "string" || !token)
+        return null;
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const payloadJson = Buffer.from(parts[1], "base64url").toString("utf8");
+        const payload = JSON.parse(payloadJson);
+        if (typeof payload.exp === "number" && Number.isFinite(payload.exp)) {
+            return payload.exp;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns true when the JWT is expired (or expires within `skewSeconds`).
+ * A token we cannot decode (or that carries no exp) is treated as NOT expired
+ * so we never block a token the Go API might still accept — the downstream
+ * validator remains the source of truth.
+ */
+export function isJwtExpired(token, skewSeconds = 0, nowMs = Date.now()) {
+    const exp = decodeJwtExp(token);
+    if (exp === null)
+        return false;
+    const nowSec = Math.floor(nowMs / 1000);
+    return exp <= nowSec + skewSeconds;
+}
+// ---------------------------------------------------------------------------
+// Machine-scoped session IDs (Fly request replay)
+// ---------------------------------------------------------------------------
+const MACHINE_PREFIX_SEP = "."; // "<machineId>.<rawSessionId>"
+/** The current Fly machine id, or "" when running locally / outside Fly. */
+export function currentMachineId() {
+    return process.env.FLY_MACHINE_ID || "";
+}
+/**
+ * Wrap a raw session ID with the current machine id when running on Fly.
+ * Local/dev (no FLY_MACHINE_ID) returns the raw id unchanged so behavior and
+ * existing session-id shapes are preserved off-platform.
+ */
+export function encodeSessionId(rawId, machineId = currentMachineId()) {
+    if (!machineId)
+        return rawId;
+    return `${machineId}${MACHINE_PREFIX_SEP}${rawId}`;
+}
+/**
+ * Extract the machine id embedded in a session ID, or "" if none is present
+ * (locally-minted id, or a legacy id from before this scheme).
+ */
+export function machineIdFromSessionId(sessionId) {
+    if (typeof sessionId !== "string")
+        return "";
+    const idx = sessionId.indexOf(MACHINE_PREFIX_SEP);
+    if (idx <= 0)
+        return "";
+    return sessionId.slice(0, idx);
+}
+/**
+ * Decide whether an incoming request for `sessionId` should be replayed to a
+ * different Fly machine.
+ *
+ * Returns the target machine id to replay to, or null to handle locally.
+ * Guards against replay loops: if the request was already replayed
+ * (fly-replay-src header present) we never replay again — the caller falls
+ * through to its normal 404 so the client re-initializes per the MCP spec.
+ */
+export function replayTargetMachine(sessionId, opts) {
+    const selfMachineId = opts.selfMachineId ?? currentMachineId();
+    // Off-Fly (no machine identity) → never replay.
+    if (!selfMachineId)
+        return null;
+    // Already bounced once → don't loop; let the caller 404.
+    if (opts.alreadyReplayed)
+        return null;
+    const target = machineIdFromSessionId(sessionId);
+    if (!target)
+        return null; // legacy / local id — can't route
+    if (target === selfMachineId)
+        return null; // we own it
+    return target;
+}