@openephemeris/mcp-server 3.2.13 → 3.3.1

package/dist/tools/specialized/progressed.js

@@ -0,0 +1,65 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris_progressed_chart",
+    description: "Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart. " +
+        "Advances the natal chart symbolically — 1 day = 1 year (secondary), or using solar arc motion. " +
+        "Returns progressed planet positions, house cusps, aspects, and retrograde status.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Secondary progressions for someone born 1985-06-21, progressed to 2026-01-01:\n" +
+        "  birth_datetime='1985-06-21T14:00:00', birth_latitude=51.5, birth_longitude=-0.12,\n" +
+        "  target_datetime='2026-01-01', method='secondary'",
+    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.",
+            },
+            target_datetime: {
+                type: "string",
+                description: "Target date to progress the chart to (ISO 8601).",
+            },
+            method: {
+                type: "string",
+                enum: ["secondary", "solar_arc", "tertiary"],
+                description: "Progression method. Defaults to 'secondary' (1 day = 1 year).",
+            },
+            include_aspects: {
+                type: "boolean",
+                description: "Whether to include aspect grid in the response. Default false.",
+            },
+        },
+        required: ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"]);
+        const body = {
+            subject: {
+                name: "Progressed Subject",
+                birth_datetime: { iso: args.birth_datetime },
+                birth_location: {
+                    latitude: { decimal: args.birth_latitude },
+                    longitude: { decimal: args.birth_longitude },
+                },
+            },
+            target_datetime: { iso: args.target_datetime },
+        };
+        if (args.method) {
+            body.progression_options = { method: args.method };
+        }
+        if (args.include_aspects != null) {
+            body.options = { include_aspects: args.include_aspects };
+        }
+        return await backendClient.post("/ephemeris/progressed", body);
+    },
+});

package/dist/tools/specialized/returns.js

@@ -7,8 +7,7 @@ registerTool({
         "Used to cast the Solar Return chart for the year ahead.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Solar return for someone born 1985-06-21 near their 2026 birthday:\n" +
-        "  birth_datetime='1985-06-21T14:00:00', birth_latitude=51.5, birth_longitude=-0.12,\n" +
-        "  target_datetime='2026-06-01'",
+        "  birth_datetime='1985-06-21T14:00:00', target_datetime='2026-06-01'",
     inputSchema: {
         type: "object",
         properties: {
@@ -16,48 +15,46 @@ registerTool({
                 type: "string",
                 description: "ISO 8601 birth date/time (e.g. '1985-06-21T14:00:00').",
             },
+            target_datetime: {
+                type: "string",
+                description: "Date/time near which to find the Solar Return (ISO 8601). Required.",
+            },
             birth_latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees.",
+                description: "Birth latitude in decimal degrees (optional, for location context).",
             },
             birth_longitude: {
                 type: "number",
-                description: "Birth longitude in decimal degrees.",
-            },
-            target_datetime: {
-                type: "string",
-                description: "Date near which to find the Solar Return (ISO 8601). Defaults to now.",
+                description: "Birth longitude in decimal degrees (optional, for location context).",
             },
             return_latitude: {
                 type: "number",
-                description: "Location latitude for the return chart (optional). Defaults to birth location.",
+                description: "Location latitude for the return chart (optional).",
             },
             return_longitude: {
                 type: "number",
-                description: "Location longitude for the return chart (optional). Defaults to birth location.",
+                description: "Location longitude for the return chart (optional).",
             },
         },
-        required: ["birth_datetime", "birth_latitude", "birth_longitude"],
+        required: ["birth_datetime", "target_datetime"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude"]);
+        validateRequired(args, ["birth_datetime", "target_datetime"]);
         const body = {
-            birth_datetime: {
-                iso: args.birth_datetime,
-            },
-            birth_location: {
+            birth_datetime: { iso: args.birth_datetime },
+            target_datetime: { iso: args.target_datetime },
+        };
+        if (args.birth_latitude != null && args.birth_longitude != null) {
+            body.location = {
                 latitude: { decimal: args.birth_latitude },
                 longitude: { decimal: args.birth_longitude },
-            },
-        };
-        if (args.target_datetime) {
-            body.target_datetime = { iso: args.target_datetime };
+            };
         }
         if (args.return_latitude != null && args.return_longitude != null) {
             body.return_location = {
-                latitude: args.return_latitude,
-                longitude: args.return_longitude,
+                latitude: { decimal: args.return_latitude },
+                longitude: { decimal: args.return_longitude },
             };
         }
         return await backendClient.post("/predictive/returns/solar", body);
@@ -70,8 +67,7 @@ registerTool({
         "Used to cast the monthly Lunar Return chart.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Next lunar return after 2026-03-15 for someone born 1990-04-15:\n" +
-        "  birth_datetime='1990-04-15T14:30:00', birth_latitude=41.88, birth_longitude=-87.63,\n" +
-        "  target_datetime='2026-03-15'",
+        "  birth_datetime='1990-04-15T14:30:00', target_datetime='2026-03-15'",
     inputSchema: {
         type: "object",
         properties: {
@@ -79,48 +75,70 @@ registerTool({
                 type: "string",
                 description: "ISO 8601 birth date/time.",
             },
-            birth_latitude: {
-                type: "number",
-                description: "Birth latitude in decimal degrees.",
-            },
-            birth_longitude: {
-                type: "number",
-                description: "Birth longitude in decimal degrees.",
-            },
             target_datetime: {
                 type: "string",
-                description: "Date near which to find the Lunar Return (ISO 8601). Defaults to now.",
+                description: "Date/time near which to find the Lunar Return (ISO 8601). Required.",
             },
-            return_latitude: {
+            birth_latitude: {
                 type: "number",
-                description: "Location latitude for return chart (optional). Defaults to birth location.",
+                description: "Birth latitude in decimal degrees (optional).",
             },
-            return_longitude: {
+            birth_longitude: {
                 type: "number",
-                description: "Location longitude for return chart (optional). Defaults to birth location.",
+                description: "Birth longitude in decimal degrees (optional).",
             },
         },
-        required: ["birth_datetime", "birth_latitude", "birth_longitude"],
+        required: ["birth_datetime", "target_datetime"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude"]);
+        validateRequired(args, ["birth_datetime", "target_datetime"]);
         const body = {
             birth_datetime: { iso: args.birth_datetime },
-            birth_location: {
+            target_datetime: { iso: args.target_datetime },
+        };
+        if (args.birth_latitude != null && args.birth_longitude != null) {
+            body.location = {
                 latitude: { decimal: args.birth_latitude },
                 longitude: { decimal: args.birth_longitude },
-            },
-        };
-        if (args.target_datetime) {
-            body.target_datetime = { iso: args.target_datetime };
-        }
-        if (args.return_latitude != null && args.return_longitude != null) {
-            body.return_location = {
-                latitude: args.return_latitude,
-                longitude: args.return_longitude,
             };
         }
         return await backendClient.post("/predictive/returns/lunar", body);
     },
 });
+// POST /predictive/returns (generic planetary return)
+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" +
+        "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'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            body: {
+                type: "string",
+                description: "Planet name: sun, moon, mercury, venus, mars, jupiter, saturn.",
+            },
+            birth_datetime: {
+                type: "string",
+                description: "ISO 8601 birth date/time.",
+            },
+            target_datetime: {
+                type: "string",
+                description: "Date/time near which to find the return (ISO 8601). Required.",
+            },
+        },
+        required: ["body", "birth_datetime", "target_datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["body", "birth_datetime", "target_datetime"]);
+        return await backendClient.post("/predictive/returns", {
+            body: args.body,
+            birth_datetime: { iso: args.birth_datetime },
+            target_datetime: { iso: args.target_datetime },
+        });
+    },
+});

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

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

package/dist/tools/specialized/venus_star_points.js

@@ -0,0 +1,187 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+function buildSubject(datetime, lat, lon) {
+    return {
+        name: "Subject",
+        birth_datetime: { iso: datetime },
+        birth_location: {
+            latitude: { decimal: lat },
+            longitude: { decimal: lon },
+        },
+    };
+}
+// POST /ephemeris/venus-star-points
+registerTool({
+    name: "venus_star_points",
+    description: "Get Venus Star Points — the Sun-Venus conjunction events nearest to a birth date. " +
+        "Shows the quality of each conjunction (cazimi, combust, under beams) with zodiac details.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Venus star points for someone born 1990-04-15:\n" +
+        "  datetime='1990-04-15T14:30:00', latitude=41.88, longitude=-87.63",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: { type: "string", description: "Birth datetime (ISO 8601)." },
+            latitude: { type: "number", description: "Birth latitude." },
+            longitude: { type: "number", description: "Birth longitude." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points", {
+            data: { subject: buildSubject(args.datetime, args.latitude, args.longitude) },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/conjunctions
+registerTool({
+    name: "venus_star_points_conjunctions",
+    description: "Find all Sun-Venus conjunctions in a date range. Returns each conjunction with " +
+        "its exact timestamp, zodiac position, orb, visibility (morning/evening star), and dignity.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Find Venus conjunctions in 2026:\n" +
+        "  start_date='2026-01-01', end_date='2026-12-31'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: { type: "string", description: "Start date (ISO 8601)." },
+            end_date: { type: "string", description: "End date (ISO 8601)." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["start_date", "end_date"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["start_date", "end_date"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points/conjunctions", {
+            data: { start_date: args.start_date, end_date: args.end_date },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/eight-year-star
+registerTool({
+    name: "venus_eight_year_star",
+    description: "Compute the 8-year Venus Star pattern — the pentagram of 5 Venus-Sun conjunctions " +
+        "that trace a near-perfect star over 8 years (the Venus synodic cycle). Returns the 5 " +
+        "vertices with their zodiac positions.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: 8-year star starting from 2020:\n" +
+        "  date='2020-01-01'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            date: { type: "string", description: "Start date for the 8-year cycle (ISO 8601)." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["date"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["date"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points/eight-year-star", {
+            data: { date: args.date },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/phase
+registerTool({
+    name: "venus_phase",
+    description: "Get the current Venus phase — morning star, evening star, or combust. Returns Venus " +
+        "longitude, Sun longitude, elongation, retrograde/cazimi status.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Venus phase right now:\n" +
+        "  date='2026-03-20'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            date: { type: "string", description: "Date to check (ISO 8601). Defaults to now." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["date"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["date"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points/phase", {
+            data: { date: args.date },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/elongations
+registerTool({
+    name: "venus_elongations",
+    description: "Find Venus greatest elongation events (when Venus is farthest from the Sun in the sky). " +
+        "Returns east (evening star) and west (morning star) elongation peaks.\n\n" +
+        "CREDIT COST: 2 credits per call.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: { type: "string", description: "Start date (ISO 8601)." },
+            end_date: { type: "string", description: "End date (ISO 8601)." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["start_date", "end_date"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["start_date", "end_date"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points/elongations", {
+            data: { start_date: args.start_date, end_date: args.end_date },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/stations
+registerTool({
+    name: "venus_stations",
+    description: "Find Venus retrograde and direct stations in a date range. Returns the exact " +
+        "moment Venus appears to stop and reverse direction.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Venus stations in 2026:\n" +
+        "  start_date='2026-01-01', end_date='2026-12-31'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: { type: "string", description: "Start date (ISO 8601)." },
+            end_date: { type: "string", description: "End date (ISO 8601). Defaults to +1 year." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["start_date"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["start_date"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points/stations", {
+            data: {
+                start_date: args.start_date,
+                end_date: args.end_date || "",
+            },
+            params: query,
+        });
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.2.13",
+  "version": "3.3.1",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "dev": "tsx watch src/index.ts",
     "dev:sse": "tsx watch src/server-sse.ts",
     "start": "node dist/index.js",
-    "start:sse": "node dist/src/server-sse.js",
+    "start:sse": "node dist/server-sse.js",
     "test": "vitest run --exclude \"dist/**\"",
     "test:watch": "vitest --exclude \"dist/**\"",
     "test:integration": "tsx scripts/test-client.ts",