@openephemeris/mcp-server 3.16.0 → 3.17.0

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)
 
@@ -337,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
@@ -357,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`): **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`
+- 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

@@ -6,7 +6,8 @@
  *   • 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_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.

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

@@ -6,7 +6,8 @@
  *   • 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_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.
@@ -704,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",

package/package.json

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