@openephemeris/mcp-server 3.2.6 → 3.2.8

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`): **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`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **17**
+- Typed tools: `auth_login`, `auth_logout`, `auth_status`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `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
@@ -206,9 +206,11 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 | `visualization` | 2 | `POST /visualization/bi-wheel`, `POST /visualization/chart-wheel` |
 <!-- GENERATED:RUNTIME_SNAPSHOT:END -->
 
+## Why OpenEphemeris for AI Agents?
 
-NPM publish
+Most LLMs (like Claude and ChatGPT) struggle heavily with astronomical calculations (trigonometry, Julian date conversions, and Swiss Ephemeris lookups). OpenEphemeris serves as a **secure, remote math engine**.
 
-publish from /c/src/openephemeris/apps/api/mcp-server
-npm login
-npm publish
+By pairing LLMs with the OpenEphemeris MCP server, your agents can instantly access:
+- **Zero-hallucination coordinates**: Direct, sub-arcsecond NASA JPL DE440/DE441 calculations.
+- **LLM-optimized tokens (`format=llm`)**: We compress standard 25,000 token JSON chart responses into minimal text blocks, cutting your inference costs by 50%.
+- **Ready-to-use astrology layers**: Built-in support for Astrocartography geoJSON lines, Hermetic Lots, Fixed Stars, and complex Human Design matrix generation.

package/dist/src/backend/client.js

@@ -256,6 +256,10 @@ export class BackendClient {
             if (status >= 500)
                 return new BackendError(`Backend error (${status}): ${msg}`, status, "server_error", true);
         }
+        // Explicit timeout or abort interception
+        if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
+            return new BackendError(`The computation took too long and timed out. This usually happens when requesting a massive date range (like 20+ years of transits) or an overly complex query. Please narrow your request and try again.`, 408, "timeout", false);
+        }
         return new BackendError(`Network error: ${error.message}`, 0, "network_error", true);
     }
     async get(path, params, timeoutMs) {

package/dist/src/index.js

@@ -99,19 +99,63 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!tool) {
         throw new Error(`Unknown tool: ${toolName}`);
     }
+    const startTime = Date.now();
+    console.error(`[MCP] Executing tool: ${toolName}`);
     try {
         const result = await tool.handler(request.params.arguments ?? {});
+        const durationMs = Date.now() - startTime;
+        console.error(`[MCP] ✅ Success: ${toolName} (${durationMs}ms)`);
+        // Intercept binary backend responses (like Chart Wheels) to return native MCP Images
+        if (result &&
+            typeof result === "object" &&
+            "encoding" in result &&
+            result.encoding === "base64" &&
+            "data_base64" in result &&
+            "content_type" in result) {
+            const binResp = result;
+            console.error(`[MCP] 🎨 Returning image (${binResp.content_length} bytes) for ${toolName}`);
+            return {
+                content: [
+                    {
+                        type: "image",
+                        data: binResp.data_base64,
+                        mimeType: binResp.content_type,
+                    },
+                ],
+            };
+        }
+        const jsonStr = JSON.stringify(result, null, 2);
+        // Safety limit: ~100kb JSON is roughly 20-30k tokens. 
+        // Usually happens if LLMs ask for 50+ years of transits or raw ephemeris arrays.
+        if (jsonStr.length > 100_000) {
+            console.error(`[MCP] ⚠️ Warning: Payload too large (${(jsonStr.length / 1024).toFixed(1)}kb) for ${toolName}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "PAYLOAD_TOO_LARGE",
+                            message: `The requested query produced too much data (${(jsonStr.length / 1024).toFixed(1)}kb). Please significantly narrow your request parameters (e.g., fewer years, smaller coordinate bounding box, etc.) to fit within context limits.`
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(result, null, 2),
+                    text: jsonStr,
                 },
             ],
         };
     }
     catch (error) {
+        const durationMs = Date.now() - startTime;
         const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`[MCP] ❌ Failed: ${toolName} (${durationMs}ms) - ${errorMessage}`);
         return {
             content: [
                 {

package/dist/src/tools/index.js

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

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

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

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

@@ -0,0 +1,66 @@
+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'.";
+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_bi_wheel",
+    description: "Generate a Bi-Wheel (Synastry/Transit) image (PNG) comparing two charts. Draws Subject A's planets on the inside wheel and Subject B's on the outside wheel. The tool returns a raw image (base64) which most Vision-enabled AI agents can display.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Compare someone born April 15, 1990 (A) to someone born June 10, 1992 (B):\n" +
+        "  datetime_a='...', latitude_a=..., longitude_a=..., datetime_b='...', latitude_b=..., longitude_b=...",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime_a: { type: "string", description: DATETIME_DESC },
+            latitude_a: { type: "number", description: "Latitude for subject A" },
+            longitude_a: { type: "number", description: "Longitude for subject A" },
+            datetime_b: { type: "string", description: DATETIME_DESC },
+            latitude_b: { type: "number", description: "Latitude for subject B" },
+            longitude_b: { type: "number", description: "Longitude for subject B" },
+            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.",
+            },
+            style: {
+                type: "string",
+                enum: ["modern", "classic", "dark"],
+                description: "Aesthetic style of the chart. Defaults to 'modern'.",
+            }
+        },
+        required: ["datetime_a", "latitude_a", "longitude_a", "datetime_b", "latitude_b", "longitude_b"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime_a", "latitude_a", "longitude_a", "datetime_b", "latitude_b", "longitude_b"]);
+        const body = {
+            subject_a: {
+                name: "Subject A",
+                birth_datetime: { iso: args.datetime_a },
+                birth_location: {
+                    latitude: { decimal: args.latitude_a },
+                    longitude: { decimal: args.longitude_a }
+                },
+            },
+            subject_b: {
+                name: "Subject B",
+                birth_datetime: { iso: args.datetime_b },
+                birth_location: {
+                    latitude: { decimal: args.latitude_b },
+                    longitude: { decimal: args.longitude_b }
+                },
+            }
+        };
+        if (args.house_system) {
+            const mappedCode = HOUSE_SYSTEM_MAP[args.house_system] || "P";
+            body.configuration = { house_system: mappedCode };
+        }
+        const styleParam = args.style ? `&style=${args.style}` : "";
+        return await backendClient.post(`/visualization/bi-wheel?format=png&size=800${styleParam}`, body);
+    },
+});

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

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

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

@@ -0,0 +1,64 @@
+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'.";
+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_chart_wheel",
+    description: "Generate a classic astrological Chart Wheel image (PNG) for a person/event. This draws a standard circular chart wheel with planets, aspects, and house cusps. The tool returns a raw image (base64) which most Vision-enabled AI agents (GPT-4o, Claude 3.5 Sonnet) can display and visually read.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Generate a natal chart wheel for someone born April 15, 1990 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.",
+            },
+            style: {
+                type: "string",
+                enum: ["modern", "classic", "dark"],
+                description: "Aesthetic style of the chart. Defaults to 'modern'.",
+            }
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        const body = {
+            subject: {
+                name: "Chart Wheel Request",
+                birth_datetime: { iso: args.datetime },
+                birth_location: {
+                    latitude: { decimal: args.latitude },
+                    longitude: { decimal: args.longitude }
+                },
+            }
+        };
+        if (args.house_system) {
+            const mappedCode = HOUSE_SYSTEM_MAP[args.house_system] || "P";
+            body.configuration = { house_system: mappedCode };
+        }
+        const styleParam = args.style ? `&style=${args.style}` : "";
+        return await backendClient.post(`/visualization/chart-wheel?format=png&size=800${styleParam}`, body);
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.2.6",
+  "version": "3.2.8",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",
@@ -42,7 +42,11 @@
     "astrology",
     "astronomy",
     "ephemeris",
-    "openephemeris"
+    "openephemeris",
+    "llm",
+    "claude",
+    "ai",
+    "swiss ephemeris"
   ],
   "author": "Open Ephemeris",
   "license": "MIT",