@openephemeris/mcp-server 3.15.0 → 3.17.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

@@ -4,7 +4,9 @@
 [![npm version](https://img.shields.io/npm/v/@openephemeris/mcp-server)](https://www.npmjs.com/package/@openephemeris/mcp-server)
 [![System Status](https://img.shields.io/badge/Status-Operational-brightgreen)](https://status.openephemeris.com/)
 
-Model Context Protocol server for OpenEphemeris — 52 typed astrology tools powered by the NASA JPL DE440 ephemeris. Zero hallucination on planetary positions, dates, and degrees. Covers 1,100 years of astronomical data.
+![OpenEphemeris in Claude — ask in plain language, get a real computed chart](https://raw.githubusercontent.com/openephemeris/openephemeris/main/docs/internal/PH-ASSETS/hero-demo.gif)
+
+Model Context Protocol server for OpenEphemeris — typed astrology tools powered by the NASA JPL DE440 ephemeris. Zero hallucination on planetary positions, dates, and degrees. Covers 1,100 years of astronomical data.
 
 **Hosted endpoint:** `https://mcp.openephemeris.com/mcp` (Streamable HTTP, MCP 2025-11-25 spec)
 
@@ -229,7 +231,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 |
@@ -335,7 +339,7 @@ When you update the MCP server logic (handlers, bug fixes, hardening), you shoul
               ┌────▼────────────────────┐
               │  openephemeris-mcp      │
               │  Node.js MCP Server     │
-              │  52 typed tools         │
+              │  typed tools            │
               │  auth: Key > JWT        │
               └────────────┬────────────┘
                            │ HTTPS
@@ -355,8 +359,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`): **84**
+- 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_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`, `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/backend/client.js

@@ -248,7 +248,9 @@ export class BackendClient {
                         `If you don't have an account, you can create one at the link above (free tier, no credit card needed).`, 401, "auth_required", true, authInfo.verification_uri_complete);
                 }
                 return new BackendError(`Authentication required: ${msg}. Run auth.login to connect your account, ` +
-                    `or set OPENEPHEMERIS_API_KEY in your MCP server config.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
+                    `or set OPENEPHEMERIS_API_KEY in your MCP server config. If you connected ` +
+                    `through Claude's connector settings, disconnect and reconnect the ` +
+                    `OpenEphemeris connector to re-authorize.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
             }
             if (status === 402) {
                 const dataObj = data && typeof data === "object" ? data : {};

package/dist/oauth/token.js

@@ -21,6 +21,20 @@ import { timingSafeEqual } from "node:crypto";
 import { verifyCodeChallenge } from "./pkce.js";
 import { issueSupabaseJWT, refreshSupabaseSession } from "./supabase-jwt.js";
 // ---------------------------------------------------------------------------
+// Supabase config check (mirrors store.ts / supabase-jwt.ts)
+// ---------------------------------------------------------------------------
+/**
+ * True when Supabase env vars are configured, meaning callers expect a real
+ * JWT. In that case a JWT-issuance failure must be reported as an OAuth
+ * error rather than silently degrading to a placeholder token — a
+ * placeholder access_token is classified as an API key downstream
+ * (server-sse.ts extractAuth) and will 401 on every subsequent request,
+ * leaving the connector stuck in a "connected but broken" state.
+ */
+function isSupabaseConfigured() {
+    return Boolean(process.env["SUPABASE_URL"] && process.env["SUPABASE_SERVICE_ROLE_KEY"]);
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 /**
@@ -113,8 +127,10 @@ async function handleAuthorizationCode(req, res, store) {
             store.storeRefreshToken(oauthRefreshToken, {
                 client_id: stored.client_id,
                 user_id: stored.user_id,
-                // Keep the Supabase refresh token for downstream refresh
-                supabase_refresh_token: supabaseTokens.refresh_token,
+                // Real Supabase refresh tokens aren't available for self-signed JWTs
+                // (see supabase-jwt.ts) — storing null avoids a doomed Supabase
+                // refresh round-trip on the next /oauth/token refresh_token grant.
+                supabase_refresh_token: null,
             });
             console.info(`[token] Supabase JWT issued for user ${stored.user_id}`);
             res.json({
@@ -125,10 +141,23 @@ async function handleAuthorizationCode(req, res, store) {
             });
             return;
         }
-        // Supabase JWT issuance failed — log a warning but continue to placeholder
+        // Supabase JWT issuance failed. If Supabase is configured, the caller
+        // expects a real JWT — returning a placeholder here would leave the
+        // connector "connected" while every subsequent API call 401s (a
+        // placeholder access_token is classified as an API key, not a JWT, by
+        // server-sse.ts's extractAuth). Report a proper OAuth error instead so
+        // the client can retry or surface the failure.
+        if (isSupabaseConfigured()) {
+            console.error(`[token] Supabase JWT issuance failed for user ${stored.user_id}; returning server_error`);
+            res.status(500).json({
+                error: "server_error",
+                error_description: "Failed to issue an access token. Please try again.",
+            });
+            return;
+        }
         console.warn(`[token] Supabase JWT issuance failed for user ${stored.user_id}, falling back to placeholder`);
     }
-    // Fallback: local placeholder tokens (test/dev path)
+    // Fallback: local placeholder tokens (test/dev path — Supabase not configured)
     const refreshToken = store.generateRefreshToken();
     store.storeRefreshToken(refreshToken, { client_id: stored.client_id });
     res.json({
@@ -166,7 +195,10 @@ async function handleRefreshToken(req, res, store) {
     // ---------------------------------------------------------------------------
     const userId = storedMeta.user_id;
     const supabaseRefresh = storedMeta.supabase_refresh_token;
-    // Try Supabase refresh first
+    // Try Supabase refresh first — only meaningful if we ever obtained a real
+    // Supabase refresh token. Self-signed JWTs (see supabase-jwt.ts) never do,
+    // so supabase_refresh_token is stored as null and this is skipped in favor
+    // of going straight to the working issueSupabaseJWT(userId) fallback below.
     if (supabaseRefresh) {
         const refreshed = await refreshSupabaseSession(supabaseRefresh);
         if (refreshed) {
@@ -192,7 +224,9 @@ async function handleRefreshToken(req, res, store) {
             const newRefreshToken = store.generateRefreshToken();
             store.storeRefreshToken(newRefreshToken, {
                 ...storedMeta,
-                supabase_refresh_token: freshTokens.refresh_token,
+                // See note above — self-signed JWTs have no real Supabase refresh
+                // token, so store null rather than the JWT's own (also fake) one.
+                supabase_refresh_token: null,
             });
             res.json({
                 access_token: freshTokens.access_token,
@@ -202,8 +236,21 @@ async function handleRefreshToken(req, res, store) {
             });
             return;
         }
+        // We have a user_id (Supabase-issued grant) but JWT issuance failed.
+        // Same reasoning as the authorization_code path: a placeholder token
+        // here would falsely appear "refreshed" while every subsequent request
+        // 401s. Report a proper OAuth error so the client can retry/reauth.
+        if (isSupabaseConfigured()) {
+            console.error(`[token] Refresh: Supabase JWT re-issuance failed for user ${userId}; returning server_error`);
+            res.status(500).json({
+                error: "server_error",
+                error_description: "Failed to refresh the access token. Please try again.",
+            });
+            return;
+        }
     }
-    // Fallback: placeholder tokens
+    // Fallback: placeholder tokens (test/dev path — Supabase not configured,
+    // or this refresh token predates any user_id/Supabase association)
     const newRefreshToken = store.generateRefreshToken();
     store.storeRefreshToken(newRefreshToken, storedMeta);
     res.json({

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

@@ -1,11 +1,16 @@
 /**
  * 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,
+ *   hd_on_connection_channel_click, hd_on_transit_channel_click (overlay, Phase 5).
+ * 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,16 @@
 /**
  * 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,
+ *   hd_on_connection_channel_click, hd_on_transit_channel_click (overlay, Phase 5).
+ * 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
@@ -700,6 +705,148 @@ registerTool({
         };
     },
 });
+const CONNECTION_TYPE_DATA = {
+    electromagnetic: {
+        label: "Electromagnetic",
+        tagline: "attraction — opposites complete the channel",
+        body: "Each of you holds one different gate of this channel; together you complete a current neither runs alone. This is the classic draw — and, on the same wiring, the friction. What the channel does comes alive only in the meeting; apart, each of you is back to half. The gift is chemistry and mutual completion. The edge is that the completeness depends on the other, and the same difference that pulls you together can push you apart. Each of you stays with your own strategy and inner authority — the connection is information about the interplay, not an instruction.",
+    },
+    companionship: {
+        label: "Companionship",
+        tagline: "sameness — you both already run the whole channel",
+        body: "You each already define this whole channel on your own, so meeting here is recognition rather than completion. Nothing has to be negotiated; you simply operate the same way. Friendship and ease live here. The edge is that there is no charge to cross — sameness can go flat, or become the place you take each other for granted. Ease is not the same as aliveness.",
+    },
+    dominance: {
+        label: "Dominance",
+        tagline: "one defines the whole channel, the other is fully open here",
+        body: "One of you defines this entire channel; the other holds neither gate and is completely open here. The defined partner conditions the open one steadily and consistently, and the open partner takes the current in fully, unfiltered by any definition of their own — seeing the defined one clearly, for exactly who they are. It is meant to be accepted and surrendered to, not fixed or matched. The gift is consistency and clear sight. The edge is the not-self reading of \"I always have to do it your way\": the open partner can lose themselves to the steady conditioning if they drift from their own authority. Surrender here is a choice made from authority, not a disappearance.",
+    },
+    compromise: {
+        label: "Compromise",
+        tagline: "one defines the whole channel, the other holds a single gate",
+        body: "One of you defines this whole channel; the other holds exactly one of its two gates. Push and pull land on that shared gate — the half-definition keeps getting overridden by the full one, so the single-gate partner is consistently compromised here. This is the spot where \"you do it your way, I do it mine\" surfaces most. Met consciously, the recurring friction on that one gate names exactly where the work is and can sharpen both of you. Unwatched, it calcifies into a standing grievance instead of a workable edge.",
+    },
+};
+const TRANSIT_CLASS_DATA = {
+    transit_completed: {
+        label: "Transit completes this channel",
+        body: "For a window, a passing transit completes this channel: one of its gates is defined in your own design, the other is switched on by the sky. While that holds, the current runs in you the way it does for someone built this way full-time — except you are not, and that is the whole point. It is a gift on loan: a real taste of standing definition here, without your having become someone else for it. The pull is to grab it and decide this is now who you are; when the transit separates and the channel opens back up, that reading only leaves you grieving. Nothing about your type, strategy, or authority has changed. Use the borrowed current while it lasts, keep deciding from your own authority, and let it go cleanly when the sky moves on.",
+    },
+    transit_only: {
+        label: "Transit defines this channel on its own",
+        body: "For a window, a passing transit lights both gates of this channel — neither is yours natally. The channel runs entirely on borrowed weather; it is not part of your design at all, and it switches off completely when the transit moves on. Notice the temporary current for what it is, and keep deciding from your own authority rather than mistaking it for a new capacity.",
+    },
+    reinforced: {
+        label: "Transit reinforces your definition here",
+        body: "You already define this channel, and a passing transit also lands on one of its gates today — your standing definition, amplified for a window. Nothing new is added; the current you already run simply gets louder. When the transit moves on, it settles back to its usual level.",
+    },
+    natal: {
+        label: "Your standing definition",
+        body: "Both gates of this channel are defined in your own design. This is part of your fixed wiring, not transit weather — the passing sky does not change it. It reads here for context alongside the temporary activations.",
+    },
+};
+// ── Tool: hd_on_connection_channel_click [app-only] ────────────────────────
+// Fired when the user clicks a connection (synastry) channel in the overlay
+// bodygraph. Serves the connection-type dynamic for that specific channel.
+registerTool({
+    name: "hd_on_connection_channel_click",
+    description: "Event handler called when the user clicks a connected channel in a Human Design connection (synastry) overlay bodygraph. " +
+        "Returns the channel identity and the relationship dynamic for its connection type " +
+        "(electromagnetic / companionship / dominance / compromise). " +
+        "This tool is called automatically by the bodygraph UI; you do not need to call it directly.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            channel: { type: "string", description: "Channel identifier string (e.g. '1-8', '20-34')." },
+            connection_type: {
+                type: "string",
+                description: "Connection type: electromagnetic | companionship | dominance | compromise.",
+            },
+            gate1: { type: "number", description: "First gate number." },
+            gate2: { type: "number", description: "Second gate number." },
+        },
+        required: ["channel"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Connection Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
+    handler: async (args) => {
+        const channelStr = String(args.channel ?? "");
+        const g1 = args.gate1 != null ? Number(args.gate1) : null;
+        const g2 = args.gate2 != null ? Number(args.gate2) : null;
+        const typeKey = String(args.connection_type ?? "").toLowerCase();
+        const key = channelStr.includes("-") ? channelStr : g1 != null && g2 != null ? `${g1}-${g2}` : channelStr;
+        const chan = HD_CHANNEL_DATA[key] ?? HD_CHANNEL_DATA[key.split("-").reverse().join("-")];
+        const conn = CONNECTION_TYPE_DATA[typeKey];
+        const chanName = chan?.name ?? "this channel";
+        const gatesLine = `**Gates:** ${g1 ?? channelStr.split("-")[0] ?? "?"} ↔ ${g2 ?? channelStr.split("-")[1] ?? "?"}`;
+        if (!conn) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `**Channel ${channelStr} — ${chanName}**\n\n${gatesLine}\n\n` +
+                            `This channel is defined across both people. ${chan?.description ?? ""}`.trim(),
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: `**${conn.label} Connection — Channel of ${chanName} (${channelStr})**\n\n` +
+                        `${gatesLine}\n\n` +
+                        `*${conn.tagline}*\n\n` +
+                        `${conn.body}` +
+                        (chan?.description ? `\n\n**This channel:** ${chan.description}` : ""),
+                }],
+        };
+    },
+});
+// ── Tool: hd_on_transit_channel_click [app-only] ──────────────────────────
+// Fired when the user clicks a channel in a transit overlay bodygraph. Serves
+// the meaning of the channel's transit class (esp. transit_completed).
+registerTool({
+    name: "hd_on_transit_channel_click",
+    description: "Event handler called when the user clicks a channel in a Human Design transit overlay bodygraph. " +
+        "Returns the channel identity and what its transit class means — especially transit_completed, where a transit " +
+        "temporarily completes a channel (one natal gate + one transit gate). " +
+        "This tool is called automatically by the bodygraph UI; you do not need to call it directly.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            channel: { type: "string", description: "Channel identifier string (e.g. '64-47')." },
+            transit_class: {
+                type: "string",
+                description: "Transit class: natal | reinforced | transit_completed | transit_only.",
+            },
+            gate1: { type: "number", description: "First gate number." },
+            gate2: { type: "number", description: "Second gate number." },
+        },
+        required: ["channel"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Transit Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
+    handler: async (args) => {
+        const channelStr = String(args.channel ?? "");
+        const g1 = args.gate1 != null ? Number(args.gate1) : null;
+        const g2 = args.gate2 != null ? Number(args.gate2) : null;
+        const cls = String(args.transit_class ?? "transit_completed").toLowerCase();
+        const key = channelStr.includes("-") ? channelStr : g1 != null && g2 != null ? `${g1}-${g2}` : channelStr;
+        const chan = HD_CHANNEL_DATA[key] ?? HD_CHANNEL_DATA[key.split("-").reverse().join("-")];
+        const info = TRANSIT_CLASS_DATA[cls] ?? TRANSIT_CLASS_DATA.transit_completed;
+        const chanName = chan?.name ?? "this channel";
+        const gatesLine = `**Gates:** ${g1 ?? channelStr.split("-")[0] ?? "?"} ↔ ${g2 ?? channelStr.split("-")[1] ?? "?"}`;
+        return {
+            content: [{
+                    type: "text",
+                    text: `**Channel of ${chanName} (${channelStr}) — ${info.label}**\n\n` +
+                        `${gatesLine}\n\n` +
+                        `${info.body}` +
+                        (chan?.description ? `\n\n**This channel:** ${chan.description}` : ""),
+                }],
+        };
+    },
+});
 const HD_CENTER_DATA = {
     Head: {
         keynote: "Inspiration, mental pressure, questioning",
@@ -1173,3 +1320,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 };
+    },
+});