@openephemeris/mcp-server 3.0.0

package/dist/tools/specialized/eclipse.js

@@ -0,0 +1,56 @@
+import { registerTool } 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) => {
+        const params = {};
+        if (args.latitude != null)
+            params.latitude = args.latitude;
+        if (args.longitude != null)
+            params.longitude = args.longitude;
+        if (args.after_date)
+            params.date = args.after_date;
+        if (args.eclipse_type === "solar") {
+            // Use local endpoint if coordinates provided, otherwise global
+            if (args.latitude != null && args.longitude != null) {
+                return await backendClient.request("GET", "/eclipse/solar/local", { params, timeoutMs: 60_000 });
+            }
+            return await backendClient.request("GET", "/eclipse/solar/global", { params, timeoutMs: 60_000 });
+        }
+        else {
+            return await backendClient.request("GET", "/eclipse/lunar/global", { params, timeoutMs: 60_000 });
+        }
+    },
+});

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

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

package/dist/tools/specialized/electional.js

@@ -0,0 +1,79 @@
+import { registerTool } 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 (Startup tier).",
+            },
+        },
+        required: ["start_date", "end_date", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        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/tools/specialized/human_design.d.ts

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

package/dist/tools/specialized/human_design.js

@@ -0,0 +1,53 @@
+import { registerTool } 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 (Pro tier). " +
+                    "'json' returns verbose full output.",
+            },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const body = {
+            datetime: 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/tools/specialized/moon.d.ts

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

package/dist/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/tools/specialized/natal.d.ts

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

package/dist/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 (requires Pro tier). 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 (Pro tier required). '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/tools/specialized/relocation.d.ts

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

package/dist/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 (Startup tier).",
+            },
+        },
+        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/tools/specialized/synastry.d.ts

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

package/dist/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 (Pro tier).",
+            },
+        },
+        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/tools/specialized/transits.d.ts

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

package/dist/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/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@openephemeris/mcp-server",
+  "version": "3.0.0",
+  "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "config/dev-allowlist.json",
+    "README.md"
+  ],
+  "bin": {
+    "openephemeris-mcp": "dist/index.js"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "regen:dev-allowlist": "tsx scripts/dev-allowlist.ts --write",
+    "check:dev-allowlist": "tsx scripts/dev-allowlist.ts --check",
+    "regen:schema-packs": "tsx scripts/schema-packs.ts --write",
+    "check:schema-packs": "tsx scripts/schema-packs.ts --check",
+    "sync:readme": "tsx scripts/sync-readme.ts --write",
+    "check:readme": "tsx scripts/sync-readme.ts --check",
+    "check:pack": "tsx scripts/pack-audit.ts",
+    "verify:release": "npm run check:dev-allowlist && npm run check:schema-packs && npm run check:readme && npm run typecheck && npm test && npm run build && npm run check:pack",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run verify:release"
+  },
+  "keywords": [
+    "mcp",
+    "astrology",
+    "astronomy",
+    "ephemeris",
+    "openephemeris"
+  ],
+  "author": "Open Ephemeris",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "axios": "^1.13.2",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "packageManager": "pnpm@10.27.0+sha512.72d699da16b1179c14ba9e64dc71c9a40988cbdc65c264cb0e489db7de917f20dcf4d64d8723625f2969ba52d4b7e2a1170682d9ac2a5dcaeaab732b7e16f04a"
+}