@openephemeris/mcp-server 3.19.0 → 3.21.0

package/CHANGELOG.md

@@ -7,6 +7,51 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.21.0] — 2026-07-09
+
+Launch-readiness wave from the three-perspective master review (directory vetting, first-run UX, revenue red-team).
+
+### Security (directory-listing conditions)
+- **`auth_*` device tools removed from the HTTP transport.** They mutate process-global state (shared credential file, env inspection) — on the multi-tenant remote server one user's `auth_logout` cleared shared credentials and `auth_status` could report the process service-key config to any tenant. Now `stdioOnly` and hidden/blocked on `/mcp`; unchanged for local stdio installs.
+- **Rate limiters no longer trust `X-Forwarded-For`** (leftmost value is attacker-controlled and let callers rotate fake IPs past every throttle). Client IP now comes from Fly's trusted `Fly-Client-IP` hop, with a spoof-resistance test.
+- **DCR redirect hardening:** `redirect_uris` must be https or http loopback (RFC 8252) — non-conforming registrations are rejected.
+
+### Conversion & instrumentation
+- **PostHog events from the MCP server** (`src/analytics.ts`, fire-and-forget, no-ops without `POSTHOG_API_KEY`): `mcp_session_init` (auth type), `mcp_tool_call` (tool, duration), `mcp_tool_error` (tool, HTTP status — makes 402 paywall hits and 429s countable). Identity is a SHA-256 prefix of the credential, never the raw key; all events tagged `source: mcp`.
+- **402 paywall fixed:** paid tiers are no longer told to "enable overages" (overage billing is switched off) — they get the next tier with exact price and a `/pricing?plan=…` deep link; free-tier 402s deep-link to the wallet top-up and `/pricing?plan=developer`.
+- **Credit costs disclosed** on the five app tools that lacked them (verified against `usage_meter.go`); `ephemeris_natal_batch` now states its Startup-tier gating and warns that N subjects = N credits.
+- **Return hooks:** `current_sky_snapshot` and `transit_forecast` prompts now end with when to check back (next Moon sign change / next exact transit).
+
+### First-run UX
+- **Routing:** `explore_natal_chart` is now explicitly the PRIMARY tool for chart requests; `ephemeris_natal_chart` marks itself raw-JSON and defers to it; the `natal_chart_reading` prompt and the astrology-mcp landing page now point at the interactive explorers.
+- **Welcome rewritten** from a 12-bullet brochure to a two-option hook (instant no-birth-data sky snapshot, or an interactive birth chart); server `instructions` now steer the model to `explore_*` tools for anything visual.
+- **Loader copy de-jargoned** ("Computing ephemeris…" → "Mapping the sky at your birth moment…" etc.); every terminal iframe error now offers "Tap to try again" wired to a real retry; `auth_login` leads with "free tier, no credit card needed"; expired-OAuth copy tells users exactly where to reconnect.
+
+### Fixed
+- **Local visual harness (`npm run harness`) was broken** by an orphaned vite process squatting port 5180: `visual-check.mjs` now kills the full process tree on Windows (`taskkill /T`), and the harness uses `strictPort` so a squatted port fails loudly instead of silently drifting. Harness index/fixtures cleaned of the deleted dormant apps; the dead bodygraph fixture was rebuilt with the real Go-SVG contract — which exposed and fixed two genuine a11y bugs (`role="img"` on an SVG containing buttons; hardcoded low-contrast gold on action buttons).
+
+---
+
+## [3.20.0] — 2026-07-09
+
+Second wave of the transport/iframe review: legacy transport retirement, resumability, and remaining hardening/quality items.
+
+### Removed
+- **Legacy SSE transport retired.** `GET /sse` + `POST /message` (pre-2025 spec, SDK-deprecated, no cross-machine replay, zero live sessions) now return `410 Gone` pointing at `/mcp`. `scripts/test-sse-client.ts` and the `test:sse` script removed; docs updated.
+
+### Added
+- **`Last-Event-ID` resumability.** Bounded in-memory `EventStore` (200 events/stream, 2h TTL) on the Streamable HTTP transport — a reconnecting SSE stream replays missed events instead of losing them. Per-process is safe because sessions are machine-pinned via fly-replay.
+- **Server-computed natal aspects.** `explore_natal_chart` was discarding the `aspects` array the natal endpoint already returns (with true ephemeris-derived `is_applying`) and re-deriving aspects client-side with an approximate heuristic — `computeAspects` deleted, server aspects mapped through. Bi-wheel cross-aspects stay client-side (two charts, no single endpoint) but the applying/separating heuristic now uses real longitude speeds instead of defaulted guesses.
+- **CSP + keyboard accessibility** on the four iframe apps: inline-only `Content-Security-Policy` meta on each shell; interactive SVG elements (planets, houses, aspects, centers/gates/channels) get `tabindex`/`role`/`aria-label`, Enter/Space activation, and visible focus indicators.
+- **Real-handler test coverage.** `createSseApp()` is now exported and `test/server-sse-real-app.test.ts` drives the actual Express app: 401/WWW-Authenticate contract, expired-JWT refresh signal, session issuance with machine prefix, cross-machine `fly-replay` 307 + loop-guard 404, resume-auth requirement, Host allowlist, and the 410 legacy responses.
+- **`check:plugin` release gate** (`scripts/plugin-audit.ts`): plugin.json version must match the package (it had rotted at 3.1.0) and `openephemeris-plugin.zip` must match the plugin tree by content; `regen:plugin` rebuilds both. Wired into `verify:release`.
+- **CI:** `validate:visual` (Playwright + axe over the app harness) added to the validate workflow; the live canary now sends a **Telegram alert on failure** (needs `TELEGRAM_BOT_TOKEN`/`TELEGRAM_CHAT_ID` secrets; no-ops without them).
+
+### Changed
+- Resume-path auth now runs **before** the session lookup so an unauthenticated probe cannot learn whether a session id exists.
+
+---
+
 ## [3.19.0] — 2026-07-09
 
 Transport hardening + E2E release verification, from a full review of the streaming HTTP transport and iframe app capability.

package/README.md

@@ -187,7 +187,7 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 
 - **Claude Web**: Add `https://mcp.openephemeris.com/mcp` as a custom connector URL — leave OAuth Client ID and Secret **blank**. The server uses OAuth 2.1 + PKCE (Dynamic Client Registration), so Claude handles authentication via a browser popup automatically.
 - **Via Smithery**: Use the [Smithery listing](https://smithery.ai/servers/open-ephemeris/openephemeris) for managed connections with any client
-- **Legacy SSE**: `https://mcp.openephemeris.com/sse` remains available for SSE-only clients
+- **Legacy SSE**: retired in 3.20.0 — use Streamable HTTP at `/mcp`
 
 ### Auth and upgrade behavior in MCP clients
 

package/dist/analytics.d.ts

@@ -0,0 +1,3 @@
+/** Stable, non-reversible identity from a credential. */
+export declare function distinctIdFor(credential: string | undefined): string;
+export declare function captureEvent(event: string, distinctId: string, properties?: Record<string, unknown>): void;

package/dist/analytics.js

@@ -0,0 +1,44 @@
+/**
+ * analytics.ts — fire-and-forget PostHog events for the remote MCP server.
+ *
+ * The launch was previously unmeasurable from the MCP side: no way to see how
+ * many sessions initialized, which tools drove usage, or how many users hit
+ * the 402 paywall. These events close that gap. Everything is best-effort:
+ * analytics must never slow down or fail a tool call.
+ *
+ * Configuration (Fly secrets / env):
+ *   POSTHOG_API_KEY  — the project API key (phc_...); absent → all no-ops.
+ *   POSTHOG_HOST     — capture host, default https://us.i.posthog.com.
+ *
+ * Identity: we never send raw API keys or JWTs. The distinct_id is a SHA-256
+ * prefix of the credential, stable per user across sessions but useless for
+ * authentication.
+ */
+import { createHash } from "node:crypto";
+const POSTHOG_HOST = process.env.POSTHOG_HOST || "https://us.i.posthog.com";
+function apiKey() {
+    return process.env.POSTHOG_API_KEY || undefined;
+}
+/** Stable, non-reversible identity from a credential. */
+export function distinctIdFor(credential) {
+    if (!credential)
+        return "anonymous";
+    return "mcp_" + createHash("sha256").update(credential).digest("hex").slice(0, 24);
+}
+export function captureEvent(event, distinctId, properties = {}) {
+    const key = apiKey();
+    if (!key)
+        return;
+    // Fire-and-forget: no await, swallow every failure.
+    fetch(`${POSTHOG_HOST}/capture/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            api_key: key,
+            event,
+            distinct_id: distinctId,
+            properties: { source: "mcp", ...properties },
+            timestamp: new Date().toISOString(),
+        }),
+    }).catch(() => { });
+}

package/dist/backend/client.js

@@ -266,25 +266,33 @@ export class BackendClient {
                 }
                 return new BackendError(`Authentication required: ${msg}. Run auth.login to connect your account, ` +
                     `or set OPENEPHEMERIS_API_KEY in your MCP server config. If you connected ` +
-                    `through Claude's connector settings, disconnect and reconnect the ` +
-                    `OpenEphemeris connector to re-authorize.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
+                    `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) {
                 // 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.
+                // ($5→150, $10→350, $20→900), Startup ($79, 500k), Scale ($199, 2M).
+                // Overage billing is OFF (OVERAGE_BILLING_AVAILABLE=false) — never
+                // suggest enabling overages; suggest the next tier instead. Keep every
+                // number below in sync with that file; do NOT hand-edit independently.
                 const dataObj = data && typeof data === "object" ? data : {};
-                const walletUrl = dataObj.upgrade?.wallets_url || "https://openephemeris.com/wallet";
+                const walletUrl = dataObj.upgrade?.wallets_url || "https://openephemeris.com/dashboard?tab=wallet";
                 const currentTier = dataObj.upgrade?.current_tier || dataObj.tier || "explorer";
+                // Next-tier upgrade path (SSOT: BILLING_PLANS order in billing-plans.ts).
+                const NEXT_TIER = {
+                    developer: { plan: "startup", label: "Startup ($79/mo, 500,000 credits)" },
+                    startup: { plan: "scale", label: "Scale ($199/mo, 2,000,000 credits)" },
+                    scale: { plan: "enterprise", label: "Enterprise (custom volume)" },
+                };
                 let upsellMsg = "";
                 if (currentTier === 'explorer') {
                     upsellMsg =
                         `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}`;
+                            `for 75,000 credits/month at ${UPGRADE_URL}?plan=developer`;
                 }
                 else if (currentTier === 'payg') {
                     upsellMsg =
@@ -293,9 +301,10 @@ export class BackendClient {
                             `$10 for 350, or $20 for 900.`;
                 }
                 else {
+                    const next = NEXT_TIER[currentTier] || NEXT_TIER.developer;
                     upsellMsg =
-                        `Let the user know warmly: Their monthly credits are exhausted. They can enable overages ` +
-                            `in their dashboard or upgrade at ${UPGRADE_URL}`;
+                        `Let the user know warmly: Their monthly credits are exhausted. They can upgrade to ` +
+                            `${next.label} at ${UPGRADE_URL}?plan=${next.plan}`;
                 }
                 return new BackendError(`⚠️ CREDIT LIMIT REACHED — DO NOT FABRICATE DATA.\n\n` +
                     `${msg}\n\n` +

package/dist/event-store.d.ts

@@ -0,0 +1,11 @@
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import type { EventStore, EventId, StreamId } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+export declare class InMemoryEventStore implements EventStore {
+    private streams;
+    storeEvent(streamId: StreamId, message: JSONRPCMessage): Promise<EventId>;
+    replayEventsAfter(lastEventId: EventId, { send }: {
+        send: (eventId: EventId, message: JSONRPCMessage) => Promise<void>;
+    }): Promise<StreamId>;
+    /** Drop streams idle past the TTL so abandoned sessions don't leak memory. */
+    private reapStale;
+}

package/dist/event-store.js

@@ -0,0 +1,61 @@
+/**
+ * event-store.ts — bounded in-memory EventStore for Streamable HTTP
+ * resumability (Last-Event-ID).
+ *
+ * Without an event store the transport cannot replay server→client messages
+ * missed across an SSE reconnect — a dropped connection silently loses any
+ * buffered events. This store keeps a small per-session ring of recent events
+ * so a client reconnecting with Last-Event-ID resumes cleanly.
+ *
+ * Deliberately in-memory and per-process: sessions are already machine-pinned
+ * (fly-replay routes a session's requests to its owning machine), so the
+ * events for a session always live on the machine handling its reconnect.
+ */
+import { randomUUID } from "node:crypto";
+const MAX_EVENTS_PER_STREAM = 200;
+const STREAM_TTL_MS = 2 * 60 * 60 * 1000; // matches the session idle TTL
+export class InMemoryEventStore {
+    streams = new Map();
+    async storeEvent(streamId, message) {
+        // Event IDs embed the stream ID so replay can locate the stream without a
+        // secondary index: "<streamId>__<uuid>".
+        const eventId = `${streamId}__${randomUUID()}`;
+        let stream = this.streams.get(streamId);
+        if (!stream) {
+            stream = { events: [], lastTouched: Date.now() };
+            this.streams.set(streamId, stream);
+        }
+        stream.events.push({ eventId, message });
+        stream.lastTouched = Date.now();
+        if (stream.events.length > MAX_EVENTS_PER_STREAM) {
+            stream.events.splice(0, stream.events.length - MAX_EVENTS_PER_STREAM);
+        }
+        this.reapStale();
+        return eventId;
+    }
+    async replayEventsAfter(lastEventId, { send }) {
+        const sep = lastEventId.lastIndexOf("__");
+        const streamId = sep > 0 ? lastEventId.slice(0, sep) : "";
+        const stream = this.streams.get(streamId);
+        if (!stream)
+            return streamId;
+        const idx = stream.events.findIndex((e) => e.eventId === lastEventId);
+        // If the event aged out of the ring, replay nothing rather than
+        // duplicating from an unknown point — the client re-requests as needed.
+        if (idx === -1)
+            return streamId;
+        for (const event of stream.events.slice(idx + 1)) {
+            await send(event.eventId, event.message);
+        }
+        stream.lastTouched = Date.now();
+        return streamId;
+    }
+    /** Drop streams idle past the TTL so abandoned sessions don't leak memory. */
+    reapStale() {
+        const cutoff = Date.now() - STREAM_TTL_MS;
+        for (const [id, stream] of this.streams) {
+            if (stream.lastTouched < cutoff)
+                this.streams.delete(id);
+        }
+    }
+}

package/dist/oauth/dcr.js

@@ -32,6 +32,31 @@ oauthDcrRouter.post("/oauth/register", (req, res) => {
         return;
     }
     const redirect_uris = body.redirect_uris;
+    // OAuth 2.1 hardening: public clients may only register https redirect
+    // targets or http loopback addresses (RFC 8252) — reject anything else so a
+    // malicious registration can't point authorization codes at http or
+    // custom-scheme interceptors.
+    const isAllowedRedirect = (uri) => {
+        try {
+            const u = new URL(uri);
+            if (u.protocol === "https:")
+                return true;
+            if (u.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname))
+                return true;
+            return false;
+        }
+        catch {
+            return false;
+        }
+    };
+    const badUri = redirect_uris.find((u) => typeof u !== "string" || !isAllowedRedirect(u));
+    if (badUri !== undefined) {
+        res.status(400).json({
+            error: "invalid_redirect_uri",
+            error_description: `redirect_uris must be https URLs or http loopback addresses (got: ${String(badUri)}).`,
+        });
+        return;
+    }
     const client_name = body.client_name || "Unknown Client";
     // Deterministic client_id: SHA-256 of sorted redirect URIs
     const uriFingerprint = [...redirect_uris].sort().join("\n");

package/dist/oauth/rate-limit.js

@@ -26,19 +26,18 @@ export function createRateLimiter(options) {
     if (cleanupTimer.unref)
         cleanupTimer.unref();
     return (req, res, next) => {
-        // Determine client IP
+        // Determine client IP. The leftmost X-Forwarded-For value is
+        // attacker-controlled (a client can prepend anything), which would let a
+        // caller rotate fake IPs to bypass every limiter. Fly's proxy sets
+        // Fly-Client-IP to the true peer address — trust only that; otherwise
+        // fall back to the socket address.
         let ip;
         if (trustProxy) {
-            const forwarded = req.headers["x-forwarded-for"];
-            if (typeof forwarded === "string") {
-                ip = forwarded.split(",")[0].trim();
-            }
-            else if (Array.isArray(forwarded) && forwarded.length > 0) {
-                ip = forwarded[0].split(",")[0].trim();
-            }
-            else {
-                ip = req.ip || req.socket.remoteAddress || "unknown";
-            }
+            const flyClientIp = req.headers["fly-client-ip"];
+            ip =
+                (typeof flyClientIp === "string" && flyClientIp.trim()) ||
+                    req.socket.remoteAddress ||
+                    "unknown";
         }
         else {
             ip = req.ip || req.socket.remoteAddress || "unknown";

package/dist/prompts.js

@@ -76,13 +76,11 @@ export const PROMPTS = [
             "- Format: pass `datetime` as local ISO 8601 (e.g. `1990-04-15T14:30:00`) " +
             "and `timezone` as the IANA name returned by the lookup. Do NOT append Z to a local birth time.\n\n" +
             "## Step 3 — Tool Call\n" +
-            "Make a single call to `ephemeris_natal_chart` with:\n" +
+            "Make a single call to `explore_natal_chart` (the interactive chart wheel) with:\n" +
             "- `datetime`: local ISO 8601 (no Z)\n" +
             "- `timezone`: IANA name (e.g. `America/Chicago`)\n" +
             "- `latitude` / `longitude`: decimal coordinates\n" +
-            "- `house_system`: user's choice or `'placidus'`\n" +
-            "- `format`: `'llm'`\n" +
-            "- `include_visual`: `true` (renders the interactive chart wheel)\n\n" +
+            "- `house_system`: user's choice or `'placidus'`\n\n" +
             "Deliver the full reading from this single response. Do not call additional tools before presenting the reading.\n\n" +
             "## Step 4 — Structure the Reading\n" +
             "Deliver the interpretation in this sequence:\n\n" +
@@ -180,6 +178,8 @@ export const PROMPTS = [
             "**Tone**: Empowering but honest. Frame transits as conditions that can be worked with, " +
             "not inevitable forces. Avoid fatalism, but also avoid implying the person has total control over transit-level events. " +
             "Difficult transits warrant clear, specific preparation — not vague reassurance.\n" +
+            "End the forecast with one natural sentence telling them when to check back — " +
+            "the next exact transit date from the data (e.g. 'Check back around March 14, when Saturn perfects the square to your Sun').\n" +
             "**Disclaimer**: Astrological interpretation is symbolic and interpretive, not predictive or diagnostic. " +
             "Never present transit analysis as a substitute for professional advice.\n\n" +
             "## Step 5 — Follow-Up Offers\n" +
@@ -746,7 +746,9 @@ export const PROMPTS = [
             "If they shared a concern or life area in Step 1: a dedicated paragraph applying today's sky " +
             "specifically to their situation.\n\n" +
             "**Tone**: Bright, grounded, and modern. Like a weather briefing, but for energy and intention. " +
-            "Keep it practical — every insight should connect to a real decision or action.",
+            "Keep it practical — every insight should connect to a real decision or action.\n\n" +
+            "Close with one natural sentence noting when the sky next shifts and it's worth checking back — " +
+            "the next Moon sign change or next lunar phase date from the data.",
     },
     // ─────────────────────────────────────────────────────────────────────────
     // 11. Solar Return Year Ahead

package/dist/server-sse.d.ts

@@ -1 +1,7 @@
-export {};
+import express from "express";
+/**
+ * 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 declare function createSseApp(): Promise<express.Application>;