@openephemeris/mcp-server 3.17.0 → 3.20.0

package/dist/server-sse.js

@@ -14,15 +14,15 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
 import express from "express";
 import axios from "axios";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { InMemoryEventStore } from "./event-store.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } 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 { BackendClient, 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";
@@ -34,6 +34,7 @@ import { oauthDcrRouter } from "./oauth/dcr.js";
 import { oauthTokenRouter } from "./oauth/token.js";
 import { OAuthStore } from "./oauth/store.js";
 import { createRateLimiter } from "./oauth/rate-limit.js";
+import { isJwtExpired, encodeSessionId, replayTargetMachine, } from "./oauth/session-utils.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -73,9 +74,14 @@ const version = resolveServerVersion();
  */
 async function validateApiKey(apiKey) {
     try {
-        const resp = await axios.get(`${BACKEND_URL}/ephemeris/moon/phase`, {
+        // Use a genuinely free, auth-gated endpoint. /catalogs/bodies is metered at
+        // 0 credits (usage_meter.go EstimateUsageUnits) yet still requires auth (NOT
+        // in middleware.go IsPublicPath), so an invalid key returns 401/403 while a
+        // valid key is validated without charging a credit on every session init.
+        // (The previous /ephemeris/moon/phase probe fell through to the default
+        // 1-credit charge — connecting cost the user a credit.)
+        const resp = await axios.get(`${BACKEND_URL}/catalogs/bodies`, {
             headers: { "X-API-Key": apiKey },
-            params: { datetime: new Date().toISOString() }, // required param per OpenAPI spec
             timeout: 5_000,
             validateStatus: () => true, // don't throw on any status
         });
@@ -279,25 +285,22 @@ function createMcpServer() {
         try {
             const startTime = Date.now();
             console.error(`[MCP] Executing tool: ${toolName}`);
-            const result = await tool.handler(request.params.arguments ?? {});
+            // Bound execution so a hung backend request can't pin the session forever.
+            // 120s comfortably covers the slowest known endpoint (cold heatmap
+            // composite ~9.3s) with a wide margin.
+            const result = await withTimeout(tool.handler(request.params.arguments ?? {}), TOOL_CALL_TIMEOUT_MS, toolName);
             const durationMs = Date.now() - startTime;
             return formatToolResponse(toolName, result, durationMs);
         }
         catch (error) {
-            const startTime = Date.now(); // Not strictly accurate for errors but acceptable for logging structure if needed
-            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,
-            };
+            console.error(`[MCP] ❌ Failed: ${toolName} - ${errorMessage}`);
+            // All failures surface as isError: true so the host can recover
+            // (retry / OAuth refresh). The remote transport has no device-auth flow,
+            // so formatToolError's device-auth exception never fires here — a 401
+            // (including the "disconnect and reconnect" message) renders as a real
+            // error and prompts the host's OAuth refresh.
+            return formatToolError(error);
         }
     });
     // --- Resource handlers ---
@@ -370,12 +373,62 @@ function createMcpServer() {
     return server;
 }
 const httpSessions = new Map();
-async function main() {
+// Sessions are held in memory and only freed on explicit DELETE / transport
+// close. Hosts that vanish without teardown (tab closed, network drop) would
+// otherwise leak sessions until process restart, so reap anything idle past
+// the TTL. A reaped session 404s on its next request and the client
+// re-initializes per the MCP spec.
+const SESSION_IDLE_TTL_MS = 2 * 60 * 60 * 1000; // 2h
+const TOOL_CALL_TIMEOUT_MS = 120_000;
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Tool '${label}' timed out after ${ms / 1000}s`)), ms);
+        promise.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+function reapIdleSessions() {
+    const cutoff = Date.now() - SESSION_IDLE_TTL_MS;
+    for (const [id, session] of httpSessions) {
+        if (session.lastSeen < cutoff) {
+            httpSessions.delete(id);
+            session.server.close().catch(() => { });
+            console.error(`[HTTP] Session reaped (idle > ${SESSION_IDLE_TTL_MS / 60000}m): ${id}`);
+        }
+    }
+}
+/**
+ * Keep a long-lived SSE response alive through Fly's proxy and any
+ * intermediaries: disable the socket idle timeout and emit an SSE comment
+ * frame every 25s (comment frames are ignored by EventSource parsers).
+ * Call only after the transport has sent the SSE headers.
+ */
+function startSseKeepalive(res) {
+    res.socket?.setTimeout(0);
+    const ping = setInterval(() => {
+        if (res.writableEnded || res.destroyed) {
+            clearInterval(ping);
+            return;
+        }
+        try {
+            res.write(":ping\n\n");
+        }
+        catch {
+            clearInterval(ping);
+        }
+    }, 25_000);
+    res.on("close", () => clearInterval(ping));
+}
+/**
+ * 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() {
     await initTools();
     const app = express();
-    // NOTE: Do NOT use express.json() globally — SSEServerTransport.handlePostMessage
-    // reads the raw request stream itself. Pre-parsing with express.json() consumes it,
-    // causing "stream is not readable" errors.
+    // NOTE: express.json() is applied per-route (jsonParser on /mcp POST), not
+    // globally — the OAuth token route needs urlencoded, and transports that
+    // read the raw request stream break if the body is pre-consumed.
     // CORS + Origin allowlist
     // Per Anthropic remote-MCP review criteria, browser-originated requests must
     // be validated against an allowlist. Native (no-Origin) clients like Claude
@@ -391,6 +444,36 @@ async function main() {
     function isOriginAllowed(origin) {
         return ORIGIN_ALLOWLIST.some((m) => typeof m === "string" ? m === origin : m.test(origin));
     }
+    // DNS-rebinding defense: Origin validation alone doesn't cover the Host
+    // header, which is the vector rebinding attacks use. Restrict the MCP
+    // endpoints to the hosts we actually serve. Override/extend with
+    // MCP_ALLOWED_HOSTS (comma-separated) if the deployment hostname changes.
+    const HOST_ALLOWLIST = [
+        /^mcp\.openephemeris\.com$/i,
+        /^oe-mcp-live\.fly\.dev$/i,
+        /^localhost(:\d+)?$/i,
+        /^127\.0\.0\.1(:\d+)?$/i,
+        /^\[::1\](:\d+)?$/i,
+        ...(process.env.MCP_ALLOWED_HOSTS ?? "")
+            .split(",")
+            .map((h) => h.trim())
+            .filter(Boolean)
+            .map((h) => new RegExp(`^${h.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(:\\d+)?$`, "i")),
+    ];
+    const MCP_ROUTES = new Set(["/mcp"]);
+    app.use((req, res, next) => {
+        if (MCP_ROUTES.has(req.path)) {
+            const host = req.headers.host;
+            if (host && !HOST_ALLOWLIST.some((m) => m.test(host))) {
+                res.status(403).json({
+                    error: "host_not_allowed",
+                    error_description: `Host '${host}' is not permitted.`,
+                });
+                return;
+            }
+        }
+        next();
+    });
     app.use((req, res, next) => {
         const origin = req.headers.origin;
         // Browser request → must match allowlist. Native client (no Origin) → allow.
@@ -413,10 +496,6 @@ async function main() {
         }
         next();
     });
-    // Track active transports by session ID
-    const transports = new Map();
-    // Per-session BackendClient — each connection authenticates independently.
-    const sessionClients = new Map();
     // ---------------------------------------------------------------------------
     // OAuth 2.1 routes — must be mounted BEFORE JSON body parser
     // ---------------------------------------------------------------------------
@@ -453,14 +532,12 @@ async function main() {
         sessionRateLimiter(req, res, next);
     };
     app.use("/mcp", throttleSessionCreation);
-    app.use("/sse", sessionRateLimiter);
     // Health check
     app.get("/health", (_req, res) => {
         res.json({
             ok: true,
             version,
-            transports: ["sse", "streamable-http"],
-            sse_sessions: transports.size,
+            transports: ["streamable-http"],
             http_sessions: httpSessions.size,
         });
     });
@@ -513,14 +590,56 @@ async function main() {
         const sessionId = req.headers["mcp-session-id"];
         // Resume existing session
         if (sessionId) {
+            // A session id alone is not a credential: require a key/JWT BEFORE the
+            // session lookup so an unauthenticated probe can't learn whether a
+            // session id exists, and reject an expired JWT with the OAuth-refresh
+            // signal (same semantics as the init gate below).
+            const resumedAuth = extractAuth(req);
+            if (!resumedAuth.apiKey && !resumedAuth.jwt) {
+                res.set("WWW-Authenticate", `Bearer realm="OpenEphemeris MCP", resource_metadata="${PROTECTED_RESOURCE_METADATA_URL}"`);
+                res.status(401).json({
+                    error: "auth_required",
+                    message: "Authentication required on every request. Pass an API key via X-API-Key header, or a Bearer token via Authorization header.",
+                });
+                return;
+            }
+            if (resumedAuth.jwt && isJwtExpired(resumedAuth.jwt)) {
+                res.set("WWW-Authenticate", `Bearer realm="OpenEphemeris MCP", error="invalid_token", error_description="The access token expired", resource_metadata="${PROTECTED_RESOURCE_METADATA_URL}"`);
+                res.status(401).json({
+                    error: "invalid_token",
+                    message: "Your session token has expired. Re-authorize to continue.",
+                });
+                return;
+            }
             const session = httpSessions.get(sessionId);
             if (!session) {
+                // Cross-machine session recovery (Fly): min_machines_running >= 2 but
+                // httpSessions is per-process. If the session id encodes a DIFFERENT
+                // machine, ask Fly's proxy to replay this request to the owning machine
+                // — unless it was already replayed once (loop guard), in which case we
+                // fall through to 404 so the client re-initializes per the MCP spec.
+                const target = replayTargetMachine(sessionId, {
+                    alreadyReplayed: typeof req.headers["fly-replay-src"] === "string",
+                });
+                if (target) {
+                    res.set("fly-replay", `instance=${target}`);
+                    res.status(307).end();
+                    return;
+                }
                 res.status(404).json({
                     error: "session_not_found",
                     message: "Unknown or expired MCP session. Re-initialize to start a new one.",
                 });
                 return;
             }
+            // Refresh the session's Bearer JWT if the host rotated it. claude.ai
+            // refreshes tokens via /oauth/token roughly hourly (self-signed Supabase
+            // JWTs expire in 1h); the frozen JWT captured at init would otherwise 401
+            // forever. Re-read the header and push the fresh token into the client.
+            if (resumedAuth.jwt) {
+                session.client.setJwt(resumedAuth.jwt);
+            }
+            session.lastSeen = Date.now();
             await runWithClient(session.client, () => session.transport.handleRequest(req, res, req.body));
             return;
         }
@@ -538,6 +657,19 @@ async function main() {
             });
             return;
         }
+        // Reject already-expired JWTs at the gate with an OAuth-refresh signal.
+        // Signature is validated downstream by the Go API — here we only decode the
+        // `exp` claim (no verification) so an expired token triggers the host's
+        // token refresh (401 invalid_token) instead of dying as a confusing tool
+        // error mid-session.
+        if (jwt && isJwtExpired(jwt)) {
+            res.set("WWW-Authenticate", `Bearer realm="OpenEphemeris MCP", error="invalid_token", error_description="The access token expired", resource_metadata="${PROTECTED_RESOURCE_METADATA_URL}"`);
+            res.status(401).json({
+                error: "invalid_token",
+                message: "Your session token has expired. Re-authorize to continue.",
+            });
+            return;
+        }
         // Validate API keys against the Go backend; JWTs are validated downstream
         // by the Go sidecar's ValidateSupabaseJWT when tool calls are proxied.
         if (apiKey) {
@@ -570,9 +702,16 @@ async function main() {
         }
         // Create per-session transport, server, and client
         const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: randomUUID,
+            // Embed the Fly machine id so a resume request landing on another machine
+            // can be replayed to the owner (see the resume branch above). No-op off
+            // Fly (FLY_MACHINE_ID unset) — the raw UUID is used unchanged.
+            sessionIdGenerator: () => encodeSessionId(randomUUID()),
+            // Last-Event-ID resumability: a reconnecting SSE stream replays the
+            // events it missed instead of silently losing them. Per-process is fine
+            // — the session is machine-pinned via fly-replay.
+            eventStore: new InMemoryEventStore(),
             onsessioninitialized: (id) => {
-                httpSessions.set(id, { server, transport, client });
+                httpSessions.set(id, { server, transport, client, lastSeen: Date.now() });
                 console.error(`[HTTP] Session initialized: ${id}`);
             },
         });
@@ -599,12 +738,24 @@ async function main() {
         }
         const session = httpSessions.get(sessionId);
         if (!session) {
+            // Cross-machine replay for the SSE leg (same scheme as POST /mcp resume).
+            const target = replayTargetMachine(sessionId, {
+                alreadyReplayed: typeof req.headers["fly-replay-src"] === "string",
+            });
+            if (target) {
+                res.set("fly-replay", `instance=${target}`);
+                res.status(307).end();
+                return;
+            }
             res.status(404).json({
                 error: "session_not_found",
                 message: "Unknown or expired MCP session.",
             });
             return;
         }
+        session.lastSeen = Date.now();
+        // The SSE leg stays open indefinitely — keep it alive through proxies.
+        startSseKeepalive(res);
         await session.transport.handleRequest(req, res);
     });
     // DELETE /mcp — client-initiated session teardown
@@ -649,102 +800,34 @@ async function main() {
         }
     });
     // ---------------------------------------------------------------------------
-    // Legacy SSE transport — MCP spec pre-2025 (kept for backward compatibility)
-    // Endpoint: GET https://mcp.openephemeris.com/sse
-    // New integrations should prefer /mcp (Streamable HTTP above).
+    // Legacy SSE transport — RETIRED in 3.20.0.
+    // The pre-2025 HTTP+SSE transport (/sse + /message) was SDK-deprecated, had
+    // no cross-machine replay (broken with min_machines_running >= 2), and live
+    // metrics showed zero sessions. 410 Gone points stragglers at /mcp.
     // ---------------------------------------------------------------------------
-    // SSE endpoint — clients GET /sse to establish a stream
-    app.get("/sse", async (req, res) => {
-        // Extract auth from query param or header (supports API keys + OAuth JWTs)
-        const { apiKey, jwt } = extractAuth(req);
-        if (!apiKey && !jwt) {
-            res.status(401).json({
-                error: "auth_required",
-                message: "Authentication required. Pass an API key via X-API-Key header or query param, or a Bearer JWT via Authorization header. Get a free key at https://openephemeris.com/dashboard?tab=apikeys",
-            });
-            return;
-        }
-        // Validate API keys against the Go backend; JWTs validated downstream.
-        if (apiKey) {
-            const keyStatus = await validateApiKey(apiKey);
-            if (keyStatus === "invalid") {
-                res.status(403).json({
-                    error: "invalid_api_key",
-                    message: "The provided API key is invalid or inactive. Check your key at https://openephemeris.com/dashboard?tab=apikeys",
-                });
-                return;
-            }
-            // Fail closed for browser clients when validation is unavailable (APP-6).
-            if (keyStatus === "unknown" && isBrowserOrigin(req)) {
-                res.set("Retry-After", "5");
-                res.status(503).json({
-                    error: "validation_unavailable",
-                    message: "Could not verify your API key right now. Please retry shortly.",
-                });
-                return;
-            }
-        }
-        const transport = new SSEServerTransport("/message", res);
-        const sessionId = transport.sessionId;
-        transports.set(sessionId, transport);
-        // Create a per-session BackendClient so concurrent SSE connections
-        // don't overwrite each other's API key on the shared singleton.
-        const sessionClient = new BackendClient({
-            baseURL: BACKEND_URL,
-            apiKey,
-            jwt,
+    const legacySseGone = (_req, res) => {
+        res.status(410).json({
+            error: "transport_retired",
+            message: "The legacy SSE transport has been retired. Connect via Streamable HTTP at https://mcp.openephemeris.com/mcp instead.",
         });
-        sessionClients.set(sessionId, sessionClient);
-        const server = createMcpServer();
-        // Guard: prevent double-close from crashing the process
-        let closed = false;
-        const cleanup = () => {
-            if (closed)
-                return;
-            closed = true;
-            transports.delete(sessionId);
-            sessionClients.delete(sessionId);
-            try {
-                server.close().catch(() => { });
-            }
-            catch { /* ignore */ }
-        };
-        transport.onclose = cleanup;
-        // Handle abrupt client disconnects (browser tab closed, etc.)
-        res.on("close", cleanup);
-        try {
-            // server.connect() calls transport.start() internally in SDK v1.27+
-            await server.connect(transport);
-        }
-        catch (err) {
-            console.error(`SSE session ${sessionId} failed to start:`, err);
-            cleanup();
-        }
-    });
-    // Message endpoint — clients POST /message?sessionId=xxx
-    app.post("/message", async (req, res) => {
-        const sessionId = req.query.sessionId;
-        const transport = transports.get(sessionId);
-        const sessionClient = sessionClients.get(sessionId);
-        if (!transport) {
-            res.status(400).json({
-                error: "invalid_session",
-                message: "Unknown or expired session. Re-connect to /sse first.",
-            });
-            return;
-        }
-        // Run handlePostMessage inside the session's client context so all tool
-        // handlers reach getActiveClient() and get this user's BackendClient.
-        if (sessionClient) {
-            await runWithClient(sessionClient, () => transport.handlePostMessage(req, res));
-        }
-        else {
-            await transport.handlePostMessage(req, res);
-        }
-    });
-    app.listen(PORT, "0.0.0.0", () => {
+    };
+    app.get("/sse", legacySseGone);
+    app.post("/message", legacySseGone);
+    return app;
+}
+async function main() {
+    const app = await createSseApp();
+    // Reap abandoned sessions (no DELETE, no transport close) every 10 minutes.
+    setInterval(reapIdleSessions, 10 * 60 * 1000).unref();
+    const httpServer = app.listen(PORT, "0.0.0.0", () => {
         console.log(`OpenEphemeris MCP SSE server v${version} listening on port ${PORT}`);
     });
+    // SSE streams are long-lived by design; Node 18+ closes idle connections
+    // after 5s keep-alive by default at the server level — the per-response
+    // socket timeout is disabled in startSseKeepalive, but also raise the
+    // server-wide headers/request timeouts so slow proxies don't get cut.
+    httpServer.keepAliveTimeout = 65_000;
+    httpServer.headersTimeout = 70_000;
 }
 // Prevent SDK recursive close bugs from crashing the process
 process.on("uncaughtException", (err) => {
@@ -755,7 +838,20 @@ process.on("uncaughtException", (err) => {
     console.error("Uncaught exception:", err);
     process.exit(1);
 });
-main().catch((error) => {
-    console.error("Fatal error:", error);
-    process.exit(1);
+// Log-and-continue on unhandled promise rejections. A rejected promise from a
+// single request (e.g. a client that disconnected mid-stream) must never take
+// down the whole server and kill every other live session. Log for triage and
+// keep serving.
+process.on("unhandledRejection", (reason) => {
+    console.error("Unhandled promise rejection:", reason);
 });
+// Only listen when run as the entry point — importing createSseApp from
+// tests must not bind a port or install the reaper interval.
+const isDirectRun = process.argv[1] !== undefined &&
+    import.meta.url.toLowerCase() === pathToFileURL(process.argv[1]).href.toLowerCase();
+if (isDirectRun) {
+    main().catch((error) => {
+        console.error("Fatal error:", error);
+        process.exit(1);
+    });
+}

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

@@ -248,15 +248,17 @@ export function computeCrossAspects(planets1, planets2) {
     const results = [];
     for (const p1 of planets1) {
         for (const p2 of planets2) {
-            let diff = Math.abs(p1.longitude - p2.longitude) % 360;
-            if (diff > 180)
-                diff = 360 - diff;
+            // Signed separation of p2 ahead of p1 (0–360), folded to shortest arc.
+            const delta = (((p2.longitude - p1.longitude) % 360) + 360) % 360;
+            const diff = delta > 180 ? 360 - delta : delta;
+            // Rate of change of the shortest-arc separation, from real daily motion.
+            const rel = (p2.speed ?? 0) - (p1.speed ?? 0);
+            const dDiff = delta > 180 ? -rel : rel;
             for (const asp of CROSS_ASPECT_DEFS) {
                 const orb = Math.abs(diff - asp.angle);
                 if (orb <= asp.orb) {
-                    const applying = ((p1.speed ?? 1) - (p2.speed ?? 0)) < 0
-                        ? diff < asp.angle
-                        : diff > asp.angle;
+                    // Applying = the separation is moving toward the exact aspect angle.
+                    const applying = (diff - asp.angle) * dDiff < 0;
                     results.push({
                         planet1: p1.name,
                         wheel1: "inner",

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

@@ -189,7 +189,7 @@ registerTool({
         const chartData = await client.post("/ephemeris/natal-chart", natalBody);
         // Build human-readable summary for the LLM context
         const summary = buildChartSummary(chartData, String(args.location ?? `${lat}, ${lon}`));
-        // Build the UI payload (planets normalised to array, aspects computed)
+        // Build the UI payload (planets normalised to array, server aspects mapped)
         const modelPayload = buildModelPayload(chartData, {
             datetime,
             timezone: args.timezone ?? null,
@@ -453,52 +453,39 @@ const ALL_KNOWN_BODIES = new Set([...CLASSICAL_PLANETS, ...EXTENDED_BODIES]);
  * Tokens saved vs. full uiPayload: ~85–95% reduction (no 100KB SVG, no asteroid flood).
  */
 /**
- * Compute major aspects between a set of planets.
- * Returns a structured AspectData[] array — the natal chart API does not
- * include aspects in its JSON response; we derive them from longitude data.
+ * Map the server-computed aspects array from /ephemeris/natal-chart (and the
+ * solar-return / progressed responses) to the AspectData shape the chart-wheel
+ * UI consumes: { planet1, planet2, type, angle, orb, applying }.
+ *
+ * The Go API computes aspects by default (options.include_aspects = true),
+ * including a proper ephemeris-based is_applying flag — so no client-side
+ * longitude heuristic is needed. Aspects are optionally filtered to the set of
+ * bodies actually displayed so lines never reference a hidden planet.
  */
-function computeAspects(planets) {
-    const ASPECTS = [
-        { type: "conjunction", angle: 0, orb: 8 },
-        { type: "opposition", angle: 180, orb: 8 },
-        { type: "trine", angle: 120, orb: 8 },
-        { type: "square", angle: 90, orb: 7 },
-        { type: "sextile", angle: 60, orb: 6 },
-        { type: "quincunx", angle: 150, orb: 3 },
-        { type: "semisquare", angle: 45, orb: 2 },
-    ];
+function mapServerAspects(rawAspects, allowedNames) {
+    if (!Array.isArray(rawAspects))
+        return [];
     const results = [];
-    for (let i = 0; i < planets.length; i++) {
-        for (let j = i + 1; j < planets.length; j++) {
-            const p1 = planets[i];
-            const p2 = planets[j];
-            // Angular separation: shortest arc (0–180)
-            let diff = Math.abs(p1.longitude - p2.longitude) % 360;
-            if (diff > 180)
-                diff = 360 - diff;
-            for (const asp of ASPECTS) {
-                const orb = Math.abs(diff - asp.angle);
-                // Tighten orbs when one or both bodies are extended (asteroids, etc.)
-                const p1Extended = EXTENDED_BODIES.has(p1.name.toLowerCase());
-                const p2Extended = EXTENDED_BODIES.has(p2.name.toLowerCase());
-                const effectiveOrb = (p1Extended || p2Extended)
-                    ? Math.min(asp.orb * 0.5, 3) // half standard, capped at 3°
-                    : asp.orb;
-                if (orb <= effectiveOrb) {
-                    // Applying: combined longitudinal speed closing the orb
-                    const applying = ((p1.speed ?? 1) - (p2.speed ?? 0)) < 0 ? diff < asp.angle : diff > asp.angle;
-                    results.push({
-                        planet1: p1.name,
-                        planet2: p2.name,
-                        type: asp.type,
-                        angle: asp.angle,
-                        orb: Math.round(orb * 100) / 100,
-                        applying,
-                    });
-                    break; // Each pair only matches one aspect type
-                }
-            }
-        }
+    for (const a of rawAspects) {
+        if (!a || typeof a !== "object")
+            continue;
+        const p1 = canonicalizeBodyName(String(a.planet1 ?? ""));
+        const p2 = canonicalizeBodyName(String(a.planet2 ?? ""));
+        if (!p1 || !p2)
+            continue;
+        if (allowedNames && (!allowedNames.has(p1) || !allowedNames.has(p2)))
+            continue;
+        results.push({
+            planet1: p1,
+            planet2: p2,
+            type: String(a.aspect_type ?? a.type ?? "aspect").toLowerCase(),
+            angle: Number(a.exact_angle ?? a.angle ?? 0),
+            orb: Math.round(Number(a.orb ?? 0) * 100) / 100,
+            // is_applying may be null when the server cannot determine it
+            applying: typeof a.is_applying === "boolean" ? a.is_applying
+                : typeof a.applying === "boolean" ? a.applying
+                    : undefined,
+        });
     }
     return results;
 }
@@ -536,8 +523,8 @@ function buildModelPayload(chartData, birthParams, houseSystem, svgBase, bodyFil
         // Already normalised (e.g. house system recalculate path)
         planetsArray = chartData.planets;
     }
-    // ── 2. Compute aspects from longitude data (API doesn't return them) ──────
-    const aspects = computeAspects(planetsArray);
+    // ── 2. Map server-computed aspects (filtered to displayed bodies) ─────────
+    const aspects = mapServerAspects(chartData.aspects, new Set(planetsArray.map((p) => p.name)));
     // ── 3. Extract angles — API nests ascendant/MC under an `angles` key ──────
     const rawAngles = chartData.angles;
     const rawHouseObj = chartData.houses;
@@ -626,10 +613,8 @@ function buildChartSummary(data, location) {
             elementCount[el]++;
     }
     const domElement = Object.entries(elementCount).sort((a, b) => b[1] - a[1])[0];
-    // Strongest aspect by tightest orb (use computed aspects from planetsArray)
-    const aspects = computeAspects(planetsArray
-        .filter((p) => p.longitude != null)
-        .map((p) => ({ name: p.name, longitude: p.longitude, speed: p.longitude_speed })));
+    // Strongest aspect by tightest orb (server-computed aspects)
+    const aspects = mapServerAspects(data.aspects);
     const strongest = aspects.sort((a, b) => a.orb - b.orb)[0];
     const strongestNote = strongest
         ? `Closest aspect: ${capitalize(strongest.planet1)} ${strongest.type} ${capitalize(strongest.planet2)} (${strongest.orb.toFixed(1)}° orb)`

package/dist/tools/dev.js

@@ -73,7 +73,7 @@ const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.open
     "  POST /acg/power-lines                 — Astrocartography power lines (lat/lon GeoJSON)\n" +
     "  POST /acg/hits                         — ACG power at a specific location\n" +
     "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
-    "  GET  /location/autocomplete            — Geocode a place name (query: q=City Name)\n" +
+    "  GET  /location/autocomplete            — Geocode a place name (query: query=City Name)\n" +
     "  POST /timezone/lookup                  — Resolve timezone + UTC offset for a location\n" +
     "  POST /chinese/bazi                     — Chinese Ba Zi (Four Pillars) chart (body: {year, month, day, hour})\n" +
     "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +