@openephemeris/mcp-server 3.9.0 → 3.9.1

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 -->

package/dist/server-sse.js

@@ -21,7 +21,7 @@ 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 { CallToolRequestSchema, ListToolsRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.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";
 // ---------------------------------------------------------------------------
@@ -93,31 +93,125 @@ function extractApiKey(req) {
         undefined);
 }
 // ---------------------------------------------------------------------------
-// MCP Server factory — one per SSE session
+// 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
+// ---------------------------------------------------------------------------
+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];
@@ -158,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;
@@ -190,23 +284,29 @@ async function main() {
             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. 48+ typed tools covering natal charts, transit forecasting, Human Design, eclipses, astrocartography, BaZi, and more — powered by DE440/DE441 for sub-arcsecond accuracy.",
+                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",
+                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: [],
+            prompts: [WELCOME_PROMPT],
         });
     });
     // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.9.0",
+  "version": "3.9.1",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",