@openephemeris/mcp-server 4.4.0 → 4.6.0

package/CHANGELOG.md

@@ -7,6 +7,101 @@ 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:
+*when* a planet reaches an angle at a place, rather than what is angular
+there at a fixed moment.
+
+### Added
+
+- **`electional_angle_crossings` — find when a body crosses the Ascendant,
+  Descendant, Midheaven, or Imum Coeli at a location.** The time-inverse of
+  astrocartography. `acg_hits` answers "which lines pass near Warsaw at this
+  moment"; this answers "at what moment does Mercury cross the Descendant
+  over Warsaw". Give it a latitude/longitude and a date range and it returns
+  the crossing moments chronologically, with each body's position and a
+  daylight hint at that instant.
+
+  Crossing times are solved on the same in-mundo (equatorial RA/Dec) geometry
+  the astrocartography line engine draws, so casting a map at a returned
+  moment puts that line through the query point — the search and the map
+  cannot disagree.
+
+  Defaults to the classical seven bodies and all four angles over the current
+  UTC day. Circumpolar cases — a body that never rises or never sets at that
+  latitude — simply return no event rather than an error. Ranges up to 366
+  days; an over-long range is rejected rather than quietly shortened.
+
+  Advertised in the default tool surface. 5 credits per call, Developer plan
+  and above.
+
 ## [4.4.0] — 2026-07-30
 
 Puts the location resolver on the natural path for the four `explore_*`

package/README.md

@@ -440,10 +440,10 @@ When you update the MCP server logic (handlers, bug fixes, hardening), you shoul
 
 Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live tool registry.
 
-- Allowlisted operations: **28**
-- Methods: `GET=4`, `POST=24`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **91**
-- Typed tools: `account_usage`, `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bazi_annual_pillar`, `bazi_chart`, `bazi_compatibility`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_recalculate`, `bazi_ten_gods`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_list_allowed`, `dev_read_api`, `dev_write_api`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bazi_chart`, `explore_bi_wheel`, `explore_human_design`, `explore_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `explore_transit_timeline`, `explore_vedic_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_connection_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_transit_channel_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `moon_phase_recalculate`, `timezone_resolve`, `vedic_chart`, `vedic_chart_recalculate`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
+- Allowlisted operations: **31**
+- Methods: `GET=5`, `POST=26`, `PUT=0`, `PATCH=0`, `DELETE=0`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **92**
+- Typed tools: `account_usage`, `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bazi_annual_pillar`, `bazi_chart`, `bazi_compatibility`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_recalculate`, `bazi_ten_gods`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_list_allowed`, `dev_read_api`, `dev_write_api`, `electional_angle_crossings`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bazi_chart`, `explore_bi_wheel`, `explore_human_design`, `explore_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `explore_transit_timeline`, `explore_vedic_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_connection_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_transit_channel_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `moon_phase_recalculate`, `timezone_resolve`, `vedic_chart`, `vedic_chart_recalculate`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
 
 ### Allowlist Families
@@ -453,8 +453,9 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 | `acg` | 4 | `POST /acg/ccg`, `POST /acg/hits` |
 | `chinese` | 5 | `POST /chinese/bazi/compatibility`, `POST /chinese/bazi/element-balance` |
 | `comparative` | 5 | `POST /comparative/composite`, `POST /comparative/composite/midpoint` |
-| `electional` | 4 | `GET /electional/aspect-search`, `GET /electional/find-window` |
+| `electional` | 5 | `GET /electional/angle-crossings`, `GET /electional/aspect-search` |
 | `ephemeris` | 1 | `POST /ephemeris/relocation` |
+| `human-design` | 2 | `POST /human-design/composite`, `POST /human-design/transit-chart` |
 | `predictive` | 6 | `POST /predictive/returns`, `POST /predictive/returns/lunar` |
 | `visualization` | 3 | `POST /visualization/bi-wheel`, `POST /visualization/bodygraph` |
 <!-- GENERATED:RUNTIME_SNAPSHOT:END -->

package/config/dev-allowlist.json

@@ -71,6 +71,10 @@
       "method": "POST",
       "path": "/comparative/synastry"
     },
+    {
+      "method": "GET",
+      "path": "/electional/angle-crossings"
+    },
     {
       "method": "GET",
       "path": "/electional/aspect-search"
@@ -91,6 +95,14 @@
       "method": "POST",
       "path": "/ephemeris/relocation"
     },
+    {
+      "method": "POST",
+      "path": "/human-design/composite"
+    },
+    {
+      "method": "POST",
+      "path": "/human-design/transit-chart"
+    },
     {
       "method": "POST",
       "path": "/predictive/returns/lunar"
@@ -128,8 +140,8 @@
       "path": "/visualization/chart-wheel"
     }
   ],
-  "last_generated_at": "2026-05-14T01:35:40.409Z",
-  "openapi_sha256": "50112cd7017466815265d92e7d73cbc29be6bdc729a87db50989f189d562d201",
+  "last_generated_at": "2026-07-30T20:30:07.623Z",
+  "openapi_sha256": "c8d62588232551c514979433b2829ceb951ddce99334e65a3deed112a28bb11a",
   "candidates_get": [
     {
       "method": "GET",
@@ -243,6 +255,14 @@
       ],
       "operationId": "get_solar_eclipse_local_eclipse_solar_local_get"
     },
+    {
+      "method": "GET",
+      "path": "/electional/angle-crossings",
+      "tags": [
+        "electional"
+      ],
+      "operationId": "ElectionalAngleCrossingsElectionalAngleCrossingsGet"
+    },
     {
       "method": "GET",
       "path": "/electional/aspect-search",
@@ -925,6 +945,14 @@
       ],
       "operationId": "human_design_penta_human_design_penta_post"
     },
+    {
+      "method": "POST",
+      "path": "/human-design/transit-chart",
+      "tags": [
+        "Human Design"
+      ],
+      "operationId": "human_design_transit_chart_human_design_transit_chart_post"
+    },
     {
       "method": "POST",
       "path": "/human-design/transit",
@@ -1105,6 +1133,8 @@
       "Non-GET allowlisted: POST /comparative/overlay",
       "Non-GET allowlisted: POST /comparative/synastry",
       "Non-GET allowlisted: POST /ephemeris/relocation",
+      "Non-GET allowlisted: POST /human-design/composite",
+      "Non-GET allowlisted: POST /human-design/transit-chart",
       "Non-GET allowlisted: POST /predictive/returns/lunar",
       "Non-GET allowlisted: POST /predictive/returns/solar",
       "Non-GET allowlisted: POST /predictive/returns",

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/index.js

@@ -66,6 +66,7 @@ export const CORE_TOOL_NAMES = new Set([
     "ephemeris_electional",
     "electional_moment_analysis",
     "electional_station_tracker",
+    "electional_angle_crossings",
     // Astrocartography
     "acg_power_lines",
     "acg_hits",

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/electional.js

@@ -239,3 +239,93 @@ registerTool({
         });
     },
 });
+// GET /electional/angle-crossings — OE-FEAT-2026-001
+registerTool({
+    name: "electional_angle_crossings",
+    description: "Find WHEN a body crosses an angle (Ascendant, Descendant, Midheaven, Imum Coeli) at a specific " +
+        "place — the time-inverse of astrocartography. Answers 'when does Mercury cross the Descendant " +
+        "in Warsaw today?'\n\n" +
+        "✅  USE THIS FOR: 'when is Venus on my horizon in Lisbon?', 'what time does Jupiter culminate " +
+        "over Tokyo on Friday?', timing a moment by a planet's angularity at a place.\n" +
+        "❌  NOT FOR: which lines pass near a place at a fixed time → use acg_hits instead.\n\n" +
+        "Crossing times use the same in-mundo geometry as the astrocartography line engine, so casting a " +
+        "map at a returned moment puts that line through the query point. Circumpolar cases (a body that " +
+        "never rises or never sets at that latitude) simply return no event.\n\n" +
+        "CREDIT COST: 5 credits per call.\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'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            latitude: {
+                type: "number",
+                description: "Latitude of the place in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
+            },
+            longitude: {
+                type: "number",
+                description: "Longitude of the place in decimal degrees (positive = East).",
+            },
+            start: {
+                type: "string",
+                description: "Start of the search range. " + WINDOW_DATE_DESC + " Defaults to the start of the current UTC day.",
+            },
+            end: {
+                type: "string",
+                description: "End of the search range. " + WINDOW_DATE_DESC + " Defaults to 24 hours after start. Maximum range 366 days.",
+            },
+            bodies: {
+                type: "string",
+                description: "Comma-separated body names, e.g. 'Mercury,Venus'. Defaults to the classical seven " +
+                    "(Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn). Aliases: 'NorthNode'/'Rahu' → MeanNode, 'Ketu' → SouthNode.",
+            },
+            angles: {
+                type: "string",
+                description: "Comma-separated angles: AC, DC, MC, IC (ASC/DSC accepted). Defaults to all four.",
+            },
+            refraction_correction: {
+                type: "boolean",
+                description: "Apply atmospheric refraction to the AC/DC horizon. Defaults to false (geometric horizon), " +
+                    "which is what the astrocartography endpoints use by default — leave it off to keep times and map lines aligned.",
+            },
+            max_results: {
+                type: "number",
+                description: "Maximum number of crossing events to return (default 5000).",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' = compact token-efficient output (available on all tiers).",
+            },
+        },
+        required: ["latitude", "longitude"],
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Angle Crossing Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        validateRequired(args, ["latitude", "longitude"]);
+        const query = {
+            latitude: args.latitude,
+            longitude: args.longitude,
+        };
+        if (args.start)
+            query.start = args.start;
+        if (args.end)
+            query.end = args.end;
+        if (args.bodies)
+            query.bodies = args.bodies;
+        if (args.angles)
+            query.angles = args.angles;
+        if (args.refraction_correction !== undefined)
+            query.refraction_correction = args.refraction_correction;
+        if (args.max_results !== undefined)
+            query.max_results = args.max_results;
+        if (args.format)
+            query.format = args.format;
+        return await getActiveClient().request("GET", "/electional/angle-crossings", {
+            data: {},
+            params: query,
+        });
+    },
+});

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.4.0",
+  "version": "4.6.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",