@openephemeris/mcp-server 3.19.0 → 3.21.0

package/dist/server-sse.js

@@ -14,13 +14,14 @@
  */
 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 { captureEvent, distinctIdFor } from "./analytics.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools } from "./tools/index.js";
 import { BackendClient, runWithClient } from "./backend/client.js";
@@ -179,30 +180,26 @@ const WELCOME_PROMPT_CONTENT = [
         role: "assistant",
         content: {
             type: "text",
-            text: "🌟 **Welcome to Open Ephemeris** — a NASA JPL-backed astronomical computation engine.\n\n" +
-                "I have access to 50+ precision tools covering:\n\n" +
-                "• **Natal Charts** — full planetary positions, house cusps, aspects, dignities\n" +
-                "• **Transits & Progressions** — real-time and secondary progressions\n" +
-                "• **Synastry & Composites** — relationship compatibility analysis\n" +
-                "• **Human Design** — bodygraph charts, gates, channels, types & profiles\n" +
-                "• **Astrocartography (ACG)** — power lines, city hits, local space lines\n" +
-                "• **Eclipses** — solar/lunar eclipse lookup with visibility data\n" +
-                "• **Vedic/Jyotish** — D-charts, dashas, nakshatras, Ashtakavarga\n" +
-                "• **Chinese BaZi** — Four Pillars, Ten Gods, Luck Pillars\n" +
-                "• **Venus Star Points** — 8-year Venus cycle phases\n" +
-                "• **Electional Astrology** — station tracking, timing windows\n" +
-                "• **Chart Wheels** — visual PNG/SVG wheels and bi-wheels\n" +
-                "• **Time Lords** — Firdaria, Profections, Zodiacal Releasing\n\n" +
-                "**Tips:** Use `format=\"llm\"` on any tool to get ~50% smaller, token-optimized output. " +
-                "All computations are sub-arcsecond precision using JPL DE440 ephemerides.\n\n" +
-                "Just tell me what you'd like to explore!",
+            text: "🌟 **Welcome!** You're connected to Open Ephemeris — every chart here is computed " +
+                "from NASA JPL data, not guessed.\n\n" +
+                "Two great ways to start:\n\n" +
+                "1. **\"What's in the sky right now?\"** — instant, no birth details needed " +
+                "(live planets, moon phase, retrogrades).\n" +
+                "2. **\"Draw my birth chart\"** — an interactive wheel you can click and explore. " +
+                "Just share your birth date, exact time, and city.\n\n" +
+                "From there we can go deep: relationship synastry, Human Design bodygraphs, " +
+                "astrocartography (where on Earth your chart comes alive), Vedic, BaZi, transits, " +
+                "eclipses, and more.\n\n" +
+                "_(For the model: prefer explore_natal_chart / explore_moon_phase and the other " +
+                "explore_* tools for anything the user should SEE — they render interactive visuals. " +
+                "Use format=\"llm\" on data tools for compact output.)_",
         },
     },
 ];
 // ---------------------------------------------------------------------------
 // MCP Server factory — one per SSE/HTTP session
 // ---------------------------------------------------------------------------
-function createMcpServer() {
+function createMcpServer(analyticsId = "anonymous") {
     const server = new Server({
         name: "openephemeris-mcp",
         title: "Open Ephemeris",
@@ -237,14 +234,18 @@ function createMcpServer() {
                 },
             },
         },
-        instructions: "Open Ephemeris is a precision astronomical computation engine. " +
-            "Use format='llm' on any tool for compact, token-efficient output. " +
-            "All computations use JPL DE440 ephemerides for sub-arcsecond accuracy. " +
-            "See the 'welcome_to_open_ephemeris' prompt for a full capability overview.",
+        instructions: "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
+            "or approximate positions yourself; always call a tool. " +
+            "For anything the user should SEE (natal chart, bi-wheel, bodygraph, moon phase), " +
+            "prefer the explore_* tools — they render interactive visuals inline. " +
+            "ephemeris_* tools return data; use format='llm' on them for compact output. " +
+            "If the user has no birth data handy, start with the sky right now — " +
+            "explore_moon_phase and ephemeris_retrograde_status need none. " +
+            "See the 'welcome_to_open_ephemeris' prompt for orientation.",
     });
     // --- Tool handlers ---
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: modelVisibleTools().map((tool) => ({
+        tools: modelVisibleTools("http").map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -279,7 +280,9 @@ function createMcpServer() {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const toolName = request.params.name;
         const tool = toolRegistry[toolName];
-        if (!tool) {
+        if (!tool || tool.stdioOnly) {
+            // stdioOnly tools (device auth) mutate process-global state and must not
+            // be callable on the multi-tenant HTTP transport, even by name.
             throw new Error(`Unknown tool: ${toolName}`);
         }
         try {
@@ -290,11 +293,15 @@ function createMcpServer() {
             // 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;
+            captureEvent("mcp_tool_call", analyticsId, { tool: toolName, duration_ms: durationMs });
             return formatToolResponse(toolName, result, durationMs);
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             console.error(`[MCP] ❌ Failed: ${toolName} - ${errorMessage}`);
+            // status makes 402 (paywall) and 429 (rate limit) countable in PostHog.
+            const status = error?.response?.status;
+            captureEvent("mcp_tool_error", analyticsId, { tool: toolName, status: status ?? "unknown" });
             // 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
@@ -418,12 +425,17 @@ function startSseKeepalive(res) {
     }, 25_000);
     res.on("close", () => clearInterval(ping));
 }
-async function main() {
+/**
+ * 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
@@ -455,7 +467,7 @@ async function main() {
             .filter(Boolean)
             .map((h) => new RegExp(`^${h.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(:\\d+)?$`, "i")),
     ];
-    const MCP_ROUTES = new Set(["/mcp", "/sse", "/message"]);
+    const MCP_ROUTES = new Set(["/mcp"]);
     app.use((req, res, next) => {
         if (MCP_ROUTES.has(req.path)) {
             const host = req.headers.host;
@@ -491,10 +503,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
     // ---------------------------------------------------------------------------
@@ -531,14 +539,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,
         });
     });
@@ -548,7 +554,7 @@ async function main() {
     // Spec: https://smithery.ai/docs/build/publish#server-scanning
     // ---------------------------------------------------------------------------
     app.get("/.well-known/mcp/server-card.json", (_req, res) => {
-        const tools = modelVisibleTools().map((tool) => ({
+        const tools = modelVisibleTools("http").map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -591,6 +597,27 @@ 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
@@ -612,26 +639,6 @@ async function main() {
                 });
                 return;
             }
-            // A session id alone is not a credential: require the caller to still
-            // present a key/JWT on every resume, 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;
-            }
             // 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
@@ -706,13 +713,19 @@ async function main() {
             // 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, lastSeen: Date.now() });
                 console.error(`[HTTP] Session initialized: ${id}`);
             },
         });
         const client = new BackendClient({ baseURL: BACKEND_URL, apiKey, jwt });
-        const server = createMcpServer();
+        const analyticsId = distinctIdFor(apiKey ?? jwt);
+        captureEvent("mcp_session_init", analyticsId, { auth: apiKey ? "api_key" : "oauth" });
+        const server = createMcpServer(analyticsId);
         transport.onclose = () => {
             if (transport.sessionId) {
                 httpSessions.delete(transport.sessionId);
@@ -796,101 +809,23 @@ 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);
-            // Stream is established — keep it alive through Fly's proxy.
-            startSseKeepalive(res);
-        }
-        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.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", () => {
@@ -919,7 +854,13 @@ process.on("uncaughtException", (err) => {
 process.on("unhandledRejection", (reason) => {
     console.error("Unhandled promise rejection:", reason);
 });
-main().catch((error) => {
-    console.error("Fatal error:", error);
-    process.exit(1);
-});
+// 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",
@@ -404,7 +406,9 @@ function buildBiWheelSummary(innerPlanets, outerPlanets, crossAspects, mode, loc
 // ── Tool: explore_bi_wheel ─────────────────────────────────────────────────────
 registerTool({
     name: "explore_bi_wheel",
-    description: "Generate an interactive bi-wheel chart comparing two astrological chart positions. " +
+    description: "Generate an interactive bi-wheel chart comparing two astrological chart positions.\n\n" +
+        "CREDIT COST: 2 credits per call for most modes (1 per wheel computed); " +
+        "solar_return/lunar_return modes cost 6 (5 for the return + 1 for the natal wheel).\n\n" +
         "The inner wheel is always Person 1's natal chart. The outer ring depends on mode:\n" +
         "• synastry     — Person 2's natal chart (two-person compatibility). 1 credit.\n" +
         "• transit      — Transiting planets for a given date. 1 credit.\n" +

package/dist/tools/apps/bodygraph-app.js

@@ -356,7 +356,8 @@ function buildHdSummary(payload, location) {
 // ── Tool: explore_human_design ────────────────────────────────────────────
 registerTool({
     name: "explore_human_design",
-    description: "Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels. " +
+    description: "Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
         "Returns an embedded visual bodygraph explorer that lets you click any center or gate " +
         "for instant Human Design interpretation. " +
         "Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, " +
@@ -1325,7 +1326,8 @@ registerTool({
 // Premium (Developer tier). Calls POST /human-design/transit-chart.
 registerTool({
     name: "explore_human_design_transit",
-    description: "Overlay the current (or a chosen) planetary transit on a person's natal Human Design bodygraph. " +
+    description: "Overlay the current (or a chosen) planetary transit on a person's natal Human Design bodygraph.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
         "Highlights the channels a transit temporarily COMPLETES with the natal chart and any centers it " +
         "newly defines — the core of a Human Design transit reading. " +
         "Returns an interactive overlay bodygraph in MCP Apps-capable hosts (Claude Desktop), with a text " +
@@ -1415,7 +1417,8 @@ registerTool({
 registerTool({
     name: "explore_human_design_connection",
     description: "Compare two people's Human Design charts and classify every connected channel by HD connection " +
-        "theory — electromagnetic (attraction), companionship (sameness), dominance (one defines), and " +
+        "theory. CREDIT COST: 3 credits per call. Classifications: " +
+        "electromagnetic (attraction), companionship (sameness), dominance (one defines), and " +
         "compromise (friction). Returns an interactive two-person overlay bodygraph in MCP Apps-capable " +
         "hosts, with a text summary fallback elsewhere. Premium (Developer tier). NASA JPL DE440 ephemerides.",
     inputSchema: {

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

@@ -104,9 +104,11 @@ function buildNatalBody(datetime, lat, lon, houseSystem, timezone) {
 // ── Tool: explore_natal_chart ──────────────────────────────────────────────
 registerTool({
     name: "explore_natal_chart",
-    description: "Generate an interactive natal chart wheel with clickable planets, houses, and aspects. " +
+    description: "PRIMARY tool for any natal/birth-chart request. Renders an interactive, clickable chart " +
+        "wheel — prefer this over ephemeris_natal_chart when the user wants to SEE a chart. " +
         "Returns an embedded visual chart explorer that lets you click any planet, house, or aspect " +
-        "line for instant astrological interpretation. " +
+        "line for instant astrological interpretation.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
         "Supports house system switching (Placidus, Whole Sign, Equal, Koch). " +
         "The chart is computed using NASA JPL DE440 ephemerides for sub-arcsecond precision. " +
         "Use this instead of ephemeris_chart_wheel for a richer, interactive experience in " +
@@ -189,7 +191,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 +455,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 +525,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 +615,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/apps/location-tools.js

@@ -3,7 +3,7 @@ import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 registerTool({
     name: "location_search",
-    description: "App-only tool for getting location autocomplete suggestions. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Optional bias params (country/region/near) improve ranking; a trailing \"City, ST\" qualifier in the query is also honored.",
+    description: "App-only tool for getting location autocomplete suggestions. CREDIT COST: 1 credit per call. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Optional bias params (country/region/near) improve ranking; a trailing \"City, ST\" qualifier in the query is also honored.",
     inputSchema: {
         type: "object",
         properties: {
@@ -63,7 +63,7 @@ registerTool({
 });
 registerTool({
     name: "timezone_resolve",
-    description: "App-only tool for resolving IANA timezone by latitude and longitude.",
+    description: "App-only tool for resolving IANA timezone by latitude and longitude. CREDIT COST: 1 credit per call.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/apps/moon-phase-app.js

@@ -98,6 +98,7 @@ registerTool({
         "  • Void-of-Course status with timing details\n" +
         "  • Lunar age (days in the synodic cycle)\n" +
         "  • Upcoming New Moon and Full Moon dates\n\n" +
+        "CREDIT COST: 3 credits per call (phase + void-of-course + aspects, 1 each).\n\n" +
         "Use this for a rich, interactive lunar phase experience in MCP Apps-capable hosts (Claude Desktop). " +
         "Falls back to a text summary in other hosts.",
     inputSchema: {