@openephemeris/mcp-server 3.1.0 → 3.2.2

package/dist/src/tools/index.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+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>;
+export declare function registerTool(tool: ToolDefinition): void;
+export type ToolProfile = "dev" | "legacy";
+/**
+ * Initializes tool modules.
+ *
+ * - `dev`: registers the allowlist-gated generic call tools AND all specialized
+ *   domain tools (natal chart, transits, moon phase, eclipse, synastry, HD).
+ * - `legacy`: registers only the generic tools (back-compat).
+ */
+export declare function initTools(profile?: ToolProfile): Promise<void>;
+/**
+ * Throws an error if any of the required keys are missing or empty.
+ */
+export declare function validateRequired(args: any, requiredKeys: string[]): void;
+/**
+ * Throws an error if only one of the coordinate pair is provided.
+ */
+export declare function validateCoordinates(args: any, latKey: string, lonKey: string): void;

package/dist/src/tools/index.js

@@ -0,0 +1,56 @@
+export const toolRegistry = {};
+export function registerTool(tool) {
+    toolRegistry[tool.name] = tool;
+}
+let toolsInitialized = false;
+/**
+ * Initializes tool modules.
+ *
+ * - `dev`: registers the allowlist-gated generic call tools AND all specialized
+ *   domain tools (natal chart, transits, moon phase, eclipse, synastry, HD).
+ * - `legacy`: registers only the generic tools (back-compat).
+ */
+export async function initTools(profile) {
+    if (toolsInitialized)
+        return;
+    toolsInitialized = true;
+    const resolvedProfile = (profile || process.env.OPENEPHEMERIS_PROFILE || process.env.ASTROMCP_PROFILE || "dev").toLowerCase();
+    // Always register auth tools (available in all profiles).
+    await import("./auth.js");
+    // Always register the generic proxy tools (dev.call + dev.list_allowed).
+    await import("./dev.js");
+    if (resolvedProfile === "dev") {
+        // Register all specialized domain tools.
+        await import("./specialized/natal.js");
+        await import("./specialized/transits.js");
+        await import("./specialized/moon.js");
+        await import("./specialized/eclipse.js");
+        await import("./specialized/human_design.js");
+        await import("./specialized/synastry.js");
+        await import("./specialized/relocation.js");
+        await import("./specialized/electional.js");
+    }
+}
+/**
+ * Throws an error if any of the required keys are missing or empty.
+ */
+export function validateRequired(args, requiredKeys) {
+    if (!args)
+        throw new Error("Missing arguments object.");
+    const missing = requiredKeys.filter((k) => args[k] == null || args[k] === "");
+    if (missing.length > 0) {
+        throw new Error(`Missing required arguments: ${missing.join(", ")}`);
+    }
+}
+/**
+ * Throws an error if only one of the coordinate pair is provided.
+ */
+export function validateCoordinates(args, latKey, lonKey) {
+    if (!args)
+        return;
+    const hasLat = args[latKey] != null && args[latKey] !== "";
+    const hasLon = args[lonKey] != null && args[lonKey] !== "";
+    if (hasLat !== hasLon) {
+        throw new Error(`Both ${latKey} and ${lonKey} must be provided together, or both omitted.`);
+    }
+}

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

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

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

@@ -0,0 +1,53 @@
+import { registerTool, validateRequired, validateCoordinates } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris_next_eclipse",
+    description: "Find the next solar or lunar eclipse visible from a given location (or globally). " +
+        "Returns the eclipse type, date/time of maximum, magnitude, duration of totality (if any), " +
+        "and local contact times if coordinates are provided.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Find the next solar eclipse visible from New York:\n" +
+        "  eclipse_type='solar', latitude=40.7128, longitude=-74.006\n\n" +
+        "EXAMPLE: Find the next lunar eclipse globally:\n" +
+        "  eclipse_type='lunar'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            eclipse_type: {
+                type: "string",
+                enum: ["solar", "lunar"],
+                description: "Eclipse type to search for.",
+            },
+            latitude: {
+                type: "number",
+                description: "Observer latitude in decimal degrees. If provided, returns local visibility and contact times.",
+            },
+            longitude: {
+                type: "number",
+                description: "Observer longitude in decimal degrees.",
+            },
+            after_date: {
+                type: "string",
+                description: "ISO 8601 date to search after (e.g. '2026-01-01'). Defaults to today if omitted.",
+            },
+        },
+        required: ["eclipse_type"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["eclipse_type"]);
+        validateCoordinates(args, "latitude", "longitude");
+        const params = {};
+        if (args.latitude != null)
+            params.lat = args.latitude;
+        if (args.longitude != null)
+            params.lon = args.longitude;
+        if (args.after_date)
+            params.date = args.after_date;
+        if (args.eclipse_type)
+            params.type = args.eclipse_type;
+        // Use /eclipse/next-visible which is the unified endpoint
+        // that accepts lat/lon and type filters
+        return await backendClient.request("GET", "/eclipse/next-visible", { params, timeoutMs: 60_000 });
+    },
+});

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

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

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

@@ -0,0 +1,80 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris_electional",
+    description: "Find optimal planetary timing windows (electional astrology). Scans a date range to find the " +
+        "best times for an event based on essential dignity, aspect quality, sect, and void-of-course " +
+        "moon penalties. Evaluates every hour and clusters the best continuous windows.\n\n" +
+        "CREDIT COST: 5 credits per call (heavy calculation).\n\n" +
+        "EXAMPLE: Find the best time to launch a business in early March 2026.\n" +
+        "  start_date='2026-03-01', end_date='2026-03-10', latitude=40.7128, longitude=-74.0060,\n" +
+        "  avoid_voc=true, lunar_phase='waxing'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: {
+                type: "string",
+                description: "ISO 8601 start date or datetime for the search window (e.g., 2026-03-01).",
+            },
+            end_date: {
+                type: "string",
+                description: "ISO 8601 end date or datetime for the search window.",
+            },
+            latitude: {
+                type: "number",
+                description: "Latitude of location in decimal degrees (positive = North).",
+            },
+            longitude: {
+                type: "number",
+                description: "Longitude of location in decimal degrees (positive = East).",
+            },
+            max_results: {
+                type: "number",
+                description: "Maximum number of top windows to return (default 5).",
+            },
+            avoid_retrograde: {
+                type: "string",
+                description: "Comma-separated list of planets to avoid when retrograde (e.g., 'mercury,venus').",
+            },
+            lunar_phase: {
+                type: "string",
+                enum: ["waxing", "waning", "new", "full", "any"],
+                description: "Filter windows by lunar phase. Defaults to 'any'.",
+            },
+            avoid_voc: {
+                type: "boolean",
+                description: "If true, strictly ignores any moments where the Moon is Void of Course.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' = compact token-efficient output (available on all tiers).",
+            },
+        },
+        required: ["start_date", "end_date", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["start_date", "end_date", "latitude", "longitude"]);
+        const query = {
+            start_date: args.start_date,
+            end_date: args.end_date,
+            latitude: args.latitude,
+            longitude: args.longitude,
+        };
+        if (args.max_results !== undefined)
+            query.max_results = args.max_results;
+        if (args.avoid_retrograde)
+            query.avoid_retrograde = args.avoid_retrograde;
+        if (args.lunar_phase)
+            query.lunar_phase = args.lunar_phase;
+        if (args.avoid_voc !== undefined)
+            query.avoid_voc = args.avoid_voc;
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("GET", "/electional/find-window", {
+            data: {},
+            params: query,
+        });
+    },
+});

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

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

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

@@ -0,0 +1,54 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "human_design_chart",
+    description: "Calculate a full Human Design bodygraph chart from birth data. Returns the person's Type " +
+        "(Generator, Manifesting Generator, Projector, Manifestor, Reflector), Strategy, Authority, " +
+        "Profile (e.g. 1/3, 2/4), defined and undefined Centers, activated Gates and Channels, " +
+        "Incarnation Cross, and both Personality (conscious) and Design (unconscious) planetary positions.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion " +
+        "before birth (~3 months prior, the Design calculation). The API handles this automatically.\n\n" +
+        "EXAMPLE: Get the Human Design 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: "ISO 8601 birth datetime (local time at birth location), e.g. '1990-04-15T14:30:00'.",
+            },
+            latitude: {
+                type: "number",
+                description: "Latitude of birth location in decimal degrees (positive = North).",
+            },
+            longitude: {
+                type: "number",
+                description: "Longitude of birth location in decimal degrees (positive = East).",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' returns compact array projection for token efficiency (available on all tiers). " +
+                    "'json' returns verbose full output.",
+            },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        const body = {
+            birth_datetime_utc: args.datetime,
+            latitude: args.latitude,
+            longitude: args.longitude,
+        };
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/human-design/chart", {
+            data: body,
+            params: query,
+        });
+    },
+});

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

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

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

@@ -0,0 +1,51 @@
+import { registerTool, validateCoordinates } 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) => {
+        validateCoordinates(args, "latitude", "longitude");
+        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,80 @@
+import { registerTool, validateRequired } 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: "Reserved for future use. Hermetic Lots / Arabic Parts are currently available via the dedicated /ephemeris/hermetic-lots endpoint.",
+            },
+            include_fixed_stars: {
+                type: "boolean",
+                description: "Reserved for future use. Fixed star positions are currently available via the dedicated /ephemeris/fixed-stars endpoint.",
+            },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        const body = {
+            subject: {
+                name: "MCP Request",
+                birth_datetime: { iso: args.datetime },
+                birth_location: {
+                    latitude: { decimal: args.latitude },
+                    longitude: { decimal: args.longitude }
+                },
+            }
+        };
+        if (args.house_system) {
+            body.configuration = { house_system: args.house_system };
+        }
+        if (args.include_arabic_parts || args.include_fixed_stars) {
+            body.options = {
+                ...(args.include_arabic_parts && { include_arabic_parts: args.include_arabic_parts }),
+                ...(args.include_fixed_stars && { 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,76 @@
+import { registerTool, validateRequired } 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) => {
+        validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"]);
+        const body = {
+            natal: {
+                subject: {
+                    name: "MCP Request",
+                    birth_datetime: { iso: args.natal_datetime },
+                    birth_location: {
+                        latitude: { decimal: args.natal_latitude },
+                        longitude: { decimal: args.natal_longitude },
+                        timezone: {},
+                    },
+                },
+            },
+            relocation_lat: args.relocation_latitude,
+            relocation_lon: 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,73 @@
+import { registerTool, validateRequired } 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: 3 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) => {
+        validateRequired(args, [
+            "person_a_datetime", "person_a_latitude", "person_a_longitude",
+            "person_b_datetime", "person_b_latitude", "person_b_longitude",
+        ]);
+        const body = {
+            subject_a: {
+                name: "Person A",
+                birth_datetime: { iso: args.person_a_datetime },
+                birth_location: {
+                    latitude: { decimal: args.person_a_latitude },
+                    longitude: { decimal: args.person_a_longitude },
+                    timezone: {},
+                },
+            },
+            subject_b: {
+                name: "Person B",
+                birth_datetime: { iso: args.person_b_datetime },
+                birth_location: {
+                    latitude: { decimal: args.person_b_latitude },
+                    longitude: { decimal: args.person_b_longitude },
+                    timezone: {},
+                },
+            },
+        };
+        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 {};