@openephemeris/mcp-server 3.2.3 → 3.2.6

package/README.md

@@ -179,8 +179,8 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 - Allowlisted operations: **97**
 - Methods: `GET=41`, `POST=56`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **13**
-- Typed tools: `auth_login`, `auth_logout`, `auth_status`, `dev_call`, `dev_list_allowed`, `ephemeris_electional`, `ephemeris_moon_phase`, `ephemeris_natal_chart`, `ephemeris_next_eclipse`, `ephemeris_relocation`, `ephemeris_synastry`, `ephemeris_transits`, `human_design_chart`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **15**
+- Typed tools: `auth_login`, `auth_logout`, `auth_status`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `ephemeris_electional`, `ephemeris_moon_phase`, `ephemeris_natal_chart`, `ephemeris_next_eclipse`, `ephemeris_relocation`, `ephemeris_synastry`, `ephemeris_transits`, `human_design_chart`, `vedic_chart`
 - Generic tools: 
 
 ### Allowlist Families

package/dist/src/index.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry } from "./tools/index.js";
 function resolveServerVersion() {
     try {
@@ -33,6 +33,7 @@ const server = new Server({
 }, {
     capabilities: {
         tools: {},
+        prompts: {},
     },
 });
 // List available tools
@@ -50,6 +51,47 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         })),
     };
 });
+// List available prompts
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: "welcome_to_open_ephemeris",
+                description: "Getting started guide for the Open Ephemeris MCP. Use this to orient yourself to available tools, astrology terminology, and usage.",
+            }
+        ]
+    };
+});
+// Get prompt content
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (request.params.name !== "welcome_to_open_ephemeris") {
+        throw new Error(`Unknown prompt: ${request.params.name}`);
+    }
+    return {
+        description: "Open Ephemeris Agent & Developer Orientation",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "Welcome to the **Open Ephemeris MCP Server**!\n\n" +
+                        "You are now connected to an enterprise-grade astrological and astronomical computation engine powered by NASA JPL DE440 and DE441 ephemeris data. As a generative guide, here is how you can best utilize these tools to help the user:\n\n" +
+                        "### Core Capabilities\n" +
+                        "- **Birth Charts:** Use `ephemeris_natal_chart` for full planetary positions, houses, dignities, and aspects.\n" +
+                        "- **Predictive Timing:** `ephemeris_transits` searches for exact dates when transiting planets hit natal points.\n" +
+                        "- **Location Astrology:** `ephemeris_relocation` projects a natal chart to a new geographic location (Astrocartography).\n" +
+                        "- **Specialized Modalities:** Dedicated tools for `vedic_chart`, `chinese_bazi`, and `human_design_chart`.\n" +
+                        "- **Eclipse Hunter:** `ephemeris_next_eclipse` dynamically scans 20 years for the next total or partial hit at the user's location.\n\n" +
+                        "### Best Practices for AI Agents\n" +
+                        "1. **Coordinate Formatting:** Always convert addresses/city names into `latitude` and `longitude` decimals *before* calling the tools (e.g., Chicago is `41.8781, -87.6298`).\n" +
+                        "2. **Datetime Handling:** Most endpoints accept ISO 8601 strings. If you have a local birth time but the endpoint asks for UTC, explicitly append a `Z` or timezone offset (e.g., `1990-04-15T19:30:00Z`).\n" +
+                        "3. **Token Efficiency:** Our responses are hyper-condensed to save you context space. You don't need to struggle with raw JSON arrays; interpret the condensed strings directly (e.g., `Su 15°Pi30 H10`).\n\n" +
+                        "You're equipped with professional-grade math. Start by asking the user if they'd like to calculate a natal chart, check recent transits, or explore another modality!"
+                }
+            }
+        ]
+    };
+});
 // Handle tool calls
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const toolName = request.params.name;

package/dist/src/tools/index.js

@@ -29,6 +29,8 @@ export async function initTools(profile) {
         await import("./specialized/synastry.js");
         await import("./specialized/relocation.js");
         await import("./specialized/electional.js");
+        await import("./specialized/vedic.js");
+        await import("./specialized/bazi.js");
     }
 }
 /**

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

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

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

@@ -0,0 +1,67 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "chinese_bazi",
+    description: "Calculate a Chinese Ba Zi (Four Pillars of Destiny) chart. Returns the Year, Month, Day, " +
+        "and Hour pillars, each containing a Heavenly Stem and Earthly Branch pair. Also includes " +
+        "the Day Master element, Wu Xing element breakdown, and basic interpretation context.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "You can provide either a datetime string (which will be decomposed automatically) " +
+        "or explicit year/month/day/hour values.\n\n" +
+        "EXAMPLE: Ba Zi for someone born July 15, 1987 at 2:00 PM:\n" +
+        "  year=1987, month=7, day=15, hour=14",
+    inputSchema: {
+        type: "object",
+        properties: {
+            year: {
+                type: "integer",
+                description: "Gregorian birth year, e.g. 1987.",
+            },
+            month: {
+                type: "integer",
+                description: "Birth month (1-12).",
+            },
+            day: {
+                type: "integer",
+                description: "Birth day of month (1-31).",
+            },
+            hour: {
+                type: "integer",
+                description: "Birth hour (0-23). Optional, defaults to 12 (noon). " +
+                    "Chinese hours (shí) are 2-hour blocks, so precision within a 2-hour window is sufficient.",
+            },
+            datetime: {
+                type: "string",
+                description: "Alternative: ISO 8601 datetime (e.g. '1987-07-15T14:00:00'). " +
+                    "If provided, year/month/day/hour are extracted automatically. " +
+                    "Use this OR the individual year/month/day fields, not both.",
+            },
+        },
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        let year = args.year;
+        let month = args.month;
+        let day = args.day;
+        let hour = args.hour;
+        // If datetime provided, extract components
+        if (args.datetime && (!year || !month || !day)) {
+            const dt = new Date(args.datetime);
+            if (!isNaN(dt.getTime())) {
+                year = dt.getUTCFullYear();
+                month = dt.getUTCMonth() + 1;
+                day = dt.getUTCDate();
+                if (hour == null)
+                    hour = dt.getUTCHours();
+            }
+        }
+        if (!year || !month || !day) {
+            throw new Error("Either provide year/month/day fields, or a datetime string. " +
+                "Example: year=1987, month=7, day=15 OR datetime='1987-07-15T14:00:00'");
+        }
+        const body = { year, month, day };
+        if (hour != null)
+            body.hour = hour;
+        return await backendClient.request("POST", "/chinese/bazi", { data: body });
+    },
+});

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

@@ -2,52 +2,49 @@ 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). " +
+    description: "Find the next solar or lunar eclipse visible from a given location. " +
         "Returns the eclipse type, date/time of maximum, magnitude, duration of totality (if any), " +
-        "and local contact times if coordinates are provided.\n\n" +
+        "and local contact times.\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'",
+        "EXAMPLE: Find the next lunar eclipse from London:\n" +
+        "  eclipse_type='lunar', latitude=51.5074, longitude=-0.1278",
     inputSchema: {
         type: "object",
         properties: {
             eclipse_type: {
                 type: "string",
-                enum: ["solar", "lunar"],
-                description: "Eclipse type to search for.",
+                enum: ["solar", "lunar", "any"],
+                description: "Eclipse type to search for. Use 'any' for whichever comes first.",
             },
             latitude: {
                 type: "number",
-                description: "Observer latitude in decimal degrees. If provided, returns local visibility and contact times.",
+                description: "Observer latitude in decimal degrees (required). Returns local visibility and contact times.",
             },
             longitude: {
                 type: "number",
-                description: "Observer longitude in decimal degrees.",
+                description: "Observer longitude in decimal degrees (required).",
             },
             after_date: {
                 type: "string",
                 description: "ISO 8601 date to search after (e.g. '2026-01-01'). Defaults to today if omitted.",
             },
         },
-        required: ["eclipse_type"],
+        required: ["eclipse_type", "latitude", "longitude"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        validateRequired(args, ["eclipse_type"]);
+        validateRequired(args, ["eclipse_type", "latitude", "longitude"]);
         validateCoordinates(args, "latitude", "longitude");
-        const params = {};
-        if (args.latitude != null)
-            params.lat = args.latitude;
-        if (args.longitude != null)
-            params.lon = args.longitude;
+        const params = {
+            lat: args.latitude,
+            lon: args.longitude,
+        };
         if (args.after_date)
             params.date = args.after_date;
-        if (args.eclipse_type)
+        if (args.eclipse_type && args.eclipse_type !== "any")
             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/human_design.js

@@ -1,5 +1,17 @@
 import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
+/**
+ * Ensure a datetime string has a timezone offset for Go's time.Time parsing.
+ * Go's encoding/json only accepts RFC 3339 (must have Z or +HH:MM offset).
+ */
+function ensureTimezone(dt) {
+    if (!dt)
+        return dt;
+    // Already has timezone indicator
+    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt) || /[+-]\d{4}$/.test(dt))
+        return dt;
+    return dt + "Z";
+}
 registerTool({
     name: "human_design_chart",
     description: "Calculate a full Human Design bodygraph chart from birth data. Returns the person's Type " +
@@ -9,14 +21,15 @@ registerTool({
         "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",
+        "IMPORTANT: The datetime should be in UTC. If you have local birth time, convert to UTC first.\n\n" +
+        "EXAMPLE: Get the Human Design chart for someone born April 15, 1990 at 7:30 PM UTC:\n" +
+        "  datetime='1990-04-15T19:30:00Z', 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'.",
+                description: "ISO 8601 birth datetime in UTC, e.g. '1990-04-15T19:30:00Z'. Must include 'Z' or timezone offset.",
             },
             latitude: {
                 type: "number",
@@ -33,16 +46,18 @@ registerTool({
                     "'json' returns verbose full output.",
             },
         },
-        required: ["datetime", "latitude", "longitude"],
+        required: ["datetime"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        validateRequired(args, ["datetime"]);
         const body = {
-            birth_datetime_utc: args.datetime,
-            latitude: args.latitude,
-            longitude: args.longitude,
+            birth_datetime_utc: ensureTimezone(args.datetime),
         };
+        if (args.latitude != null)
+            body.latitude = args.latitude;
+        if (args.longitude != null)
+            body.longitude = args.longitude;
         const query = {};
         if (args.format)
             query.format = args.format;

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

@@ -2,6 +2,12 @@ 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'.";
+/** Map human-readable house system names to Swiss Ephemeris single-letter codes */
+const HOUSE_SYSTEM_MAP = {
+    placidus: "P", whole_sign: "W", equal: "E", koch: "K",
+    campanus: "C", regiomontanus: "R", porphyry: "O",
+    alcabitius: "B", morinus: "M",
+};
 registerTool({
     name: "ephemeris_natal_chart",
     description: "Calculate a full natal (birth) chart for a person. Returns planetary positions, house cusps, " +
@@ -61,12 +67,18 @@ registerTool({
             }
         };
         if (args.house_system) {
-            body.configuration = { house_system: args.house_system };
+            const code = HOUSE_SYSTEM_MAP[args.house_system] ?? args.house_system;
+            body.configuration = { house_system: code };
         }
-        if (args.include_arabic_parts || args.include_fixed_stars) {
+        if (args.include_fixed_stars) {
+            body.configuration = {
+                ...(body.configuration || {}),
+                fixed_star_options: { include: true }
+            };
+        }
+        if (args.include_arabic_parts) {
             body.options = {
-                ...(args.include_arabic_parts && { include_arabic_parts: args.include_arabic_parts }),
-                ...(args.include_fixed_stars && { include_fixed_stars: args.include_fixed_stars }),
+                include_hermetic_lots: true,
             };
         }
         const query = {};

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

@@ -70,6 +70,11 @@ registerTool({
         const body = {
             start_date: startStr,
             end_date: endStr,
+            natal_chart: {
+                datetime: args.natal_datetime,
+                latitude: args.natal_latitude,
+                longitude: args.natal_longitude,
+            },
         };
         if (args.transiting_planets)
             body.planet_names = args.transiting_planets;

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

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

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

@@ -0,0 +1,48 @@
+import { registerTool, validateRequired, validateCoordinates } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "vedic_chart",
+    description: "Calculate a Vedic (Jyotish) natal chart with sidereal positions. Returns planet placements " +
+        "in rashis (sidereal signs), nakshatras with pada, navamsa placements, and bhavas (houses). " +
+        "Uses Whole Sign houses, sidereal zodiac with configurable ayanamsa.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "SUPPORTED AYANAMSA: lahiri (default), fagan_bradley, krishnamurti, raman, yukteshwar\n\n" +
+        "EXAMPLE: Vedic chart for someone born Jan 15, 1990 at 8:30 AM UTC in Mumbai:\n" +
+        "  datetime='1990-01-15T08:30:00Z', latitude=19.076, longitude=72.8777",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: "ISO 8601 birth datetime in UTC, e.g. '1990-01-15T08:30:00Z'. Include 'Z' or timezone offset.",
+            },
+            latitude: {
+                type: "number",
+                description: "Birth latitude in decimal degrees (north positive).",
+            },
+            longitude: {
+                type: "number",
+                description: "Birth longitude in decimal degrees (east positive).",
+            },
+            ayanamsa: {
+                type: "string",
+                enum: ["lahiri", "fagan_bradley", "krishnamurti", "raman", "yukteshwar"],
+                description: "Ayanamsa system for sidereal conversion. Defaults to 'lahiri'.",
+            },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        validateCoordinates(args, "latitude", "longitude");
+        const body = {
+            datetime_utc: args.datetime,
+            latitude: args.latitude,
+            longitude: args.longitude,
+        };
+        if (args.ayanamsa)
+            body.ayanamsa = args.ayanamsa;
+        return await backendClient.request("POST", "/vedic/chart", { data: body });
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.2.3",
+  "version": "3.2.6",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",