@openephemeris/mcp-server 3.2.11 → 3.2.13

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,7 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
 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 +48,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,

package/dist/tools/specialized/human_design.js

@@ -1,22 +1,35 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
+/**
+ * Ensure a datetime string has a timezone offset for Go's time.Time parsing.
+ * Go's encoding/json only accepts RFC 3339 (must have Z or +HH:MM offset).
+ */
+function ensureTimezone(dt) {
+    if (!dt)
+        return dt;
+    // Already has timezone indicator
+    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt) || /[+-]\d{4}$/.test(dt))
+        return dt;
+    return dt + "Z";
+}
 registerTool({
-    name: "human_design.chart",
-    description: "Calculate a full Human Design bodygraph chart from birth data. Returns the person's Type " +
+    name: "human_design_chart",
+    description: "Calculate a full Human Design I Ching hexagram chart from birth data. Returns the person's Type " +
         "(Generator, Manifesting Generator, Projector, Manifestor, Reflector), Strategy, Authority, " +
         "Profile (e.g. 1/3, 2/4), defined and undefined Centers, activated Gates and Channels, " +
         "Incarnation Cross, and both Personality (conscious) and Design (unconscious) planetary positions.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion " +
         "before birth (~3 months prior, the Design calculation). The API handles this automatically.\n\n" +
-        "EXAMPLE: Get the Human Design chart for someone born April 15, 1990 at 2:30 PM in Chicago:\n" +
-        "  datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298",
+        "IMPORTANT: The datetime should be in UTC. If you have local birth time, convert to UTC first.\n\n" +
+        "EXAMPLE: Get the Human Design chart for someone born April 15, 1990 at 7:30 PM UTC:\n" +
+        "  datetime='1990-04-15T19:30:00Z', latitude=41.8781, longitude=-87.6298",
     inputSchema: {
         type: "object",
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime (local time at birth location), e.g. '1990-04-15T14:30:00'.",
+                description: "ISO 8601 birth datetime in UTC, e.g. '1990-04-15T19:30:00Z'. Must include 'Z' or timezone offset.",
             },
             latitude: {
                 type: "number",
@@ -29,19 +42,22 @@ registerTool({
             format: {
                 type: "string",
                 enum: ["json", "llm"],
-                description: "Output format. 'llm' returns compact array projection for token efficiency (Pro tier). " +
+                description: "Output format. 'llm' returns compact array projection for token efficiency (available on all tiers). " +
                     "'json' returns verbose full output.",
             },
         },
-        required: ["datetime", "latitude", "longitude"],
+        required: ["datetime"],
         additionalProperties: false,
     },
     handler: async (args) => {
+        validateRequired(args, ["datetime"]);
         const body = {
-            datetime: args.datetime,
-            latitude: args.latitude,
-            longitude: args.longitude,
+            birth_datetime_utc: ensureTimezone(args.datetime),
         };
+        if (args.latitude != null)
+            body.latitude = args.latitude;
+        if (args.longitude != null)
+            body.longitude = args.longitude;
         const query = {};
         if (args.format)
             query.format = args.format;

package/dist/tools/specialized/moon.js

@@ -1,7 +1,7 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateCoordinates } from "../index.js";
 import { backendClient } from "../../backend/client.js";
 registerTool({
-    name: "ephemeris.moon_phase",
+    name: "ephemeris_moon_phase",
     description: "Get the current Moon phase and void-of-course status. Returns the Moon's sign, phase name " +
         "(New, Waxing Crescent, First Quarter, Waxing Gibbous, Full, Waning Gibbous, Last Quarter, " +
         "Waning Crescent), exact phase angle, illumination percentage, and the next void-of-course period.\n\n" +
@@ -31,6 +31,7 @@ registerTool({
         additionalProperties: false,
     },
     handler: async (args) => {
+        validateCoordinates(args, "latitude", "longitude");
         const params = {};
         if (args.datetime)
             params.datetime = args.datetime;

package/dist/tools/specialized/natal.js

@@ -1,12 +1,18 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
 const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
     "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
+/** Map human-readable house system names to Swiss Ephemeris single-letter codes */
+const HOUSE_SYSTEM_MAP = {
+    placidus: "P", whole_sign: "W", equal: "E", koch: "K",
+    campanus: "C", regiomontanus: "R", porphyry: "O",
+    alcabitius: "B", morinus: "M",
+};
 registerTool({
-    name: "ephemeris.natal_chart",
+    name: "ephemeris_natal_chart",
     description: "Calculate a full natal (birth) chart for a person. Returns planetary positions, house cusps, " +
         "aspects, and chart patterns. Use format='llm' for a compact, token-efficient output ideal for " +
-        "interpretation (requires Pro tier). The result includes all major planets, angles (ASC/MC/DSC/IC), " +
+        "interpretation (available on all tiers). The result includes all major planets, angles (ASC/MC/DSC/IC), " +
         "essential dignities, retrograde status, house system data, and major aspect grid.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Calculate the natal chart for someone born April 15, 1990 at 2:30 PM in Chicago:\n" +
@@ -34,32 +40,47 @@ registerTool({
             format: {
                 type: "string",
                 enum: ["json", "llm"],
-                description: "Output format. 'llm' returns a compact array-based projection optimized for LLM token efficiency (Pro tier required). 'json' returns full verbose JSON.",
+                description: "Output format. 'llm' returns a compact array-based projection optimized for LLM token efficiency (available on all tiers). 'json' returns full verbose JSON.",
             },
             include_arabic_parts: {
                 type: "boolean",
-                description: "If true, include Hermetic Lots (Arabic Parts) in the response.",
+                description: "Reserved for future use. Hermetic Lots / Arabic Parts are currently available via the dedicated /ephemeris/hermetic-lots endpoint.",
             },
             include_fixed_stars: {
                 type: "boolean",
-                description: "If true, include fixed star conjunctions in the response.",
+                description: "Reserved for future use. Fixed star positions are currently available via the dedicated /ephemeris/fixed-stars endpoint.",
             },
         },
         required: ["datetime", "latitude", "longitude"],
         additionalProperties: false,
     },
     handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
         const body = {
-            datetime: args.datetime,
-            latitude: args.latitude,
-            longitude: args.longitude,
+            subject: {
+                name: "MCP Request",
+                birth_datetime: { iso: args.datetime },
+                birth_location: {
+                    latitude: { decimal: args.latitude },
+                    longitude: { decimal: args.longitude }
+                },
+            }
         };
-        if (args.house_system)
-            body.house_system = args.house_system;
-        if (args.include_arabic_parts)
-            body.include_arabic_parts = args.include_arabic_parts;
-        if (args.include_fixed_stars)
-            body.include_fixed_stars = args.include_fixed_stars;
+        if (args.house_system) {
+            const code = HOUSE_SYSTEM_MAP[args.house_system] ?? args.house_system;
+            body.configuration = { house_system: code };
+        }
+        if (args.include_fixed_stars) {
+            body.configuration = {
+                ...(body.configuration || {}),
+                fixed_star_options: { include: true }
+            };
+        }
+        if (args.include_arabic_parts) {
+            body.options = {
+                include_hermetic_lots: true,
+            };
+        }
         const query = {};
         if (args.format)
             query.format = args.format;

package/dist/tools/specialized/relocation.js

@@ -1,7 +1,7 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
 registerTool({
-    name: "ephemeris.relocation",
+    name: "ephemeris_relocation",
     description: "Calculate a relocation chart — the same natal planetary positions re-cast for a different " +
         "geographic location. Used to understand how living in a different city shifts house placements " +
         "and angles, without changing the planetary longitudes in the chart.\n\n" +
@@ -40,23 +40,27 @@ 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: ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"],
         additionalProperties: false,
     },
     handler: async (args) => {
+        validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"]);
         const body = {
             natal: {
-                datetime: args.natal_datetime,
-                latitude: args.natal_latitude,
-                longitude: args.natal_longitude,
-            },
-            relocation: {
-                latitude: args.relocation_latitude,
-                longitude: args.relocation_longitude,
+                subject: {
+                    name: "MCP Request",
+                    birth_datetime: { iso: args.natal_datetime },
+                    birth_location: {
+                        latitude: { decimal: args.natal_latitude },
+                        longitude: { decimal: args.natal_longitude },
+                    },
+                },
             },
+            relocation_lat: args.relocation_latitude,
+            relocation_lon: args.relocation_longitude,
         };
         if (args.house_system)
             body.house_system = args.house_system;

package/dist/tools/specialized/returns.js

@@ -0,0 +1,126 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+// POST /predictive/returns/solar
+registerTool({
+    name: "ephemeris_solar_return",
+    description: "Calculate the exact Solar Return date/time — when the Sun returns to its natal ecliptic longitude. " +
+        "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'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            birth_datetime: {
+                type: "string",
+                description: "ISO 8601 birth date/time (e.g. '1985-06-21T14:00:00').",
+            },
+            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 Solar Return (ISO 8601). Defaults to now.",
+            },
+            return_latitude: {
+                type: "number",
+                description: "Location latitude for the return chart (optional). Defaults to birth location.",
+            },
+            return_longitude: {
+                type: "number",
+                description: "Location longitude for the return chart (optional). Defaults to birth location.",
+            },
+        },
+        required: ["birth_datetime", "birth_latitude", "birth_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude"]);
+        const body = {
+            birth_datetime: {
+                iso: args.birth_datetime,
+            },
+            birth_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/solar", body);
+    },
+});
+// POST /predictive/returns/lunar
+registerTool({
+    name: "ephemeris_lunar_return",
+    description: "Calculate the exact Lunar Return date/time — when the Moon returns to its natal ecliptic longitude (~every 27.3 days). " +
+        "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'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            birth_datetime: {
+                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.",
+            },
+            return_latitude: {
+                type: "number",
+                description: "Location latitude for return chart (optional). Defaults to birth location.",
+            },
+            return_longitude: {
+                type: "number",
+                description: "Location longitude for return chart (optional). Defaults to birth location.",
+            },
+        },
+        required: ["birth_datetime", "birth_latitude", "birth_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude"]);
+        const body = {
+            birth_datetime: { iso: args.birth_datetime },
+            birth_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);
+    },
+});

package/dist/tools/specialized/synastry.js

@@ -1,11 +1,11 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
 registerTool({
-    name: "ephemeris.synastry",
+    name: "ephemeris_synastry",
     description: "Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects " +
         "(planetary connections between the two charts), composite points, and relationship indicators. " +
         "Use this for compatibility analysis, relationship timing, or partnership insights.\n\n" +
-        "CREDIT COST: 5 credits per call.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Compare two people's charts:\n" +
         "  person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.8781, person_a_longitude=-87.6298,\n" +
         "  person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.0522, person_b_longitude=-118.2437",
@@ -26,7 +26,7 @@ registerTool({
             format: {
                 type: "string",
                 enum: ["json", "llm"],
-                description: "Output format. 'llm' is compact and token-efficient (Pro tier).",
+                description: "Output format. 'llm' is compact and token-efficient (available on all tiers).",
             },
         },
         required: [
@@ -36,16 +36,26 @@ registerTool({
         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",
+        ]);
         const body = {
-            natal_a: {
-                datetime: args.person_a_datetime,
-                latitude: args.person_a_latitude,
-                longitude: args.person_a_longitude,
+            subject_a: {
+                name: "Person A",
+                birth_datetime: { iso: args.person_a_datetime },
+                birth_location: {
+                    latitude: { decimal: args.person_a_latitude },
+                    longitude: { decimal: args.person_a_longitude },
+                },
             },
-            natal_b: {
-                datetime: args.person_b_datetime,
-                latitude: args.person_b_latitude,
-                longitude: args.person_b_longitude,
+            subject_b: {
+                name: "Person B",
+                birth_datetime: { iso: args.person_b_datetime },
+                birth_location: {
+                    latitude: { decimal: args.person_b_latitude },
+                    longitude: { decimal: args.person_b_longitude },
+                },
             },
         };
         if (args.house_system)

package/dist/tools/specialized/transits.js

@@ -1,12 +1,14 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
 registerTool({
-    name: "ephemeris.transits",
+    name: "ephemeris_transits",
     description: "Search for astrological transit events affecting a natal chart over a date range. " +
         "Returns a list of exact transit moments — when transiting planets form specified aspects " +
         "to natal planet positions. Ideal for generating horoscope timelines, event forecasting, or " +
         "finding optimal timing windows.\n\n" +
-        "CREDIT COST: 5 credits per call.\n\n" +
+        "HOW IT WORKS: This tool first calculates the natal chart to extract your actual planetary " +
+        "ecliptic longitudes, then searches for transiting planets crossing those exact degrees.\n\n" +
+        "CREDIT COST: 6 credits per call (1 for natal + 5 for transit search).\n\n" +
         "EXAMPLE: Find all Saturn transits to the natal Sun/Moon for the next 6 months:\n" +
         "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
         "  start_date='2026-01-01', end_date='2026-06-30', transiting_planets=['saturn']",
@@ -42,39 +44,87 @@ registerTool({
             natal_points: {
                 type: "array",
                 items: { type: "string" },
-                description: "Natal point IDs to receive transits. E.g. ['sun', 'moon', 'asc', 'mc']. Omit for all core points.",
-            },
-            aspects: {
-                type: "array",
-                items: { type: "string", enum: ["conjunction", "opposition", "trine", "square", "sextile"] },
-                description: "Aspect types to include in the search. Defaults to all major aspects.",
-            },
-            orb: {
-                type: "number",
-                description: "Maximum orb in degrees (default: 1.0).",
+                description: "Natal point IDs whose exact longitudes should be targeted. E.g. ['sun', 'moon', 'asc', 'mc']. Omit for all core points.",
             },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        const body = {
-            natal: {
-                datetime: args.natal_datetime,
-                latitude: args.natal_latitude,
-                longitude: args.natal_longitude,
+        validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"]);
+        // ── Step 1: Compute natal chart to extract real planetary longitudes ──
+        const natalBody = {
+            subject: {
+                name: "Transit Natal Subject",
+                birth_datetime: { iso: args.natal_datetime },
+                birth_location: {
+                    latitude: { decimal: args.natal_latitude },
+                    longitude: { decimal: args.natal_longitude }
+                },
             },
-            start_date: args.start_date,
-            end_date: args.end_date,
+        };
+        const natalResult = await backendClient.post("/ephemeris/natal-chart", natalBody);
+        // Extract ecliptic longitudes from natal chart planets
+        const targetDegrees = [];
+        const natalPositionMap = {};
+        // The natal response typically has a `planets` array or object
+        const planets = natalResult?.planets || natalResult?.data?.planets || [];
+        const planetArray = Array.isArray(planets) ? planets : Object.values(planets);
+        // Filter to requested natal points if specified
+        const wantedPoints = args.natal_points
+            ? new Set(args.natal_points.map((p) => p.toLowerCase()))
+            : null;
+        for (const planet of planetArray) {
+            const name = (planet.name || planet.id || "").toLowerCase();
+            const lon = planet.longitude ?? planet.ecliptic_longitude ?? planet.lon;
+            if (typeof lon !== "number" || !isFinite(lon))
+                continue;
+            if (wantedPoints && !wantedPoints.has(name))
+                continue;
+            targetDegrees.push(Math.round(lon * 100) / 100); // 2 decimal places
+            natalPositionMap[name] = lon;
+        }
+        // Also extract angles (ASC, MC, DSC, IC) if present
+        const angles = natalResult?.angles || natalResult?.data?.angles;
+        if (angles) {
+            const angleEntries = Array.isArray(angles) ? angles : Object.entries(angles).map(([k, v]) => ({ name: k, ...(typeof v === 'object' ? v : { longitude: v }) }));
+            for (const angle of angleEntries) {
+                const name = (angle.name || angle.id || "").toLowerCase();
+                const lon = angle.longitude ?? angle.ecliptic_longitude ?? angle.lon;
+                if (typeof lon !== "number" || !isFinite(lon))
+                    continue;
+                if (wantedPoints && !wantedPoints.has(name))
+                    continue;
+                targetDegrees.push(Math.round(lon * 100) / 100);
+                natalPositionMap[name] = lon;
+            }
+        }
+        if (targetDegrees.length === 0) {
+            throw new Error("Could not extract natal planet longitudes from the natal chart calculation. " +
+                "Please verify your natal_datetime, natal_latitude, and natal_longitude are correct.");
+        }
+        // ── Step 2: Search transits against those real natal longitudes ──
+        let startStr = args.start_date;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(startStr)) {
+            startStr += "T00:00:00Z";
+        }
+        let endStr = args.end_date;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(endStr)) {
+            endStr += "T23:59:59Z";
+        }
+        const transitBody = {
+            start_date: startStr,
+            end_date: endStr,
+            target_degrees: targetDegrees,
         };
         if (args.transiting_planets)
-            body.transiting_planets = args.transiting_planets;
-        if (args.natal_points)
-            body.natal_points = args.natal_points;
-        if (args.aspects)
-            body.aspects = args.aspects;
-        if (args.orb != null)
-            body.orb = args.orb;
-        return await backendClient.request("POST", "/predictive/transits/search", { data: body });
+            transitBody.planet_names = args.transiting_planets;
+        const transitResult = await backendClient.request("POST", "/predictive/transits/search", { data: transitBody });
+        // Return combined context so the LLM knows what natal positions were targeted
+        return {
+            natal_positions: natalPositionMap,
+            target_degrees_used: targetDegrees,
+            transit_results: transitResult,
+        };
     },
 });