@openephemeris/mcp-server 3.0.1 → 3.2.0

package/dist/test/backend-client.test.js

@@ -0,0 +1,286 @@
+import http from "node:http";
+import { describe, expect, it } from "vitest";
+import { BackendClient, BackendError } from "../src/backend/client.js";
+async function startJsonServer(handler) {
+    const server = http.createServer(handler);
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address();
+    return {
+        baseURL: `http://127.0.0.1:${port}`,
+        close: () => new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve()))),
+    };
+}
+describe("BackendClient", () => {
+    async function getErrorMessage(run) {
+        try {
+            await run();
+            return "";
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+    }
+    it("injects service key with highest priority", async () => {
+        const srv = await startJsonServer((req, res) => {
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ headers: req.headers }));
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+                serviceKey: "svc-key",
+                apiKey: "api-key",
+                jwt: "jwt-token",
+            });
+            const out = await client.get("/headers");
+            expect(out.headers["x-service-key"]).toBe("svc-key");
+            expect(out.headers["x-api-key"]).toBeUndefined();
+            expect(out.headers.authorization).toBeUndefined();
+        }
+        finally {
+            await srv.close();
+        }
+    });
+    it("respects explicit request auth headers over injected credentials", async () => {
+        const srv = await startJsonServer((req, res) => {
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ headers: req.headers }));
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+                serviceKey: "svc-key",
+            });
+            const out = await client.request("GET", "/headers", {
+                headers: {
+                    Authorization: "Bearer explicit-token",
+                },
+            });
+            expect(out.headers.authorization).toBe("Bearer explicit-token");
+            expect(out.headers["x-service-key"]).toBeUndefined();
+        }
+        finally {
+            await srv.close();
+        }
+    });
+    it("maps backend 404 into an MCP-friendly error", async () => {
+        const srv = await startJsonServer((_req, res) => {
+            res.statusCode = 404;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ message: "missing resource" }));
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+            });
+            await expect(client.get("/missing")).rejects.toThrow("Resource not found: missing resource");
+        }
+        finally {
+            await srv.close();
+        }
+    });
+    it("maps backend 401 into signup and API key guidance", async () => {
+        const srv = await startJsonServer((_req, res) => {
+            res.statusCode = 401;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+                detail: "Missing credentials. Provide X-API-Key or Authorization bearer token.",
+            }));
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+            });
+            const message = await getErrorMessage(() => client.get("/secure"));
+            expect(message).toContain("Authentication required:");
+            expect(message).toContain("auth.login");
+            expect(message).toContain("OPENEPHEMERIS_API_KEY");
+        }
+        finally {
+            await srv.close();
+        }
+    });
+    it("maps backend 402 into quota and upgrade guidance", async () => {
+        const srv = await startJsonServer((_req, res) => {
+            res.statusCode = 402;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+                detail: "Monthly quota exceeded for this account.",
+            }));
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+            });
+            const message = await getErrorMessage(() => client.get("/quota"));
+            expect(message).toContain("Usage quota exceeded:");
+            expect(message).toContain("https://openephemeris.com/pay");
+            expect(message).toContain("https://openephemeris.com/dashboard?tab=account");
+        }
+        finally {
+            await srv.close();
+        }
+    });
+    it("maps backend 403 into tier-upgrade guidance", async () => {
+        const srv = await startJsonServer((_req, res) => {
+            res.statusCode = 403;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+                detail: "This endpoint requires at least the Developer tier.",
+            }));
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+            });
+            const message = await getErrorMessage(() => client.get("/tier-gated"));
+            expect(message).toContain("Access blocked by plan or policy:");
+            expect(message).toContain("https://openephemeris.com/pay");
+            expect(message).toContain("https://openephemeris.com/dashboard?tab=account");
+        }
+        finally {
+            await srv.close();
+        }
+    });
+    it("maps backend 429 into dashboard usage guidance", async () => {
+        const srv = await startJsonServer((_req, res) => {
+            res.statusCode = 429;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+                detail: "Rate limit exceeded for authenticated user tier.",
+            }));
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+            });
+            const message = await getErrorMessage(() => client.get("/rate-limit"));
+            expect(message).toContain("Rate limit exceeded.");
+            expect(message).toContain("https://openephemeris.com/dashboard?tab=account");
+        }
+        finally {
+            await srv.close();
+        }
+    }, 15_000); // Extended timeout: 3 retries with backoff + jitter
+    it("retries on 503 and succeeds on second attempt", async () => {
+        let attempt = 0;
+        const srv = await startJsonServer((_req, res) => {
+            attempt++;
+            if (attempt === 1) {
+                res.statusCode = 503;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ detail: "Service unavailable" }));
+            }
+            else {
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ ok: true }));
+            }
+        });
+        try {
+            const client = new BackendClient({ baseURL: srv.baseURL });
+            const result = await client.get("/transient");
+            expect(result.ok).toBe(true);
+            expect(attempt).toBe(2);
+        }
+        finally {
+            await srv.close();
+        }
+    }, 10_000);
+    it("BackendError exposes status, code, and retryable", async () => {
+        const srv = await startJsonServer((_req, res) => {
+            res.statusCode = 403;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ detail: "Tier upgrade required" }));
+        });
+        try {
+            const client = new BackendClient({ baseURL: srv.baseURL });
+            try {
+                await client.get("/gated");
+                expect.unreachable("Should have thrown");
+            }
+            catch (err) {
+                expect(err).toBeInstanceOf(BackendError);
+                const be = err;
+                expect(be.status).toBe(403);
+                expect(be.code).toBe("tier_required");
+                expect(be.retryable).toBe(false);
+                expect(be.upgradeUrl).toContain("openephemeris.com");
+            }
+        }
+        finally {
+            await srv.close();
+        }
+    });
+    it("returns a base64 payload envelope for chart-wheel binary endpoints", async () => {
+        const pngBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x01, 0x02]);
+        const srv = await startJsonServer((_req, res) => {
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "image/png");
+            res.end(pngBytes);
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+            });
+            const payload = await client.request("POST", "/visualization/chart-wheel", {
+                params: { format: "png" },
+                data: {},
+            });
+            expect(payload.content_type).toBe("image/png");
+            expect(payload.content_length).toBe(pngBytes.length);
+            expect(payload.encoding).toBe("base64");
+            expect(Buffer.from(payload.data_base64, "base64").equals(pngBytes)).toBe(true);
+        }
+        finally {
+            await srv.close();
+        }
+    });
+    it("treats chart-wheel as binary without explicit format query", async () => {
+        const svg = "<svg></svg>";
+        const srv = await startJsonServer((_req, res) => {
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "image/svg+xml");
+            res.end(svg);
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+            });
+            const payload = await client.request("POST", "/visualization/chart-wheel", {
+                data: {},
+            });
+            expect(payload.content_type).toBe("image/svg+xml");
+            expect(payload.content_length).toBe(Buffer.byteLength(svg));
+            expect(payload.encoding).toBe("base64");
+            expect(Buffer.from(payload.data_base64, "base64").toString("utf8")).toBe(svg);
+        }
+        finally {
+            await srv.close();
+        }
+    });
+    it("preserves structured 403 detail for binary-endpoint requests", async () => {
+        const srv = await startJsonServer((_req, res) => {
+            res.statusCode = 403;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+                detail: "This endpoint requires at least the Startup (Pro) tier.",
+            }));
+        });
+        try {
+            const client = new BackendClient({
+                baseURL: srv.baseURL,
+            });
+            const message = await getErrorMessage(() => client.request("POST", "/visualization/bi-wheel", {
+                params: { format: "png" },
+                data: {},
+            }));
+            expect(message).toContain("Access blocked by plan or policy:");
+            expect(message).toContain("Startup (Pro) tier");
+            expect(message).toContain("https://openephemeris.com/pay");
+        }
+        finally {
+            await srv.close();
+        }
+    });
+});

package/dist/test/credentials.test.d.ts

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

package/dist/test/credentials.test.js

@@ -0,0 +1,143 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import path from "node:path";
+import os from "node:os";
+import { CredentialManager } from "../src/auth/credentials.js";
+// Use a temp directory to avoid polluting the real ~/.openephemeris
+const TEMP_DIR = path.join(os.tmpdir(), `oe-cred-test-${Date.now()}`);
+const TEMP_CREDS_FILE = path.join(TEMP_DIR, "credentials.json");
+// We can't easily override the private constant, so we'll test the public API
+// using a real CredentialManager and clean up after ourselves.
+function makeCredentials(overrides = {}) {
+    return {
+        access_token: "test-access-token-" + Date.now(),
+        refresh_token: "test-refresh-token-" + Date.now(),
+        expires_at: new Date(Date.now() + 3600 * 1000).toISOString(),
+        user_id: "test-user-id",
+        user_email: "test@example.com",
+        updated_at: new Date().toISOString(),
+        ...overrides,
+    };
+}
+describe("CredentialManager", () => {
+    let manager;
+    beforeEach(() => {
+        manager = new CredentialManager();
+    });
+    afterEach(() => {
+        // Clean up the default credentials file if it was created by tests
+        manager.clear();
+    });
+    it("returns null when no credentials file exists", () => {
+        manager.clear(); // Ensure clean state
+        const creds = manager.load();
+        // It's either null (no file) or returns existing credentials
+        // For a fresh test, it should be null after clear()
+        expect(creds).toBeNull();
+    });
+    it("saves and loads credentials", () => {
+        const testCreds = makeCredentials();
+        manager.save(testCreds);
+        // Create a new manager to test loading from disk
+        const freshManager = new CredentialManager();
+        const loaded = freshManager.load();
+        expect(loaded).not.toBeNull();
+        expect(loaded.access_token).toBe(testCreds.access_token);
+        expect(loaded.refresh_token).toBe(testCreds.refresh_token);
+        expect(loaded.user_email).toBe("test@example.com");
+        expect(loaded.user_id).toBe("test-user-id");
+        // Cleanup
+        freshManager.clear();
+    });
+    it("detects non-expired credentials", () => {
+        const creds = makeCredentials({
+            expires_at: new Date(Date.now() + 3600 * 1000).toISOString(), // 1 hour from now
+        });
+        expect(manager.isExpired(creds)).toBe(false);
+    });
+    it("detects expired credentials", () => {
+        const creds = makeCredentials({
+            expires_at: new Date(Date.now() - 1000).toISOString(), // 1 second ago
+        });
+        expect(manager.isExpired(creds)).toBe(true);
+    });
+    it("treats credentials expiring within 2 minutes as expired", () => {
+        const creds = makeCredentials({
+            expires_at: new Date(Date.now() + 60 * 1000).toISOString(), // 60 seconds from now
+        });
+        // Within the 120-second buffer, should be considered expired
+        expect(manager.isExpired(creds)).toBe(true);
+    });
+    it("treats null/missing credentials as expired", () => {
+        expect(manager.isExpired(null)).toBe(true);
+        expect(manager.isExpired(undefined)).toBe(true);
+        expect(manager.isExpired({ ...makeCredentials(), expires_at: "" })).toBe(true);
+    });
+    it("clear removes credentials", () => {
+        manager.save(makeCredentials());
+        expect(manager.load()).not.toBeNull();
+        manager.clear();
+        expect(manager.load()).toBeNull();
+    });
+    it("clear is idempotent (doesn't throw on missing file)", () => {
+        manager.clear();
+        expect(() => manager.clear()).not.toThrow();
+    });
+    it("getStatus returns authenticated: false when no credentials", () => {
+        manager.clear();
+        const status = manager.getStatus();
+        expect(status.authenticated).toBe(false);
+        expect(status.email).toBeUndefined();
+    });
+    it("getStatus returns authenticated: true for valid credentials", () => {
+        const creds = makeCredentials({
+            expires_at: new Date(Date.now() + 3600 * 1000).toISOString(),
+            user_email: "status@example.com",
+        });
+        manager.save(creds);
+        const status = manager.getStatus();
+        expect(status.authenticated).toBe(true);
+        expect(status.email).toBe("status@example.com");
+        expect(status.expiresAt).toBe(creds.expires_at);
+        manager.clear();
+    });
+    it("getStatus returns authenticated: false for expired credentials", () => {
+        const creds = makeCredentials({
+            expires_at: new Date(Date.now() - 1000).toISOString(),
+        });
+        manager.save(creds);
+        const status = manager.getStatus();
+        expect(status.authenticated).toBe(false);
+        manager.clear();
+    });
+    it("saves with updated_at timestamp", () => {
+        const before = Date.now();
+        manager.save(makeCredentials());
+        const loaded = manager.load();
+        expect(loaded).not.toBeNull();
+        const updatedAt = new Date(loaded.updated_at).getTime();
+        expect(updatedAt).toBeGreaterThanOrEqual(before);
+        expect(updatedAt).toBeLessThanOrEqual(Date.now());
+        manager.clear();
+    });
+    it("getValidToken returns null when no credentials", async () => {
+        manager.clear();
+        const token = await manager.getValidToken();
+        expect(token).toBeNull();
+    });
+    it("getValidToken returns token when not expired", async () => {
+        const creds = makeCredentials({
+            access_token: "valid-token-123",
+            expires_at: new Date(Date.now() + 3600 * 1000).toISOString(),
+        });
+        manager.save(creds);
+        const token = await manager.getValidToken();
+        expect(token).toBe("valid-token-123");
+        manager.clear();
+    });
+    it("credentialsPath is a string in the home directory", () => {
+        const credPath = CredentialManager.credentialsPath;
+        expect(typeof credPath).toBe("string");
+        expect(credPath).toContain(".openephemeris");
+        expect(credPath).toContain("credentials.json");
+    });
+});

package/dist/tools/dev.js

@@ -36,10 +36,11 @@ registerTool({
         "Call dev.list_allowed to see all currently available endpoint paths.\n\n" +
         "AUTH: Set ASTROMCP_API_KEY in your environment. See openephemeris.com/dashboard for active plan limits.\n\n" +
         "CREDIT COSTS:\n" +
-        "  • Standard chart (natal, synastry, composite, progressed): 1 credit\n" +
+        "  • Standard chart math (natal, progressed, bazi, HD): 1 credit\n" +
+        "  • Visualization rendering (chart-wheel, bi-wheel, charts/*): 2 credits\n" +
+        "  • Comparative math (synastry, composite, overlay): 3 credits\n" +
         "  • Predictive ops (transits, returns, transit-chart): 5 credits\n" +
         "  • ACG / astrocartography: 5 credits\n" +
-        "  • Human Design chart: 1 credit\n" +
         "  • Catalog / metadata / health endpoints: 0 credits\n" +
         "  • format=llm (token-optimized output): requires Pro tier ($49+/mo)\n\n" +
         "COMMON CALLS:\n" +
@@ -62,7 +63,7 @@ registerTool({
         "  GET  /eclipse/next-visible             — Next eclipse visible from a location\n" +
         "  GET  /tidal/forcing                    — Gravitational tidal forcing index\n" +
         "  GET  /tidal/forcing/deep-time          — Extended tidal deep-time analysis\n" +
-        "  POST /acg/natal-lines                  — Astrocartography natal lines (lat/lon GeoJSON)\n" +
+        "  POST /acg/power-lines                 — Astrocartography power lines (lat/lon GeoJSON)\n" +
         "  POST /acg/hits                         — ACG power at a specific location\n" +
         "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
         "  GET  /location/autocomplete            — Geocode a place name (query: q=City Name)\n" +
@@ -71,6 +72,9 @@ registerTool({
         "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
         "  POST /vedic/chart                      — Vedic (Jyotish) natal chart\n" +
         "  GET  /catalogs/bodies                  — List all supported celestial bodies\n\n" +
+        "BINARY RESPONSES:\n" +
+        "  • Binary/image endpoints return {content_type, content_length, encoding, data_base64}\n" +
+        "    so callers can decode bytes deterministically.\n\n" +
         "ECLIPSE NOTE: Eclipse endpoints accept format=llm via the query param like other endpoints.\n\n" +
         "format=llm NOTE: Add query: {format: 'llm'} to natal/synastry/composite/HD endpoints for " +
         "compact columnar output optimized for LLM token budgets (availability depends on your current plan).",

package/dist/tools/index.d.ts

@@ -3,6 +3,13 @@ export interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: z.ZodType<any> | Record<string, unknown>;
+    annotations?: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
     handler: (args: any) => Promise<any>;
 }
 export declare const toolRegistry: Record<string, ToolDefinition>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",
@@ -19,8 +19,8 @@
     "build": "tsc",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run --exclude \"dist/**\"",
+    "test:watch": "vitest --exclude \"dist/**\"",
     "typecheck": "tsc --noEmit",
     "regen:dev-allowlist": "tsx scripts/dev-allowlist.ts --write",
     "check:dev-allowlist": "tsx scripts/dev-allowlist.ts --check",