@openephemeris/mcp-server 3.15.0 → 3.16.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.16.0] — 2026-07-05
+
+### Added
+- **`explore_human_design_transit`** — personalized Human Design transit overlay. Overlays a transiting moment on a person's natal bodygraph and highlights the channels the transit temporarily completes plus any newly-defined centers. Premium (Developer tier); renders an interactive overlay bodygraph in MCP Apps hosts.
+- **`explore_human_design_connection`** — two-person Human Design connection (synastry) overlay. Classifies every connected channel as electromagnetic / companionship / dominance / compromise and renders a two-person overlay bodygraph. Premium (Developer tier).
+
+### Changed
+- **`human_design_composite` is now Developer-tier** (was Explorer) and returns real connection-channel scoring — the previously-stubbed relationship endpoint (`/human-design/composite`) is now live end-to-end.
+
+---
+
 ## [3.15.0] — 2026-06-15
 
 ### Changed

package/README.md

@@ -229,7 +229,9 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 | Station tracker | `electional_station_tracker` | Developer |
 | Aspect search | `electional_aspect_search` | Developer |
 | Human Design chart | `human_design_chart` | Explorer |
-| HD composite | `human_design_composite` | Explorer |
+| HD composite | `human_design_composite` | Developer |
+| HD transit overlay | `explore_human_design_transit` | Developer |
+| HD connection (synastry) | `explore_human_design_connection` | Developer |
 | HD penta | `human_design_penta` | Explorer |
 | HD return / opposition | `hd_planetary_return`, `hd_opposition` | Explorer |
 | Vedic chart | `vedic_chart` | Explorer |
@@ -355,8 +357,8 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 - Allowlisted operations: **28**
 - Methods: `GET=4`, `POST=24`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **80**
-- Typed tools: `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_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_bi_wheel`, `explore_human_design`, `explore_moon_phase`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `timezone_resolve`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **82**
+- Typed tools: `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_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_bi_wheel`, `explore_human_design`, `explore_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `timezone_resolve`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
 
 ### Allowlist Families

package/dist/tools/apps/bodygraph-app.d.ts

@@ -1,11 +1,15 @@
 /**
  * bodygraph-app.ts — MCP App tool registration for the Human Design Bodygraph Explorer.
  *
- * Registers 4 tools:
- *   • explore_human_design      — primary entry point, returns data + UI resource [model]
- *   • hd_on_center_click        — center click handler [app-only]
- *   • hd_on_gate_click          — gate click handler [app-only]
- *   • hd_on_channel_click       — channel click handler [app-only]
+ * Entry tools [model + app]:
+ *   • explore_human_design             — natal bodygraph, data + UI resource
+ *   • explore_human_design_transit     — natal + transit overlay (premium)
+ *   • explore_human_design_connection  — two-person connection/synastry overlay (premium)
+ * Click handlers [app-only]: hd_on_center_click, hd_on_gate_click,
+ *   hd_on_channel_click, hd_on_planet_click, hd_on_variable_click.
+ * The transit + connection tools reuse this bodygraph iframe resource; their
+ * overlay SVG is returned inline by /human-design/transit-chart and
+ * /human-design/composite (include_visual) rather than a separate render call.
  *
  * The bodygraph is rendered client-side from structured JSON — no SVG endpoint
  * is called, keeping latency at zero and the architecture consistent with

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

@@ -1,11 +1,15 @@
 /**
  * bodygraph-app.ts — MCP App tool registration for the Human Design Bodygraph Explorer.
  *
- * Registers 4 tools:
- *   • explore_human_design      — primary entry point, returns data + UI resource [model]
- *   • hd_on_center_click        — center click handler [app-only]
- *   • hd_on_gate_click          — gate click handler [app-only]
- *   • hd_on_channel_click       — channel click handler [app-only]
+ * Entry tools [model + app]:
+ *   • explore_human_design             — natal bodygraph, data + UI resource
+ *   • explore_human_design_transit     — natal + transit overlay (premium)
+ *   • explore_human_design_connection  — two-person connection/synastry overlay (premium)
+ * Click handlers [app-only]: hd_on_center_click, hd_on_gate_click,
+ *   hd_on_channel_click, hd_on_planet_click, hd_on_variable_click.
+ * The transit + connection tools reuse this bodygraph iframe resource; their
+ * overlay SVG is returned inline by /human-design/transit-chart and
+ * /human-design/composite (include_visual) rather than a separate render call.
  *
  * The bodygraph is rendered client-side from structured JSON — no SVG endpoint
  * is called, keeping latency at zero and the architecture consistent with
@@ -1173,3 +1177,181 @@ registerTool({
         };
     },
 });
+// ── Tool: explore_human_design_transit ───────────────────────────────────────
+// Personalized Human Design transit overlay (natal chart + a transiting moment).
+// Premium (Developer tier). Calls POST /human-design/transit-chart.
+registerTool({
+    name: "explore_human_design_transit",
+    description: "Overlay the current (or a chosen) planetary transit on a person's natal Human Design bodygraph. " +
+        "Highlights the channels a transit temporarily COMPLETES with the natal chart and any centers it " +
+        "newly defines — the core of a Human Design transit reading. " +
+        "Returns an interactive overlay bodygraph in MCP Apps-capable hosts (Claude Desktop), with a text " +
+        "summary fallback elsewhere. Premium (Developer tier). Calculated with NASA JPL DE440 ephemerides.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                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." },
+            timezone: { type: "string", description: "IANA timezone for the birth location (e.g. 'America/New_York')." },
+            transit_datetime: {
+                type: "string",
+                description: "Transit moment, ISO 8601. Defaults to now (UTC) when omitted.",
+            },
+        },
+        required: ["datetime"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: {
+        title: "Human Design Transit Overlay",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
+    _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["model", "app"] } },
+    handler: async (args) => {
+        const client = getActiveClient();
+        const timezone = args.timezone;
+        const natalIso = localToUtcIso(String(args.datetime), timezone);
+        const lat = args.latitude ?? 0;
+        const lon = args.longitude ?? 0;
+        // 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",
+                birth_datetime: { iso: natalIso },
+                birth_location: {
+                    latitude: { decimal: lat },
+                    longitude: { decimal: lon },
+                    ...(timezone ? { timezone: { iana_name: timezone } } : {}),
+                },
+            },
+        };
+        if (args.transit_datetime) {
+            body.transit_datetime = { iso: ensureTimezone(String(args.transit_datetime)) };
+        }
+        const bundleAvailable = Boolean(getBodygraphBundle());
+        if (bundleAvailable)
+            body.include_visual = true;
+        const resp = await client.request("POST", "/human-design/transit-chart", { data: body });
+        const transit = (resp?.transit ?? {});
+        const completed = Array.isArray(transit.completed_channels) ? transit.completed_channels : [];
+        const newCenters = Array.isArray(transit.newly_defined_centers) ? transit.newly_defined_centers : [];
+        const natal = (resp?.natal ?? {});
+        const svg = resp?.visual?.data;
+        const summary = `**Human Design Transit Overlay**\n\n` +
+            `Natal: ${natal.type ?? "—"} ${natal.profile ?? ""} · ${natal.authority ?? ""} authority.\n\n` +
+            (completed.length
+                ? `The transit **completes ${completed.length} channel${completed.length === 1 ? "" : "s"}**: ${completed.join(", ")}.`
+                : `The transit completes no channels right now.`) +
+            (newCenters.length
+                ? `\n\nNewly-defined center${newCenters.length === 1 ? "" : "s"}: **${newCenters.join(", ")}** — a temporary shift while the transit holds.`
+                : "");
+        const payload = { ...resp, _svg: svg, server_version: SERVER_VERSION };
+        if (bundleAvailable && svg) {
+            return {
+                content: [{ type: "text", text: summary }],
+                structuredContent: payload,
+                _meta: { "ui/resourceUri": BODYGRAPH_RESOURCE_URI, ui: { resourceUri: BODYGRAPH_RESOURCE_URI } },
+            };
+        }
+        return { content: [{ type: "text", text: summary }], structuredContent: payload };
+    },
+});
+// ── Tool: explore_human_design_connection ────────────────────────────────────
+// Two-person Human Design connection (synastry) overlay. Premium (Developer tier).
+// Calls POST /human-design/composite.
+registerTool({
+    name: "explore_human_design_connection",
+    description: "Compare two people's Human Design charts and classify every connected channel by HD connection " +
+        "theory — electromagnetic (attraction), companionship (sameness), dominance (one defines), and " +
+        "compromise (friction). Returns an interactive two-person overlay bodygraph in MCP Apps-capable " +
+        "hosts, with a text summary fallback elsewhere. Premium (Developer tier). NASA JPL DE440 ephemerides.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            person_a: {
+                type: "object",
+                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." },
+                    timezone: { type: "string", description: "IANA timezone (e.g. 'America/New_York')." },
+                },
+                required: ["datetime"],
+            },
+            person_b: {
+                type: "object",
+                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." },
+                    timezone: { type: "string", description: "IANA timezone (e.g. 'America/New_York')." },
+                },
+                required: ["datetime"],
+            },
+        },
+        required: ["person_a", "person_b"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: {
+        title: "Human Design Connection (Synastry)",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["model", "app"] } },
+    handler: async (args) => {
+        const client = getActiveClient();
+        const toSubject = (p) => {
+            const tz = p?.timezone;
+            return {
+                birth_datetime_utc: localToUtcIso(String(p?.datetime), tz),
+                latitude: p?.latitude ?? 0,
+                longitude: p?.longitude ?? 0,
+            };
+        };
+        const body = {
+            subject_1: toSubject(args.person_a),
+            subject_2: toSubject(args.person_b),
+        };
+        const bundleAvailable = Boolean(getBodygraphBundle());
+        if (bundleAvailable)
+            body.include_visual = true;
+        const resp = await client.request("POST", "/human-design/composite", { data: body });
+        const connections = Array.isArray(resp?.connections) ? resp.connections : [];
+        const svg = resp?.visual?.data;
+        const byType = (t) => connections.filter((c) => c?.type === t).map((c) => c.id);
+        const line = (label, t) => {
+            const ids = byType(t);
+            return ids.length ? `\n- **${label}** (${ids.length}): ${ids.join(", ")}` : "";
+        };
+        const summary = `**Human Design Connection**\n\n` +
+            `${connections.length} connected channel${connections.length === 1 ? "" : "s"}:` +
+            line("Electromagnetic — attraction", "electromagnetic") +
+            line("Companionship — sameness", "companionship") +
+            line("Dominance — one defines", "dominance") +
+            line("Compromise — friction", "compromise") +
+            (connections.length ? "" : " none.");
+        const payload = { ...resp, _svg: svg, server_version: SERVER_VERSION };
+        if (bundleAvailable && svg) {
+            return {
+                content: [{ type: "text", text: summary }],
+                structuredContent: payload,
+                _meta: { "ui/resourceUri": BODYGRAPH_RESOURCE_URI, ui: { resourceUri: BODYGRAPH_RESOURCE_URI } },
+            };
+        }
+        return { content: [{ type: "text", text: summary }], structuredContent: payload };
+    },
+});