@openephemeris/mcp-server 4.16.0 → 4.18.0

package/dist/tools/specialized/moon.js

@@ -1,5 +1,5 @@
 import { registerTool, validateCoordinates } from "../index.js";
-import { getActiveClient } from "../../backend/client.js";
+import { getActiveClient, rethrowBillingOrAuth } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { TIMEZONE_PROPERTY } from "../datetime.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
@@ -53,8 +53,15 @@ registerTool({
             getActiveClient().request("GET", "/ephemeris/moon/phase", { params }),
             getActiveClient().request("GET", "/ephemeris/moon/void-of-course", { params }),
         ]);
+        // Out of credits / signed out / tier-gated must reach the assistant as
+        // the thrown credit-wall (or auth) error with its top-up link — never
+        // as an `error` string tucked inside a success-shaped result.
+        rethrowBillingOrAuth([phase, voc]);
+        // The phase IS the answer; with it gone there is nothing to degrade to.
+        if (phase.status === "rejected")
+            throw phase.reason;
         return {
-            phase: phase.status === "fulfilled" ? phase.value : { error: phase.reason?.message },
+            phase: phase.value,
             void_of_course: voc.status === "fulfilled" ? voc.value : { error: voc.reason?.message },
         };
     },
@@ -65,7 +72,7 @@ registerTool({
         "date is the next quarter moon' or 'list the next 3 full moons'. Returns the exact UTC datetime " +
         "of each upcoming occurrence of the requested phase (phase = new_moon | full_moon | first_quarter " +
         "| last_quarter), optionally after a given date and for count occurrences.\n\n" +
-        "CREDIT COST: 10-20 credits per occurrence (calendar endpoint); keep count=1 unless asked.\n\n" +
+        "CREDIT COST: 2 credits per occurrence; count max 12.\n\n" +
         "Do not use for the phase or sign the Moon is in right now — use ephemeris_moon_phase; for " +
         "eclipses use ephemeris_next_eclipse.",
     inputSchema: {
@@ -86,7 +93,7 @@ registerTool({
             },
             count: {
                 type: "integer",
-                description: "Number of upcoming occurrences to return (1-12). Default 1.",
+                description: "Number of upcoming occurrences to return (1-12, 2 credits each). Default 1.",
             },
         },
         required: ["phase"],
@@ -113,55 +120,24 @@ registerTool({
         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));
+        const requested = Number.isFinite(Number(args.count)) ? Math.trunc(Number(args.count)) : 1;
+        const count = Math.max(1, Math.min(NEXT_LUNAR_PHASE_MAX_COUNT, requested));
         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 client = getActiveClient();
         const results = [];
-        let cursorMs = startMs - 1; // include an occurrence at exactly 00:00 on after_date
+        // Include an occurrence at exactly 00:00 on after_date: the engine
+        // reports phases strictly after the probe instant.
+        let probeMs = startMs - 1000;
         for (let i = 0; i < count; i++) {
-            const hitMs = await findNext(cursorMs);
+            const hitMs = await nextPhaseAfter(client, probeMs, wanted);
             if (hitMs == null)
                 break;
             results.push({ phase: args.phase, datetime: new Date(hitMs).toISOString() });
-            cursorMs = hitMs;
+            probeMs = hitMs + PROBE_STEP_PAST_HIT_MS;
         }
         // 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.
@@ -179,3 +155,35 @@ registerTool({
         };
     },
 });
+// ── Next-lunar-phase lookup ─────────────────────────────────────────────────
+//
+// /calendar/astrology/moon-phases is the engine's exact principal-phase
+// finder. It takes a single instant (`jd`, or a `date` = noon UTC), not a
+// range, and returns the first New / First Quarter / Full / Third Quarter
+// strictly after it within 30 days — so one call yields exactly one
+// occurrence of each phase. The Go meter prices it at a flat 2 credits (one
+// fixed 30-day span; usage_meter.go). There is no range form to widen, so
+// `count` occurrences of one phase take `count` calls: 2 credits each.
+//
+// Probing with `jd` (the exact instant) rather than `date` (noon UTC) is what
+// makes it one call per occurrence: the search origin sits exactly on the
+// cursor, so no occurrence between midnight and noon can be skipped and no
+// re-probe is needed.
+export const NEXT_LUNAR_PHASE_MAX_COUNT = 12;
+const UNIX_EPOCH_JD = 2440587.5;
+const DAY_MS = 86_400_000;
+/** Step past a found root before the next probe, so the solver's tolerance cannot return it again. */
+const PROBE_STEP_PAST_HIT_MS = 60_000;
+async function nextPhaseAfter(client, afterMs, wanted) {
+    const jd = afterMs / DAY_MS + UNIX_EPOCH_JD;
+    const result = await client.request("GET", "/calendar/astrology/moon-phases", {
+        params: { jd: jd.toFixed(6) },
+    });
+    const events = Array.isArray(result?.data?.events) ? result.data.events : [];
+    const hits = 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 > afterMs)
+        .sort((a, b) => a - b);
+    return hits.length ? hits[0] : null;
+}

package/dist/tools/specialized/progressed.js

@@ -1,6 +1,6 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
-import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
+import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, WINDOW_DATE_DESC, assertZonedDatetime } from "../datetime.js";
 registerTool({
     name: "ephemeris_progressed_chart",
@@ -44,26 +44,11 @@ registerTool({
                 type: "boolean",
                 description: "Whether to include aspect grid in the response. Default false.",
             },
-            include_visual: {
-                type: "boolean",
-                description: "When true, renders the progressed chart wheel as an SVG and embeds it in the response. " +
-                    "The chart image will display in the conversation alongside the data. " +
-                    "Costs 2 additional credits on top of the base call cost.",
-            },
-            visual_config: {
-                type: "object",
-                description: "Optional rendering preferences (only used when include_visual=true).",
-                properties: {
-                    theme: { type: "string", enum: ["light", "dark"], description: "Color theme. Default: light." },
-                    size: { type: "number", description: "Canvas size in pixels, 200–4000. Default: 800." },
-                },
-                additionalProperties: false,
-            },
         },
         required: ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Progressed Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"]);
@@ -91,14 +76,6 @@ registerTool({
         if (args.include_aspects != null) {
             body.options = { include_aspects: args.include_aspects };
         }
-        if (args.include_visual) {
-            body.include_visual = true;
-            body.visual_config = {
-                format: "svg",
-                theme: args.visual_config?.theme || "light",
-                size: args.visual_config?.size || 800,
-            };
-        }
         return await getActiveClient().post("/ephemeris/progressed", body);
     },
 });

package/dist/tools/specialized/transits.js

@@ -11,11 +11,11 @@ registerTool({
         "ASPECT ANGLES (aspect_angle): 0 = conjunction/return (default), 180 = opposition, 90 = square, " +
         "120 = trine. Saturn return → transiting_planets=['saturn'], natal_points=['saturn'], " +
         "aspect_angle=0.\n" +
-        "EFFICIENCY: always pass transiting_planets and natal_points — omitting both sweeps all outer " +
-        "planets against all core points and is slow. DEFAULT natal_points: sun, moon, mercury, venus, " +
-        "mars, jupiter, saturn.\n" +
-        "SEARCH RANGE LIMITS: Explorer/PayG → 1 year; Pro → 5 years; Startup → 10 years.\n" +
-        "CREDIT COST: 6 credits per call (natal chart + search).\n\n" +
+        "EFFICIENCY: always pass transiting_planets and natal_points (omitting both is slow). DEFAULT " +
+        "natal_points: sun, moon, mercury, venus, mars, jupiter, saturn.\n" +
+        "MAX SPAN: Explorer/PayG 1y, Pro 5y, Startup 10y, Scale 40y (longer = 400).\n" +
+        "CREDIT COST: 1 + span price: ≤1y 5, ≤3y 10, ≤5y 15, ≤10y 25, ≤20y 40, ≤40y 70. truncated:true = " +
+        "partial; re-call from truncation.resume_from.\n\n" +
         "Do not use when the user should SEE a forecast — use explore_transit_timeline; for the sky today " +
         "with no birth data use electional_moment_analysis; for retrograde dates use " +
         "electional_station_tracker.",