@openephemeris/mcp-server 3.1.0 → 3.2.2

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/credentials.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Stored credential shape persisted to ~/.openephemeris/credentials.json.
+ */
+export interface StoredCredentials {
+    access_token: string;
+    refresh_token: string;
+    /** ISO 8601 timestamp when the access_token expires. */
+    expires_at: string;
+    /** Supabase user ID. */
+    user_id?: string;
+    /** User email for display purposes. */
+    user_email?: string;
+    /** Timestamp when these credentials were created/refreshed. */
+    updated_at: string;
+}
+/**
+ * CredentialManager handles reading, writing, refreshing, and clearing
+ * persisted OAuth credentials for the MCP server.
+ */
+export declare class CredentialManager {
+    private cachedCredentials;
+    private backendBaseURL;
+    constructor(backendBaseURL?: string);
+    /**
+     * Load credentials from disk. Returns null if file doesn't exist or is invalid.
+     */
+    load(): StoredCredentials | null;
+    /**
+     * Save credentials to disk.
+     */
+    save(credentials: StoredCredentials): void;
+    /**
+     * Check whether the current access_token is expired (or nearly expired).
+     */
+    isExpired(credentials?: StoredCredentials | null): boolean;
+    /**
+     * Attempt to refresh the access token using the stored refresh_token.
+     * Uses the Supabase GoTrue refresh endpoint directly.
+     */
+    refresh(): Promise<StoredCredentials | null>;
+    /**
+     * Fallback refresh via the web app's token refresh endpoint.
+     */
+    private refreshViaWebApp;
+    /**
+     * Get a valid access token, refreshing if necessary.
+     * Returns null if no credentials exist or refresh fails.
+     */
+    getValidToken(): Promise<string | null>;
+    /**
+     * Delete stored credentials.
+     */
+    clear(): void;
+    /**
+     * Get display info about the current auth state.
+     */
+    getStatus(): {
+        authenticated: boolean;
+        email?: string;
+        userId?: string;
+        expiresAt?: string;
+    };
+    /** Path to the credentials file (for diagnostics). */
+    static get credentialsPath(): string;
+}

package/dist/src/auth/credentials.js

@@ -0,0 +1,200 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const CREDENTIALS_DIR = path.join(os.homedir(), ".openephemeris");
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
+/** How many seconds before actual expiry to consider the token "expired". */
+const EXPIRY_BUFFER_SECONDS = 120;
+/**
+ * CredentialManager handles reading, writing, refreshing, and clearing
+ * persisted OAuth credentials for the MCP server.
+ */
+export class CredentialManager {
+    cachedCredentials = null;
+    backendBaseURL;
+    constructor(backendBaseURL) {
+        this.backendBaseURL =
+            backendBaseURL ||
+                process.env.NEXT_PUBLIC_APP_URL ||
+                process.env.OPENEPHEMERIS_FRONTEND_URL ||
+                "https://openephemeris.com";
+    }
+    /**
+     * Load credentials from disk. Returns null if file doesn't exist or is invalid.
+     */
+    load() {
+        if (this.cachedCredentials)
+            return this.cachedCredentials;
+        try {
+            if (!fs.existsSync(CREDENTIALS_FILE))
+                return null;
+            const raw = fs.readFileSync(CREDENTIALS_FILE, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (!parsed.access_token || !parsed.refresh_token || !parsed.expires_at) {
+                return null;
+            }
+            this.cachedCredentials = parsed;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Save credentials to disk.
+     */
+    save(credentials) {
+        try {
+            if (!fs.existsSync(CREDENTIALS_DIR)) {
+                fs.mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+            }
+            const data = { ...credentials, updated_at: new Date().toISOString() };
+            fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify(data, null, 2), {
+                encoding: "utf-8",
+                mode: 0o600, // Owner read/write only
+            });
+            this.cachedCredentials = data;
+        }
+        catch (err) {
+            console.error("Failed to save credentials:", err);
+        }
+    }
+    /**
+     * Check whether the current access_token is expired (or nearly expired).
+     */
+    isExpired(credentials) {
+        const creds = credentials || this.load();
+        if (!creds?.expires_at)
+            return true;
+        const expiresAt = new Date(creds.expires_at).getTime();
+        const now = Date.now();
+        return now >= expiresAt - EXPIRY_BUFFER_SECONDS * 1000;
+    }
+    /**
+     * Attempt to refresh the access token using the stored refresh_token.
+     * Uses the Supabase GoTrue refresh endpoint directly.
+     */
+    async refresh() {
+        const creds = this.load();
+        if (!creds?.refresh_token)
+            return null;
+        const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL ||
+            process.env.SUPABASE_URL;
+        const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ||
+            process.env.SUPABASE_ANON_KEY;
+        if (!supabaseUrl || !supabaseAnonKey) {
+            // Can't refresh without Supabase config — fall back to the web app endpoint
+            return this.refreshViaWebApp(creds.refresh_token);
+        }
+        try {
+            const response = await fetch(`${supabaseUrl}/auth/v1/token?grant_type=refresh_token`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "apikey": supabaseAnonKey,
+                },
+                body: JSON.stringify({ refresh_token: creds.refresh_token }),
+            });
+            if (!response.ok)
+                return null;
+            const data = await response.json();
+            if (!data.access_token || !data.refresh_token)
+                return null;
+            const expiresAt = new Date(Date.now() + (data.expires_in || 3600) * 1000).toISOString();
+            const updated = {
+                access_token: data.access_token,
+                refresh_token: data.refresh_token,
+                expires_at: expiresAt,
+                user_id: data.user?.id || creds.user_id,
+                user_email: data.user?.email || creds.user_email,
+                updated_at: new Date().toISOString(),
+            };
+            this.save(updated);
+            return updated;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Fallback refresh via the web app's token refresh endpoint.
+     */
+    async refreshViaWebApp(refreshToken) {
+        try {
+            const response = await fetch(`${this.backendBaseURL}/api/device/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    grant_type: "refresh_token",
+                    refresh_token: refreshToken,
+                }),
+            });
+            if (!response.ok)
+                return null;
+            const data = await response.json();
+            if (!data.access_token)
+                return null;
+            const expiresAt = new Date(Date.now() + (data.expires_in || 3600) * 1000).toISOString();
+            const updated = {
+                access_token: data.access_token,
+                refresh_token: data.refresh_token || refreshToken,
+                expires_at: expiresAt,
+                user_id: data.user?.id,
+                user_email: data.user?.email,
+                updated_at: new Date().toISOString(),
+            };
+            this.save(updated);
+            return updated;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get a valid access token, refreshing if necessary.
+     * Returns null if no credentials exist or refresh fails.
+     */
+    async getValidToken() {
+        const creds = this.load();
+        if (!creds)
+            return null;
+        if (!this.isExpired(creds)) {
+            return creds.access_token;
+        }
+        // Try refresh
+        const refreshed = await this.refresh();
+        return refreshed?.access_token || null;
+    }
+    /**
+     * Delete stored credentials.
+     */
+    clear() {
+        this.cachedCredentials = null;
+        try {
+            if (fs.existsSync(CREDENTIALS_FILE)) {
+                fs.unlinkSync(CREDENTIALS_FILE);
+            }
+        }
+        catch {
+            // Ignore
+        }
+    }
+    /**
+     * Get display info about the current auth state.
+     */
+    getStatus() {
+        const creds = this.load();
+        if (!creds)
+            return { authenticated: false };
+        return {
+            authenticated: !this.isExpired(creds),
+            email: creds.user_email,
+            userId: creds.user_id,
+            expiresAt: creds.expires_at,
+        };
+    }
+    /** Path to the credentials file (for diagnostics). */
+    static get credentialsPath() {
+        return CREDENTIALS_FILE;
+    }
+}

package/dist/src/auth/device-auth.d.ts

@@ -0,0 +1,56 @@
+import { CredentialManager } from "./credentials.js";
+export interface DeviceAuthStartResult {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceAuthTokenResult {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_in: number;
+    user?: {
+        id: string;
+        email: string;
+    };
+}
+/**
+ * Custom error thrown when the MCP server needs authentication
+ * but no credentials are available and device auth hasn't been started.
+ */
+export declare class NeedsAuthError extends Error {
+    readonly verificationUri: string;
+    readonly userCode: string;
+    constructor(verificationUri: string, userCode: string);
+}
+/**
+ * DeviceAuthFlow implements RFC 8628 Device Authorization Grant
+ * for connecting the MCP server to a user's OpenEphemeris account.
+ */
+export declare class DeviceAuthFlow {
+    private baseURL;
+    private credentialManager;
+    constructor(baseURL?: string, credentialManager?: CredentialManager);
+    /**
+     * Start the device authorization flow.
+     * Calls POST /api/device/authorize to get a device code + user code.
+     */
+    start(clientName?: string): Promise<DeviceAuthStartResult>;
+    /**
+     * Poll the token endpoint until the user authorizes the device code
+     * or the code expires.
+     *
+     * @param deviceCode - The device_code from start()
+     * @param onPending - Optional callback fired on each "authorization_pending" poll
+     * @returns The token result with access_token and refresh_token
+     */
+    poll(deviceCode: string, onPending?: (attempt: number) => void): Promise<DeviceAuthTokenResult>;
+    /**
+     * Start the full device auth flow: request code, print instructions, poll for token.
+     * This is the main entry point for interactive use.
+     */
+    authenticate(): Promise<DeviceAuthTokenResult>;
+}