@openephemeris/mcp-server 3.8.0 → 3.9.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.9.0] — 2026-04-22
+
+### Added
+- **Streamable HTTP transport** (`POST/GET/DELETE /mcp`) — implements the MCP 2025-11-25
+  specification. New integrations (Smithery, cursor, Claude Web) should prefer
+  `https://mcp.openephemeris.com/mcp` over the legacy SSE endpoint. The SSE endpoint
+  (`/sse`) is retained for backward compatibility.
+- **`/.well-known/mcp/server-card.json`** — static server card served at the standard
+  well-known path. Allows Smithery and other registries to scan tool metadata without
+  requiring an authenticated session, enabling automatic listing and discovery.
+- **`extractApiKey()` helper** — shared auth extraction (X-API-Key / Authorization: Bearer
+  / X-OpenEphemeris-API-Key / ?apiKey) used by both transports, eliminating duplication.
+
+### Changed
+- `smithery.yaml` upgraded to modern `configSchema` + `commandFunction` format. Smithery
+  now renders a typed API key input field in its UI instead of a raw env map.
+- `/health` now reports both `sse_sessions` and `http_sessions` counts, and lists
+  `transports: ["sse", "streamable-http"]` for client introspection.
+
+---
+
 ## [3.8.0] — 2026-04-21
 
 ### Added
@@ -96,7 +117,7 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 
 ### Fixed
-- Chiron position fallback for edge-date calculations now uses full Swiss Ephemeris path instead of simplified approximation
+- Chiron position fallback for edge-date calculations now uses full high-precision ephemeris path instead of simplified approximation
 - SSE server chart wheel responses now correctly deliver native MCP image blocks instead of raw base64 JSON
 
 ### Changed

package/README.md

@@ -244,7 +244,7 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 ## Why OpenEphemeris for AI Agents?
 
-Most LLMs (like Claude and ChatGPT) struggle heavily with astronomical calculations (trigonometry, Julian date conversions, and Swiss Ephemeris lookups). OpenEphemeris serves as a **secure, remote math engine**.
+Most LLMs (like Claude and ChatGPT) struggle heavily with astronomical calculations (trigonometry, Julian date conversions, and planetary lookups). OpenEphemeris serves as a **secure, remote math engine**.
 
 By pairing LLMs with the OpenEphemeris MCP server, your agents can instantly access:
 - **Zero-hallucination coordinates**: Direct, sub-arcsecond NASA JPL DE440/DE441 calculations.

package/config/dev-allowlist.json

@@ -108,8 +108,8 @@
       "path": "/visualization/chart-wheel"
     }
   ],
-  "last_generated_at": "2026-04-22T01:16:37.771Z",
-  "openapi_sha256": "c649b6a9ba32e1576f9f12d2d78f1706d5bc279d7733a29f1e69a8ca042024d6",
+  "last_generated_at": "2026-04-22T15:19:21.508Z",
+  "openapi_sha256": "0c29ad2e37fd08d48800ec54059e262fbbdb681b844e00fed9274611bae678ac",
   "candidates_get": [
     {
       "method": "GET",

package/dist/server-sse.js

@@ -15,11 +15,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } 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 { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse } from "./tools/index.js";
 import { BackendClient, runWithClient } from "./backend/client.js";
 // ---------------------------------------------------------------------------
@@ -76,6 +78,20 @@ async function validateApiKey(apiKey) {
         return true;
     }
 }
+/**
+ * Extract an API key from a request using priority order:
+ *   1. X-API-Key header
+ *   2. X-OpenEphemeris-API-Key header
+ *   3. Authorization: Bearer <token>
+ *   4. ?apiKey query param
+ */
+function extractApiKey(req) {
+    return (req.headers["x-api-key"] ||
+        req.headers["x-openephemeris-api-key"] ||
+        req.headers["authorization"]?.replace(/^Bearer\s+/i, "") ||
+        req.query.apiKey ||
+        undefined);
+}
 // ---------------------------------------------------------------------------
 // MCP Server factory — one per SSE session
 // ---------------------------------------------------------------------------
@@ -132,9 +148,7 @@ function createMcpServer() {
     });
     return server;
 }
-// ---------------------------------------------------------------------------
-// Express + SSE wiring
-// ---------------------------------------------------------------------------
+const httpSessions = new Map();
 async function main() {
     await initTools();
     const app = express();
@@ -158,7 +172,143 @@ async function main() {
     const sessionClients = new Map();
     // Health check
     app.get("/health", (_req, res) => {
-        res.json({ ok: true, version, transport: "sse", sessions: transports.size });
+        res.json({
+            ok: true,
+            version,
+            transports: ["sse", "streamable-http"],
+            sse_sessions: transports.size,
+            http_sessions: httpSessions.size,
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Static server card — lets Smithery (and other registries) scan tools
+    // without needing an authenticated session. Updated on every deploy.
+    // Spec: https://smithery.ai/docs/build/publish#server-scanning
+    // ---------------------------------------------------------------------------
+    app.get("/.well-known/mcp/server-card.json", (_req, res) => {
+        const tools = Object.values(toolRegistry).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }));
+        res.json({
+            serverInfo: {
+                name: "Open Ephemeris",
+                version,
+                description: "NASA JPL-backed astronomical computation engine for AI agents. 48+ typed tools covering natal charts, transit forecasting, Human Design, eclipses, astrocartography, BaZi, and more — powered by DE440/DE441 for sub-arcsecond accuracy.",
+                iconUrl: "https://mcp.openephemeris.com/icon.png",
+                homepage: "https://openephemeris.com",
+            },
+            authentication: {
+                required: true,
+                schemes: ["apiKey"],
+                instructions: "Pass your Open Ephemeris API key via the X-API-Key header. Get a free Explorer key at https://openephemeris.com/dashboard",
+            },
+            tools,
+            resources: [],
+            prompts: [],
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Streamable HTTP transport — MCP spec 2025-11-25
+    // Endpoint: POST/GET/DELETE https://mcp.openephemeris.com/mcp
+    // Clients send X-API-Key (or Authorization: Bearer) on the init request.
+    // Session ID is managed via mcp-session-id response header.
+    // ---------------------------------------------------------------------------
+    // Parse JSON bodies only for /mcp routes (keeps SSE routes safe)
+    const jsonParser = express.json({ limit: "4mb" });
+    // POST /mcp — initialize a new session OR resume an existing one
+    app.post("/mcp", jsonParser, async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        // Resume existing session
+        if (sessionId) {
+            const session = httpSessions.get(sessionId);
+            if (!session) {
+                res.status(404).json({
+                    error: "session_not_found",
+                    message: "Unknown or expired MCP session. Re-initialize to start a new one.",
+                });
+                return;
+            }
+            await runWithClient(session.client, () => session.transport.handleRequest(req, res, req.body));
+            return;
+        }
+        // New session — must be an initialize request
+        if (!isInitializeRequest(req.body)) {
+            res.status(400).json({
+                error: "expected_initialize",
+                message: "First request to /mcp must be an MCP Initialize request.",
+            });
+            return;
+        }
+        // Auth — required on Initialize
+        const apiKey = extractApiKey(req);
+        if (!apiKey) {
+            res.status(401).json({
+                error: "api_key_required",
+                message: "An Open Ephemeris API key is required. Pass it via X-API-Key header or Authorization: Bearer. Get a free key at https://openephemeris.com/dashboard",
+            });
+            return;
+        }
+        const valid = await validateApiKey(apiKey);
+        if (!valid) {
+            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;
+        }
+        // Create per-session transport, server, and client
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: randomUUID,
+            onsessioninitialized: (id) => {
+                httpSessions.set(id, { server, transport, client });
+                console.error(`[HTTP] Session initialized: ${id}`);
+            },
+        });
+        const client = new BackendClient({ baseURL: BACKEND_URL, apiKey });
+        const server = createMcpServer();
+        transport.onclose = () => {
+            if (transport.sessionId) {
+                httpSessions.delete(transport.sessionId);
+                console.error(`[HTTP] Session closed: ${transport.sessionId}`);
+            }
+        };
+        await server.connect(transport);
+        await runWithClient(client, () => transport.handleRequest(req, res, req.body));
+    });
+    // GET /mcp — SSE stream leg of Streamable HTTP (server → client events)
+    app.get("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId) {
+            res.status(400).json({
+                error: "session_id_required",
+                message: "mcp-session-id header is required for GET /mcp.",
+            });
+            return;
+        }
+        const session = httpSessions.get(sessionId);
+        if (!session) {
+            res.status(404).json({
+                error: "session_not_found",
+                message: "Unknown or expired MCP session.",
+            });
+            return;
+        }
+        await session.transport.handleRequest(req, res);
+    });
+    // DELETE /mcp — client-initiated session teardown
+    app.delete("/mcp", (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (sessionId) {
+            const session = httpSessions.get(sessionId);
+            if (session) {
+                httpSessions.delete(sessionId);
+                session.server.close().catch(() => { });
+                console.error(`[HTTP] Session deleted: ${sessionId}`);
+            }
+        }
+        res.status(204).end();
     });
     // Serve the MCP icon (earth + star)
     // Compiled JS at dist/src/server-sse.js: ../../assets
@@ -188,13 +338,15 @@ async function main() {
             res.status(404).end();
         }
     });
+    // ---------------------------------------------------------------------------
+    // 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).
+    // ---------------------------------------------------------------------------
     // SSE endpoint — clients GET /sse to establish a stream
     app.get("/sse", async (req, res) => {
         // Extract API key from query param or header
-        const apiKey = req.query.apiKey ||
-            req.headers["x-api-key"] ||
-            req.headers["x-openephemeris-api-key"] ||
-            req.headers["authorization"]?.replace(/^Bearer\s+/i, "");
+        const apiKey = extractApiKey(req);
         if (!apiKey) {
             res.status(401).json({
                 error: "api_key_required",

package/dist/tools/specialized/acg.js

@@ -87,7 +87,7 @@ registerTool({
             return {
                 type: "acg_power_lines_summary",
                 total_lines: condensed.length,
-                note: "Coordinate geometry stripped for LLM context efficiency. Use the full API or Ela Map for geographic rendering.",
+                note: "Coordinate geometry stripped for LLM context efficiency. Use the full API or a map rendering client for geographic visualization.",
                 lines: condensed,
             };
         }

package/dist/tools/specialized/natal.js

@@ -2,7 +2,7 @@ import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
     "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
-/** Map human-readable house system names to Swiss Ephemeris single-letter codes */
+/** Map human-readable house system names to standard single-letter codes */
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R", porphyry: "O",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",
@@ -52,7 +52,7 @@
     "llm",
     "claude",
     "ai",
-    "swiss ephemeris"
+    "ephemeris"
   ],
   "author": "Open Ephemeris",
   "homepage": "https://openephemeris.com",