@openephemeris/mcp-server 4.1.0 → 4.3.0

package/dist/tools/specialized/moon.js

@@ -68,10 +68,13 @@ registerTool({
 registerTool({
     name: "ephemeris_next_lunar_phase",
     description: "Find the next occurrence of a specific Moon phase after a given date. " +
-        "Returns the exact UTC datetime, zodiac sign, and degree.\n\n" +
+        "Returns the exact UTC datetime of each occurrence.\n\n" +
         "✅  USE THIS TOOL FOR: 'When is the next new moon?', 'When is the next full moon?', " +
-        "'What date is the next quarter moon?', or any question about UPCOMING phase dates.\n\n" +
-        "CREDIT COST: 1 credit per call.\n\n" +
+        "'What date is the next quarter moon?', or any question about UPCOMING phase dates.\n" +
+        "❌  NOT FOR: 'What phase is the moon in right now?' or 'What sign is the moon in?'\n" +
+        "→   For the phase, sign and degree AT a moment, use ephemeris_moon_phase.\n\n" +
+        "CREDIT COST: about 1 credit per occurrence returned — count=1 costs 1 credit, " +
+        "count=3 costs 3.\n\n" +
         "EXAMPLE: Find the next new moon:\n" +
         "  phase='new_moon'\n\n" +
         "EXAMPLE: Find the next full moon after a specific date:\n" +
@@ -105,64 +108,87 @@ registerTool({
     outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Next Lunar Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
-        // Map our clean enum to display names the calendar API returns
-        const phaseNameMap = {
+        const PHASE_LABELS = {
             new_moon: "New Moon",
             full_moon: "Full Moon",
             first_quarter: "First Quarter",
             last_quarter: "Last Quarter",
         };
-        const phaseLabel = phaseNameMap[args.phase] ?? args.phase;
+        // The engine names the waning quarter `third_quarter`; accept both spellings.
+        const PHASE_IDS = {
+            new_moon: ["new_moon"],
+            full_moon: ["full_moon"],
+            first_quarter: ["first_quarter"],
+            last_quarter: ["last_quarter", "third_quarter"],
+        };
+        const phaseLabel = PHASE_LABELS[args.phase];
+        const wanted = PHASE_IDS[args.phase];
+        if (!wanted) {
+            throw new Error(`Unknown phase '${args.phase}'. Use one of: ${Object.keys(PHASE_IDS).join(", ")}.`);
+        }
         const count = Math.max(1, Math.min(12, args.count ?? 1));
-        // Build a search window wide enough to capture `count` occurrences.
-        // Lunar cycle is ~29.5 days, so count * 35 days guarantees coverage.
-        const startDate = args.after_date
-            ? args.after_date.substring(0, 10)
-            : new Date().toISOString().substring(0, 10);
-        const endMs = new Date(startDate + "T00:00:00Z").getTime() + count * 35 * 24 * 60 * 60 * 1000;
-        const endDate = new Date(endMs).toISOString().substring(0, 10);
-        const result = await getActiveClient().request("GET", "/calendar/astrology/moon-phases", {
-            params: { start_date: startDate, end_date: endDate },
-        });
-        // Normalise response shape — defensively handle every known API envelope shape.
-        // Crash "allPhases.filter is not a function" occurs when a property like
-        // result.data is truthy but is an object, not an array.
-        function extractArray(val) {
-            if (Array.isArray(val))
-                return val;
-            if (val && typeof val === "object") {
-                // one level deeper: { phases: [...] }, { data: [...] }, etc.
-                for (const key of ["phases", "data", "events", "moon_phases", "results", "items"]) {
-                    const nested = val[key];
-                    if (Array.isArray(nested))
-                        return nested;
-                }
+        const startDate = (args.after_date ?? new Date().toISOString()).substring(0, 10);
+        const startMs = Date.parse(startDate + "T00:00:00Z");
+        if (Number.isNaN(startMs)) {
+            throw new Error(`after_date must be an ISO date like '2026-06-01', got '${args.after_date}'.`);
+        }
+        const HALF_DAY = 12 * 60 * 60 * 1000;
+        // The calendar endpoint takes a single `date` (it searches forward from noon UTC
+        // that day) and returns the first occurrence of each principal phase within the
+        // following ~30 days. So one request yields at most one hit for the phase we want.
+        async function phaseTimesFrom(probeDay) {
+            const result = await getActiveClient().request("GET", "/calendar/astrology/moon-phases", { params: { date: probeDay } });
+            const events = Array.isArray(result?.data?.events) ? result.data.events : [];
+            // The endpoint prepends the Moon's *current* 8-phase bucket, stamped with the
+            // query instant (noon UTC of `date`) rather than an event time. Left in, it
+            // reads as a real phase occurring at exactly 12:00:00. Computed moments always
+            // carry sub-second precision, so an exact hit on noon is that placeholder.
+            const probeNoonMs = Date.parse(probeDay + "T12:00:00Z");
+            return events
+                .filter((e) => wanted.includes(String(e?.phase ?? e?.phase_name ?? "").toLowerCase()))
+                .map((e) => Date.parse(e?.time ?? e?.iso_time ?? ""))
+                .filter((ms) => !Number.isNaN(ms) && ms !== probeNoonMs)
+                .sort((a, b) => a - b);
+        }
+        // Probe from the day containing `afterMs - 12h`, so its noon-UTC search origin is
+        // always at or before `afterMs` and an occurrence earlier the same day is still
+        // visible. That leaves under a day of slack behind the cursor, which can hold at
+        // most one occurrence (they are ~29.5 days apart) — hence a single re-probe.
+        async function findNext(afterMs) {
+            let probeMs = afterMs - HALF_DAY;
+            for (let probe = 0; probe < 2; probe++) {
+                const hits = await phaseTimesFrom(new Date(probeMs).toISOString().substring(0, 10));
+                const next = hits.find((ms) => ms > afterMs);
+                if (next != null)
+                    return next;
+                if (hits.length === 0)
+                    return null;
+                probeMs = hits[hits.length - 1] + HALF_DAY;
             }
             return null;
         }
-        const allPhases = extractArray(result) ?? [];
-        const matching = allPhases
-            .filter((p) => {
-            const name = (p.phase_name ?? p.name ?? p.phase ?? "").toLowerCase();
-            return (name === phaseLabel.toLowerCase() ||
-                name === args.phase.replace("_", " ").toLowerCase());
-        })
-            .slice(0, count);
-        if (matching.length === 0) {
-            // Return full calendar as fallback so the LLM can inspect it
-            return {
-                requested_phase: phaseLabel,
-                search_window: { start_date: startDate, end_date: endDate },
-                result_count: 0,
-                note: "No matching phase found in window. Full calendar returned for inspection.",
-                full_calendar: allPhases,
-            };
+        const results = [];
+        let cursorMs = startMs - 1; // include an occurrence at exactly 00:00 on after_date
+        for (let i = 0; i < count; i++) {
+            const hitMs = await findNext(cursorMs);
+            if (hitMs == null)
+                break;
+            results.push({ phase: args.phase, datetime: new Date(hitMs).toISOString() });
+            cursorMs = hitMs;
+        }
+        // Every principal phase recurs every ~29.5 days, so an empty result is impossible.
+        // Fail loudly rather than handing back a plausible "there isn't one" non-answer.
+        if (results.length === 0) {
+            throw new Error(`Lunar phase search failed: the backend returned no ${phaseLabel} after ` +
+                `${startDate}. A ${phaseLabel} occurs roughly every 29.5 days, so this is a ` +
+                `backend fault, not a real answer — do not report that there is no upcoming ` +
+                `${phaseLabel}.`);
         }
         return {
             requested_phase: phaseLabel,
             after_date: startDate,
-            results: matching,
-            result_count: matching.length,
+            result_count: results.length,
+            results,
         };
     },
 });

package/dist/tools/specialized/returns.js

@@ -1,7 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON, OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, toDateTimeInputBody } from "../datetime.js";
 // POST /predictive/returns/solar
 registerTool({
     name: "ephemeris_solar_return",
@@ -71,8 +71,8 @@ registerTool({
         // Default target to current year if not provided
         const targetDt = args.target_datetime ?? new Date().toISOString();
         const body = {
-            birth_datetime: { iso: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone) },
-            target_datetime: { iso: localToUtcIso("target_datetime", targetDt, args.timezone) },
+            birth_datetime: toDateTimeInputBody("birth_datetime", args.birth_datetime, args.timezone),
+            target_datetime: toDateTimeInputBody("target_datetime", targetDt, args.timezone),
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {
@@ -143,8 +143,8 @@ registerTool({
         assertZonedDatetime("target_datetime", args.target_datetime, args.timezone);
         const targetDt = args.target_datetime ?? new Date().toISOString();
         const body = {
-            birth_datetime: { iso: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone) },
-            target_datetime: { iso: localToUtcIso("target_datetime", targetDt, args.timezone) },
+            birth_datetime: toDateTimeInputBody("birth_datetime", args.birth_datetime, args.timezone),
+            target_datetime: toDateTimeInputBody("target_datetime", targetDt, args.timezone),
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {