@openephemeris/mcp-server 3.2.13 → 3.3.1

package/dist/tools/specialized/electional.js

@@ -1,5 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
+// All electional endpoints are GET endpoints with query params.
+// GET /electional/find-window — already existed, keeping it
 registerTool({
     name: "ephemeris_electional",
     description: "Find optimal planetary timing windows (electional astrology). Scans a date range to find the " +
@@ -78,3 +80,179 @@ registerTool({
         });
     },
 });
+// GET /electional/moment-analysis
+registerTool({
+    name: "electional_moment_analysis",
+    description: "Analyze the astrological quality of a specific moment: planet positions, aspects, " +
+        "void of course status, lunar phase, day ruler, and an overall electional score (0-100). " +
+        "Perfect for evaluating whether 'right now' or a specific date/time is good for action.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Analyze March 21, 2026 at noon:\n" +
+        "  date='2026-03-21T12:00:00'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            date: {
+                type: "string",
+                description: "ISO 8601 datetime to analyze (e.g., '2026-03-21T12:00:00'). Defaults to now.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format.",
+            },
+        },
+        required: [],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const query = {};
+        if (args.date)
+            query.date = args.date;
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("GET", "/electional/moment-analysis", {
+            data: {},
+            params: query,
+        });
+    },
+});
+// GET /electional/station-tracker
+registerTool({
+    name: "electional_station_tracker",
+    description: "Find all upcoming retrograde and direct stations for planets in a date range. " +
+        "Returns exact station times, longitudes, and signs. Essential for timing around " +
+        "Mercury retrograde, Venus retrograde, etc.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
+        "EXAMPLE: Stations in the next 3 months:\n" +
+        "  start_date='2026-03-01', end_date='2026-06-01'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: {
+                type: "string",
+                description: "Start date (ISO 8601). Defaults to now.",
+            },
+            end_date: {
+                type: "string",
+                description: "End date (ISO 8601). Defaults to +90 days.",
+            },
+            planets: {
+                type: "string",
+                description: "Comma-separated planet IDs (e.g., '2,3,4'). Defaults to Mercury-Saturn.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format.",
+            },
+        },
+        required: [],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const query = {};
+        if (args.start_date)
+            query.start_date = args.start_date;
+        if (args.end_date)
+            query.end_date = args.end_date;
+        if (args.planets)
+            query.planets = args.planets;
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("GET", "/electional/station-tracker", {
+            data: {},
+            params: query,
+        });
+    },
+});
+// GET /electional/ingress-calendar
+registerTool({
+    name: "electional_ingress_calendar",
+    description: "Get a calendar of sign ingresses — when planets change zodiac signs. " +
+        "Returns each ingress event with exact time, from/to signs, and retrograde flag.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
+        "EXAMPLE: Ingresses in March 2026:\n" +
+        "  start_date='2026-03-01', end_date='2026-03-31'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: {
+                type: "string",
+                description: "Start date (ISO 8601). Defaults to now.",
+            },
+            end_date: {
+                type: "string",
+                description: "End date (ISO 8601). Defaults to +30 days.",
+            },
+            planets: {
+                type: "string",
+                description: "Comma-separated planet IDs. Defaults to all major planets.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format.",
+            },
+        },
+        required: [],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const query = {};
+        if (args.start_date)
+            query.start_date = args.start_date;
+        if (args.end_date)
+            query.end_date = args.end_date;
+        if (args.planets)
+            query.planets = args.planets;
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("GET", "/electional/ingress-calendar", {
+            data: {},
+            params: query,
+        });
+    },
+});
+// GET /electional/aspect-search
+registerTool({
+    name: "electional_aspect_search",
+    description: "Find all active aspects between planets at a specific moment. Returns aspect type, " +
+        "orb, quality score, and whether it's applying or separating. Great for checking " +
+        "the 'weather' of a given day.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: What aspects are active on March 21, 2026?\n" +
+        "  date='2026-03-21T12:00:00'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            date: {
+                type: "string",
+                description: "ISO 8601 datetime to check. Defaults to now.",
+            },
+            max_orb: {
+                type: "number",
+                description: "Maximum orb in degrees. Default uses standard orbs per aspect type.",
+            },
+            aspects: {
+                type: "string",
+                description: "Comma-separated aspect types to filter (e.g., 'conjunction,trine,square'). Default all.",
+            },
+        },
+        required: [],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const query = {};
+        if (args.date)
+            query.date = args.date;
+        if (args.max_orb != null)
+            query.max_orb = args.max_orb;
+        if (args.aspects)
+            query.aspects = args.aspects;
+        return await backendClient.request("GET", "/electional/aspect-search", {
+            data: {},
+            params: query,
+        });
+    },
+});

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

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

package/dist/tools/specialized/ephemeris_core.js

@@ -0,0 +1,93 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+// POST /ephemeris/planet-position — OE-016
+registerTool({
+    name: "ephemeris_planet_position",
+    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" +
+        "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'",
+    inputSchema: {
+        type: "object",
+        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).",
+            },
+            datetime: {
+                type: "string",
+                description: "ISO 8601 date/time (e.g. '2026-03-20T12:00:00Z').",
+            },
+            latitude: {
+                type: "number",
+                description: "Observer latitude for topocentric position (optional). Omit for geocentric.",
+            },
+            longitude: {
+                type: "number",
+                description: "Observer longitude for topocentric position (optional). Omit for geocentric.",
+            },
+        },
+        required: ["planet_id", "datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["planet_id", "datetime"]);
+        const body = {
+            planet_id: args.planet_id,
+            date_time: { iso: args.datetime },
+        };
+        if (args.latitude != null)
+            body.latitude = args.latitude;
+        if (args.longitude != null)
+            body.longitude = args.longitude;
+        return await backendClient.post("/ephemeris/planet-position", body);
+    },
+});
+// POST /ephemeris/house-cusps — OE-017
+registerTool({
+    name: "ephemeris_house_cusps",
+    description: "Calculate house cusps and angles (ASC, MC, DSC, IC) for a given date, time, and location " +
+        "using one or more house systems.\n\n" +
+        "House system codes: P=Placidus, K=Koch, O=Porphyry, R=Regiomontanus, C=Campanus, E=Equal, W=Whole Sign.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Placidus houses for London at 2026-03-20 noon UTC:\n" +
+        "  datetime='2026-03-20T12:00:00Z', latitude=51.5074, longitude=-0.1278, house_systems=['P']",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: "ISO 8601 date/time.",
+            },
+            latitude: {
+                type: "number",
+                description: "Observer latitude in decimal degrees.",
+            },
+            longitude: {
+                type: "number",
+                description: "Observer longitude in decimal degrees.",
+            },
+            house_systems: {
+                type: "array",
+                items: { type: "string" },
+                description: "List of house system codes. E.g. ['P', 'W']. Defaults to ['P'] (Placidus).",
+            },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        const body = {
+            date_time: { iso: args.datetime },
+            latitude: args.latitude,
+            longitude: args.longitude,
+        };
+        if (args.house_systems)
+            body.house_systems = args.house_systems;
+        return await backendClient.post("/ephemeris/house-cusps", body);
+    },
+});

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

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

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