@openephemeris/mcp-server 3.2.7 → 3.2.9

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/index.js

@@ -105,6 +105,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         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.

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/dist/src/tools/specialized/transits.js

@@ -6,7 +6,9 @@ registerTool({
         "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" +
+        "HOW IT WORKS: This tool first calculates the natal chart to extract your actual planetary " +
+        "ecliptic longitudes, then searches for transiting planets crossing those exact degrees.\n\n" +
+        "CREDIT COST: 6 credits per call (1 for natal + 5 for transit search).\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']",
@@ -42,16 +44,7 @@ registerTool({
             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).",
+                description: "Natal point IDs whose exact longitudes should be targeted. E.g. ['sun', 'moon', 'asc', 'mc']. Omit for all core points.",
             },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
@@ -59,6 +52,58 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"]);
+        // ── Step 1: Compute natal chart to extract real planetary longitudes ──
+        const natalBody = {
+            subject: {
+                name: "Transit Natal Subject",
+                birth_datetime: { iso: args.natal_datetime },
+                birth_location: {
+                    latitude: { decimal: args.natal_latitude },
+                    longitude: { decimal: args.natal_longitude }
+                },
+            },
+        };
+        const natalResult = await backendClient.post("/ephemeris/natal", natalBody);
+        // Extract ecliptic longitudes from natal chart planets
+        const targetDegrees = [];
+        const natalPositionMap = {};
+        // The natal response typically has a `planets` array or object
+        const planets = natalResult?.planets || natalResult?.data?.planets || [];
+        const planetArray = Array.isArray(planets) ? planets : Object.values(planets);
+        // Filter to requested natal points if specified
+        const wantedPoints = args.natal_points
+            ? new Set(args.natal_points.map((p) => p.toLowerCase()))
+            : null;
+        for (const planet of planetArray) {
+            const name = (planet.name || planet.id || "").toLowerCase();
+            const lon = planet.longitude ?? planet.ecliptic_longitude ?? planet.lon;
+            if (typeof lon !== "number" || !isFinite(lon))
+                continue;
+            if (wantedPoints && !wantedPoints.has(name))
+                continue;
+            targetDegrees.push(Math.round(lon * 100) / 100); // 2 decimal places
+            natalPositionMap[name] = lon;
+        }
+        // Also extract angles (ASC, MC, DSC, IC) if present
+        const angles = natalResult?.angles || natalResult?.data?.angles;
+        if (angles) {
+            const angleEntries = Array.isArray(angles) ? angles : Object.entries(angles).map(([k, v]) => ({ name: k, ...(typeof v === 'object' ? v : { longitude: v }) }));
+            for (const angle of angleEntries) {
+                const name = (angle.name || angle.id || "").toLowerCase();
+                const lon = angle.longitude ?? angle.ecliptic_longitude ?? angle.lon;
+                if (typeof lon !== "number" || !isFinite(lon))
+                    continue;
+                if (wantedPoints && !wantedPoints.has(name))
+                    continue;
+                targetDegrees.push(Math.round(lon * 100) / 100);
+                natalPositionMap[name] = lon;
+            }
+        }
+        if (targetDegrees.length === 0) {
+            throw new Error("Could not extract natal planet longitudes from the natal chart calculation. " +
+                "Please verify your natal_datetime, natal_latitude, and natal_longitude are correct.");
+        }
+        // ── Step 2: Search transits against those real natal longitudes ──
         let startStr = args.start_date;
         if (/^\d{4}-\d{2}-\d{2}$/.test(startStr)) {
             startStr += "T00:00:00Z";
@@ -67,26 +112,19 @@ registerTool({
         if (/^\d{4}-\d{2}-\d{2}$/.test(endStr)) {
             endStr += "T23:59:59Z";
         }
-        const body = {
+        const transitBody = {
             start_date: startStr,
             end_date: endStr,
-            natal_chart: {
-                datetime: args.natal_datetime,
-                latitude: args.natal_latitude,
-                longitude: args.natal_longitude,
-            },
+            target_degrees: targetDegrees,
         };
         if (args.transiting_planets)
-            body.planet_names = args.transiting_planets;
-        const searchCriteria = {};
-        if (args.natal_points)
-            searchCriteria.natal_points = args.natal_points;
-        if (args.aspects)
-            searchCriteria.aspects = args.aspects;
-        if (args.orb != null)
-            searchCriteria.orb = args.orb;
-        if (Object.keys(searchCriteria).length > 0)
-            body.search_criteria = searchCriteria;
-        return await backendClient.request("POST", "/predictive/transits/search", { data: body });
+            transitBody.planet_names = args.transiting_planets;
+        const transitResult = await backendClient.request("POST", "/predictive/transits/search", { data: transitBody });
+        // Return combined context so the LLM knows what natal positions were targeted
+        return {
+            natal_positions: natalPositionMap,
+            target_degrees_used: targetDegrees,
+            transit_results: transitResult,
+        };
     },
 });

package/package.json

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