@openephemeris/mcp-server 3.2.12 → 3.3.0

package/dist/tools/specialized/acg.js

@@ -0,0 +1,143 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+const ACG_BODY_DESCRIPTION = "List of celestial bodies for line calculation. " +
+    "E.g. ['Sun', 'Moon', 'Venus', 'Mars', 'Jupiter', 'Saturn']. " +
+    "Aliases: 'NorthNode'/'Node'/'Rahu' → MeanNode, 'SouthNode'/'Ketu' → SouthNode. " +
+    "Omit to use all classical planets.";
+// POST /acg/power-lines — OE-018
+registerTool({
+    name: "acg_power_lines",
+    description: "Calculate Astrocartography power lines (MC, IC, AC/ASC, DC/DSC) for a natal chart. " +
+        "Returns GeoJSON LineStrings tracing each planetary angle line around the globe. " +
+        "These are the latitudinal lines where a planet was rising (AC), setting (DC), " +
+        "culminating (MC), or anti-culminating (IC) at birth.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
+        "EXAMPLE: Saturn and Jupiter power lines for a chart born 1990-04-15 in Chicago:\n" +
+        "  birth_datetime='1990-04-15T14:30:00', birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
+        "  bodies=['Saturn', 'Jupiter']",
+    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.",
+            },
+            bodies: {
+                type: "array",
+                items: { type: "string" },
+                description: ACG_BODY_DESCRIPTION,
+            },
+            query_latitude: {
+                type: "number",
+                description: "Filter lines near this latitude (optional, for hits mode).",
+            },
+            query_longitude: {
+                type: "number",
+                description: "Filter lines near this longitude (optional, for hits mode).",
+            },
+            radius_deg: {
+                type: "number",
+                description: "Search radius in degrees for hits filtering. Default 2°.",
+            },
+        },
+        required: ["birth_datetime", "birth_latitude", "birth_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude"]);
+        const body = {
+            natal: {
+                birthplace_lat: args.birth_latitude,
+                birthplace_lon: args.birth_longitude,
+            },
+            epoch: args.birth_datetime,
+        };
+        if (args.bodies)
+            body.bodies = args.bodies;
+        if (args.query_latitude != null)
+            body.query_lat = args.query_latitude;
+        if (args.query_longitude != null)
+            body.query_lon = args.query_longitude;
+        if (args.radius_deg != null)
+            body.radius_deg = args.radius_deg;
+        return await backendClient.post("/acg/power-lines", body);
+    },
+});
+// POST /acg/hits — OE-018
+registerTool({
+    name: "acg_hits",
+    description: "Find all Astrocartography lines (power lines + aspect lines) passing near a specific location. " +
+        "Returns features sorted by distance, making it easy to interpret planetary influences at a place.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
+        "EXAMPLE: All ACG lines within 3° of Paris for a chart born 1990-04-15 in Chicago:\n" +
+        "  birth_datetime='1990-04-15T14:30:00', birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
+        "  query_latitude=48.8566, query_longitude=2.3522, radius_deg=3",
+    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.",
+            },
+            query_latitude: {
+                type: "number",
+                description: "Latitude of the location to check for nearby lines.",
+            },
+            query_longitude: {
+                type: "number",
+                description: "Longitude of the location to check for nearby lines.",
+            },
+            radius_deg: {
+                type: "number",
+                description: "Search radius in degrees (default 2°, max 90°).",
+            },
+            bodies: {
+                type: "array",
+                items: { type: "string" },
+                description: ACG_BODY_DESCRIPTION,
+            },
+            include_aspects: {
+                type: "boolean",
+                description: "Include aspect lines in results (default true).",
+            },
+        },
+        required: ["birth_datetime", "birth_latitude", "birth_longitude", "query_latitude", "query_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "query_latitude", "query_longitude"]);
+        const body = {
+            natal: {
+                birthplace_lat: args.birth_latitude,
+                birthplace_lon: args.birth_longitude,
+            },
+            epoch: args.birth_datetime,
+            query_lat: args.query_latitude,
+            query_lon: args.query_longitude,
+        };
+        if (args.bodies)
+            body.bodies = args.bodies;
+        if (args.radius_deg != null)
+            body.radius_deg = args.radius_deg;
+        if (args.include_aspects != null) {
+            body.options = { include_aspects: args.include_aspects };
+        }
+        return await backendClient.post("/acg/hits", body);
+    },
+});

package/dist/tools/specialized/comparative.js

@@ -0,0 +1,153 @@
+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 /comparative/composite
+registerTool({
+    name: "ephemeris_composite",
+    description: "Calculate a composite chart from two or more natal charts. The composite " +
+        "uses midpoints of each planet pair to derive a single relationship chart.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
+        "EXAMPLE: Composite for two people:\n" +
+        "  person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.88, person_a_longitude=-87.63,\n" +
+        "  person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.05, person_b_longitude=-118.24",
+    inputSchema: {
+        type: "object",
+        properties: {
+            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
+            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_latitude: { type: "number", description: "Person B birth latitude." },
+            person_b_longitude: { type: "number", description: "Person B birth longitude." },
+        },
+        required: [
+            "person_a_datetime", "person_a_latitude", "person_a_longitude",
+            "person_b_datetime", "person_b_latitude", "person_b_longitude",
+        ],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, [
+            "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),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude),
+            ],
+        });
+    },
+});
+// POST /comparative/composite/midpoint
+registerTool({
+    name: "ephemeris_composite_midpoint",
+    description: "Calculate a midpoint composite chart — an alternative composite method " +
+        "using the midpoints of matching planet positions.\n\n" +
+        "CREDIT COST: 3 credits per call.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
+            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_latitude: { type: "number", description: "Person B birth latitude." },
+            person_b_longitude: { type: "number", description: "Person B birth longitude." },
+        },
+        required: [
+            "person_a_datetime", "person_a_latitude", "person_a_longitude",
+            "person_b_datetime", "person_b_latitude", "person_b_longitude",
+        ],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, [
+            "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),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude),
+            ],
+        });
+    },
+});
+// POST /comparative/overlay
+registerTool({
+    name: "ephemeris_overlay",
+    description: "Calculate an overlay chart — place one person's planets in another person's houses. " +
+        "Shows how person A's energies impact person B's life areas and vice versa.\n\n" +
+        "CREDIT COST: 3 credits per call.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
+            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_latitude: { type: "number", description: "Person B birth latitude." },
+            person_b_longitude: { type: "number", description: "Person B birth longitude." },
+        },
+        required: [
+            "person_a_datetime", "person_a_latitude", "person_a_longitude",
+            "person_b_datetime", "person_b_latitude", "person_b_longitude",
+        ],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, [
+            "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),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude),
+            ],
+        });
+    },
+});
+// POST /comparative/natal-transits
+registerTool({
+    name: "ephemeris_natal_transits",
+    description: "Calculate active transits to a natal chart — shows which current planets " +
+        "are aspecting natal positions. Essential for predictive astrology.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
+        "EXAMPLE: Current transits to someone born 1990-04-15:\n" +
+        "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.88, natal_longitude=-87.63",
+    inputSchema: {
+        type: "object",
+        properties: {
+            natal_datetime: { type: "string", description: "Natal birth datetime (ISO 8601)." },
+            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." },
+        },
+        required: ["natal_datetime", "natal_latitude", "natal_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude"]);
+        const subjects = [
+            buildSubject("Natal", args.natal_datetime, args.natal_latitude, args.natal_longitude),
+        ];
+        // 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));
+        }
+        return await backendClient.post("/comparative/natal-transits", {
+            subjects,
+        });
+    },
+});

package/dist/tools/specialized/eclipse.js

@@ -1,56 +1,50 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateRequired, validateCoordinates } from "../index.js";
 import { backendClient } from "../../backend/client.js";
 registerTool({
-    name: "ephemeris.next_eclipse",
-    description: "Find the next solar or lunar eclipse visible from a given location (or globally). " +
+    name: "ephemeris_next_eclipse",
+    description: "Find the next solar or lunar eclipse visible from a given location. " +
         "Returns the eclipse type, date/time of maximum, magnitude, duration of totality (if any), " +
-        "and local contact times if coordinates are provided.\n\n" +
+        "and local contact times.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Find the next solar eclipse visible from New York:\n" +
         "  eclipse_type='solar', latitude=40.7128, longitude=-74.006\n\n" +
-        "EXAMPLE: Find the next lunar eclipse globally:\n" +
-        "  eclipse_type='lunar'",
+        "EXAMPLE: Find the next lunar eclipse from London:\n" +
+        "  eclipse_type='lunar', latitude=51.5074, longitude=-0.1278",
     inputSchema: {
         type: "object",
         properties: {
             eclipse_type: {
                 type: "string",
-                enum: ["solar", "lunar"],
-                description: "Eclipse type to search for.",
+                enum: ["solar", "lunar", "any"],
+                description: "Eclipse type to search for. Use 'any' for whichever comes first.",
             },
             latitude: {
                 type: "number",
-                description: "Observer latitude in decimal degrees. If provided, returns local visibility and contact times.",
+                description: "Observer latitude in decimal degrees (required). Returns local visibility and contact times.",
             },
             longitude: {
                 type: "number",
-                description: "Observer longitude in decimal degrees.",
+                description: "Observer longitude in decimal degrees (required).",
             },
             after_date: {
                 type: "string",
                 description: "ISO 8601 date to search after (e.g. '2026-01-01'). Defaults to today if omitted.",
             },
         },
-        required: ["eclipse_type"],
+        required: ["eclipse_type", "latitude", "longitude"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        const params = {};
-        if (args.latitude != null)
-            params.latitude = args.latitude;
-        if (args.longitude != null)
-            params.longitude = args.longitude;
+        validateRequired(args, ["eclipse_type", "latitude", "longitude"]);
+        validateCoordinates(args, "latitude", "longitude");
+        const params = {
+            lat: args.latitude,
+            lon: args.longitude,
+        };
         if (args.after_date)
             params.date = args.after_date;
-        if (args.eclipse_type === "solar") {
-            // Use local endpoint if coordinates provided, otherwise global
-            if (args.latitude != null && args.longitude != null) {
-                return await backendClient.request("GET", "/eclipse/solar/local", { params, timeoutMs: 60_000 });
-            }
-            return await backendClient.request("GET", "/eclipse/solar/global", { params, timeoutMs: 60_000 });
-        }
-        else {
-            return await backendClient.request("GET", "/eclipse/lunar/global", { params, timeoutMs: 60_000 });
-        }
+        if (args.eclipse_type && args.eclipse_type !== "any")
+            params.type = args.eclipse_type;
+        return await backendClient.request("GET", "/eclipse/next-visible", { params, timeoutMs: 60_000 });
     },
 });

package/dist/tools/specialized/electional.js

@@ -1,7 +1,9 @@
-import { registerTool } from "../index.js";
+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",
+    name: "ephemeris_electional",
     description: "Find optimal planetary timing windows (electional astrology). Scans a date range to find the " +
         "best times for an event based on essential dignity, aspect quality, sect, and void-of-course " +
         "moon penalties. Evaluates every hour and clusters the best continuous windows.\n\n" +
@@ -48,13 +50,14 @@ registerTool({
             format: {
                 type: "string",
                 enum: ["json", "llm"],
-                description: "Output format. 'llm' = compact token-efficient output (Startup tier).",
+                description: "Output format. 'llm' = compact token-efficient output (available on all tiers).",
             },
         },
         required: ["start_date", "end_date", "latitude", "longitude"],
         additionalProperties: false,
     },
     handler: async (args) => {
+        validateRequired(args, ["start_date", "end_date", "latitude", "longitude"]);
         const query = {
             start_date: args.start_date,
             end_date: args.end_date,
@@ -77,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.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);
+    },
+});