@openephemeris/mcp-server 3.3.2 → 3.4.0

package/dist/backend/client.js

@@ -277,6 +277,8 @@ export class BackendClient {
                 return new BackendError(`Resource not found: ${msg}`, 404, "not_found", false);
             if (status === 400)
                 return new BackendError(`Invalid request: ${msg}`, 400, "bad_request", false);
+            if (status === 422)
+                return new BackendError(`Validation error: ${msg}`, 422, "unprocessable_entity", false);
             if (status >= 500)
                 return new BackendError(`Backend error (${status}): ${msg}`, status, "server_error", true);
         }

package/dist/tools/specialized/comparative.js

@@ -34,6 +34,7 @@ registerTool({
             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." },
+            format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
         },
         required: [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -46,11 +47,17 @@ registerTool({
             "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, args.person_a_timezone),
-                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
-            ],
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/comparative/composite", {
+            params: query,
+            data: {
+                subjects: [
+                    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),
+                ],
+            }
         });
     },
 });
@@ -71,6 +78,7 @@ registerTool({
             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." },
+            format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
         },
         required: [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -83,11 +91,17 @@ registerTool({
             "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, args.person_a_timezone),
-                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
-            ],
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/comparative/composite/midpoint", {
+            params: query,
+            data: {
+                subjects: [
+                    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),
+                ],
+            }
         });
     },
 });
@@ -108,6 +122,7 @@ registerTool({
             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." },
+            format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
         },
         required: [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -120,11 +135,17 @@ registerTool({
             "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, args.person_a_timezone),
-                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
-            ],
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/comparative/overlay", {
+            params: query,
+            data: {
+                subjects: [
+                    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),
+                ],
+            }
         });
     },
 });
@@ -145,6 +166,7 @@ registerTool({
             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." },
+            format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude"],
         additionalProperties: false,
@@ -154,12 +176,15 @@ registerTool({
         const subjects = [
             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, args.transit_timezone));
         }
-        return await backendClient.post("/comparative/natal-transits", {
-            subjects,
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/comparative/natal-transits", {
+            params: query,
+            data: { subjects }
         });
     },
 });

package/dist/tools/specialized/returns.js

@@ -110,16 +110,19 @@ registerTool({
 registerTool({
     name: "ephemeris_planetary_return",
     description: "Calculate a planetary return — when any planet returns to its natal longitude. " +
-        "Useful for Jupiter returns (~12 years), Saturn returns (~29 years), etc.\n\n" +
+        "Useful for Jupiter returns (~12 years), Saturn returns (~29 years), Chiron returns (~50 years), " +
+        "Uranus returns (~84 years), etc.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Saturn return for birth 1990-04-15 near year 2019:\n" +
-        "  body='saturn', birth_datetime='1990-04-15T14:30:00', target_datetime='2019-01-01'",
+        "  body='saturn', birth_datetime='1990-04-15T14:30:00', target_datetime='2019-01-01'\n" +
+        "EXAMPLE: Chiron return for birth 1975-03-10 near age 50:\n" +
+        "  body='chiron', birth_datetime='1975-03-10T08:00:00', target_datetime='2025-01-01'",
     inputSchema: {
         type: "object",
         properties: {
             body: {
                 type: "string",
-                description: "Planet name: sun, moon, mercury, venus, mars, jupiter, saturn.",
+                description: "Planet name: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, chiron, pholus.",
             },
             birth_datetime: {
                 type: "string",

package/dist/tools/specialized/transits.js

@@ -8,6 +8,13 @@ registerTool({
         "finding optimal timing windows.\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" +
+        "ASPECT ANGLES: Use aspect_angle to search for specific aspects to natal positions:\n" +
+        "  0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine.\n" +
+        "  Example: Saturn Return → transiting_planets=['saturn'], natal_points=['saturn'], aspect_angle=0\n" +
+        "  Example: Uranus Opposition → transiting_planets=['uranus'], natal_points=['uranus'], aspect_angle=180\n" +
+        "  Example: Chiron Return → transiting_planets=['chiron'], natal_points=['chiron'], aspect_angle=0\n\n" +
+        "SUPPORTED BODIES: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, " +
+        "Pluto, Chiron, Pholus, Ceres, Pallas, Juno, Vesta, MeanNode.\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" +
@@ -38,13 +45,19 @@ registerTool({
             transiting_planets: {
                 type: "array",
                 items: { type: "string" },
-                description: "List of transiting planet IDs to search. E.g. ['saturn', 'jupiter', 'uranus', 'pluto']. " +
+                description: "List of transiting planet IDs to search. E.g. ['saturn', 'jupiter', 'uranus', 'pluto', 'chiron']. " +
                     "Omit to search all outer planets.",
             },
             natal_points: {
                 type: "array",
                 items: { type: "string" },
-                description: "Natal point IDs whose exact longitudes should be targeted. E.g. ['sun', 'moon', 'asc', 'mc']. Omit for all core points.",
+                description: "Natal point IDs whose exact longitudes should be targeted. E.g. ['sun', 'moon', 'asc', 'mc', 'saturn', 'chiron']. Omit for all core points.",
+            },
+            aspect_angle: {
+                type: "number",
+                description: "Aspect angle in degrees to apply to each natal longitude. 0 = conjunction/return (default), " +
+                    "180 = opposition, 90 = square, 120 = trine. The effective search target becomes " +
+                    "(natal_longitude + aspect_angle) mod 360.",
             },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
@@ -119,11 +132,21 @@ registerTool({
         };
         if (args.transiting_planets)
             transitBody.planet_names = args.transiting_planets;
+        // When aspect_angle is provided, apply offset to compute effective target degrees
+        // (natal_lon + aspect_angle) mod 360 for each natal point
+        let effectiveTargets = targetDegrees;
+        if (typeof args.aspect_angle === "number" && args.aspect_angle !== 0) {
+            effectiveTargets = targetDegrees.map((deg) => ((deg + args.aspect_angle) % 360 + 360) % 360);
+            transitBody.target_degrees = effectiveTargets;
+            // Also include aspect metadata for labeling in results
+            transitBody.search_criteria = { aspect_angle: args.aspect_angle };
+        }
         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,
+            target_degrees_used: effectiveTargets,
+            aspect_angle: args.aspect_angle ?? 0,
             transit_results: transitResult,
         };
     },

package/package.json

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