@openephemeris/mcp-server 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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/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/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/package.json

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