@openephemeris/mcp-server 4.17.0 → 4.18.0

package/dist/tools/dev.js

@@ -46,10 +46,11 @@ const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.open
     "Call dev_list_allowed to see all currently available endpoint paths.\n\n" +
     // Prices mirror go-sidecar/internal/api/auth/usage_meter.go; tiers mirror
     // auth/middleware.go requiredTierForPath. /iching/* aliases /human-design/*.
-    "CREDIT COST: 1 for most GET calls; /calendar/* 10; /acg/* 10 (Pro tier); /electional/* 5 " +
-    "(find-window and aspect-search are Pro tier; moment-analysis and station-tracker are free); " +
-    "/human-design/* and /iching/* 2; catalogs/health 0; requests over 30s add 1 " +
-    "per 30s. Pass query {format: 'llm'} for compact output.\n\n";
+    "CREDIT COST: 1 for most; /predictive/* 5 (transits/search 5-70 by span); /comparative/* 3; " +
+    "/calendar/* 10 (moon-phases, lunar-standstill 2; cross-quarter 5); /acg/* 10 (Pro); " +
+    "/electional/* 5 (Pro, span-priced searches; moment-analysis, station-tracker free); " +
+    "/human-design/*, /iching/* 2 (composite, transit-chart 3; penta 2/member); catalogs 0; " +
+    "4xx/5xx refunded. Query {format: 'llm'} = compact output.\n\n";
 const READ_COMMON_CALLS = "COMMON CALLS:\n" +
     "  GET  /ephemeris/moon/phase             — Current/queried moon phase\n" +
     "  GET  /ephemeris/moon/void-of-course    — Next void-of-course period\n" +
@@ -60,13 +61,13 @@ const READ_COMMON_CALLS = "COMMON CALLS:\n" +
     "  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)\n" +
     "  GET  /eclipse/solar/local              — Local solar eclipse (query: lat, lon)\n" +
     "  GET  /tidal/forcing                    — Gravitational tidal forcing index\n" +
-    "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
+    "  GET  /calendar/astrology/moon-phases   — next New/Quarter/Full Moon after a date or jd\n" +
     "  GET  /location/autocomplete            — Geocode a place name (query: query=City Name)\n" +
     "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
     "  GET  /catalogs/bodies                  — List all supported celestial bodies\n";
 const WRITE_COMMON_CALLS = "COMMON CALLS:\n" +
     "  POST /ephemeris/natal-chart            — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}})\n" +
-    "  POST /ephemeris/natal/batch            — Up to 50 natal charts in one request\n" +
+    "  POST /ephemeris/natal/batch            — Up to 100 natal charts in one request (Startup tier)\n" +
     "  POST /ephemeris/relocation             — Relocated chart (same natal, new location)\n" +
     "  POST /predictive/transits/search       — Transit event search over a date range\n" +
     "  POST /predictive/returns/solar         — Solar return chart\n" +

package/dist/tools/specialized/electional.js

@@ -10,7 +10,8 @@ registerTool({
         "date range, 'find me a good day next month' or 'pick an auspicious window'. Returns the best " +
         "continuous timing windows in the range, scored hourly on essential dignity, aspect quality, sect " +
         "and void-of-course Moon penalties, with optional filters (avoid_voc, lunar_phase).\n\n" +
-        "CREDIT COST: 5 credits per call. Pro tier.\n\n" +
+        "CREDIT COST: ≤30 days 5, ≤60 days 8, ≤120 days 12. Pro tier; max window Pro 30 days, Startup " +
+        "60, Scale 120.\n\n" +
         "Do not use to score one specific moment or 'right now' — use electional_moment_analysis; for " +
         "retrograde dates use electional_station_tracker.",
     inputSchema: {
@@ -222,7 +223,7 @@ registerTool({
     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: 5 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call. Pro tier.\n\n" +
         "EXAMPLE: What aspects are active on March 21, 2026?\n" +
         "  date='2026-03-21T12:00:00Z'",
     inputSchema: {
@@ -276,7 +277,7 @@ registerTool({
         "Sun, Moon, Mercury, Venus, Mars and the lunar nodes — the same body set and formula the CCG hybrid " +
         "transit map (/acg/ccg mode=ccg_hybrid) draws with; every other body stays a transit. Progressed " +
         "crossings carry progressed: true and search_summary.progression names what was progressed.\n\n" +
-        "CREDIT COST: 5 credits per call.\n\n" +
+        "CREDIT COST: priced by start→end span — ≤1 month 5, ≤3 months 8, ≤6 months 10, ≤1 year 12. Pro tier.\n\n" +
         "EXAMPLE: When does Mercury cross the Descendant over Warsaw on 2026-07-30?\n" +
         "  latitude=52.2297, longitude=21.0122, bodies='Mercury', angles='DC',\n" +
         "  start='2026-07-30T00:00:00Z', end='2026-07-31T00:00:00Z'",

package/dist/tools/specialized/ephemeris_extended.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired, 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 { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, toDateTimeInputBody } from "../datetime.js";
 // `field`/`timezoneField` name the caller's own argument path (e.g.
@@ -134,10 +134,19 @@ registerTool({
         }
         // Fan-out: the backend only handles one planet per call; query all 10 in parallel.
         const PLANET_IDS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
-        const results = await Promise.all(PLANET_IDS.map((pid) => client.post("/ephemeris/retrograde-status", {
+        const settled = await Promise.allSettled(PLANET_IDS.map((pid) => client.post("/ephemeris/retrograde-status", {
             date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
             planet_id: pid,
-        }).catch(() => null)));
+        })));
+        // Out of credits / signed out / tier-gated: throw the credit-wall (or
+        // auth) error so its top-up link reaches the assistant. Swallowing it
+        // used to return `{planets: {}, success: true}` at zero credits.
+        rethrowBillingOrAuth(settled);
+        const results = settled.map((s) => (s.status === "fulfilled" ? s.value : null));
+        if (results.every((r) => r == null)) {
+            // Every planet failed for a non-billing reason — never report success with no data.
+            throw settled[0].reason;
+        }
         // Merge into a keyed object: { planet_name: {...status} }
         const merged = {};
         for (const res of results) {
@@ -151,7 +160,13 @@ registerTool({
                 };
             }
         }
-        return { planets: merged, datetime: args.datetime, success: true };
+        const failed = PLANET_IDS.filter((_, i) => results[i] == null);
+        return {
+            planets: merged,
+            datetime: args.datetime,
+            success: true,
+            ...(failed.length ? { failed_planet_ids: failed } : {}),
+        };
     },
 });
 // POST /ephemeris/midpoints

package/dist/tools/specialized/hd_group.js

@@ -8,7 +8,7 @@ registerTool({
     name: "human_design_composite",
     description: "Calculate a Human Design composite chart for two people. Merges both bodygraphs " +
         "to show shared channels, authority dynamics, and relationship type.\n\n" +
-        "CREDIT COST: 4 credits per call.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE (local times + zones):\n" +
         "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
         "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles'\n" +
@@ -74,7 +74,7 @@ registerTool({
     name: "human_design_penta",
     description: "Calculate a Human Design Penta (group) chart for 3-5 people. Shows functional " +
         "attributes, leadership dynamics, channels, redundancies, and a group stability score.\n\n" +
-        "CREDIT COST: 6 credits per call.\n\n" +
+        "CREDIT COST: 2 credits per member (6-10 for 3-5 people).\n\n" +
         "EXAMPLE (3 people — each datetime states its zone):\n" +
         "  group_name='Team Alpha',\n" +
         "  members=[\n" +

package/dist/tools/specialized/moon.d.ts

@@ -1 +1 @@
-export {};
+export declare const NEXT_LUNAR_PHASE_MAX_COUNT = 12;

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.",