@openephemeris/mcp-server 3.13.9 → 3.13.10

package/README.md

@@ -355,8 +355,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`): **72**
-- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `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_call`, `dev_list_allowed`, `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_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_call`, `dev_list_allowed`, `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_moon_phase`, `explore_natal_chart`, `explore_transit_timeline`, `explore_vedic_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/config/dev-allowlist.json

@@ -128,8 +128,8 @@
       "path": "/visualization/chart-wheel"
     }
   ],
-  "last_generated_at": "2026-04-25T17:47:00.681Z",
-  "openapi_sha256": "9b2a79811fef658557233fc649b598178488985708b3ad10f252be598567080a",
+  "last_generated_at": "2026-05-14T01:35:40.409Z",
+  "openapi_sha256": "50112cd7017466815265d92e7d73cbc29be6bdc729a87db50989f189d562d201",
   "candidates_get": [
     {
       "method": "GET",
@@ -469,6 +469,14 @@
       ],
       "operationId": "aspects_acg_aspects_post"
     },
+    {
+      "method": "POST",
+      "path": "/acg/ccg/parans",
+      "tags": [
+        "ACG"
+      ],
+      "operationId": "acg_ccg_parans_post"
+    },
     {
       "method": "POST",
       "path": "/acg/ccg",
@@ -541,6 +549,14 @@
       ],
       "operationId": "midpoints_acg_midpoints_post"
     },
+    {
+      "method": "POST",
+      "path": "/acg/parans",
+      "tags": [
+        "ACG"
+      ],
+      "operationId": "acg_parans_post"
+    },
     {
       "method": "POST",
       "path": "/acg/power-lines",
@@ -549,6 +565,14 @@
       ],
       "operationId": "power_lines_acg_power_lines_post"
     },
+    {
+      "method": "POST",
+      "path": "/acg/relational-parans",
+      "tags": [
+        "ACG"
+      ],
+      "operationId": "acg_relational_parans_post"
+    },
     {
       "method": "POST",
       "path": "/chinese/bazi/annual-pillar",
@@ -699,7 +723,7 @@
       "tags": [
         "ephemeris"
       ],
-      "operationId": "calculate_draconic_chart_ephemeris_draconic_post"
+      "operationId": "CalculateDraconicChart"
     },
     {
       "method": "POST",
@@ -779,7 +803,7 @@
       "tags": [
         "ephemeris"
       ],
-      "operationId": "calculate_prenatal_lunation_ephemeris_prenatal_lunation_post"
+      "operationId": "CalculatePrenatalLunation"
     },
     {
       "method": "POST",

package/dist/index.js

@@ -10,6 +10,9 @@ import { listPrompts, getPromptContent } from "./prompts.js";
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
 import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
 import { BI_WHEEL_RESOURCE_URI, BI_WHEEL_MIME_TYPE, getBiWheelBundle, } from "./tools/apps/bi-wheel-app.js";
+import { TRANSIT_TIMELINE_RESOURCE_URI, TRANSIT_TIMELINE_MIME_TYPE, getTransitTimelineBundle, } from "./tools/apps/transit-timeline-app.js";
+import { MOON_PHASE_RESOURCE_URI, MOON_PHASE_MIME_TYPE, getMoonPhaseBundle, } from "./tools/apps/moon-phase-app.js";
+import { BAZI_RESOURCE_URI, BAZI_MIME_TYPE, getBaziBundle, } from "./tools/apps/bazi-app.js";
 function resolveServerVersion() {
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
@@ -124,6 +127,30 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
             mimeType: BI_WHEEL_MIME_TYPE,
         });
     }
+    if (getTransitTimelineBundle()) {
+        resources.push({
+            uri: TRANSIT_TIMELINE_RESOURCE_URI,
+            name: "Transit Timeline Explorer",
+            description: "Interactive Gantt-style transit timeline showing planetary aspects over time.",
+            mimeType: TRANSIT_TIMELINE_MIME_TYPE,
+        });
+    }
+    if (getMoonPhaseBundle()) {
+        resources.push({
+            uri: MOON_PHASE_RESOURCE_URI,
+            name: "Moon Phase Explorer",
+            description: "Interactive lunar phase dial showing illumination, sign, and void-of-course status.",
+            mimeType: MOON_PHASE_MIME_TYPE,
+        });
+    }
+    if (getBaziBundle()) {
+        resources.push({
+            uri: BAZI_RESOURCE_URI,
+            name: "BaZi Four Pillars Explorer",
+            description: "Interactive BaZi chart with pillars, Ten Gods, hidden stems, and Wu Xing balance.",
+            mimeType: BAZI_MIME_TYPE,
+        });
+    }
     return { resources };
 });
 // Read resource
@@ -147,6 +174,24 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             throw new Error("Bi-Wheel UI bundle not found. Run `npm run build:ui` to build it.");
         return { contents: [{ uri: BI_WHEEL_RESOURCE_URI, mimeType: BI_WHEEL_MIME_TYPE, text: bundle }] };
     }
+    if (uri === TRANSIT_TIMELINE_RESOURCE_URI) {
+        const bundle = getTransitTimelineBundle();
+        if (!bundle)
+            throw new Error("Transit Timeline UI bundle not found. Run `npm run build:ui` to build it.");
+        return { contents: [{ uri: TRANSIT_TIMELINE_RESOURCE_URI, mimeType: TRANSIT_TIMELINE_MIME_TYPE, text: bundle }] };
+    }
+    if (uri === MOON_PHASE_RESOURCE_URI) {
+        const bundle = getMoonPhaseBundle();
+        if (!bundle)
+            throw new Error("Moon Phase UI bundle not found. Run `npm run build:ui` to build it.");
+        return { contents: [{ uri: MOON_PHASE_RESOURCE_URI, mimeType: MOON_PHASE_MIME_TYPE, text: bundle }] };
+    }
+    if (uri === BAZI_RESOURCE_URI) {
+        const bundle = getBaziBundle();
+        if (!bundle)
+            throw new Error("BaZi UI bundle not found. Run `npm run build:ui` to build it.");
+        return { contents: [{ uri: BAZI_RESOURCE_URI, mimeType: BAZI_MIME_TYPE, text: bundle }] };
+    }
     throw new Error(`Unknown resource: ${uri}`);
 });
 // Handle tool calls

package/dist/oauth/dcr.d.ts

@@ -0,0 +1,11 @@
+/**
+ * src/oauth/dcr.ts — Dynamic Client Registration (RFC 7591).
+ *
+ * POST /oauth/register
+ *
+ * Deterministic client_id: SHA-256 of the sorted, joined redirect_uris.
+ * This means the same set of redirect URIs always produces the same client_id,
+ * making registration idempotent.
+ */
+import { type Router } from "express";
+export declare const oauthDcrRouter: Router;

package/dist/oauth/dcr.js

@@ -0,0 +1,49 @@
+/**
+ * src/oauth/dcr.ts — Dynamic Client Registration (RFC 7591).
+ *
+ * POST /oauth/register
+ *
+ * Deterministic client_id: SHA-256 of the sorted, joined redirect_uris.
+ * This means the same set of redirect URIs always produces the same client_id,
+ * making registration idempotent.
+ */
+import express from "express";
+import { createHash } from "node:crypto";
+export const oauthDcrRouter = express.Router();
+oauthDcrRouter.post("/oauth/register", (req, res) => {
+    // Validate Content-Type
+    const contentType = req.headers["content-type"];
+    if (!contentType || !contentType.includes("application/json")) {
+        res.status(400).json({
+            error: "invalid_request",
+            error_description: "Content-Type must be application/json.",
+        });
+        return;
+    }
+    const body = req.body;
+    // Validate redirect_uris
+    if (!body ||
+        !Array.isArray(body.redirect_uris) ||
+        body.redirect_uris.length === 0) {
+        res.status(400).json({
+            error: "invalid_client_metadata",
+            error_description: "redirect_uris must be a non-empty array of strings.",
+        });
+        return;
+    }
+    const redirect_uris = body.redirect_uris;
+    const client_name = body.client_name || "Unknown Client";
+    // Deterministic client_id: SHA-256 of sorted redirect URIs
+    const uriFingerprint = [...redirect_uris].sort().join("\n");
+    const client_id = createHash("sha256")
+        .update(uriFingerprint, "utf8")
+        .digest("hex");
+    res.status(201).json({
+        client_id,
+        client_name,
+        redirect_uris,
+        grant_types: ["authorization_code", "refresh_token"],
+        token_endpoint_auth_method: "none",
+        created_at: new Date().toISOString(),
+    });
+});

package/dist/oauth/discovery.d.ts

@@ -0,0 +1,11 @@
+/**
+ * src/oauth/discovery.ts — OAuth 2.1 Discovery endpoints.
+ *
+ * Implements:
+ *   GET /.well-known/oauth-protected-resource  (RFC 8707)
+ *   GET /.well-known/oauth-authorization-server (RFC 8414)
+ *
+ * All URLs use https:// per the OAuth 2.1 specification.
+ */
+import { type Router } from "express";
+export declare const oauthDiscoveryRouter: Router;

package/dist/oauth/discovery.js

@@ -0,0 +1,40 @@
+/**
+ * src/oauth/discovery.ts — OAuth 2.1 Discovery endpoints.
+ *
+ * Implements:
+ *   GET /.well-known/oauth-protected-resource  (RFC 8707)
+ *   GET /.well-known/oauth-authorization-server (RFC 8414)
+ *
+ * All URLs use https:// per the OAuth 2.1 specification.
+ */
+import express from "express";
+const MCP_SERVER_ORIGIN = "https://mcp.openephemeris.com";
+const WEB_APP_ORIGIN = "https://openephemeris.com";
+export const oauthDiscoveryRouter = express.Router();
+// ---------------------------------------------------------------------------
+// GET /.well-known/oauth-protected-resource
+// ---------------------------------------------------------------------------
+oauthDiscoveryRouter.get("/.well-known/oauth-protected-resource", (_req, res) => {
+    res.json({
+        resource: MCP_SERVER_ORIGIN,
+        authorization_servers: [MCP_SERVER_ORIGIN],
+        bearer_methods_supported: ["header"],
+        scopes_supported: ["openephemeris:read"],
+    });
+});
+// ---------------------------------------------------------------------------
+// GET /.well-known/oauth-authorization-server
+// ---------------------------------------------------------------------------
+oauthDiscoveryRouter.get("/.well-known/oauth-authorization-server", (_req, res) => {
+    res.json({
+        issuer: MCP_SERVER_ORIGIN,
+        authorization_endpoint: `${WEB_APP_ORIGIN}/oauth/authorize`,
+        token_endpoint: `${MCP_SERVER_ORIGIN}/oauth/token`,
+        registration_endpoint: `${MCP_SERVER_ORIGIN}/oauth/register`,
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["none"],
+        scopes_supported: ["openephemeris:read"],
+    });
+});

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,18 @@
+/**
+ * src/oauth/pkce.ts — PKCE (Proof Key for Code Exchange) utilities.
+ *
+ * Implements RFC 7636 S256 challenge verification and cryptographically
+ * random authorization code generation.
+ */
+/**
+ * Verify that `code_challenge === base64url(SHA-256(code_verifier))`.
+ *
+ * Uses crypto.timingSafeEqual for the final comparison to prevent
+ * timing side-channel attacks.
+ */
+export declare function verifyCodeChallenge(code_verifier: string, code_challenge: string): boolean;
+/**
+ * Generate a cryptographically random authorization code.
+ * Returns 64 hex characters (32 random bytes).
+ */
+export declare function generateAuthorizationCode(): string;

package/dist/oauth/pkce.js

@@ -0,0 +1,34 @@
+/**
+ * src/oauth/pkce.ts — PKCE (Proof Key for Code Exchange) utilities.
+ *
+ * Implements RFC 7636 S256 challenge verification and cryptographically
+ * random authorization code generation.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+/**
+ * Verify that `code_challenge === base64url(SHA-256(code_verifier))`.
+ *
+ * Uses crypto.timingSafeEqual for the final comparison to prevent
+ * timing side-channel attacks.
+ */
+export function verifyCodeChallenge(code_verifier, code_challenge) {
+    if (!code_verifier || !code_challenge)
+        return false;
+    // SHA-256 hash the verifier and base64url encode it
+    const computed = createHash("sha256")
+        .update(code_verifier, "ascii")
+        .digest("base64url");
+    // Buffers must be equal length for timingSafeEqual
+    const computedBuf = Buffer.from(computed, "utf8");
+    const challengeBuf = Buffer.from(code_challenge, "utf8");
+    if (computedBuf.length !== challengeBuf.length)
+        return false;
+    return timingSafeEqual(computedBuf, challengeBuf);
+}
+/**
+ * Generate a cryptographically random authorization code.
+ * Returns 64 hex characters (32 random bytes).
+ */
+export function generateAuthorizationCode() {
+    return randomBytes(32).toString("hex");
+}

package/dist/oauth/rate-limit.d.ts

@@ -0,0 +1,20 @@
+/**
+ * src/oauth/rate-limit.ts — Simple per-IP rate limiter for the token endpoint.
+ *
+ * No external dependencies — uses a plain Map + setInterval for cleanup.
+ *
+ * Usage:
+ *   app.use("/oauth/token", createRateLimiter({ windowMs: 60_000, maxRequests: 10 }));
+ */
+import type { Request, Response, NextFunction } from "express";
+export interface RateLimiterOptions {
+    windowMs: number;
+    maxRequests: number;
+    trustProxy?: boolean;
+}
+/**
+ * Creates a rate-limiting Express middleware.
+ *
+ * Returns 429 with Retry-After header when the per-IP limit is exceeded.
+ */
+export declare function createRateLimiter(options: RateLimiterOptions): (req: Request, res: Response, next: NextFunction) => void;

package/dist/oauth/rate-limit.js

@@ -0,0 +1,65 @@
+/**
+ * src/oauth/rate-limit.ts — Simple per-IP rate limiter for the token endpoint.
+ *
+ * No external dependencies — uses a plain Map + setInterval for cleanup.
+ *
+ * Usage:
+ *   app.use("/oauth/token", createRateLimiter({ windowMs: 60_000, maxRequests: 10 }));
+ */
+/**
+ * Creates a rate-limiting Express middleware.
+ *
+ * Returns 429 with Retry-After header when the per-IP limit is exceeded.
+ */
+export function createRateLimiter(options) {
+    const { windowMs, maxRequests, trustProxy = false } = options;
+    const store = new Map();
+    // Cleanup expired entries every windowMs
+    const cleanupTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [ip, entry] of store) {
+            if (entry.resetAt <= now) {
+                store.delete(ip);
+            }
+        }
+    }, windowMs);
+    if (cleanupTimer.unref)
+        cleanupTimer.unref();
+    return (req, res, next) => {
+        // Determine client IP
+        let ip;
+        if (trustProxy) {
+            const forwarded = req.headers["x-forwarded-for"];
+            if (typeof forwarded === "string") {
+                ip = forwarded.split(",")[0].trim();
+            }
+            else if (Array.isArray(forwarded) && forwarded.length > 0) {
+                ip = forwarded[0].split(",")[0].trim();
+            }
+            else {
+                ip = req.ip || req.socket.remoteAddress || "unknown";
+            }
+        }
+        else {
+            ip = req.ip || req.socket.remoteAddress || "unknown";
+        }
+        const now = Date.now();
+        let entry = store.get(ip);
+        // Reset window if expired
+        if (!entry || entry.resetAt <= now) {
+            entry = { count: 0, resetAt: now + windowMs };
+            store.set(ip, entry);
+        }
+        entry.count++;
+        if (entry.count > maxRequests) {
+            const retryAfterSec = Math.ceil((entry.resetAt - now) / 1_000);
+            res.setHeader("Retry-After", String(retryAfterSec));
+            res.status(429).json({
+                error: "rate_limit_exceeded",
+                error_description: "Too many requests. Please try again later.",
+            });
+            return;
+        }
+        next();
+    };
+}

package/dist/oauth/store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * src/oauth/store.ts — OAuth authorization code store.
+ *
+ * Architecture: in-memory is always the source of truth for the MCP server
+ * process. When Supabase env vars are present AND valid, codes are ALSO
+ * persisted async to Supabase for durability and multi-instance lookup.
+ *
+ * This means:
+ *   - Unit tests (no env vars) → pure in-memory, zero network calls ✓
+ *   - Production (Supabase set)  → in-memory for hot-path, Supabase for
+ *     persistence/audit trail ✓
+ *
+ * NOTE: The consent page (/api/oauth/approve) writes directly to Supabase
+ * using the service role key without going through this store.  The store
+ * is used by the MCP server's own /oauth/* endpoints.
+ *
+ * Security:
+ *   - NEVER log the `code` value.  Log only the row `id` (uuid).
+ *   - consumeCodeAsync marks codes consumed atomically in Supabase when
+ *     Supabase is reachable; falls through to in-memory otherwise.
+ */
+export interface IssuedCodeOptions {
+    client_id: string;
+    redirect_uri: string;
+    code_challenge: string;
+    code_challenge_method: "S256";
+    /** Optional user_id — set by consent page; undefined in unit tests */
+    user_id?: string;
+    expiresInMs?: number;
+}
+export declare class OAuthStore {
+    /** In-memory is ALWAYS the hot-path source of truth */
+    private codes;
+    private refreshTokens;
+    private cleanupTimer;
+    constructor();
+    /**
+     * Issue a new authorization code.
+     *
+     * Always writes to in-memory (fast, test-safe).
+     * Also fire-and-forgets a Supabase persist when env vars are set.
+     */
+    issueCode(options: IssuedCodeOptions): string;
+    /**
+     * Consume a code synchronously from in-memory (single-use).
+     * This is the fast-path used by the token endpoint.
+     */
+    consumeCode(code: string): (IssuedCodeOptions & {
+        used: boolean;
+        expires_at: Date;
+    }) | null;
+    /**
+     * Async consume — checks in-memory first, then Supabase.
+     *
+     * Use this from token.ts so production deployments with Supabase
+     * can survive process restarts (code issued before restart lives in DB).
+     */
+    consumeCodeAsync(code: string): Promise<(IssuedCodeOptions & {
+        used: boolean;
+        expires_at: Date;
+    }) | null>;
+    storeRefreshToken(token: string, meta: object): void;
+    consumeRefreshToken(token: string): object | null;
+    generateRefreshToken(): string;
+    reset(): void;
+    private purgeExpired;
+    destroy(): void;
+}