@openephemeris/mcp-server 3.2.13 → 3.3.1

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`): **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`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **49**
+- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `electional_aspect_search`, `electional_ingress_calendar`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
 
 ### Allowlist Families

package/dist/index.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { initTools, toolRegistry } from "./tools/index.js";
+import { initTools, toolRegistry, formatToolResponse } from "./tools/index.js";
 function resolveServerVersion() {
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
@@ -104,53 +104,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     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: jsonStr,
-                },
-            ],
-        };
+        return formatToolResponse(toolName, result, durationMs);
     }
     catch (error) {
         const durationMs = Date.now() - startTime;

package/dist/server-sse.js

@@ -20,7 +20,7 @@ import axios from "axios";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { initTools, toolRegistry } from "./tools/index.js";
+import { initTools, toolRegistry, formatToolResponse } from "./tools/index.js";
 import { backendClient } from "./backend/client.js";
 // ---------------------------------------------------------------------------
 // Helpers
@@ -108,13 +108,16 @@ function createMcpServer() {
             throw new Error(`Unknown tool: ${toolName}`);
         }
         try {
+            const startTime = Date.now();
+            console.error(`[MCP] Executing tool: ${toolName}`);
             const result = await tool.handler(request.params.arguments ?? {});
-            return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            };
+            const durationMs = Date.now() - startTime;
+            return formatToolResponse(toolName, result, durationMs);
         }
         catch (error) {
+            const startTime = Date.now(); // Not strictly accurate for errors but acceptable for logging structure if needed
             const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error(`[MCP] \u274c Failed: ${toolName} - ${errorMessage}`);
             return {
                 content: [
                     {

package/dist/tools/index.d.ts

@@ -31,3 +31,28 @@ export declare function validateRequired(args: any, requiredKeys: string[]): voi
  * Throws an error if only one of the coordinate pair is provided.
  */
 export declare function validateCoordinates(args: any, latKey: string, lonKey: string): void;
+/**
+ * Formats a raw tool response into native MCP content blocks.
+ * Intercepts binary image responses (like Chart Wheels) and returns them as native MCP Images.
+ * Applies a safety limit to JSON payloads to prevent crashing LLM contexts.
+ */
+export declare function formatToolResponse(toolName: string, result: any, durationMs: number): {
+    content: {
+        type: string;
+        data: string;
+        mimeType: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+};

package/dist/tools/index.js

@@ -33,6 +33,14 @@ export async function initTools(profile) {
         await import("./specialized/bazi.js");
         await import("./specialized/chart_wheel.js");
         await import("./specialized/bi_wheel.js");
+        await import("./specialized/returns.js");
+        await import("./specialized/progressed.js");
+        await import("./specialized/ephemeris_core.js");
+        await import("./specialized/acg.js");
+        await import("./specialized/comparative.js");
+        await import("./specialized/hd_group.js");
+        await import("./specialized/ephemeris_extended.js");
+        await import("./specialized/venus_star_points.js");
     }
 }
 /**
@@ -58,3 +66,57 @@ export function validateCoordinates(args, latKey, lonKey) {
         throw new Error(`Both ${latKey} and ${lonKey} must be provided together, or both omitted.`);
     }
 }
+/**
+ * Formats a raw tool response into native MCP content blocks.
+ * Intercepts binary image responses (like Chart Wheels) and returns them as native MCP Images.
+ * Applies a safety limit to JSON payloads to prevent crashing LLM contexts.
+ */
+export function formatToolResponse(toolName, result, durationMs) {
+    // 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} (${durationMs}ms)`);
+        return {
+            content: [
+                {
+                    type: "image",
+                    data: binResp.data_base64,
+                    mimeType: binResp.content_type,
+                },
+            ],
+        };
+    }
+    const jsonStr = JSON.stringify(result, null, 2);
+    // Safety limit: ~500kb JSON is roughly 100k+ tokens. 
+    // Usually happens if LLMs ask for 50+ years of transits or raw ephemeris arrays.
+    if (jsonStr.length > 500_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,
+        };
+    }
+    console.error(`[MCP] ✅ Success: ${toolName} (${durationMs}ms)`);
+    return {
+        content: [
+            {
+                type: "text",
+                text: jsonStr,
+            },
+        ],
+    };
+}

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

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

package/dist/tools/specialized/acg.js

@@ -0,0 +1,143 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+const ACG_BODY_DESCRIPTION = "List of celestial bodies for line calculation. " +
+    "E.g. ['Sun', 'Moon', 'Venus', 'Mars', 'Jupiter', 'Saturn']. " +
+    "Aliases: 'NorthNode'/'Node'/'Rahu' → MeanNode, 'SouthNode'/'Ketu' → SouthNode. " +
+    "Omit to use all classical planets.";
+// POST /acg/power-lines — OE-018
+registerTool({
+    name: "acg_power_lines",
+    description: "Calculate Astrocartography power lines (MC, IC, AC/ASC, DC/DSC) for a natal chart. " +
+        "Returns GeoJSON LineStrings tracing each planetary angle line around the globe. " +
+        "These are the latitudinal lines where a planet was rising (AC), setting (DC), " +
+        "culminating (MC), or anti-culminating (IC) at birth.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
+        "EXAMPLE: Saturn and Jupiter power lines for a chart born 1990-04-15 in Chicago:\n" +
+        "  birth_datetime='1990-04-15T14:30:00', birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
+        "  bodies=['Saturn', 'Jupiter']",
+    inputSchema: {
+        type: "object",
+        properties: {
+            birth_datetime: {
+                type: "string",
+                description: "ISO 8601 natal birth date/time.",
+            },
+            birth_latitude: {
+                type: "number",
+                description: "Birth latitude in decimal degrees.",
+            },
+            birth_longitude: {
+                type: "number",
+                description: "Birth longitude in decimal degrees.",
+            },
+            bodies: {
+                type: "array",
+                items: { type: "string" },
+                description: ACG_BODY_DESCRIPTION,
+            },
+            query_latitude: {
+                type: "number",
+                description: "Filter lines near this latitude (optional, for hits mode).",
+            },
+            query_longitude: {
+                type: "number",
+                description: "Filter lines near this longitude (optional, for hits mode).",
+            },
+            radius_deg: {
+                type: "number",
+                description: "Search radius in degrees for hits filtering. Default 2°.",
+            },
+        },
+        required: ["birth_datetime", "birth_latitude", "birth_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude"]);
+        const body = {
+            natal: {
+                birthplace_lat: args.birth_latitude,
+                birthplace_lon: args.birth_longitude,
+            },
+            epoch: args.birth_datetime,
+        };
+        if (args.bodies)
+            body.bodies = args.bodies;
+        if (args.query_latitude != null)
+            body.query_lat = args.query_latitude;
+        if (args.query_longitude != null)
+            body.query_lon = args.query_longitude;
+        if (args.radius_deg != null)
+            body.radius_deg = args.radius_deg;
+        return await backendClient.post("/acg/power-lines", body);
+    },
+});
+// POST /acg/hits — OE-018
+registerTool({
+    name: "acg_hits",
+    description: "Find all Astrocartography lines (power lines + aspect lines) passing near a specific location. " +
+        "Returns features sorted by distance, making it easy to interpret planetary influences at a place.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
+        "EXAMPLE: All ACG lines within 3° of Paris for a chart born 1990-04-15 in Chicago:\n" +
+        "  birth_datetime='1990-04-15T14:30:00', birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
+        "  query_latitude=48.8566, query_longitude=2.3522, radius_deg=3",
+    inputSchema: {
+        type: "object",
+        properties: {
+            birth_datetime: {
+                type: "string",
+                description: "ISO 8601 natal birth date/time.",
+            },
+            birth_latitude: {
+                type: "number",
+                description: "Birth latitude in decimal degrees.",
+            },
+            birth_longitude: {
+                type: "number",
+                description: "Birth longitude in decimal degrees.",
+            },
+            query_latitude: {
+                type: "number",
+                description: "Latitude of the location to check for nearby lines.",
+            },
+            query_longitude: {
+                type: "number",
+                description: "Longitude of the location to check for nearby lines.",
+            },
+            radius_deg: {
+                type: "number",
+                description: "Search radius in degrees (default 2°, max 90°).",
+            },
+            bodies: {
+                type: "array",
+                items: { type: "string" },
+                description: ACG_BODY_DESCRIPTION,
+            },
+            include_aspects: {
+                type: "boolean",
+                description: "Include aspect lines in results (default true).",
+            },
+        },
+        required: ["birth_datetime", "birth_latitude", "birth_longitude", "query_latitude", "query_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "query_latitude", "query_longitude"]);
+        const body = {
+            natal: {
+                birthplace_lat: args.birth_latitude,
+                birthplace_lon: args.birth_longitude,
+            },
+            epoch: args.birth_datetime,
+            query_lat: args.query_latitude,
+            query_lon: args.query_longitude,
+        };
+        if (args.bodies)
+            body.bodies = args.bodies;
+        if (args.radius_deg != null)
+            body.radius_deg = args.radius_deg;
+        if (args.include_aspects != null) {
+            body.options = { include_aspects: args.include_aspects };
+        }
+        return await backendClient.post("/acg/hits", body);
+    },
+});

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

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

package/dist/tools/specialized/comparative.js

@@ -0,0 +1,153 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+function buildSubject(name, datetime, lat, lon) {
+    return {
+        name,
+        birth_datetime: { iso: datetime },
+        birth_location: {
+            latitude: { decimal: lat },
+            longitude: { decimal: lon },
+        },
+    };
+}
+// POST /comparative/composite
+registerTool({
+    name: "ephemeris_composite",
+    description: "Calculate a composite chart from two or more natal charts. The composite " +
+        "uses midpoints of each planet pair to derive a single relationship chart.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
+        "EXAMPLE: Composite for two people:\n" +
+        "  person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.88, person_a_longitude=-87.63,\n" +
+        "  person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.05, person_b_longitude=-118.24",
+    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." },
+        },
+        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",
+        ]);
+        return await backendClient.post("/comparative/composite", {
+            subjects: [
+                buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude),
+            ],
+        });
+    },
+});
+// POST /comparative/composite/midpoint
+registerTool({
+    name: "ephemeris_composite_midpoint",
+    description: "Calculate a midpoint composite chart — an alternative composite method " +
+        "using the midpoints of matching planet positions.\n\n" +
+        "CREDIT COST: 3 credits per call.",
+    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." },
+        },
+        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",
+        ]);
+        return await backendClient.post("/comparative/composite/midpoint", {
+            subjects: [
+                buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude),
+            ],
+        });
+    },
+});
+// POST /comparative/overlay
+registerTool({
+    name: "ephemeris_overlay",
+    description: "Calculate an overlay chart — place one person's planets in another person's houses. " +
+        "Shows how person A's energies impact person B's life areas and vice versa.\n\n" +
+        "CREDIT COST: 3 credits per call.",
+    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." },
+        },
+        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",
+        ]);
+        return await backendClient.post("/comparative/overlay", {
+            subjects: [
+                buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude),
+            ],
+        });
+    },
+});
+// POST /comparative/natal-transits
+registerTool({
+    name: "ephemeris_natal_transits",
+    description: "Calculate active transits to a natal chart — shows which current planets " +
+        "are aspecting natal positions. Essential for predictive astrology.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
+        "EXAMPLE: Current transits to someone born 1990-04-15:\n" +
+        "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.88, natal_longitude=-87.63",
+    inputSchema: {
+        type: "object",
+        properties: {
+            natal_datetime: { type: "string", description: "Natal birth datetime (ISO 8601)." },
+            natal_latitude: { type: "number", description: "Natal birth latitude." },
+            natal_longitude: { type: "number", description: "Natal birth longitude." },
+            transit_datetime: { type: "string", description: "Transit moment (ISO 8601). Defaults to now." },
+        },
+        required: ["natal_datetime", "natal_latitude", "natal_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude"]);
+        const subjects = [
+            buildSubject("Natal", args.natal_datetime, args.natal_latitude, args.natal_longitude),
+        ];
+        // The transit subject uses the transit datetime or current time
+        if (args.transit_datetime) {
+            subjects.push(buildSubject("Transit", args.transit_datetime, args.natal_latitude, args.natal_longitude));
+        }
+        return await backendClient.post("/comparative/natal-transits", {
+            subjects,
+        });
+    },
+});