@openephemeris/mcp-server 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.2.0] — 2026-07-29
+
+`ephemeris_next_lunar_phase` could not answer the question it exists to answer. The
+tool's response shape changes with this fix, hence a minor rather than a patch.
+
+### Fixed
+
+- **`ephemeris_next_lunar_phase` returned zero results for every query.** "When is the
+  next full moon?" answered `result_count: 0` with the note *"No matching phase found in
+  window"* — an empty result that reads like a real one, so the answer came back as
+  "there is no full moon in the next month". Four faults stacked up:
+
+  - the tool sent `start_date`/`end_date`, but the calendar endpoint takes a single
+    `date`, so the search window was silently ignored;
+  - it looked for the phase array at `phases`/`data`/`events`, while the response nests
+    it at `data.events`, so the list was always empty;
+  - it matched phase names as `"full moon"` against the engine's `"full_moon"`, so
+    nothing would have matched even once the list was found;
+  - `last_quarter` had no match at all, because the engine names it `third_quarter`.
+
+  The search now walks the calendar forward one lunation at a time, so `count` above 1
+  works. An empty result is no longer reported as an answer: since every principal phase
+  recurs about every 29.5 days, zero results is a fault and the tool now says so instead
+  of handing back a plausible non-answer.
+
+### Changed
+
+- **`ephemeris_retrograde_status` now leads with the single-planet path.** The
+  description opened on the all-planets sweep and mentioned `planet_id` last, so "is
+  Mercury retrograde?" tended to take the 10-credit route instead of the 1-credit one.
+  `planet_id` now carries the planet-id table and both costs are stated up front.
+- **`ephemeris_next_lunar_phase` no longer claims to return the zodiac sign and degree.**
+  It never did — it returns exact UTC datetimes. It now points at `ephemeris_moon_phase`
+  for the sign, and states that cost scales with `count`.
+
+---
+
 ## [4.1.0] — 2026-07-26
 
 Follow-up to 4.0.0. The new `400` was telling REST callers to do something that, on

package/dist/tools/specialized/ephemeris_extended.js

@@ -88,19 +88,27 @@ registerTool({
 // the documented "all planets" behaviour works correctly.
 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 for every planet.\n\n" +
-        "✅  Answers 'is X retrograde?' at ONE instant. For WHEN a planet turns retrograde or " +
-        "direct, or whether it stations anywhere in a date range, use electional_station_tracker.\n\n" +
-        "CREDIT COST: for a single planet — the common case — pass planet_id (0-9, e.g. 2 for " +
-        "Mercury): 1 credit. Omitting planet_id runs the all-planets sweep: 10 credits (the " +
-        "backend bills one credit per body and this fans out to 10).",
+    description: "Get retrograde/direct status and speed for ONE planet — or, if you ask for it, all " +
+        "ten — at a given date/time. Returns is_retrograde flag, longitude speed, and station " +
+        "proximity.\n\n" +
+        "✅  Answers 'is X retrograde?' at ONE instant. Pass planet_id for the named planet; " +
+        "'is Mercury retrograde?' is planet_id=2, not a whole-sky sweep. For WHEN a planet turns " +
+        "retrograde or direct, or whether it stations anywhere in a date range, use " +
+        "electional_station_tracker.\n\n" +
+        "CREDIT COST: 1 credit for a single planet (pass planet_id). Omitting planet_id runs the " +
+        "all-planets sweep and costs 10 credits — the backend bills one credit per body and this " +
+        "fans out to 10. Only omit it when the question really is about every planet.",
     inputSchema: {
         type: "object",
         properties: {
             datetime: { type: "string", description: DATETIME_DESC },
             timezone: TIMEZONE_PROPERTY,
-            planet_id: { type: "integer", description: "Optional single planet ID (0-9). Omit for all planets." },
+            planet_id: {
+                type: "integer",
+                description: "Single planet ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, " +
+                    "6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto). Pass this whenever the question " +
+                    "names a planet — 1 credit. Omit only to sweep all ten — 10 credits.",
+            },
         },
         required: ["datetime"],
         additionalProperties: false,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",