@openephemeris/mcp-server 4.5.0 → 4.6.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.6.0] — 2026-07-30
+
+Fixes the tool that could not answer the question it is named for, closes the
+last two places a chart was silently computed at 0°N 0°E, and stops two tools
+discarding a timezone the caller supplied. The first three come from a 75-run
+behavioural eval (25 prompts × 3, fresh context each) run against 4.4.0; the
+last from the directory-submission readiness review.
+
+### Fixed
+
+- **`ephemeris_next_eclipse` can now find the next eclipse.** Without a
+  location it routed to `/eclipse/solar/global` or `/eclipse/lunar/global`,
+  which classify whatever eclipse is occurring *at* a given instant rather
+  than searching forward from one. The consequences compounded: `after_date`
+  was documented as optional and defaulting to today, but the backend
+  rejected the call without it; an ordinary date returned *"no solar eclipse
+  occurs at the requested date"*; and `eclipse_type: 'any'` was accepted and
+  ignored. Asking *"when is the next solar eclipse"* was unanswerable.
+
+  It now calls a new `/eclipse/next` endpoint that genuinely searches forward
+  from `after_date` (defaulting to now), honours `any` by returning whichever
+  of solar/lunar comes first, and needs no arguments beyond the type. Server
+  side in [`openephemeris#473`](https://github.com/openephemeris/openephemeris/pull/473).
+
+  Worth stating plainly, because it is the reason this is the lede: a broken
+  tool did not surface an error to the end user. Across three runs of the
+  same prompt the model answered from its own memory twice — once correctly,
+  once naming an eclipse in the wrong year — and disagreed with itself. Only
+  one run in three reported that the tool had failed.
+
+- **`explore_human_design_transit` and `explore_human_design_connection` no
+  longer silently compute at 0°N 0°E.** 4.4.0 fixed this for
+  `explore_human_design` and wired `location` into four chart tools; these
+  two were missed. `explore_human_design_transit` accepted a `location` that
+  was display-only — its own description conceded the chart would be cast on
+  the Gulf of Guinea — and `explore_human_design_connection` had no location
+  field at all for either person. Both now resolve a place name through the
+  same lookup `location_search` uses, and reject the call outright when
+  neither coordinates nor a resolvable location is supplied.
+
+- **`ephemeris_natal_batch` and `explore_transit_timeline` no longer discard a
+  supplied timezone.** Both declared a timezone parameter and then built the
+  request body without it, so a naive local birth time plus an IANA zone — the
+  remedy the server's own error message recommends — was rejected by the
+  datetime contract. `ephemeris_natal_batch` failed this way for *every*
+  subject in a batch, and its documented example was the failing shape;
+  `explore_transit_timeline` never read `natal_timezone` at all. Both now route
+  the value through the same canonical helper the rest of the surface uses, so
+  the zone reaches the wire.
+
+### Changed
+
+- **Two server-side fixes change what these tools return** (no MCP change
+  required, listed because the output differs):
+  `ephemeris_natal_chart` with `format: 'llm'` now distinguishes the mean and
+  true lunar nodes — both previously carried the id `north_node`, so a
+  consumer keying by id silently dropped one and the `aspects` indices
+  inherited the ambiguity ([`#475`](https://github.com/openephemeris/openephemeris/pull/475)).
+  And `server_version` in calculation metadata is now derived from the
+  deployed image reference rather than Fly's per-machine version counter, so
+  every instance serving a given release reports the same value; a separate
+  `instance_id` carries per-machine attribution
+  ([`#474`](https://github.com/openephemeris/openephemeris/pull/474)).
+
+---
+
 ## [4.5.0] — 2026-07-30
 
 Adds a tool for the question the astrocartography tools could not answer:

package/dist/tools/apps/bodygraph-app.js

@@ -1319,9 +1319,9 @@ registerTool({
                 description: "Natal birth datetime, ISO 8601 (e.g. '1990-04-15T19:30:00Z'). Include 'Z' or an offset, " +
                     "or supply timezone for local time. HD is time-sensitive to the minute.",
             },
-            latitude: { type: "number", description: "Natal birth latitude (decimal degrees, +N). Optional." },
-            longitude: { type: "number", description: "Natal birth longitude (decimal degrees, +E). Optional." },
-            location: { type: "string", description: "Natal location name, display only. This is a caption, NOT a geocoder — it does not set the chart location. Supply latitude/longitude too (resolve them with location_search), or the chart is computed at 0N 0E." },
+            latitude: { type: "number", description: "Natal birth latitude in decimal degrees (positive = North). Optional if `location` is a place name — the resolver fills it in." },
+            longitude: { type: "number", description: "Natal birth longitude in decimal degrees (positive = East). Optional if `location` is a place name." },
+            location: { type: "string", description: "Natal birth location. Prefer a plain place name like 'New York, NY' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). If neither location nor lat/lon is supplied the call is rejected — no silent 0°N 0°E charts." },
             timezone: { type: "string", description: "IANA timezone for the birth location (e.g. 'America/New_York')." },
             transit_datetime: {
                 type: "string",
@@ -1355,16 +1355,30 @@ registerTool({
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["model", "app"] } },
     handler: async (args) => {
         const client = getActiveClient();
-        const timezone = args.timezone;
+        // Resolve `location` → lat/lon/tz when the caller left coords unset.
+        // If neither is provided we throw rather than silently computing at
+        // 0°N 0°E (a plausible-looking chart nothing downstream can detect).
+        const resolved = await coordsFromArgsOrLocation({
+            latitude: args.latitude,
+            longitude: args.longitude,
+            timezone: args.timezone,
+            location: args.location,
+        });
+        const timezone = args.timezone ?? resolved.timezone;
         const natalIso = localToUtcIso("datetime", String(args.datetime), timezone);
-        const lat = args.latitude ?? 0;
-        const lon = args.longitude ?? 0;
+        const lat = resolved.latitude;
+        const lon = resolved.longitude;
+        if (lat == null || lon == null) {
+            throw new Error("explore_human_design_transit requires either `latitude` + `longitude` or a resolvable `location` name. " +
+                "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
+        }
+        const location = String(resolved.location ?? args.location ?? "Subject").slice(0, 120);
         // SubjectRequest wire shape: name (required), birth_datetime.iso, and
         // birth_location with struct-typed coordinate/timezone inputs (matches the
         // live bi-wheel/transit-timeline tools — bare scalars are rejected).
         const body = {
             subject: {
-                name: args.location ?? "Subject",
+                name: location,
                 birth_datetime: { iso: natalIso },
                 birth_location: {
                     latitude: { decimal: lat },
@@ -1441,8 +1455,9 @@ registerTool({
                 description: "First person's birth data.",
                 properties: {
                     datetime: { type: "string", description: "Birth datetime, ISO 8601 (Z/offset, or local with timezone)." },
-                    latitude: { type: "number", description: "Birth latitude (decimal degrees, +N). Optional." },
-                    longitude: { type: "number", description: "Birth longitude (decimal degrees, +E). Optional." },
+                    latitude: { type: "number", description: "Birth latitude, decimal degrees (+N). Optional if `location` is set." },
+                    longitude: { type: "number", description: "Birth longitude, decimal degrees (+E). Optional if `location` is set." },
+                    location: { type: "string", description: "Birth location, e.g. 'New York, NY' — resolved like location_search (ambiguous names throw). Omitting both this and lat/lon rejects the call rather than defaulting to 0°N 0°E." },
                     timezone: { type: "string", description: "IANA timezone (e.g. 'America/New_York')." },
                 },
                 required: ["datetime"],
@@ -1452,8 +1467,9 @@ registerTool({
                 description: "Second person's birth data.",
                 properties: {
                     datetime: { type: "string", description: "Birth datetime, ISO 8601 (Z/offset, or local with timezone)." },
-                    latitude: { type: "number", description: "Birth latitude (decimal degrees, +N). Optional." },
-                    longitude: { type: "number", description: "Birth longitude (decimal degrees, +E). Optional." },
+                    latitude: { type: "number", description: "Birth latitude, decimal degrees (+N). Optional if `location` is set." },
+                    longitude: { type: "number", description: "Birth longitude, decimal degrees (+E). Optional if `location` is set." },
+                    location: { type: "string", description: "Birth location, e.g. 'New York, NY' — resolved like location_search (ambiguous names throw). Omitting both this and lat/lon rejects the call rather than defaulting to 0°N 0°E." },
                     timezone: { type: "string", description: "IANA timezone (e.g. 'America/New_York')." },
                 },
                 required: ["datetime"],
@@ -1486,17 +1502,32 @@ registerTool({
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["model", "app"] } },
     handler: async (args) => {
         const client = getActiveClient();
-        const toSubject = (p, label) => {
-            const tz = p?.timezone;
+        // Resolve each person's `location` → lat/lon/tz when coords are unset.
+        // If neither is provided we throw rather than silently computing at
+        // 0°N 0°E (a plausible-looking chart nothing downstream can detect).
+        const toSubject = async (p, label) => {
+            const resolved = await coordsFromArgsOrLocation({
+                latitude: p?.latitude,
+                longitude: p?.longitude,
+                timezone: p?.timezone,
+                location: p?.location,
+            });
+            const tz = p?.timezone ?? resolved.timezone;
+            const lat = resolved.latitude;
+            const lon = resolved.longitude;
+            if (lat == null || lon == null) {
+                throw new Error(`${label} requires either \`latitude\` + \`longitude\` or a resolvable \`location\` name. ` +
+                    "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
+            }
             return {
                 birth_datetime_utc: localToUtcIso(`${label}.datetime`, String(p?.datetime), tz, `${label}.timezone`),
-                latitude: p?.latitude ?? 0,
-                longitude: p?.longitude ?? 0,
+                latitude: lat,
+                longitude: lon,
             };
         };
         const body = {
-            subject_1: toSubject(args.person_a, "person_a"),
-            subject_2: toSubject(args.person_b, "person_b"),
+            subject_1: await toSubject(args.person_a, "person_a"),
+            subject_2: await toSubject(args.person_b, "person_b"),
         };
         const bundleAvailable = Boolean(getBodygraphBundle());
         // Mirror the transit tool: explicit dark default, host-theme refetch.

package/dist/tools/apps/transit-timeline-app.js

@@ -18,7 +18,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, WINDOW_DATE_DESC, timezoneProperty } from "../datetime.js";
+import { DATETIME_DESC, WINDOW_DATE_DESC, timezoneProperty, toDateTimeInputBody } from "../datetime.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const TRANSIT_TIMELINE_RESOURCE_URI = "ui://openephemeris/transit-timeline";
 export const TRANSIT_TIMELINE_MIME_TYPE = "text/html;profile=mcp-app";
@@ -150,10 +150,15 @@ registerTool({
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"]);
         const client = getActiveClient();
         // ── Step 1: natal chart → real planetary longitudes ──────────────────────
+        // natal_timezone is a declared parameter — it must reach the wire body.
+        // It previously did not, so a caller following the server's own remedy for
+        // a naive datetime ("name the zone in the sibling `timezone` argument")
+        // had the zone silently dropped and got a 400 from the Go contract with no
+        // working alternative.
         const natalBody = {
             subject: {
                 name: "Transit Natal Subject",
-                birth_datetime: { iso: args.natal_datetime },
+                birth_datetime: toDateTimeInputBody("natal_datetime", String(args.natal_datetime), args.natal_timezone, "natal_timezone"),
                 birth_location: {
                     latitude: { decimal: args.natal_latitude },
                     longitude: { decimal: args.natal_longitude },

package/dist/tools/specialized/eclipse.js

@@ -60,12 +60,14 @@ registerTool({
             return await getActiveClient().request("GET", "/eclipse/next-visible", { params, timeoutMs: 60_000 });
         }
         else {
-            // Global query — route to global endpoint
-            const params = {};
+            // Global query — forward-search for the next eclipse of this type,
+            // anywhere on Earth. /eclipse/solar|lunar/global classify whatever
+            // eclipse (if any) is occurring exactly at a given date, so they
+            // can't answer "when is the next one" — /eclipse/next can.
+            const params = { eclipse_type: args.eclipse_type ?? "any" };
             if (args.after_date)
                 params.date = args.after_date;
-            const endpoint = args.eclipse_type === "lunar" ? "/eclipse/lunar/global" : "/eclipse/solar/global";
-            return await getActiveClient().request("GET", endpoint, { params, timeoutMs: 60_000 });
+            return await getActiveClient().request("GET", "/eclipse/next", { params, timeoutMs: 60_000 });
         }
     },
 });

package/dist/tools/specialized/ephemeris_extended.js

@@ -2,10 +2,18 @@ import { registerTool, validateRequired, validateCoordinates } from "../index.js
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, toDateTimeInputBody } from "../datetime.js";
-function buildSubject(name, datetime, lat, lon) {
+// `field`/`timezoneField` name the caller's own argument path (e.g.
+// "subjects[2].datetime") so a zone-less value is rejected with a message
+// that points at the offending subject rather than the batch as a whole.
+//
+// birth_datetime MUST go through toDateTimeInputBody: a naive clock time plus
+// a sibling `timezone` is a valid input shape, and dropping the zone here
+// turns it into an ambiguous datetime the Go contract rejects per-subject —
+// which is what this tool used to do to every subject in the batch.
+function buildSubject(name, datetime, lat, lon, timezone, field = "datetime", timezoneField = "timezone") {
     return {
         name,
-        birth_datetime: { iso: datetime },
+        birth_datetime: toDateTimeInputBody(field, datetime, timezone, timezoneField),
         birth_location: {
             latitude: { decimal: lat },
             longitude: { decimal: lon },
@@ -52,8 +60,8 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["subjects"]);
         args.subjects.forEach((s, i) => assertZonedDatetime(`subjects[${i}].datetime`, s?.datetime, s?.timezone, `subjects[${i}].timezone`));
-        const items = args.subjects.map((s) => ({
-            subject: buildSubject(s.name, s.datetime, s.latitude, s.longitude),
+        const items = args.subjects.map((s, i) => ({
+            subject: buildSubject(s.name, s.datetime, s.latitude, s.longitude, s?.timezone, `subjects[${i}].datetime`, `subjects[${i}].timezone`),
         }));
         return await getActiveClient().post("/ephemeris/natal/batch", { items });
     },

package/package.json

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