@openephemeris/mcp-server 3.2.0 → 3.2.3

package/dist/scripts/test-client.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/test-client.js

@@ -0,0 +1,69 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+async function main() {
+    console.log("🚀 Starting MCP Integration Test...");
+    // Path to the primary entrypoint
+    const serverPath = path.resolve(__dirname, "../src/index.ts");
+    // Spin up the stdio transport simulating a client like Claude/Cursor
+    const transport = new StdioClientTransport({
+        command: "npx",
+        args: ["tsx", serverPath],
+        env: {
+            ...process.env,
+            // Pass the profile explicitly for predictable responses
+            OPENEPHEMERIS_PROFILE: "dev",
+        },
+    });
+    const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+    console.log("🔌 Connecting to local MCP server via stdio...");
+    await client.connect(transport);
+    console.log("✅ Handshake complete. Protocol negotiated successfully.");
+    // Test 1: List Tools
+    console.log("\n📡 Polling server tools...");
+    const toolsResponse = await client.listTools();
+    console.log(`✅ Discovered ${toolsResponse.tools.length} tools.`);
+    // Verify core tools exist
+    const toolNames = toolsResponse.tools.map((t) => t.name);
+    const coreTools = ["auth.login", "dev.call", "ephemeris.moon_phase", "ephemeris.natal_chart"];
+    for (const name of coreTools) {
+        if (!toolNames.includes(name)) {
+            throw new Error(`❌ Missing expected tool: ${name}`);
+        }
+    }
+    // Test 2: Call an open endpoint that doesn't strictly require API Key for simple responses, 
+    // or handle the graceful 401 prompt gracefully if it does.
+    // Tools returning standard 401s with markdown prompts are still valid successful MCP JSON-RPC calls.
+    console.log("\n⚙️ Testing 'ephemeris.moon_phase' tool call...");
+    try {
+        const result = await client.callTool({
+            name: "ephemeris.moon_phase",
+            arguments: {}, // Defaults to current time
+        });
+        // An MCP tool response is usually { content: [ { type: 'text', text: '...' } ], isError: boolean }
+        const res = result;
+        if (res.isError) {
+            console.log("⚠️ Tool execution returned an expected application error (e.g. 401 Unauthorized expected without valid credentials):\n");
+            console.log(res.content);
+        }
+        else {
+            console.log("✅ Tool executed successfully! Response preview:");
+            const content = res.content[0];
+            console.log(content.text ? content.text.slice(0, 300) + "..." : res.content);
+        }
+    }
+    catch (err) {
+        console.error("❌ Exception during tool execution:", err);
+        process.exit(1);
+    }
+    console.log("\n🎉 Integration Test Passed. Client and Server are communicating perfectly.");
+    // Cleanup gracefully
+    await transport.close();
+    process.exit(0);
+}
+main().catch((err) => {
+    console.error("Fatal Error:", err);
+    process.exit(1);
+});

package/dist/scripts/test-sse-client.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/test-sse-client.js

@@ -0,0 +1,221 @@
+/**
+ * test-sse-client.ts — Integration tests for the Remote SSE MCP server.
+ *
+ * Usage:
+ *   Internal (local):
+ *     Start the SSE server first:  npm run dev:sse
+ *     Then run:                    npx tsx scripts/test-sse-client.ts
+ *
+ *   External (production):
+ *     OPENEPHEMERIS_SSE_URL=https://mcp.openephemeris.com \
+ *     OPENEPHEMERIS_API_KEY=opene-xxx \
+ *     npx tsx scripts/test-sse-client.ts
+ *
+ * Tests:
+ *   1. Health endpoint responds correctly
+ *   2. SSE connection without API key is rejected (401)
+ *   3. SSE connection with invalid API key is rejected (403)
+ *   4. SSE connection + MCP handshake succeeds with valid key
+ *   5. Tool discovery returns expected core tools
+ *   6. Tool call (moon phase) executes end-to-end
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import axios from "axios";
+const SSE_BASE = process.env.OPENEPHEMERIS_SSE_URL?.replace(/\/+$/, "") ||
+    "http://localhost:3001";
+const API_KEY = process.env.OPENEPHEMERIS_API_KEY || "";
+const passed = [];
+const failed = [];
+function ok(name) {
+    passed.push(name);
+    console.log(`  ✅ ${name}`);
+}
+function fail(name, err) {
+    failed.push(name);
+    console.error(`  ❌ ${name}: ${err instanceof Error ? err.message : String(err)}`);
+}
+// ---------------------------------------------------------------------------
+// Test 1: Health endpoint
+// ---------------------------------------------------------------------------
+async function testHealth() {
+    const name = "Health endpoint responds";
+    try {
+        const res = await axios.get(`${SSE_BASE}/health`, { timeout: 5_000 });
+        if (res.data.ok !== true)
+            throw new Error(`Expected ok:true, got ${JSON.stringify(res.data)}`);
+        if (!res.data.version)
+            throw new Error("Missing version in health response");
+        if (res.data.transport !== "sse")
+            throw new Error(`Expected transport:sse, got ${res.data.transport}`);
+        ok(name);
+    }
+    catch (err) {
+        fail(name, err);
+    }
+}
+// ---------------------------------------------------------------------------
+// Test 2: No API key → 401
+// ---------------------------------------------------------------------------
+async function testNoApiKey() {
+    const name = "SSE without API key returns 401";
+    try {
+        const res = await axios.get(`${SSE_BASE}/sse`, {
+            timeout: 5_000,
+            validateStatus: () => true,
+        });
+        if (res.status !== 401)
+            throw new Error(`Expected 401, got ${res.status}`);
+        if (res.data.error !== "api_key_required")
+            throw new Error(`Unexpected error code: ${res.data.error}`);
+        ok(name);
+    }
+    catch (err) {
+        fail(name, err);
+    }
+}
+// ---------------------------------------------------------------------------
+// Test 3: Invalid API key → 403 (or accepted if backend can't validate)
+// ---------------------------------------------------------------------------
+async function testInvalidApiKey() {
+    const name = "SSE with invalid API key is handled";
+    try {
+        const controller = new AbortController();
+        // Give the server 3s to respond with 403 or start SSE
+        const timeout = setTimeout(() => controller.abort(), 3_000);
+        const res = await axios.get(`${SSE_BASE}/sse?apiKey=opene-clearly-invalid-key-000`, {
+            validateStatus: () => true,
+            signal: controller.signal,
+            // Disable response buffering so the SSE stream doesn't hang
+            responseType: "stream",
+        });
+        clearTimeout(timeout);
+        if (res.status === 403) {
+            // Backend validated and rejected the key — ideal
+            ok(name + " (403 rejected)");
+        }
+        else if (res.status === 200) {
+            // Backend couldn't distinguish keys or endpoint doesn't require auth —
+            // SSE stream started. This is acceptable, the tool calls will fail later.
+            console.log(`  ⚠️  ${name}: Key accepted (backend may not validate at this layer)`);
+            passed.push(name);
+        }
+        else {
+            ok(name + ` (${res.status})`);
+        }
+        // Clean up the stream
+        try {
+            res.data?.destroy?.();
+        }
+        catch { /* ignore */ }
+    }
+    catch (err) {
+        if (err.code === "ERR_CANCELED" || err.name === "CanceledError") {
+            // The SSE stream started (200) and we aborted — that's valid
+            console.log(`  ⚠️  ${name}: SSE stream started (key was accepted), aborted cleanly`);
+            passed.push(name);
+        }
+        else {
+            fail(name, err);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Test 4-6: Full SSE client connection + tool discovery + tool call
+// ---------------------------------------------------------------------------
+async function testFullSseFlow() {
+    if (!API_KEY) {
+        const skip = "Full SSE flow (skipped — no OPENEPHEMERIS_API_KEY set)";
+        console.log(`  ⏭️  ${skip}`);
+        return;
+    }
+    // Test 4: Connect
+    const connectName = "SSE connection + MCP handshake";
+    let client = null;
+    let transport = null;
+    try {
+        const sseUrl = new URL(`${SSE_BASE}/sse?apiKey=${API_KEY}`);
+        transport = new SSEClientTransport(sseUrl);
+        client = new Client({ name: "sse-test-client", version: "1.0.0" }, { capabilities: {} });
+        await client.connect(transport);
+        ok(connectName);
+    }
+    catch (err) {
+        fail(connectName, err);
+        return; // Can't continue without a connection
+    }
+    // Test 5: Tool discovery
+    const discoveryName = "Tool discovery returns core tools";
+    try {
+        const tools = await client.listTools();
+        const names = tools.tools.map((t) => t.name);
+        const required = ["auth_login", "dev_call", "ephemeris_moon_phase", "ephemeris_natal_chart"];
+        const missing = required.filter((r) => !names.includes(r));
+        if (missing.length > 0)
+            throw new Error(`Missing tools: ${missing.join(", ")}`);
+        console.log(`    Found ${tools.tools.length} tools`);
+        ok(discoveryName);
+    }
+    catch (err) {
+        fail(discoveryName, err);
+    }
+    // Test 6: Tool call
+    const callName = "Tool call (moon_phase) returns data";
+    try {
+        const result = await client.callTool({
+            name: "ephemeris_moon_phase",
+            arguments: {},
+        });
+        const res = result;
+        if (res.isError) {
+            // A 401 error is acceptable if the server's own key isn't set
+            const text = res.content?.[0]?.text || "";
+            if (text.includes("401") || text.includes("auth")) {
+                console.log(`    ⚠️ Tool returned auth error (server service key may not be configured)`);
+                ok(callName + " (auth expected)");
+            }
+            else {
+                throw new Error(`Tool returned error: ${text.slice(0, 200)}`);
+            }
+        }
+        else {
+            const text = res.content?.[0]?.text || "";
+            console.log(`    Response preview: ${text.slice(0, 150)}...`);
+            ok(callName);
+        }
+    }
+    catch (err) {
+        fail(callName, err);
+    }
+    // Cleanup
+    try {
+        await transport?.close();
+    }
+    catch {
+        // ignore
+    }
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+async function main() {
+    console.log(`\n🧪 SSE MCP Server Integration Tests`);
+    console.log(`   Target: ${SSE_BASE}`);
+    console.log(`   API Key: ${API_KEY ? API_KEY.slice(0, 10) + "..." : "(none — full flow skipped)"}\n`);
+    await testHealth();
+    await testNoApiKey();
+    await testInvalidApiKey();
+    await testFullSseFlow();
+    console.log(`\n${"─".repeat(50)}`);
+    console.log(`  Passed: ${passed.length}  |  Failed: ${failed.length}`);
+    if (failed.length > 0) {
+        console.error(`\n❌ ${failed.length} test(s) failed.`);
+        process.exit(1);
+    }
+    console.log(`\n🎉 All tests passed!`);
+    process.exit(0);
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/dist/src/auth/device-auth.js

@@ -129,6 +129,9 @@ export class DeviceAuthFlow {
         console.error(`║  ${startResult.verification_uri_complete.slice(0, 48).padEnd(48)} ║`);
         console.error("╚══════════════════════════════════════════════════╝");
         console.error("");
+        console.error("By using the OpenEphemeris API, you agree to the Terms of Service");
+        console.error("at https://openephemeris.com/terms");
+        console.error("");
         console.error("Waiting for authorization...");
         const result = await this.poll(startResult.device_code, (attempt) => {
             if (attempt % 6 === 0) {

package/dist/src/index.js

@@ -24,6 +24,12 @@ function resolveServerVersion() {
 const server = new Server({
     name: "openephemeris-mcp",
     version: resolveServerVersion(),
+    icons: [
+        {
+            src: "https://mcp.openephemeris.com/icon.png",
+            mimeType: "image/png",
+        }
+    ]
 }, {
     capabilities: {
         tools: {},

package/dist/src/server-sse.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/server-sse.js

@@ -0,0 +1,264 @@
+/**
+ * server-sse.ts — Remote SSE transport for the OpenEphemeris MCP server.
+ *
+ * This wraps the exact same tool registry used by the local stdio server
+ * but exposes it over HTTP + Server-Sent Events so that Claude Web,
+ * Claude Mobile (future), and any remote MCP client can connect via URL.
+ *
+ * Architecture:
+ *   - The SSE server validates the user's API key at connection time by
+ *     making a lightweight call to the Go backend.
+ *   - All subsequent tool calls use the server's OPENEPHEMERIS_SERVICE_KEY
+ *     (set as a Fly secret) via the singleton BackendClient's X-Service-Key header.
+ *   - This avoids the need to refactor all tool handlers for per-session auth.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+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 { initTools, toolRegistry } from "./tools/index.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveServerVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        // Try multiple levels up — compiled JS is at dist/src/, source is at src/
+        for (const rel of ["..", "../.."]) {
+            const pkgPath = path.resolve(here, rel, "package.json");
+            try {
+                const raw = fs.readFileSync(pkgPath, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (typeof parsed.version === "string" && parsed.version.trim()) {
+                    return parsed.version.trim();
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0-unknown";
+}
+const PORT = parseInt(process.env.PORT || "3001", 10);
+const BACKEND_URL = process.env.OPENEPHEMERIS_BACKEND_URL ||
+    process.env.ASTROMCP_BACKEND_URL ||
+    "https://api.openephemeris.com";
+const version = resolveServerVersion();
+/**
+ * Validate a user-supplied API key by hitting an auth-gated endpoint on
+ * the Go sidecar. Returns true if the key yields a 2xx, false on 401/403.
+ */
+async function validateApiKey(apiKey) {
+    try {
+        const resp = await axios.get(`${BACKEND_URL}/ephemeris/moon/phase`, {
+            headers: { "X-API-Key": apiKey },
+            timeout: 5_000,
+            validateStatus: () => true, // don't throw on any status
+        });
+        // 2xx = valid key, 401/403 = invalid key, anything else = let through
+        if (resp.status === 401 || resp.status === 403)
+            return false;
+        return true;
+    }
+    catch {
+        // Network error — let them through; tool calls will fail if key is bad.
+        console.warn("Could not validate API key against backend, allowing connection.");
+        return true;
+    }
+}
+// ---------------------------------------------------------------------------
+// MCP Server factory — one per SSE session
+// ---------------------------------------------------------------------------
+function createMcpServer() {
+    const server = new Server({
+        name: "openephemeris-mcp",
+        version,
+        icons: [
+            {
+                src: "https://mcp.openephemeris.com/icon.png",
+                mimeType: "image/png",
+            }
+        ]
+    }, { capabilities: { tools: {} } });
+    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,
+            },
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const toolName = request.params.name;
+        const tool = toolRegistry[toolName];
+        if (!tool) {
+            throw new Error(`Unknown tool: ${toolName}`);
+        }
+        try {
+            const result = await tool.handler(request.params.arguments ?? {});
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: false, error: "TOOL_EXECUTION_ERROR", message: errorMessage }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}
+// ---------------------------------------------------------------------------
+// Express + SSE wiring
+// ---------------------------------------------------------------------------
+async function main() {
+    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.
+    // 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-Meridian-API-Key");
+        if (_req.method === "OPTIONS") {
+            res.status(204).end();
+            return;
+        }
+        next();
+    });
+    // Track active transports by session ID
+    const transports = new Map();
+    // Health check
+    app.get("/health", (_req, res) => {
+        res.json({ ok: true, version, transport: "sse", sessions: transports.size });
+    });
+    // Serve the MCP icon (earth + star)
+    // Compiled JS at dist/src/server-sse.js: ../../assets
+    // Source TS at src/server-sse.ts: ../assets
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const assetsDir = fs.existsSync(path.resolve(here, "..", "..", "assets"))
+        ? path.resolve(here, "..", "..", "assets")
+        : path.resolve(here, "..", "assets");
+    app.get("/icon.png", (_req, res) => {
+        const iconPath = path.join(assetsDir, "icon.png");
+        if (fs.existsSync(iconPath)) {
+            res.setHeader("Cache-Control", "public, max-age=86400");
+            res.sendFile(iconPath);
+        }
+        else {
+            res.status(404).end();
+        }
+    });
+    app.get("/favicon.ico", (_req, res) => {
+        const iconPath = path.join(assetsDir, "icon.png");
+        if (fs.existsSync(iconPath)) {
+            res.setHeader("Content-Type", "image/png");
+            res.setHeader("Cache-Control", "public, max-age=86400");
+            res.sendFile(iconPath);
+        }
+        else {
+            res.status(404).end();
+        }
+    });
+    // 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-meridian-api-key"] ||
+            req.headers["authorization"]?.replace(/^Bearer\s+/i, "");
+        if (!apiKey) {
+            res.status(401).json({
+                error: "api_key_required",
+                message: "An OpenEphemeris API key is required. Generate one at https://openephemeris.com/dashboard?tab=apikeys",
+            });
+            return;
+        }
+        // Validate the user's key against the Go backend
+        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;
+        }
+        const transport = new SSEServerTransport("/message", res);
+        const sessionId = transport.sessionId;
+        transports.set(sessionId, transport);
+        const server = createMcpServer();
+        // Guard: prevent double-close from crashing the process
+        let closed = false;
+        const cleanup = () => {
+            if (closed)
+                return;
+            closed = true;
+            transports.delete(sessionId);
+            try {
+                server.close().catch(() => { });
+            }
+            catch { /* ignore */ }
+        };
+        transport.onclose = cleanup;
+        // Handle abrupt client disconnects (browser tab closed, etc.)
+        res.on("close", cleanup);
+        try {
+            // server.connect() calls transport.start() internally in SDK v1.27+
+            await server.connect(transport);
+        }
+        catch (err) {
+            console.error(`SSE session ${sessionId} failed to start:`, err);
+            cleanup();
+        }
+    });
+    // Message endpoint — clients POST /message?sessionId=xxx
+    app.post("/message", async (req, res) => {
+        const sessionId = req.query.sessionId;
+        const transport = transports.get(sessionId);
+        if (!transport) {
+            res.status(400).json({
+                error: "invalid_session",
+                message: "Unknown or expired session. Re-connect to /sse first.",
+            });
+            return;
+        }
+        await transport.handlePostMessage(req, res);
+    });
+    app.listen(PORT, "0.0.0.0", () => {
+        console.log(`OpenEphemeris MCP SSE server v${version} listening on port ${PORT}`);
+    });
+}
+// Prevent SDK recursive close bugs from crashing the process
+process.on("uncaughtException", (err) => {
+    if (err instanceof RangeError && err.message.includes("call stack")) {
+        console.error("Caught stack overflow (likely SDK close recursion), ignoring.");
+        return;
+    }
+    console.error("Uncaught exception:", err);
+    process.exit(1);
+});
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/src/tools/auth.js

@@ -6,7 +6,7 @@ const credentialManager = new CredentialManager();
 // auth.login — Start the device authorization flow
 // ────────────────────────────────────────────────────────
 registerTool({
-    name: "auth.login",
+    name: "auth_login",
     description: "Start the device authorization flow to connect this MCP server to your OpenEphemeris account. " +
         "Returns a verification URL and code for the user to enter in their browser. " +
         "The MCP server will then automatically receive credentials and all API calls will be " +
@@ -31,7 +31,7 @@ registerTool({
                 email: status.email,
                 user_id: status.userId,
                 expires_at: status.expiresAt,
-                message: `Already authenticated as ${status.email}. Use auth.logout to disconnect.`,
+                message: `Already authenticated as ${status.email}. Use auth_logout to disconnect.`,
             };
         }
         // Check if env var credentials are set
@@ -86,7 +86,7 @@ registerTool({
 // auth.status — Check current authentication state
 // ────────────────────────────────────────────────────────
 registerTool({
-    name: "auth.status",
+    name: "auth_status",
     description: "Check the current authentication status of this MCP server. " +
         "Shows whether the server is authenticated, which account it's linked to, " +
         "the authentication method (API key, JWT, device auth), and token expiry.",
@@ -155,14 +155,14 @@ registerTool({
                 expired_at: creds.expires_at,
                 message: "Device auth credentials exist but are expired. " +
                     "The server will attempt to refresh automatically on the next API call, " +
-                    "or you can run auth.login to re-authenticate.",
+                    "or you can run auth_login to re-authenticate.",
             };
         }
         return {
             authenticated: false,
             method: "none",
             message: "Not authenticated. Set OPENEPHEMERIS_API_KEY in your MCP server config, " +
-                "or run auth.login to connect your account interactively.",
+                "or run auth_login to connect your account interactively.",
         };
     },
 });
@@ -170,7 +170,7 @@ registerTool({
 // auth.logout — Clear cached credentials
 // ────────────────────────────────────────────────────────
 registerTool({
-    name: "auth.logout",
+    name: "auth_logout",
     description: "Disconnect this MCP server from your OpenEphemeris account by clearing " +
         "cached credentials. Does NOT revoke the API key if one is set via environment " +
         "variable — only clears device-auth cached credentials.",