@openephemeris/mcp-server 3.1.0 → 3.2.2

package/dist/src/tools/specialized/transits.js

@@ -0,0 +1,87 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris_transits",
+    description: "Search for astrological transit events affecting a natal chart over a date range. " +
+        "Returns a list of exact transit moments — when transiting planets form specified aspects " +
+        "to natal planet positions. Ideal for generating horoscope timelines, event forecasting, or " +
+        "finding optimal timing windows.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
+        "EXAMPLE: Find all Saturn transits to the natal Sun/Moon for the next 6 months:\n" +
+        "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
+        "  start_date='2026-01-01', end_date='2026-06-30', transiting_planets=['saturn']",
+    inputSchema: {
+        type: "object",
+        properties: {
+            natal_datetime: {
+                type: "string",
+                description: "ISO 8601 birth datetime for the natal chart.",
+            },
+            natal_latitude: {
+                type: "number",
+                description: "Latitude of birth location in decimal degrees.",
+            },
+            natal_longitude: {
+                type: "number",
+                description: "Longitude of birth location in decimal degrees.",
+            },
+            start_date: {
+                type: "string",
+                description: "Start of the transit search window, ISO 8601 date or datetime (e.g. '2026-01-01').",
+            },
+            end_date: {
+                type: "string",
+                description: "End of the transit search window, ISO 8601 date or datetime (e.g. '2026-06-30').",
+            },
+            transiting_planets: {
+                type: "array",
+                items: { type: "string" },
+                description: "List of transiting planet IDs to search. E.g. ['saturn', 'jupiter', 'uranus', 'pluto']. " +
+                    "Omit to search all outer planets.",
+            },
+            natal_points: {
+                type: "array",
+                items: { type: "string" },
+                description: "Natal point IDs to receive transits. E.g. ['sun', 'moon', 'asc', 'mc']. Omit for all core points.",
+            },
+            aspects: {
+                type: "array",
+                items: { type: "string", enum: ["conjunction", "opposition", "trine", "square", "sextile"] },
+                description: "Aspect types to include in the search. Defaults to all major aspects.",
+            },
+            orb: {
+                type: "number",
+                description: "Maximum orb in degrees (default: 1.0).",
+            },
+        },
+        required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"]);
+        let startStr = args.start_date;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(startStr)) {
+            startStr += "T00:00:00Z";
+        }
+        let endStr = args.end_date;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(endStr)) {
+            endStr += "T23:59:59Z";
+        }
+        const body = {
+            start_date: startStr,
+            end_date: endStr,
+        };
+        if (args.transiting_planets)
+            body.planet_names = args.transiting_planets;
+        const searchCriteria = {};
+        if (args.natal_points)
+            searchCriteria.natal_points = args.natal_points;
+        if (args.aspects)
+            searchCriteria.aspects = args.aspects;
+        if (args.orb != null)
+            searchCriteria.orb = args.orb;
+        if (Object.keys(searchCriteria).length > 0)
+            body.search_criteria = searchCriteria;
+        return await backendClient.request("POST", "/predictive/transits/search", { data: body });
+    },
+});

package/dist/test/allowlist-and-tools.test.d.ts

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

package/dist/test/allowlist-and-tools.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { toolRegistry, initTools } from "../src/tools/index.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const allowlistPath = path.resolve(here, "../config/dev-allowlist.json");
+function isDeniedByPrefix(pathname, prefixes) {
+    return prefixes.some((p) => pathname.startsWith(p));
+}
+function isAllowedOperation(method, pathname, allow) {
+    return allow.some((e) => e.method.toUpperCase() === method.toUpperCase() && e.path === pathname);
+}
+describe("dev-allowlist.json", () => {
+    const raw = fs.readFileSync(allowlistPath, "utf-8");
+    const allowlist = JSON.parse(raw);
+    it("has valid schema identifier", () => {
+        expect(allowlist.schema).toBe("astromcp-dev-allowlist-v1");
+    });
+    it("has at least 60 allowlisted operations", () => {
+        // 68 entries from Go openapi.json; this guard catches accidental mass-deletion
+        expect(allowlist.allow.length).toBeGreaterThanOrEqual(60);
+    });
+    it("all allow entries have valid method and path starting with /", () => {
+        const validMethods = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+        for (const entry of allowlist.allow) {
+            expect(validMethods.has(entry.method), `Invalid method: ${entry.method}`).toBe(true);
+            expect(entry.path.startsWith("/"), `Path must start with /: ${entry.path}`).toBe(true);
+        }
+    });
+    it("deny prefixes block auth/billing/admin paths", () => {
+        const denyPrefixes = allowlist.deny?.path_prefixes ?? [];
+        const blockedPaths = ["/auth/login", "/billing/me", "/admin/users", "/api-keys"];
+        for (const blocked of blockedPaths) {
+            expect(isDeniedByPrefix(blocked, denyPrefixes), `Expected ${blocked} to be blocked by deny prefixes`).toBe(true);
+        }
+    });
+    it("no allow entry violates deny prefixes", () => {
+        const denyPrefixes = allowlist.deny?.path_prefixes ?? [];
+        for (const entry of allowlist.allow) {
+            expect(isDeniedByPrefix(entry.path, denyPrefixes), `Allow entry ${entry.method} ${entry.path} violates a deny prefix`).toBe(false);
+        }
+    });
+    it("isAllowedOperation works for known Go endpoints", () => {
+        expect(isAllowedOperation("GET", "/catalogs/bodies", allowlist.allow)).toBe(true);
+        expect(isAllowedOperation("GET", "/electional/find-window", allowlist.allow)).toBe(true);
+    });
+    it("phantom paths are NOT in the allowlist (Go API only)", () => {
+        // These paths don't exist in the Go openapi.json — they were legacy Python routes
+        expect(isAllowedOperation("GET", "/agro/daily", allowlist.allow)).toBe(false);
+        expect(isAllowedOperation("GET", "/agro/calendar", allowlist.allow)).toBe(false);
+        expect(isAllowedOperation("GET", "/batch/position", allowlist.allow)).toBe(false);
+        expect(isAllowedOperation("GET", "/houses", allowlist.allow)).toBe(false);
+        expect(isAllowedOperation("GET", "/lunar/solunar", allowlist.allow)).toBe(false);
+        expect(isAllowedOperation("GET", "/lunar/void-of-course", allowlist.allow)).toBe(false);
+    });
+    it("isAllowedOperation blocks denied paths", () => {
+        expect(isAllowedOperation("POST", "/auth/login", allowlist.allow)).toBe(false);
+        expect(isAllowedOperation("GET", "/admin/users", allowlist.allow)).toBe(false);
+        expect(isAllowedOperation("DELETE", "/api-keys/abc", allowlist.allow)).toBe(false);
+    });
+});
+describe("toolRegistry", () => {
+    beforeAll(async () => {
+        await initTools("dev");
+    });
+    it("registers all expected tools", () => {
+        const expectedTools = [
+            "auth_login",
+            "auth_status",
+            "auth_logout",
+            "dev_call",
+            "dev_list_allowed",
+            "ephemeris_natal_chart",
+            "ephemeris_transits",
+            "ephemeris_moon_phase",
+            "ephemeris_next_eclipse",
+            "ephemeris_synastry",
+            "ephemeris_relocation",
+            "ephemeris_electional",
+            "human_design_chart",
+        ];
+        for (const name of expectedTools) {
+            expect(toolRegistry[name], `Missing tool: ${name}`).toBeDefined();
+        }
+    });
+    it("every registered tool has required fields", () => {
+        for (const [name, tool] of Object.entries(toolRegistry)) {
+            expect(typeof tool.name, `${name}: name must be string`).toBe("string");
+            expect(typeof tool.description, `${name}: description must be string`).toBe("string");
+            expect(tool.description.length, `${name}: description must not be empty`).toBeGreaterThan(10);
+            expect(typeof tool.handler, `${name}: handler must be function`).toBe("function");
+            expect(tool.inputSchema, `${name}: inputSchema must be defined`).toBeDefined();
+        }
+    });
+});

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

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

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

@@ -0,0 +1,284 @@
+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).toMatch(/Account connection required|Authentication required:/);
+        }
+        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");
+    });
+});