@openephemeris/mcp-server 3.8.0 → 3.9.1

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

@@ -1,11 +1,115 @@
 # OpenEphemeris MCP Server
 
+[![smithery badge](https://smithery.ai/badge/open-ephemeris/openephemeris)](https://smithery.ai/servers/open-ephemeris/openephemeris)
+[![npm version](https://img.shields.io/npm/v/@openephemeris/mcp-server)](https://www.npmjs.com/package/@openephemeris/mcp-server)
 [![System Status](https://img.shields.io/badge/Status-Operational-brightgreen)](https://status.openephemeris.com/)
 
-Model Context Protocol server for OpenEphemeris. This package exposes typed astrology tools and an allowlist-gated generic proxy (`dev.call`) for MCP-compatible clients.
+Model Context Protocol server for OpenEphemeris — 50+ typed astrology tools powered by NASA JPL DE440/DE441 ephemerides. Zero hallucination on planetary positions, dates, and degrees.
+
+**Hosted endpoint:** `https://mcp.openephemeris.com/mcp` (Streamable HTTP, MCP 2025-11-25 spec)
 
 ## Quick Start
 
+### Install via Smithery (recommended)
+
+The fastest way to connect any MCP-compatible client:
+
+```bash
+npx -y @smithery/cli install @open-ephemeris/openephemeris --client claude
+```
+
+Or browse the listing and copy connection snippets: **[smithery.ai/servers/open-ephemeris/openephemeris](https://smithery.ai/servers/open-ephemeris/openephemeris)**
+
+---
+
+### Connect via AI SDK (Vercel AI SDK)
+
+```typescript
+import Smithery from "@smithery/api"
+import { createMCPClient } from "@ai-sdk/mcp"
+import { generateText } from "ai"
+import { anthropic } from "@ai-sdk/anthropic"
+import { createConnection } from "@smithery/api/mcp"
+
+const smithery = new Smithery()
+
+const conn = await smithery.connections.create("{your-namespace}", {
+  mcpUrl: "https://server.smithery.ai/open-ephemeris/openephemeris",
+  headers: {
+    apiKey: "your-openephemeris-api-key", // get one free at openephemeris.com/dashboard
+  },
+})
+
+const { transport } = await createConnection({
+  client: smithery,
+  namespace: "{your-namespace}",
+  connectionId: conn.connectionId,
+})
+
+const mcpClient = await createMCPClient({ transport })
+const tools = await mcpClient.tools()
+
+const { text } = await generateText({
+  model: anthropic("claude-sonnet-4-20250514"),
+  tools,
+  prompt: "Calculate a natal chart for someone born April 15, 1990 at 2:30 PM in Chicago.",
+})
+
+await mcpClient.close()
+```
+
+### Connect via MCP SDK (TypeScript)
+
+```typescript
+import Smithery from "@smithery/api"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { createConnection } from "@smithery/api/mcp"
+
+const smithery = new Smithery()
+
+const conn = await smithery.connections.create("{your-namespace}", {
+  mcpUrl: "https://server.smithery.ai/open-ephemeris/openephemeris",
+  headers: {
+    apiKey: "your-openephemeris-api-key",
+  },
+})
+
+const { transport } = await createConnection({
+  client: smithery,
+  namespace: "{your-namespace}",
+  connectionId: conn.connectionId,
+})
+
+const mcpClient = new Client(
+  { name: "my-app", version: "1.0.0" },
+  { capabilities: {} }
+)
+await mcpClient.connect(transport)
+
+const { tools } = await mcpClient.listTools()
+const result = await mcpClient.callTool({
+  name: "ephemeris_natal_chart",
+  arguments: { datetime: "1990-04-15T14:30:00", latitude: 41.8781, longitude: -87.6298, format: "llm" },
+})
+```
+
+### Connect directly (Streamable HTTP, no Smithery)
+
+```typescript
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+
+const transport = new StreamableHTTPClientTransport(
+  new URL("https://mcp.openephemeris.com/mcp"),
+  { requestInit: { headers: { "X-API-Key": "your-openephemeris-api-key" } } }
+)
+
+const client = new Client({ name: "my-app", version: "1.0.0" }, { capabilities: {} })
+await client.connect(transport)
+```
+
+---
+
 ### One-click install (Cursor)
 
 <!-- GENERATED:CURSOR_INSTALL:BEGIN -->
@@ -54,10 +158,12 @@ Cursor deeplink payload:
 
 | Client | Install mode | Config location |
 |---|---|---|
+| Smithery | One-click | [smithery.ai](https://smithery.ai/servers/open-ephemeris/openephemeris) |
 | Cursor | One-click deeplink or manual | `~/.cursor/mcp.json` |
 | Claude Desktop (macOS) | Manual | `~/Library/Application Support/Claude/claude_desktop_config.json` |
 | Claude Desktop (Windows) | Manual | `%APPDATA%\Claude\claude_desktop_config.json` |
 | Windsurf | Manual | `~/.codeium/windsurf/mcp_config.json` (or legacy `~/.codeium/mcp_config.json`) |
+| Claude Web / ChatGPT / remote clients | Hosted URL | `https://mcp.openephemeris.com/mcp` |
 
 ### Client install walkthroughs
 
@@ -73,9 +179,13 @@ Cursor deeplink payload:
    - Add the `mcpServers.openephemeris` block from "Manual install".
    - Restart Windsurf.
 
-### Remote-only clients (ChatGPT Developer Mode, Antigravity, etc.)
+### Remote-only clients (Claude Web, ChatGPT, etc.)
+
+The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable HTTP support (MCP 2025-11-25 spec). Remote-only clients can connect directly — no bridge/proxy required:
 
-This package runs as a local stdio MCP server. Remote-only clients require a hosted MCP endpoint (Streamable HTTP/SSE), so you must run this server behind an MCP bridge/proxy and expose it over HTTPS before adding it in those clients.
+- **Claude Web**: Add `https://mcp.openephemeris.com/mcp` as a remote MCP server with `X-API-Key: your-key` header
+- **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
 
 ### Auth and upgrade behavior in MCP clients
 
@@ -209,14 +319,32 @@ When you update the MCP server logic (handlers, bug fixes, hardening), you shoul
 ## Architecture
 
 ```text
-MCP Client (Cursor / Claude / Windsurf / other stdio clients)
-    | stdio JSON-RPC
-    v
-openephemeris-mcp (Node.js)
-    | typed tools + dev.call/dev.list_allowed
-    | auth chain: Service Key > API Key > JWT
-    v
-OpenEphemeris API
+┌─────────────────────────────────────────────────────────┐
+│                    MCP Clients                          │
+│  Smithery Gateway · Claude Web · ChatGPT · Remote apps  │
+└──────────────────┬──────────────────────────────────────┘
+                   │ Streamable HTTP (MCP 2025-11-25)
+                   │ https://mcp.openephemeris.com/mcp
+                   │
+┌─────────────────────────────────────────────────────────┐
+│          Cursor · Claude Desktop · Windsurf             │
+└──────────────────┬──────────────────────────────────────┘
+                   │ stdio JSON-RPC
+                   │ npx @openephemeris/mcp-server
+                   │
+              ┌────▼────────────────────┐
+              │  openephemeris-mcp      │
+              │  Node.js MCP Server     │
+              │  52 typed tools         │
+              │  auth: Key > JWT        │
+              └────────────┬────────────┘
+                           │ HTTPS
+                           ▼
+              ┌────────────────────────┐
+              │  OpenEphemeris API     │
+              │  api.openephemeris.com │
+              │  JPL DE440/DE441       │
+              └────────────────────────┘
 ```
 
 <!-- GENERATED:RUNTIME_SNAPSHOT:BEGIN -->
@@ -244,7 +372,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, ListPromptsRequestSchema, GetPromptRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse } from "./tools/index.js";
 import { BackendClient, runWithClient } from "./backend/client.js";
 // ---------------------------------------------------------------------------
@@ -76,32 +78,140 @@ 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);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Convert snake_case tool name → Human Title (e.g. "ephemeris_natal_chart" → "Natal Chart") */
+function humanTitle(name) {
+    // Strip common prefixes that don't add value in a title context
+    const stripped = name
+        .replace(/^ephemeris_/, "")
+        .replace(/^acg_/, "ACG ")
+        .replace(/^hd_/, "Human Design ")
+        .replace(/^human_design_/, "Human Design ")
+        .replace(/^electional_/, "Electional ")
+        .replace(/^venus_/, "Venus ")
+        .replace(/^vedic_/, "Vedic ")
+        .replace(/^bazi_/, "BaZi ")
+        .replace(/^chinese_/, "Chinese ");
+    return stripped
+        .split("_")
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/** Build MCP-spec tool annotations for a tool */
+function buildAnnotations(tool) {
+    return {
+        title: humanTitle(tool.name),
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+        ...(tool.annotations ?? {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Welcome prompt — orientation guide for LLMs connecting via MCP
 // ---------------------------------------------------------------------------
-// MCP Server factory — one per SSE session
+const WELCOME_PROMPT = {
+    name: "welcome_to_open_ephemeris",
+    description: "An orientation guide that introduces the Open Ephemeris MCP server, " +
+        "its capabilities, and how to use its tools effectively. " +
+        "Invoke this prompt when a user first connects or asks 'what can you do?'",
+    arguments: [],
+};
+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/DE441 ephemerides.\n\n" +
+                "Just tell me what you'd like to explore!",
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// MCP Server factory — one per SSE/HTTP session
 // ---------------------------------------------------------------------------
 function createMcpServer() {
     const server = new Server({
         name: "openephemeris-mcp",
+        title: "Open Ephemeris",
         version,
+        websiteUrl: "https://openephemeris.com",
         icons: [
             {
                 src: "https://mcp.openephemeris.com/icon.png",
                 mimeType: "image/png",
             }
-        ]
-    }, { capabilities: { tools: {} } });
+        ],
+        // description is in the MCP spec (spec.types.d.ts Implementation interface)
+        // but the SDK's Zod schema doesn't include it yet — pass via spread
+        ...{
+            description: "NASA JPL-backed astronomical computation engine for AI agents. " +
+                "50+ typed tools covering natal charts, transit forecasting, Human Design " +
+                "bodygraphs, eclipses, astrocartography power lines, Venus Star Points, " +
+                "electional timing, synastry, composite charts, Vedic/Jyotish, Chinese BaZi, " +
+                "and more — powered by JPL DE440/DE441 ephemerides for sub-arcsecond accuracy.",
+        },
+    }, {
+        capabilities: { tools: {}, prompts: {} },
+        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/DE441 ephemerides for sub-arcsecond accuracy. " +
+            "See the 'welcome_to_open_ephemeris' prompt for a full capability overview.",
+    });
+    // --- Tool handlers ---
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: Object.values(toolRegistry).map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
-            annotations: tool.annotations ?? {
-                title: tool.name,
-                readOnlyHint: true,
-                destructiveHint: false,
-            },
+            annotations: buildAnnotations(tool),
         })),
     }));
+    // --- Prompt handlers ---
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+        prompts: [WELCOME_PROMPT],
+    }));
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        if (request.params.name !== WELCOME_PROMPT.name) {
+            throw new Error(`Unknown prompt: ${request.params.name}`);
+        }
+        return {
+            description: WELCOME_PROMPT.description,
+            messages: WELCOME_PROMPT_CONTENT,
+        };
+    });
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const toolName = request.params.name;
         const tool = toolRegistry[toolName];
@@ -132,9 +242,7 @@ function createMcpServer() {
     });
     return server;
 }
-// ---------------------------------------------------------------------------
-// Express + SSE wiring
-// ---------------------------------------------------------------------------
+const httpSessions = new Map();
 async function main() {
     await initTools();
     const app = express();
@@ -144,8 +252,8 @@ async function main() {
     // CORS — required for Claude Web cross-origin SSE connections
     app.use((_req, res, next) => {
         res.setHeader("Access-Control-Allow-Origin", "*");
-        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-API-Key, X-OpenEphemeris-API-Key");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-API-Key, X-OpenEphemeris-API-Key, mcp-session-id");
         if (_req.method === "OPTIONS") {
             res.status(204).end();
             return;
@@ -158,7 +266,149 @@ 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,
+            annotations: buildAnnotations(tool),
+        }));
+        res.json({
+            serverInfo: {
+                name: "Open Ephemeris",
+                version,
+                description: "NASA JPL-backed astronomical computation engine for AI agents. 50+ typed tools covering " +
+                    "natal charts, transit forecasting, Human Design bodygraphs, eclipses, astrocartography " +
+                    "power lines, Venus Star Points, electional timing, synastry, composite charts, Vedic/Jyotish, " +
+                    "Chinese BaZi, and more — powered by JPL DE440/DE441 ephemerides for sub-arcsecond " +
+                    "zero-hallucination accuracy. Free Explorer tier available.",
+                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 — no credit card required.",
+            },
+            tools,
+            resources: [],
+            prompts: [WELCOME_PROMPT],
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // 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 +438,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.1",
   "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",