@openephemeris/mcp-server 3.1.0 → 3.2.2

package/dist/src/server-sse.js

@@ -0,0 +1,264 @@
+/**
+ * server-sse.ts — Remote SSE transport for the OpenEphemeris MCP server.
+ *
+ * This wraps the exact same tool registry used by the local stdio server
+ * but exposes it over HTTP + Server-Sent Events so that Claude Web,
+ * Claude Mobile (future), and any remote MCP client can connect via URL.
+ *
+ * Architecture:
+ *   - The SSE server validates the user's API key at connection time by
+ *     making a lightweight call to the Go backend.
+ *   - All subsequent tool calls use the server's OPENEPHEMERIS_SERVICE_KEY
+ *     (set as a Fly secret) via the singleton BackendClient's X-Service-Key header.
+ *   - This avoids the need to refactor all tool handlers for per-session auth.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import express from "express";
+import axios from "axios";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { initTools, toolRegistry } from "./tools/index.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveServerVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        // Try multiple levels up — compiled JS is at dist/src/, source is at src/
+        for (const rel of ["..", "../.."]) {
+            const pkgPath = path.resolve(here, rel, "package.json");
+            try {
+                const raw = fs.readFileSync(pkgPath, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (typeof parsed.version === "string" && parsed.version.trim()) {
+                    return parsed.version.trim();
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0-unknown";
+}
+const PORT = parseInt(process.env.PORT || "3001", 10);
+const BACKEND_URL = process.env.OPENEPHEMERIS_BACKEND_URL ||
+    process.env.ASTROMCP_BACKEND_URL ||
+    "https://api.openephemeris.com";
+const version = resolveServerVersion();
+/**
+ * Validate a user-supplied API key by hitting an auth-gated endpoint on
+ * the Go sidecar. Returns true if the key yields a 2xx, false on 401/403.
+ */
+async function validateApiKey(apiKey) {
+    try {
+        const resp = await axios.get(`${BACKEND_URL}/ephemeris/moon/phase`, {
+            headers: { "X-API-Key": apiKey },
+            timeout: 5_000,
+            validateStatus: () => true, // don't throw on any status
+        });
+        // 2xx = valid key, 401/403 = invalid key, anything else = let through
+        if (resp.status === 401 || resp.status === 403)
+            return false;
+        return true;
+    }
+    catch {
+        // Network error — let them through; tool calls will fail if key is bad.
+        console.warn("Could not validate API key against backend, allowing connection.");
+        return true;
+    }
+}
+// ---------------------------------------------------------------------------
+// MCP Server factory — one per SSE session
+// ---------------------------------------------------------------------------
+function createMcpServer() {
+    const server = new Server({
+        name: "openephemeris-mcp",
+        version,
+        icons: [
+            {
+                src: "https://mcp.openephemeris.com/icon.png",
+                mimeType: "image/png",
+            }
+        ]
+    }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: Object.values(toolRegistry).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations ?? {
+                title: tool.name,
+                readOnlyHint: true,
+                destructiveHint: false,
+            },
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const toolName = request.params.name;
+        const tool = toolRegistry[toolName];
+        if (!tool) {
+            throw new Error(`Unknown tool: ${toolName}`);
+        }
+        try {
+            const result = await tool.handler(request.params.arguments ?? {});
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: false, error: "TOOL_EXECUTION_ERROR", message: errorMessage }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}
+// ---------------------------------------------------------------------------
+// Express + SSE wiring
+// ---------------------------------------------------------------------------
+async function main() {
+    await initTools();
+    const app = express();
+    // NOTE: Do NOT use express.json() globally — SSEServerTransport.handlePostMessage
+    // reads the raw request stream itself. Pre-parsing with express.json() consumes it,
+    // causing "stream is not readable" errors.
+    // CORS — required for Claude Web cross-origin SSE connections
+    app.use((_req, res, next) => {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-API-Key, X-Meridian-API-Key");
+        if (_req.method === "OPTIONS") {
+            res.status(204).end();
+            return;
+        }
+        next();
+    });
+    // Track active transports by session ID
+    const transports = new Map();
+    // Health check
+    app.get("/health", (_req, res) => {
+        res.json({ ok: true, version, transport: "sse", sessions: transports.size });
+    });
+    // Serve the MCP icon (earth + star)
+    // Compiled JS at dist/src/server-sse.js: ../../assets
+    // Source TS at src/server-sse.ts: ../assets
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const assetsDir = fs.existsSync(path.resolve(here, "..", "..", "assets"))
+        ? path.resolve(here, "..", "..", "assets")
+        : path.resolve(here, "..", "assets");
+    app.get("/icon.png", (_req, res) => {
+        const iconPath = path.join(assetsDir, "icon.png");
+        if (fs.existsSync(iconPath)) {
+            res.setHeader("Cache-Control", "public, max-age=86400");
+            res.sendFile(iconPath);
+        }
+        else {
+            res.status(404).end();
+        }
+    });
+    app.get("/favicon.ico", (_req, res) => {
+        const iconPath = path.join(assetsDir, "icon.png");
+        if (fs.existsSync(iconPath)) {
+            res.setHeader("Content-Type", "image/png");
+            res.setHeader("Cache-Control", "public, max-age=86400");
+            res.sendFile(iconPath);
+        }
+        else {
+            res.status(404).end();
+        }
+    });
+    // SSE endpoint — clients GET /sse to establish a stream
+    app.get("/sse", async (req, res) => {
+        // Extract API key from query param or header
+        const apiKey = req.query.apiKey ||
+            req.headers["x-api-key"] ||
+            req.headers["x-meridian-api-key"] ||
+            req.headers["authorization"]?.replace(/^Bearer\s+/i, "");
+        if (!apiKey) {
+            res.status(401).json({
+                error: "api_key_required",
+                message: "An OpenEphemeris API key is required. Generate one at https://openephemeris.com/dashboard?tab=apikeys",
+            });
+            return;
+        }
+        // Validate the user's key against the Go backend
+        const valid = await validateApiKey(apiKey);
+        if (!valid) {
+            res.status(403).json({
+                error: "invalid_api_key",
+                message: "The provided API key is invalid or inactive. Check your key at https://openephemeris.com/dashboard?tab=apikeys",
+            });
+            return;
+        }
+        const transport = new SSEServerTransport("/message", res);
+        const sessionId = transport.sessionId;
+        transports.set(sessionId, transport);
+        const server = createMcpServer();
+        // Guard: prevent double-close from crashing the process
+        let closed = false;
+        const cleanup = () => {
+            if (closed)
+                return;
+            closed = true;
+            transports.delete(sessionId);
+            try {
+                server.close().catch(() => { });
+            }
+            catch { /* ignore */ }
+        };
+        transport.onclose = cleanup;
+        // Handle abrupt client disconnects (browser tab closed, etc.)
+        res.on("close", cleanup);
+        try {
+            // server.connect() calls transport.start() internally in SDK v1.27+
+            await server.connect(transport);
+        }
+        catch (err) {
+            console.error(`SSE session ${sessionId} failed to start:`, err);
+            cleanup();
+        }
+    });
+    // Message endpoint — clients POST /message?sessionId=xxx
+    app.post("/message", async (req, res) => {
+        const sessionId = req.query.sessionId;
+        const transport = transports.get(sessionId);
+        if (!transport) {
+            res.status(400).json({
+                error: "invalid_session",
+                message: "Unknown or expired session. Re-connect to /sse first.",
+            });
+            return;
+        }
+        await transport.handlePostMessage(req, res);
+    });
+    app.listen(PORT, "0.0.0.0", () => {
+        console.log(`OpenEphemeris MCP SSE server v${version} listening on port ${PORT}`);
+    });
+}
+// Prevent SDK recursive close bugs from crashing the process
+process.on("uncaughtException", (err) => {
+    if (err instanceof RangeError && err.message.includes("call stack")) {
+        console.error("Caught stack overflow (likely SDK close recursion), ignoring.");
+        return;
+    }
+    console.error("Uncaught exception:", err);
+    process.exit(1);
+});
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/src/tools/auth.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/auth.js

@@ -0,0 +1,202 @@
+import { registerTool } from "./index.js";
+import { CredentialManager } from "../auth/credentials.js";
+import { DeviceAuthFlow } from "../auth/device-auth.js";
+const credentialManager = new CredentialManager();
+// ────────────────────────────────────────────────────────
+// auth.login — Start the device authorization flow
+// ────────────────────────────────────────────────────────
+registerTool({
+    name: "auth_login",
+    description: "Start the device authorization flow to connect this MCP server to your OpenEphemeris account. " +
+        "Returns a verification URL and code for the user to enter in their browser. " +
+        "The MCP server will then automatically receive credentials and all API calls will be " +
+        "linked to the user's account (tier, credits, rate limits). " +
+        "Only needed if no OPENEPHEMERIS_API_KEY env var is set and no cached credentials exist.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "Connect Account",
+        readOnlyHint: false,
+        destructiveHint: false,
+    },
+    handler: async () => {
+        // Check if already authenticated
+        const status = credentialManager.getStatus();
+        if (status.authenticated) {
+            return {
+                already_authenticated: true,
+                email: status.email,
+                user_id: status.userId,
+                expires_at: status.expiresAt,
+                message: `Already authenticated as ${status.email}. Use auth_logout to disconnect.`,
+            };
+        }
+        // Check if env var credentials are set
+        if (process.env.OPENEPHEMERIS_API_KEY ||
+            process.env.OPENEPHEMERIS_JWT ||
+            process.env.OPENEPHEMERIS_SERVICE_KEY) {
+            return {
+                already_authenticated: true,
+                method: "environment_variable",
+                message: "Credentials are configured via environment variables. " +
+                    "Device auth is not needed.",
+            };
+        }
+        // Start the device auth flow
+        const flow = new DeviceAuthFlow();
+        const startResult = await flow.start();
+        // Begin polling in the background — this runs until the user authorizes
+        // or the code expires. We don't await it here because the tool should
+        // return immediately with the code for the user.
+        flow
+            .poll(startResult.device_code, (attempt) => {
+            if (attempt % 6 === 0) {
+                console.error(`Still waiting... Visit ${startResult.verification_uri} and enter code: ${startResult.user_code}`);
+            }
+        })
+            .then((result) => {
+            console.error(`✅ Authenticated as ${result.user?.email || "user"}`);
+            console.error(`   Credentials saved to ${CredentialManager.credentialsPath}`);
+        })
+            .catch((err) => {
+            console.error(`❌ Device auth failed: ${err.message}`);
+        });
+        return {
+            action_required: true,
+            verification_uri: startResult.verification_uri,
+            user_code: startResult.user_code,
+            verification_uri_complete: startResult.verification_uri_complete,
+            expires_in: startResult.expires_in,
+            message: `Please visit ${startResult.verification_uri} and enter the code: ${startResult.user_code}. ` +
+                `Alternatively, open this direct link: ${startResult.verification_uri_complete}. ` +
+                `The server is polling in the background — once you authorize, all subsequent ` +
+                `tool calls will be linked to your account automatically.`,
+            instructions_for_agent: "Present the verification URL and code to the user clearly. " +
+                "They need to open the URL in a browser, log in to their OpenEphemeris account, " +
+                "and enter the code. After that, all API calls will work automatically. " +
+                "Wait 10-15 seconds after the user confirms they've entered the code, " +
+                "then try the original request again.",
+        };
+    },
+});
+// ────────────────────────────────────────────────────────
+// auth.status — Check current authentication state
+// ────────────────────────────────────────────────────────
+registerTool({
+    name: "auth_status",
+    description: "Check the current authentication status of this MCP server. " +
+        "Shows whether the server is authenticated, which account it's linked to, " +
+        "the authentication method (API key, JWT, device auth), and token expiry.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "Auth Status",
+        readOnlyHint: true,
+        destructiveHint: false,
+    },
+    handler: async () => {
+        // Check env var methods first
+        const hasApiKey = !!(process.env.OPENEPHEMERIS_API_KEY ||
+            process.env.ASTROMCP_API_KEY ||
+            process.env.MERIDIAN_API_KEY);
+        const hasJwt = !!(process.env.OPENEPHEMERIS_JWT ||
+            process.env.ASTROMCP_JWT ||
+            process.env.MERIDIAN_AUTH_TOKEN);
+        const hasServiceKey = !!(process.env.OPENEPHEMERIS_SERVICE_KEY ||
+            process.env.ASTROMCP_SERVICE_KEY ||
+            process.env.MERIDIAN_SERVICE_KEY);
+        if (hasServiceKey) {
+            return {
+                authenticated: true,
+                method: "service_key",
+                message: "Authenticated via service key (admin/internal access).",
+            };
+        }
+        if (hasApiKey) {
+            return {
+                authenticated: true,
+                method: "api_key",
+                message: "Authenticated via API key environment variable.",
+            };
+        }
+        if (hasJwt) {
+            return {
+                authenticated: true,
+                method: "jwt_env_var",
+                message: "Authenticated via JWT environment variable.",
+            };
+        }
+        // Check cached credentials
+        const status = credentialManager.getStatus();
+        if (status.authenticated) {
+            return {
+                authenticated: true,
+                method: "device_auth",
+                email: status.email,
+                user_id: status.userId,
+                expires_at: status.expiresAt,
+                credentials_path: CredentialManager.credentialsPath,
+                message: `Authenticated as ${status.email} via device authorization.`,
+            };
+        }
+        // Check if credentials exist but are expired
+        const creds = credentialManager.load();
+        if (creds) {
+            return {
+                authenticated: false,
+                method: "device_auth_expired",
+                email: creds.user_email,
+                expired_at: creds.expires_at,
+                message: "Device auth credentials exist but are expired. " +
+                    "The server will attempt to refresh automatically on the next API call, " +
+                    "or you can run auth_login to re-authenticate.",
+            };
+        }
+        return {
+            authenticated: false,
+            method: "none",
+            message: "Not authenticated. Set OPENEPHEMERIS_API_KEY in your MCP server config, " +
+                "or run auth_login to connect your account interactively.",
+        };
+    },
+});
+// ────────────────────────────────────────────────────────
+// auth.logout — Clear cached credentials
+// ────────────────────────────────────────────────────────
+registerTool({
+    name: "auth_logout",
+    description: "Disconnect this MCP server from your OpenEphemeris account by clearing " +
+        "cached credentials. Does NOT revoke the API key if one is set via environment " +
+        "variable — only clears device-auth cached credentials.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "Disconnect Account",
+        readOnlyHint: false,
+        destructiveHint: true,
+    },
+    handler: async () => {
+        const status = credentialManager.getStatus();
+        if (!status.authenticated && !credentialManager.load()) {
+            return {
+                success: true,
+                message: "No cached credentials to clear.",
+            };
+        }
+        credentialManager.clear();
+        return {
+            success: true,
+            previous_email: status.email,
+            message: `Disconnected. Cached credentials for ${status.email || "unknown user"} have been removed.`,
+        };
+    },
+});

package/dist/src/tools/dev.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/dev.js

@@ -0,0 +1,195 @@
+import { registerTool, validateRequired } from "./index.js";
+import { backendClient } from "../backend/client.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function getAllowlistPath() {
+    const envPath = process.env.OPENEPHEMERIS_DEV_ALLOWLIST_PATH || process.env.ASTROMCP_DEV_ALLOWLIST_PATH;
+    if (envPath && envPath.trim())
+        return envPath;
+    // dist lives at mcp-server/dist; src lives at mcp-server/src.
+    // We resolve relative to current file location for both dev+prod.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    let mcpServerRoot = path.resolve(here, "..", "..");
+    if (path.basename(mcpServerRoot) === "dist") {
+        mcpServerRoot = path.resolve(mcpServerRoot, "..");
+    }
+    return path.join(mcpServerRoot, "config", "dev-allowlist.json");
+}
+function loadAllowlist() {
+    const allowlistPath = getAllowlistPath();
+    const raw = fs.readFileSync(allowlistPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || parsed.schema !== "astromcp-dev-allowlist-v1" || !Array.isArray(parsed.allow)) {
+        throw new Error(`Invalid allowlist file at ${allowlistPath}. Expected schema astromcp-dev-allowlist-v1.`);
+    }
+    return parsed;
+}
+function isDeniedByPrefix(pathname, prefixes) {
+    return prefixes.some((p) => pathname.startsWith(p));
+}
+function isAllowedOperation(method, pathname, allow) {
+    return allow.some((e) => e.method === method && e.path === pathname);
+}
+registerTool({
+    name: "dev_call",
+    description: "Call any allowlisted Open Ephemeris API endpoint directly. This is the power-user escape hatch " +
+        "— use the typed tools (ephemeris_natal_chart, ephemeris_transits, etc.) first for common operations. " +
+        "Call dev_list_allowed to see all currently available endpoint paths.\n\n" +
+        "AUTH: Set OPENEPHEMERIS_API_KEY in your environment. See openephemeris.com/dashboard for active plan limits.\n\n" +
+        "CREDIT COSTS:\n" +
+        "  • Standard chart math (natal, progressed, bazi, HD): 1 credit\n" +
+        "  • Visualization rendering (chart-wheel, bi-wheel, charts/*): 2 credits\n" +
+        "  • Comparative math (synastry, composite, overlay): 3 credits\n" +
+        "  • Predictive ops (transits, returns, transit-chart): 5 credits\n" +
+        "  • ACG / astrocartography: 5 credits\n" +
+        "  • Catalog / metadata / health endpoints: 0 credits\n" +
+        "  • format=llm (token-optimized output): available on all tiers\n\n" +
+        "COMMON CALLS:\n" +
+        "  POST /ephemeris/natal-chart            — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}})\n" +
+        "  POST /ephemeris/natal/batch            — Up to 50 natal charts in one request\n" +
+        "  POST /ephemeris/relocation             — Relocated chart (same natal, new location)\n" +
+        "  POST /predictive/transits/search       — Transit event search over a date range\n" +
+        "  POST /predictive/returns/solar         — Solar return chart\n" +
+        "  POST /predictive/returns/lunar         — Lunar return chart\n" +
+        "  POST /comparative/synastry             — Two-person synastry chart\n" +
+        "  POST /comparative/composite            — Composite (midpoint) chart\n" +
+        "  POST /human-design/chart               — Full HD bodygraph (body: {birth_datetime_utc: '1990-04-15T19:30:00Z'}) — lat/lon optional\n" +
+        "  POST /time/julian-day                  — Convert date to JD (body: {year: 1987, month: 7, day: 15, hour: 14, minute: 1})\n" +
+        "  GET  /ephemeris/moon/phase             — Current/queried moon phase\n" +
+        "  GET  /ephemeris/moon/void-of-course    — Next void-of-course period\n" +
+        "  GET  /ephemeris/agro/daily             — Biodynamic farming day quality\n" +
+        "  GET  /ephemeris/agro/calendar          — Multi-day biodynamic calendar\n" +
+        "  GET  /ephemeris/agro/void-of-course    — Biodynamic VoC periods\n" +
+        "  GET  /eclipse/next-visible             — Next eclipse visible from a location (query: lat, lon, type=solar|lunar)\n" +
+        "  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)\n" +
+        "  GET  /eclipse/solar/local              — Local solar eclipse (query: lat, lon)\n" +
+        "  GET  /tidal/forcing                    — Gravitational tidal forcing index\n" +
+        "  GET  /tidal/forcing/deep-time          — Extended tidal deep-time analysis\n" +
+        "  POST /acg/power-lines                 — Astrocartography power lines (lat/lon GeoJSON)\n" +
+        "  POST /acg/hits                         — ACG power at a specific location\n" +
+        "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
+        "  GET  /location/autocomplete            — Geocode a place name (query: q=City Name)\n" +
+        "  POST /timezone/lookup                  — Resolve timezone + UTC offset for a location\n" +
+        "  POST /chinese/bazi                     — Chinese Ba Zi (Four Pillars) chart (body: {year, month, day, hour})\n" +
+        "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
+        "  POST /vedic/chart                      — Vedic (Jyotish) natal chart (body: {datetime_utc, latitude, longitude})\n" +
+        "  GET  /catalogs/bodies                  — List all supported celestial bodies\n\n" +
+        "BINARY RESPONSES:\n" +
+        "  • Binary/image endpoints return {content_type, content_length, encoding, data_base64}\n" +
+        "    so callers can decode bytes deterministically.\n\n" +
+        "ECLIPSE NOTE: Eclipse endpoints accept format=llm via the query param like other endpoints.\n\n" +
+        "format=llm NOTE: Add query: {format: 'llm'} to natal/synastry/composite/HD endpoints for " +
+        "compact columnar output optimized for LLM token budgets (availability depends on your current plan).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            method: {
+                type: "string",
+                enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+                description: "HTTP method",
+            },
+            path: {
+                type: "string",
+                description: "Absolute API path (e.g., /ephemeris/natal-chart)",
+            },
+            query: {
+                type: "object",
+                additionalProperties: true,
+                description: "Query params for GET requests (optional)",
+            },
+            body: {
+                description: "JSON body for POST/PUT/PATCH (optional)",
+            },
+            preset: {
+                type: "string",
+                enum: ["full", "simple"],
+                description: "Convenience: if provided, set query.preset (optional).",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm", "llm_v2"],
+                description: "Convenience: if provided, set query.format (optional). 'llm' is canonical; 'llm_v2' is accepted as a legacy alias.",
+            },
+            output_mode: {
+                type: "string",
+                enum: ["full", "simple", "llm", "llm_v2"],
+                description: "Legacy convenience (deprecated): if provided, set query.output_mode and also map to query.preset/query.format when possible.",
+            },
+        },
+        required: ["method", "path"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["path"]);
+        const methodStr = String(args.method || "GET").toUpperCase();
+        if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(methodStr)) {
+            throw new Error(`Invalid HTTP method: ${methodStr}`);
+        }
+        const method = methodStr;
+        const pathname = String(args.path);
+        if (!pathname.startsWith("/")) {
+            throw new Error("path must start with '/'");
+        }
+        const allowlist = loadAllowlist();
+        const denyPrefixes = allowlist.deny?.path_prefixes ?? [];
+        if (denyPrefixes.length > 0 && isDeniedByPrefix(pathname, denyPrefixes)) {
+            throw new Error(`Endpoint denied by policy: ${pathname}`);
+        }
+        if (!isAllowedOperation(method, pathname, allowlist.allow)) {
+            throw new Error(`Endpoint not allowlisted: ${method} ${pathname}`);
+        }
+        const queryBase = args.query && typeof args.query === "object" ? args.query : {};
+        const query = { ...queryBase };
+        const body = args.body;
+        if (args.preset) {
+            query.preset = args.preset;
+        }
+        if (args.format) {
+            const rawFormat = String(args.format).trim().toLowerCase();
+            // Canonical: "llm". Normalize legacy alias "llm_v2" → "llm".
+            query.format = rawFormat === "llm_v2" ? "llm" : rawFormat;
+        }
+        // Legacy: output_mode used to overload both compute preset and output projection.
+        // Keep forwarding it for older endpoints, but also map it to preset/format for new endpoints.
+        if (args.output_mode) {
+            const rawMode = String(args.output_mode).trim().toLowerCase();
+            query.output_mode = rawMode;
+            if ((rawMode === "full" || rawMode === "simple") && query.preset == null) {
+                query.preset = rawMode;
+            }
+            if ((rawMode === "llm" || rawMode === "llm_v2") && query.format == null) {
+                query.format = "llm";
+            }
+        }
+        return await backendClient.request(method, pathname, {
+            params: query,
+            data: body,
+        });
+    },
+});
+registerTool({
+    name: "dev_list_allowed",
+    description: "List all API operations (method + path) that this MCP instance is authorized to call. " +
+        "Returns endpoint entries grouped by method, plus the active deny rules. " +
+        "Use this to discover what's available before calling dev_call, or to verify an endpoint path. " +
+        "Typed shortcut tools (ephemeris_natal_chart, ephemeris_transits, etc.) cover the most common operations — " +
+        "check those first before reaching for dev_call.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    handler: async () => {
+        const allowlist = loadAllowlist();
+        return {
+            schema: allowlist.schema,
+            generated_from: allowlist.generated_from,
+            deny: allowlist.deny ?? null,
+            allow: allowlist.allow,
+            counts: {
+                allow: allowlist.allow.length,
+            },
+        };
+    },
+});