@openephemeris/mcp-server 4.16.0 → 4.17.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.17.0] — 2026-09-24
+
+### Added
+- **Transit timelines show when each transit starts and ends.** `explore_transit_timeline` now asks
+  for orb windows (new `orb_deg` parameter, default 1°): every exact hit carries the in-orb window it
+  belongs to — the date the transit comes into orb and the date it leaves — and "pass 2 of 3" when a
+  retrograde brings the planet back over the same point without leaving the orb. Transits already in
+  orb at the start of the range are listed with whether they are applying or separating. The
+  interactive timeline shows the window on each card.
+- **Two new API capabilities reachable through `dev_read_api`:** orb windows on
+  `POST /predictive/transits/search` (`orb_deg`, `aspect_orbs`, `natal_points`, `aspects`) and the new
+  `POST /human-design/transit-timeline` — every gate (and line) a transiting planet enters and leaves
+  over a date range, and when a transit completes one of your channels. 121 public endpoints.
+
+### Fixed
+- **`dev_read_api` now reaches three endpoints it was missing:** `/ephemeris/draconic`,
+  `/ephemeris/prenatal-lunation` and `/predictive/primary-directions` (124 allowlisted operations).
+
 ## [4.16.0] — 2026-09-21
 
 ### Changed

package/README.md

@@ -490,8 +490,8 @@ 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: **120**
-- Methods: `GET=44`, `POST=76`, `PUT=0`, `PATCH=0`, `DELETE=0`
+- Allowlisted operations: **124**
+- Methods: `GET=44`, `POST=80`, `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`, `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: `dev_list_allowed`, `dev_read_api`, `dev_write_api`
@@ -507,11 +507,11 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 | `comparative` | 5 | `POST /comparative/composite`, `POST /comparative/composite/midpoint` |
 | `eclipse` | 6 | `GET /eclipse/besselian-elements`, `GET /eclipse/lunar/global` |
 | `electional` | 6 | `GET /electional/angle-crossings`, `GET /electional/aspect-search` |
-| `ephemeris` | 36 | `GET /ephemeris/agro/calendar`, `GET /ephemeris/agro/daily` |
+| `ephemeris` | 38 | `GET /ephemeris/agro/calendar`, `GET /ephemeris/agro/daily` |
 | `health` | 2 | `GET /health`, `GET /health/detailed` |
-| `human-design` | 8 | `POST /human-design/chart`, `POST /human-design/composite` |
+| `human-design` | 9 | `POST /human-design/chart`, `POST /human-design/composite` |
 | `location` | 2 | `GET /location/autocomplete`, `GET /location/reverse` |
-| `predictive` | 10 | `POST /predictive/returns`, `POST /predictive/returns/lunar` |
+| `predictive` | 11 | `POST /predictive/primary-directions`, `POST /predictive/returns` |
 | `root` | 1 | `GET /` |
 | `tidal` | 2 | `GET /tidal/forcing`, `GET /tidal/forcing/deep-time` |
 | `time` | 6 | `GET /time/delta-t`, `GET /time/equation-of-time` |

package/config/dev-allowlist.json

@@ -1,7 +1,7 @@
 {
   "schema": "astromcp-dev-allowlist-v1",
   "description": "Allowlist derived from the Go sidecar openapi.json. Every entry in allow[] corresponds to a real Go endpoint. Run 'npm run check:dev-allowlist' to validate freshness.",
-  "generated_from": "C:\\src\\openephemeris\\.claude\\worktrees\\mcp-allowlist-gaps-b8befc\\apps\\api\\go-sidecar\\openapi.json",
+  "generated_from": "C:\\src\\openephemeris\\.claude\\worktrees\\adoring-rhodes-871fd7\\apps\\api\\go-sidecar\\openapi.json",
   "deny": {
     "path_prefixes": [
       "/auth",
@@ -235,6 +235,10 @@
       "method": "POST",
       "path": "/ephemeris/dispositor-tree"
     },
+    {
+      "method": "POST",
+      "path": "/ephemeris/draconic"
+    },
     {
       "method": "POST",
       "path": "/ephemeris/fixed-stars"
@@ -291,6 +295,10 @@
       "method": "POST",
       "path": "/ephemeris/planet-position"
     },
+    {
+      "method": "POST",
+      "path": "/ephemeris/prenatal-lunation"
+    },
     {
       "method": "POST",
       "path": "/ephemeris/progressed"
@@ -383,6 +391,10 @@
       "method": "POST",
       "path": "/human-design/transit-chart"
     },
+    {
+      "method": "POST",
+      "path": "/human-design/transit-timeline"
+    },
     {
       "method": "POST",
       "path": "/human-design/transit"
@@ -395,6 +407,10 @@
       "method": "GET",
       "path": "/location/reverse"
     },
+    {
+      "method": "POST",
+      "path": "/predictive/primary-directions"
+    },
     {
       "method": "POST",
       "path": "/predictive/returns/lunar"
@@ -496,8 +512,8 @@
       "path": "/visualization/chart-wheel"
     }
   ],
-  "last_generated_at": "2026-08-31T23:51:24.873Z",
-  "openapi_sha256": "4347724c414ef94075a3db63016a4935ca7b533ecf18f37fac1ca16c22ca0195",
+  "last_generated_at": "2026-09-24T18:29:22.473Z",
+  "openapi_sha256": "f5927cecddb0f8629f7c94d380ca878e6780bc491f85490bacb2508e1b721b3d",
   "candidates_get": [
     {
       "method": "GET",
@@ -893,22 +909,6 @@
       ],
       "operationId": "declination_lines_acg_declination_lines_post"
     },
-    {
-      "method": "POST",
-      "path": "/acg/features",
-      "tags": [
-        "ACG"
-      ],
-      "operationId": "features_acg_features_post"
-    },
-    {
-      "method": "POST",
-      "path": "/acg/heatmap/composite",
-      "tags": [
-        "Astrocartography"
-      ],
-      "operationId": "AcgHeatmapCompositeAcgHeatmapCompositePost"
-    },
     {
       "method": "POST",
       "path": "/acg/hermetic-lines",
@@ -1341,6 +1341,14 @@
       ],
       "operationId": "human_design_transit_chart_human_design_transit_chart_post"
     },
+    {
+      "method": "POST",
+      "path": "/human-design/transit-timeline",
+      "tags": [
+        "Human Design"
+      ],
+      "operationId": "human_design_transit_timeline_human_design_transit_timeline_post"
+    },
     {
       "method": "POST",
       "path": "/human-design/transit",
@@ -1538,6 +1546,7 @@
       "Non-GET allowlisted: POST /ephemeris/declinations",
       "Non-GET allowlisted: POST /ephemeris/dignities",
       "Non-GET allowlisted: POST /ephemeris/dispositor-tree",
+      "Non-GET allowlisted: POST /ephemeris/draconic",
       "Non-GET allowlisted: POST /ephemeris/fixed-stars",
       "Non-GET allowlisted: POST /ephemeris/harmonics",
       "Non-GET allowlisted: POST /ephemeris/hermetic-lots",
@@ -1547,6 +1556,7 @@
       "Non-GET allowlisted: POST /ephemeris/natal-chart",
       "Non-GET allowlisted: POST /ephemeris/natal/batch",
       "Non-GET allowlisted: POST /ephemeris/planet-position",
+      "Non-GET allowlisted: POST /ephemeris/prenatal-lunation",
       "Non-GET allowlisted: POST /ephemeris/progressed",
       "Non-GET allowlisted: POST /ephemeris/relocation",
       "Non-GET allowlisted: POST /ephemeris/retrograde-status",
@@ -1563,7 +1573,9 @@
       "Non-GET allowlisted: POST /human-design/cycles/solar-return",
       "Non-GET allowlisted: POST /human-design/penta",
       "Non-GET allowlisted: POST /human-design/transit-chart",
+      "Non-GET allowlisted: POST /human-design/transit-timeline",
       "Non-GET allowlisted: POST /human-design/transit",
+      "Non-GET allowlisted: POST /predictive/primary-directions",
       "Non-GET allowlisted: POST /predictive/returns/lunar",
       "Non-GET allowlisted: POST /predictive/returns/solar",
       "Non-GET allowlisted: POST /predictive/returns",

package/dist/tools/apps/transit-timeline-app.d.ts

@@ -8,6 +8,9 @@
  * chart to extract real planetary longitudes, searches predictive transits
  * against those targets, then flattens the (planet@target → hits) result map
  * into a single chronological array the iframe renders as a vertical timeline.
+ * The search asks for orb windows (orb_deg) too, so every exact hit carries the
+ * in-orb window it belongs to — when the transit starts and ends, and which
+ * pass it is when a retrograde brings the planet back over the same point.
  *
  * Also exports resource helpers (getTransitTimelineBundle, etc.) for use in
  * index.ts and server-sse.ts.

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

@@ -8,6 +8,9 @@
  * chart to extract real planetary longitudes, searches predictive transits
  * against those targets, then flattens the (planet@target → hits) result map
  * into a single chronological array the iframe renders as a vertical timeline.
+ * The search asks for orb windows (orb_deg) too, so every exact hit carries the
+ * in-orb window it belongs to — when the transit starts and ends, and which
+ * pass it is when a retrograde brings the planet back over the same point.
  *
  * Also exports resource helpers (getTransitTimelineBundle, etc.) for use in
  * index.ts and server-sse.ts.
@@ -67,18 +70,32 @@ function normDeg(d) {
     return ((d % 360) + 360) % 360;
 }
 // ── Summary builder ──────────────────────────────────────────────────────────
-function buildSummary(transits, aspectLabel, win) {
+function shortDate(iso) {
+    return iso ? new Date(iso).toISOString().slice(0, 10) : "?";
+}
+function buildSummary(transits, windows, aspectLabel, orbDeg, win) {
+    const active = windows.filter((w) => w.phase_at_start);
+    const activeLines = active.slice(0, 6).map((w) => "  • " + w.planet_name + " " + (w.aspect ?? aspectLabel) + (w.natal_point ? " natal " + w.natal_point : "") +
+        " — " + w.phase_at_start + ", " + (Math.round((w.orb_at_start ?? 0) * 100) / 100) + "° from exact, in orb until " +
+        shortDate(w.leave));
+    const activeBlock = activeLines.length
+        ? "\n\nAlready in orb (" + orbDeg + "°) at the start:\n" + activeLines.join("\n")
+        : "";
     if (transits.length === 0) {
-        return "**Transit Timeline** — no exact transit hits matched the search window and criteria.";
+        return "**Transit Timeline** — no exact transit hits matched the search window and criteria." + activeBlock;
     }
     const planets = [...new Set(transits.map((t) => t.planet_name).filter(Boolean))];
     const lines = transits.slice(0, 8).map((t) => {
         const asp = t.aspect ?? aspectLabel;
         const natal = t.natal_point ? " natal " + t.natal_point : "";
         const when = new Date(t.date).toISOString().slice(0, 10);
+        const passes = t.pass_count > 1 ? ", pass " + t.pass_index + " of " + t.pass_count : "";
+        const inOrb = t.window_start !== undefined
+            ? " — in orb " + shortDate(t.window_start) + " → " + shortDate(t.window_end) + passes
+            : "";
         return "  • " + when + " — " + t.planet_name + " " + asp + natal +
             (t.zodiac_sign ? " (" + (t.zodiac_degree ?? 0) + "° " + t.zodiac_sign + ")" : "") +
-            (t.is_retrograde ? " ℞" : "");
+            (t.is_retrograde ? " ℞" : "") + inOrb;
     });
     let summary = "**Transit Timeline** — " + transits.length + (transits.length === 1 ? " event" : " events") +
         " from " + win.start_date + " to " + win.end_date +
@@ -86,6 +103,7 @@ function buildSummary(transits, aspectLabel, win) {
         lines.join("\n");
     if (transits.length > 8)
         summary += "\n  … and " + (transits.length - 8) + " more.";
+    summary += activeBlock;
     summary += "\n\nClick any transit for details and interpretation.";
     return summary;
 }
@@ -97,7 +115,9 @@ registerTool({
         "astrologically for me in 2027' — a forecast they should SEE. Returns an interactive, " +
         "date-ordered timeline (inline in Claude and ChatGPT; text summary elsewhere) of exact transit " +
         "hits grouped by month — transiting planet glyph, the natal point it contacts, the aspect, zodiac " +
-        "position and retrograde markers — each clickable for a focused interpretation.\n\n" +
+        "position and retrograde markers — each clickable for a focused interpretation. Every hit carries its " +
+        "in-orb window (when the transit starts and ends, and which pass it is when a retrograde repeats it), " +
+        "and transits already in orb at the start are listed with applying/separating.\n\n" +
         "ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 " +
         "= sextile. EFFICIENCY: specify transiting_planets and natal_points to keep compute fast. DEFAULT " +
         "natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. SEARCH RANGE LIMITS: " +
@@ -127,6 +147,10 @@ registerTool({
                 type: "number",
                 description: "Aspect angle in degrees. 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile.",
             },
+            orb_deg: {
+                type: "number",
+                description: "Orb in degrees that defines when a transit starts and ends (the in-orb window around each exact hit). Default 1. Greater than 0, at most 15.",
+            },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
         additionalProperties: false,
@@ -222,10 +246,12 @@ registerTool({
         let endStr = args.end_date;
         if (/^\d{4}-\d{2}-\d{2}$/.test(endStr))
             endStr += "T23:59:59Z";
+        const orbDeg = typeof args.orb_deg === "number" && args.orb_deg > 0 ? Math.min(args.orb_deg, 15) : 1;
         const transitBody = {
             start_date: startStr,
             end_date: endStr,
             target_degrees: effectiveTargets,
+            orb_deg: orbDeg,
         };
         if (args.transiting_planets)
             transitBody.planet_names = args.transiting_planets;
@@ -278,10 +304,53 @@ registerTool({
             }
         }
         transits.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+        // ── Step 5: orb windows → attach each exact hit to its window ────────────
+        // A window groups every pass the planet makes without leaving the orb, so
+        // a retrograde triple pass is one window with three exacts. Hits are
+        // matched to windows by planet, target degree and exact time.
+        const rawWindows = Array.isArray(transitResult?.windows) ? transitResult.windows : [];
+        const windows = rawWindows.map((w) => {
+            const target = typeof w?.target_longitude === "number" ? w.target_longitude : null;
+            return {
+                planet: String(w?.planet_name ?? "").toLowerCase(),
+                planet_name: String(w?.planet_name ?? ""),
+                natal_point: target != null ? nearestPoint(target) : "",
+                aspect: aspectLabel,
+                target_longitude: target,
+                orb_deg: w?.orb_deg ?? orbDeg,
+                enter: w?.enter ?? null,
+                leave: w?.leave ?? null,
+                exacts: Array.isArray(w?.exacts)
+                    ? w.exacts.map((e) => ({ time: e?.time, is_retrograde: Boolean(e?.is_retrograde) }))
+                    : [],
+                duration_days: w?.duration_days ?? null,
+                phase_at_start: w?.phase_at_start ?? null,
+                orb_at_start: w?.orb_at_start ?? null,
+            };
+        });
+        for (const t of transits) {
+            const hitMs = new Date(t.date).getTime();
+            for (const w of windows) {
+                if (w.planet_name !== t.planet_name || w.target_longitude == null || t.target_longitude == null)
+                    continue;
+                if (Math.abs(w.target_longitude - t.target_longitude) > 0.01)
+                    continue;
+                const idx = w.exacts.findIndex((e) => Math.abs(new Date(e.time).getTime() - hitMs) <= 60_000);
+                if (idx < 0)
+                    continue;
+                t.window_start = w.enter;
+                t.window_end = w.leave;
+                t.pass_index = idx + 1;
+                t.pass_count = w.exacts.length;
+                break;
+            }
+        }
         const win = { start_date: startStr.slice(0, 10), end_date: endStr.slice(0, 10) };
-        const summary = buildSummary(transits, aspectLabel, win);
+        const summary = buildSummary(transits, windows, aspectLabel, orbDeg, win);
         const uiPayload = {
             transits,
+            windows,
+            orb_deg: orbDeg,
             natal_positions: natalPositionMap,
             aspect_angle: aspectAngle,
             aspect_label: aspectLabel,

package/dist/ui/transit-timeline.html

@@ -6616,8 +6616,8 @@ function d_(e4, t2, n2, r2) {
       var t4, n3, r3, i3, a3;
       let o3 = ee2++;
       te2[o3] = e6;
-      let s3 = ((t4 = (n3 = e6.planet) == null ? e6.planet_name : n3) == null ? "" : t4).toLowerCase(), l3 = r_(s3), u3 = i_(s3), d3 = a_((r3 = e6.planet_name) == null ? s3 : r3), f3 = e6.is_retrograde ? '<span class="tl-retro" title="Retrograde at exact crossing">\u211E</span>' : "", p3 = (i3 = e6.aspect) == null ? c2 : i3, m3 = (a3 = n_[p3]) == null ? "" : a3, h3 = e6.natal_point ? '<span class="tl-natal">' + $(m3 ? m3 + " " : "") + $(p3) + ' natal <span class="tl-natal-glyph">' + $(i_(e6.natal_point)) + "</span> " + $(a_(e6.natal_point)) + "</span>" : '<span class="tl-natal">' + $(m3 ? m3 + " " : "") + $(a_(p3)) + "</span>", ne3 = u_(e6);
-      return '<div class="tl-event" data-idx="' + o3 + '" tabindex="0" role="button" aria-label="' + $(d3 + " " + p3 + (e6.natal_point ? " natal " + e6.natal_point : "") + " on " + s_(e6.date)) + '"><div class="tl-event-rail" aria-hidden="true"><span class="tl-node" style="--planet-color:' + l3 + '"></span></div><div class="tl-event-glyph" style="--planet-color:' + l3 + '" aria-hidden="true">' + u3 + '</div><div class="tl-event-body"><div class="tl-event-line1"><span class="tl-planet-name">' + $(d3) + "</span>" + f3 + h3 + '</div><div class="tl-event-line2"><span class="tl-date">' + $(c_(e6.date)) + "</span>" + (ne3 ? '<span class="tl-dot">\xB7</span><span class="tl-pos">' + $(ne3) + "</span>" : "") + '</div><button class="tl-ask" type="button" data-ask="' + o3 + '">\u2728 Interpret this transit</button></div></div>';
+      let s3 = ((t4 = (n3 = e6.planet) == null ? e6.planet_name : n3) == null ? "" : t4).toLowerCase(), l3 = r_(s3), u3 = i_(s3), d3 = a_((r3 = e6.planet_name) == null ? s3 : r3), f3 = e6.is_retrograde ? '<span class="tl-retro" title="Retrograde at exact crossing">\u211E</span>' : "", p3 = (i3 = e6.aspect) == null ? c2 : i3, m3 = (a3 = n_[p3]) == null ? "" : a3, h3 = e6.natal_point ? '<span class="tl-natal">' + $(m3 ? m3 + " " : "") + $(p3) + ' natal <span class="tl-natal-glyph">' + $(i_(e6.natal_point)) + "</span> " + $(a_(e6.natal_point)) + "</span>" : '<span class="tl-natal">' + $(m3 ? m3 + " " : "") + $(a_(p3)) + "</span>", ne3 = u_(e6), re3 = e6.window_start === void 0 ? "" : "In orb " + (e6.window_start ? s_(e6.window_start) : "\u2026") + " \u2013 " + (e6.window_end ? s_(e6.window_end) : "\u2026") + (e6.pass_count && e6.pass_count > 1 ? " \xB7 pass " + e6.pass_index + " of " + e6.pass_count : "");
+      return '<div class="tl-event" data-idx="' + o3 + '" tabindex="0" role="button" aria-label="' + $(d3 + " " + p3 + (e6.natal_point ? " natal " + e6.natal_point : "") + " on " + s_(e6.date)) + '"><div class="tl-event-rail" aria-hidden="true"><span class="tl-node" style="--planet-color:' + l3 + '"></span></div><div class="tl-event-glyph" style="--planet-color:' + l3 + '" aria-hidden="true">' + u3 + '</div><div class="tl-event-body"><div class="tl-event-line1"><span class="tl-planet-name">' + $(d3) + "</span>" + f3 + h3 + '</div><div class="tl-event-line2"><span class="tl-date">' + $(c_(e6.date)) + "</span>" + (ne3 ? '<span class="tl-dot">\xB7</span><span class="tl-pos">' + $(ne3) + "</span>" : "") + "</div>" + (re3 ? '<div class="tl-event-line2"><span class="tl-pos">' + $(re3) + "</span></div>" : "") + '<button class="tl-ask" type="button" data-ask="' + o3 + '">\u2728 Interpret this transit</button></div></div>';
     }).join("");
     return '<section class="tl-group"><h2 class="tl-group-label">' + $(e5.key) + '</h2><div class="tl-events">' + t3 + "</div></section>";
   }).join(""), h2 = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "description": "MCP server for Open Ephemeris — NASA JPL DE440 astrology and astronomy, with interactive charts that render inline in Claude and ChatGPT",
   "type": "module",
   "main": "dist/index.js",