@openephemeris/mcp-server 3.3.0 → 3.3.2

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

@@ -66,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/bi_wheel.js

@@ -17,9 +17,11 @@ registerTool({
         type: "object",
         properties: {
             datetime_a: { type: "string", description: DATETIME_DESC },
+            timezone_a: { type: "string", description: "IANA timezone name for subject A, e.g. 'America/Denver'." },
             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 },
+            timezone_b: { type: "string", description: "IANA timezone name for subject B, e.g. 'Europe/London'." },
             latitude_b: { type: "number", description: "Latitude for subject B" },
             longitude_b: { type: "number", description: "Longitude for subject B" },
             house_system: {
@@ -56,6 +58,12 @@ registerTool({
                 },
             }
         };
+        if (args.timezone_a) {
+            body.subject_a.birth_location.timezone = { iana_name: args.timezone_a };
+        }
+        if (args.timezone_b) {
+            body.subject_b.birth_location.timezone = { iana_name: args.timezone_b };
+        }
         if (args.house_system) {
             const mappedCode = HOUSE_SYSTEM_MAP[args.house_system] || "P";
             body.configuration = { house_system: mappedCode };

package/dist/tools/specialized/chart_wheel.js

@@ -20,6 +20,10 @@ registerTool({
                 type: "string",
                 description: DATETIME_DESC,
             },
+            timezone: {
+                type: "string",
+                description: "IANA timezone name, e.g. 'America/Denver'. Use this if passing local time without a UTC offset in the datetime string.",
+            },
             latitude: {
                 type: "number",
                 description: "Geographic latitude of birth location in decimal degrees (positive = North).",
@@ -54,6 +58,9 @@ registerTool({
                 },
             }
         };
+        if (args.timezone) {
+            body.subject.birth_location.timezone = { iana_name: args.timezone };
+        }
         if (args.house_system) {
             const mappedCode = HOUSE_SYSTEM_MAP[args.house_system] || "P";
             body.configuration = { house_system: mappedCode };

package/dist/tools/specialized/comparative.js

@@ -1,7 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
-function buildSubject(name, datetime, lat, lon) {
-    return {
+function buildSubject(name, datetime, lat, lon, timezone) {
+    const subj = {
         name,
         birth_datetime: { iso: datetime },
         birth_location: {
@@ -9,6 +9,10 @@ function buildSubject(name, datetime, lat, lon) {
             longitude: { decimal: lon },
         },
     };
+    if (timezone) {
+        subj.birth_location.timezone = { iana_name: timezone };
+    }
+    return subj;
 }
 // POST /comparative/composite
 registerTool({
@@ -23,9 +27,11 @@ registerTool({
         type: "object",
         properties: {
             person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
+            person_a_timezone: { type: "string", description: "IANA timezone name for Person A, e.g. 'America/Denver'." },
             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_timezone: { type: "string", description: "IANA timezone name for Person B, e.g. 'Europe/London'." },
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
         },
@@ -42,8 +48,8 @@ registerTool({
         ]);
         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),
+                buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude, args.person_a_timezone),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
             ],
         });
     },
@@ -58,9 +64,11 @@ registerTool({
         type: "object",
         properties: {
             person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
+            person_a_timezone: { type: "string", description: "IANA timezone name for Person A, e.g. 'America/Denver'." },
             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_timezone: { type: "string", description: "IANA timezone name for Person B, e.g. 'Europe/London'." },
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
         },
@@ -77,8 +85,8 @@ registerTool({
         ]);
         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),
+                buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude, args.person_a_timezone),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
             ],
         });
     },
@@ -93,9 +101,11 @@ registerTool({
         type: "object",
         properties: {
             person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
+            person_a_timezone: { type: "string", description: "IANA timezone name for Person A, e.g. 'America/Denver'." },
             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_timezone: { type: "string", description: "IANA timezone name for Person B, e.g. 'Europe/London'." },
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
         },
@@ -112,8 +122,8 @@ registerTool({
         ]);
         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),
+                buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude, args.person_a_timezone),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
             ],
         });
     },
@@ -130,9 +140,11 @@ registerTool({
         type: "object",
         properties: {
             natal_datetime: { type: "string", description: "Natal birth datetime (ISO 8601)." },
+            natal_timezone: { type: "string", description: "IANA timezone name for Natal, e.g. 'America/Denver'." },
             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." },
+            transit_timezone: { type: "string", description: "IANA timezone name for Transit, e.g. 'America/Denver'. Only applicable if transit_datetime is provided without offset." },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude"],
         additionalProperties: false,
@@ -140,11 +152,11 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude"]);
         const subjects = [
-            buildSubject("Natal", args.natal_datetime, args.natal_latitude, args.natal_longitude),
+            buildSubject("Natal", args.natal_datetime, args.natal_latitude, args.natal_longitude, args.natal_timezone),
         ];
         // 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));
+            subjects.push(buildSubject("Transit", args.transit_datetime, args.natal_latitude, args.natal_longitude, args.transit_timezone));
         }
         return await backendClient.post("/comparative/natal-transits", {
             subjects,

package/dist/tools/specialized/ephemeris_core.js

@@ -6,7 +6,8 @@ registerTool({
     description: "Get the precise ecliptic longitude, latitude, distance, speed, and retrograde status " +
         "for a single planet/body at a given date and time. " +
         "Planet IDs: 0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, " +
-        "7=Uranus, 8=Neptune, 9=Pluto, 10=North Node, 11=South Node, 12=Lilith.\n\n" +
+        "7=Uranus, 8=Neptune, 9=Pluto, 10=North Node, 11=South Node, 12=Lilith, " +
+        "15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Where is Mars on 2026-03-20 at noon UTC?\n" +
         "  planet_id=4, datetime='2026-03-20T12:00:00Z'",
@@ -15,11 +16,11 @@ registerTool({
         properties: {
             planet_id: {
                 type: "integer",
-                description: "Planet/body ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=MeanNode, 11=TrueNode, 12=Lilith).",
+                description: "Planet/body ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=MeanNode, 11=TrueNode, 12=Lilith, 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta).",
             },
             datetime: {
                 type: "string",
-                description: "ISO 8601 date/time (e.g. '2026-03-20T12:00:00Z').",
+                description: "ISO 8601 date/time in UTC or with offset (e.g. '2026-03-20T12:00:00Z' or '2026-03-20T12:00:00-05:00').",
             },
             latitude: {
                 type: "number",
@@ -60,7 +61,7 @@ registerTool({
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 date/time.",
+                description: "ISO 8601 date/time in UTC or with offset (e.g. '2026-03-20T12:00:00Z').",
             },
             latitude: {
                 type: "number",

package/dist/tools/specialized/natal.js

@@ -12,8 +12,8 @@ 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 (available on all tiers). The result includes all major planets, angles (ASC/MC/DSC/IC), " +
-        "essential dignities, retrograde status, house system data, and major aspect grid.\n\n" +
+        "interpretation (available on all tiers). The result includes all major planets, Chiron and major asteroids like Ceres, angles (ASC/MC/DSC/IC), " +
+        "essential dignities, retrograde status, house system data, and major aspect grid. Asteroids are automatically included.\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",
@@ -24,6 +24,10 @@ registerTool({
                 type: "string",
                 description: DATETIME_DESC,
             },
+            timezone: {
+                type: "string",
+                description: "IANA timezone name, e.g. 'America/Denver'. Use this if passing local time without a UTC offset in the datetime string.",
+            },
             latitude: {
                 type: "number",
                 description: "Geographic latitude of birth location in decimal degrees (positive = North).",
@@ -66,6 +70,9 @@ registerTool({
                 },
             }
         };
+        if (args.timezone) {
+            body.subject.birth_location.timezone = { iana_name: args.timezone };
+        }
         if (args.house_system) {
             const code = HOUSE_SYSTEM_MAP[args.house_system] ?? args.house_system;
             body.configuration = { house_system: code };

package/dist/tools/specialized/returns.js

@@ -13,11 +13,11 @@ registerTool({
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time (e.g. '1985-06-21T14:00:00').",
+                description: "ISO 8601 birth date/time. MUST include offset or Z (e.g. '1985-06-21T14:00:00-05:00').",
             },
             target_datetime: {
                 type: "string",
-                description: "Date/time near which to find the Solar Return (ISO 8601). Required.",
+                description: "Date/time near which to find the Solar Return (ISO 8601). MUST include offset or Z. Required.",
             },
             birth_latitude: {
                 type: "number",
@@ -73,11 +73,11 @@ registerTool({
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time.",
+                description: "ISO 8601 birth date/time. MUST include offset or Z.",
             },
             target_datetime: {
                 type: "string",
-                description: "Date/time near which to find the Lunar Return (ISO 8601). Required.",
+                description: "Date/time near which to find the Lunar Return (ISO 8601). MUST include offset or Z. Required.",
             },
             birth_latitude: {
                 type: "number",
@@ -123,11 +123,11 @@ registerTool({
             },
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time.",
+                description: "ISO 8601 birth date/time. MUST include offset or Z.",
             },
             target_datetime: {
                 type: "string",
-                description: "Date/time near which to find the return (ISO 8601). Required.",
+                description: "Date/time near which to find the return (ISO 8601). MUST include offset or Z. Required.",
             },
         },
         required: ["body", "birth_datetime", "target_datetime"],

package/package.json

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