@openephemeris/mcp-server 3.2.13 → 3.3.0

package/dist/tools/specialized/ephemeris_extended.js

@@ -0,0 +1,234 @@
+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 /ephemeris/natal/batch — OE-028
+registerTool({
+    name: "ephemeris_natal_batch",
+    description: "Calculate natal charts for multiple subjects in a single request. " +
+        "Supports up to 100 subjects. Returns enhanced natal chart data for each.\n\n" +
+        "CREDIT COST: 1 credit per subject.\n\n" +
+        "EXAMPLE: Two people batch:\n" +
+        "  subjects: [\n" +
+        "    { name: 'Alice', datetime: '1990-04-15T14:30:00', latitude: 41.88, longitude: -87.63 },\n" +
+        "    { name: 'Bob', datetime: '1988-09-22T08:15:00', latitude: 34.05, longitude: -118.24 }\n" +
+        "  ]",
+    inputSchema: {
+        type: "object",
+        properties: {
+            subjects: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Subject name." },
+                        datetime: { type: "string", description: "Birth datetime (ISO 8601)." },
+                        latitude: { type: "number", description: "Birth latitude." },
+                        longitude: { type: "number", description: "Birth longitude." },
+                    },
+                    required: ["name", "datetime", "latitude", "longitude"],
+                },
+                description: "Array of subjects (1-100).",
+            },
+        },
+        required: ["subjects"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["subjects"]);
+        const items = args.subjects.map((s) => ({
+            subject: buildSubject(s.name, s.datetime, s.latitude, s.longitude),
+        }));
+        return await backendClient.post("/ephemeris/natal/batch", { items });
+    },
+});
+// POST /ephemeris/dignities
+registerTool({
+    name: "ephemeris_dignities",
+    description: "Calculate essential dignities (domicile, exaltation, detriment, fall, peregrine) " +
+        "for all planets at a given date/time. Essential for traditional astrology.\n\n" +
+        "CREDIT COST: 1 credit per call.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: { type: "string", description: "ISO 8601 date/time." },
+        },
+        required: ["datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime"]);
+        return await backendClient.post("/ephemeris/dignities", {
+            date_time: { iso: args.datetime },
+        });
+    },
+});
+// POST /ephemeris/retrograde-status
+registerTool({
+    name: "ephemeris_retrograde_status",
+    description: "Get retrograde/direct status and speed for all planets at a given date/time. " +
+        "Returns is_retrograde flag, longitude speed, and station proximity.\n\n" +
+        "CREDIT COST: 1 credit per call.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: { type: "string", description: "ISO 8601 date/time." },
+            planet_id: { type: "integer", description: "Optional single planet ID (0-9). Omit for all planets." },
+        },
+        required: ["datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime"]);
+        const body = {
+            date_time: { iso: args.datetime },
+        };
+        if (args.planet_id != null)
+            body.planet_id = args.planet_id;
+        return await backendClient.post("/ephemeris/retrograde-status", body);
+    },
+});
+// POST /ephemeris/midpoints
+registerTool({
+    name: "ephemeris_midpoints",
+    description: "Calculate midpoints between all planet pairs for a given date/time and location. " +
+        "Returns midpoint longitude, the two planets involved, and any planet at the midpoint.\n\n" +
+        "CREDIT COST: 1 credit per call.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: { type: "string", description: "ISO 8601 date/time." },
+            latitude: { type: "number", description: "Observer latitude." },
+            longitude: { type: "number", description: "Observer longitude." },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        return await backendClient.post("/ephemeris/midpoints", {
+            date_time: { iso: args.datetime },
+            latitude: args.latitude,
+            longitude: args.longitude,
+        });
+    },
+});
+// POST /ephemeris/fixed-stars
+registerTool({
+    name: "ephemeris_fixed_stars",
+    description: "Calculate positions of fixed stars and conjunctions to natal planets. " +
+        "Returns star longitude, magnitude, and any planets within orb.\n\n" +
+        "CREDIT COST: 1 credit per call.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: { type: "string", description: "ISO 8601 date/time." },
+            star_names: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional list of star names (e.g. ['Regulus', 'Spica']). Omit for default list.",
+            },
+            orb: { type: "number", description: "Conjunction orb in degrees. Default 1°." },
+        },
+        required: ["datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime"]);
+        const body = {
+            date_time: { iso: args.datetime },
+        };
+        if (args.star_names)
+            body.star_names = args.star_names;
+        if (args.orb != null)
+            body.orb = args.orb;
+        return await backendClient.post("/ephemeris/fixed-stars", body);
+    },
+});
+// POST /ephemeris/hermetic-lots
+registerTool({
+    name: "ephemeris_hermetic_lots",
+    description: "Calculate Arabic Parts / Hermetic Lots (Lot of Fortune, Spirit, etc.) " +
+        "for a given chart.\n\n" +
+        "CREDIT COST: 1 credit per call.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: { type: "string", description: "ISO 8601 date/time." },
+            latitude: { type: "number", description: "Observer latitude." },
+            longitude: { type: "number", description: "Observer longitude." },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        return await backendClient.post("/ephemeris/hermetic-lots", {
+            date_time: { iso: args.datetime },
+            latitude: args.latitude,
+            longitude: args.longitude,
+        });
+    },
+});
+// POST /ephemeris/angles-points
+registerTool({
+    name: "ephemeris_angles_points",
+    description: "Calculate chart angles and sensitive points (ASC, MC, DSC, IC, Vertex, " +
+        "East Point, etc.) for a given date/time and location.\n\n" +
+        "CREDIT COST: 1 credit per call.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: { type: "string", description: "ISO 8601 date/time." },
+            latitude: { type: "number", description: "Observer latitude." },
+            longitude: { type: "number", description: "Observer longitude." },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        return await backendClient.post("/ephemeris/angles-points", {
+            date_time: { iso: args.datetime },
+            latitude: args.latitude,
+            longitude: args.longitude,
+        });
+    },
+});
+// POST /ephemeris/aspect-check
+registerTool({
+    name: "ephemeris_aspect_check",
+    description: "Check the aspect between two ecliptic longitudes. Returns the angular separation " +
+        "and any aspects within orb (conjunction, sextile, square, trine, opposition, etc.).\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Check aspect between 15° Aries and 75° Gemini:\n" +
+        "  longitude_1=15, longitude_2=75",
+    inputSchema: {
+        type: "object",
+        properties: {
+            longitude_1: { type: "number", description: "First ecliptic longitude (0-360)." },
+            longitude_2: { type: "number", description: "Second ecliptic longitude (0-360)." },
+            max_orb: { type: "number", description: "Maximum orb in degrees. Default 8°." },
+        },
+        required: ["longitude_1", "longitude_2"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["longitude_1", "longitude_2"]);
+        const body = {
+            longitude_1: args.longitude_1,
+            longitude_2: args.longitude_2,
+        };
+        if (args.max_orb != null)
+            body.max_orb = args.max_orb;
+        return await backendClient.post("/ephemeris/aspect-check", body);
+    },
+});

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

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

package/dist/tools/specialized/hd_group.js

@@ -0,0 +1,107 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+// POST /human-design/composite — OE-027
+registerTool({
+    name: "human_design_composite",
+    description: "Calculate a Human Design composite chart for two people. Merges both bodygraphs " +
+        "to show shared channels, authority dynamics, and relationship type.\n\n" +
+        "CREDIT COST: 4 credits per call.\n\n" +
+        "EXAMPLE:\n" +
+        "  person_a_datetime='1990-04-15T14:30:00Z', person_b_datetime='1988-09-22T08:15:00Z'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            person_a_datetime: {
+                type: "string",
+                description: "Person A birth datetime as ISO 8601 UTC (e.g. '1990-04-15T14:30:00Z').",
+            },
+            person_b_datetime: {
+                type: "string",
+                description: "Person B birth datetime as ISO 8601 UTC.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' is compact.",
+            },
+        },
+        required: ["person_a_datetime", "person_b_datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["person_a_datetime", "person_b_datetime"]);
+        const body = {
+            subject_1: {
+                birth_datetime_utc: args.person_a_datetime,
+            },
+            subject_2: {
+                birth_datetime_utc: args.person_b_datetime,
+            },
+        };
+        if (args.format)
+            body.format = args.format;
+        return await backendClient.post("/human-design/composite", body);
+    },
+});
+// POST /human-design/penta — OE-027
+registerTool({
+    name: "human_design_penta",
+    description: "Calculate a Human Design Penta (group) chart for 3-5 people. Shows functional " +
+        "attributes, leadership dynamics, channels, redundancies, and a group stability score.\n\n" +
+        "CREDIT COST: 6 credits per call.\n\n" +
+        "EXAMPLE (3 people):\n" +
+        "  group_name='Team Alpha',\n" +
+        "  members=[\n" +
+        "    {id: 'alice', name: 'Alice', datetime: '1990-04-15T14:30:00Z'},\n" +
+        "    {id: 'bob',   name: 'Bob',   datetime: '1988-09-22T08:15:00Z'},\n" +
+        "    {id: 'carol', name: 'Carol', datetime: '1995-01-10T11:00:00Z'}\n" +
+        "  ]",
+    inputSchema: {
+        type: "object",
+        properties: {
+            group_name: {
+                type: "string",
+                description: "Name of the group.",
+            },
+            members: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Unique member ID." },
+                        name: { type: "string", description: "Member's name." },
+                        datetime: { type: "string", description: "Birth datetime as ISO 8601 UTC." },
+                    },
+                    required: ["id", "name", "datetime"],
+                },
+                description: "Array of 3-5 members with id, name, and datetime.",
+                minItems: 3,
+                maxItems: 5,
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format.",
+            },
+        },
+        required: ["group_name", "members"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["group_name", "members"]);
+        const members = args.members.map((m) => ({
+            id: m.id,
+            name: m.name,
+            birth_data: {
+                birth_datetime_utc: m.datetime,
+            },
+        }));
+        const body = {
+            group_name: args.group_name,
+            members,
+        };
+        if (args.format)
+            body.format = args.format;
+        return await backendClient.post("/human-design/penta", body);
+    },
+});

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

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

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 {};