@openephemeris/mcp-server 3.0.1 → 3.2.0

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

@@ -0,0 +1,50 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris.moon_phase",
+    description: "Get the current Moon phase and void-of-course status. Returns the Moon's sign, phase name " +
+        "(New, Waxing Crescent, First Quarter, Waxing Gibbous, Full, Waning Gibbous, Last Quarter, " +
+        "Waning Crescent), exact phase angle, illumination percentage, and the next void-of-course period.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "If no datetime is provided, returns the current (live) moon phase.\n\n" +
+        "EXAMPLE: Get moon phase for a specific date/time:\n" +
+        "  datetime='2026-03-20T12:00:00Z'\n\n" +
+        "EXAMPLE: Get the current moon phase right now:\n" +
+        "  (call with no arguments)",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: "ISO 8601 datetime to query. If omitted, returns the current live moon phase (UTC now).",
+            },
+            latitude: {
+                type: "number",
+                description: "Observer latitude (optional, used for local void-of-course calculations).",
+            },
+            longitude: {
+                type: "number",
+                description: "Observer longitude (optional, used for local void-of-course calculations).",
+            },
+        },
+        required: [],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const params = {};
+        if (args.datetime)
+            params.datetime = args.datetime;
+        if (args.latitude != null)
+            params.latitude = args.latitude;
+        if (args.longitude != null)
+            params.longitude = args.longitude;
+        const [phase, voc] = await Promise.allSettled([
+            backendClient.request("GET", "/ephemeris/moon/phase", { params }),
+            backendClient.request("GET", "/ephemeris/moon/void-of-course", { params }),
+        ]);
+        return {
+            phase: phase.status === "fulfilled" ? phase.value : { error: phase.reason?.message },
+            void_of_course: voc.status === "fulfilled" ? voc.value : { error: voc.reason?.message },
+        };
+    },
+});

package/dist/src/tools/specialized/natal.d.ts

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

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

@@ -0,0 +1,71 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
+    "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
+registerTool({
+    name: "ephemeris.natal_chart",
+    description: "Calculate a full natal (birth) chart for a person. Returns planetary positions, house cusps, " +
+        "aspects, and chart patterns. Use format='llm' for a compact, token-efficient output ideal for " +
+        "interpretation (available on all tiers). The result includes all major planets, angles (ASC/MC/DSC/IC), " +
+        "essential dignities, retrograde status, house system data, and major aspect grid.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Calculate the natal chart for someone born April 15, 1990 at 2:30 PM in Chicago:\n" +
+        "  datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: DATETIME_DESC,
+            },
+            latitude: {
+                type: "number",
+                description: "Geographic latitude of birth location in decimal degrees (positive = North).",
+            },
+            longitude: {
+                type: "number",
+                description: "Geographic longitude of birth location in decimal degrees (positive = East).",
+            },
+            house_system: {
+                type: "string",
+                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry", "alcabitius", "morinus"],
+                description: "House system to use. Defaults to 'placidus' if omitted.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' returns a compact array-based projection optimized for LLM token efficiency (available on all tiers). 'json' returns full verbose JSON.",
+            },
+            include_arabic_parts: {
+                type: "boolean",
+                description: "If true, include Hermetic Lots (Arabic Parts) in the response.",
+            },
+            include_fixed_stars: {
+                type: "boolean",
+                description: "If true, include fixed star conjunctions in the response.",
+            },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const body = {
+            datetime: args.datetime,
+            latitude: args.latitude,
+            longitude: args.longitude,
+        };
+        if (args.house_system)
+            body.house_system = args.house_system;
+        if (args.include_arabic_parts)
+            body.include_arabic_parts = args.include_arabic_parts;
+        if (args.include_fixed_stars)
+            body.include_fixed_stars = args.include_fixed_stars;
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/natal-chart", {
+            data: body,
+            params: query,
+        });
+    },
+});

package/dist/src/tools/specialized/relocation.d.ts

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

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

@@ -0,0 +1,71 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris.relocation",
+    description: "Calculate a relocation chart — the same natal planetary positions re-cast for a different " +
+        "geographic location. Used to understand how living in a different city shifts house placements " +
+        "and angles, without changing the planetary longitudes in the chart.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: How does moving from Chicago to London change someone's chart?\n" +
+        "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
+        "  relocation_latitude=51.5074, relocation_longitude=-0.1278",
+    inputSchema: {
+        type: "object",
+        properties: {
+            natal_datetime: {
+                type: "string",
+                description: "ISO 8601 birth datetime (local time at birth location).",
+            },
+            natal_latitude: {
+                type: "number",
+                description: "Latitude of birth location in decimal degrees.",
+            },
+            natal_longitude: {
+                type: "number",
+                description: "Longitude of birth location in decimal degrees.",
+            },
+            relocation_latitude: {
+                type: "number",
+                description: "Latitude of the relocation city in decimal degrees (positive = North).",
+            },
+            relocation_longitude: {
+                type: "number",
+                description: "Longitude of the relocation city in decimal degrees (positive = East).",
+            },
+            house_system: {
+                type: "string",
+                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry"],
+                description: "House system to use. Defaults to 'placidus'.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' = compact token-efficient output (available on all tiers).",
+            },
+        },
+        required: ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const body = {
+            natal: {
+                datetime: args.natal_datetime,
+                latitude: args.natal_latitude,
+                longitude: args.natal_longitude,
+            },
+            relocation: {
+                latitude: args.relocation_latitude,
+                longitude: args.relocation_longitude,
+            },
+        };
+        if (args.house_system)
+            body.house_system = args.house_system;
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/relocation", {
+            data: body,
+            params: query,
+        });
+    },
+});

package/dist/src/tools/specialized/synastry.d.ts

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

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

@@ -0,0 +1,61 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris.synastry",
+    description: "Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects " +
+        "(planetary connections between the two charts), composite points, and relationship indicators. " +
+        "Use this for compatibility analysis, relationship timing, or partnership insights.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
+        "EXAMPLE: Compare two people's charts:\n" +
+        "  person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.8781, person_a_longitude=-87.6298,\n" +
+        "  person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.0522, person_b_longitude=-118.2437",
+    inputSchema: {
+        type: "object",
+        properties: {
+            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
+            person_a_latitude: { type: "number", description: "Person A birth latitude." },
+            person_a_longitude: { type: "number", description: "Person A birth longitude." },
+            person_b_datetime: { type: "string", description: "Person B birth datetime (ISO 8601)." },
+            person_b_latitude: { type: "number", description: "Person B birth latitude." },
+            person_b_longitude: { type: "number", description: "Person B birth longitude." },
+            house_system: {
+                type: "string",
+                enum: ["placidus", "whole_sign", "equal", "koch"],
+                description: "House system for both charts. Defaults to 'placidus'.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' is compact and token-efficient (available on all tiers).",
+            },
+        },
+        required: [
+            "person_a_datetime", "person_a_latitude", "person_a_longitude",
+            "person_b_datetime", "person_b_latitude", "person_b_longitude",
+        ],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const body = {
+            natal_a: {
+                datetime: args.person_a_datetime,
+                latitude: args.person_a_latitude,
+                longitude: args.person_a_longitude,
+            },
+            natal_b: {
+                datetime: args.person_b_datetime,
+                latitude: args.person_b_latitude,
+                longitude: args.person_b_longitude,
+            },
+        };
+        if (args.house_system)
+            body.house_system = args.house_system;
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/comparative/synastry", {
+            data: body,
+            params: query,
+        });
+    },
+});

package/dist/src/tools/specialized/transits.d.ts

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

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

@@ -0,0 +1,80 @@
+import { registerTool } 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) => {
+        const body = {
+            natal: {
+                datetime: args.natal_datetime,
+                latitude: args.natal_latitude,
+                longitude: args.natal_longitude,
+            },
+            start_date: args.start_date,
+            end_date: args.end_date,
+        };
+        if (args.transiting_planets)
+            body.transiting_planets = args.transiting_planets;
+        if (args.natal_points)
+            body.natal_points = args.natal_points;
+        if (args.aspects)
+            body.aspects = args.aspects;
+        if (args.orb != null)
+            body.orb = args.orb;
+        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 {};