@openephemeris/mcp-server 3.2.12 → 3.2.13

package/dist/backend/client.d.ts

@@ -21,20 +21,42 @@ export interface BinaryBackendResponse {
     encoding: "base64";
     data_base64: string;
 }
+export declare class BackendError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly upgradeUrl?: string | undefined;
+    constructor(message: string, status: number, code: string, retryable: boolean, upgradeUrl?: string | undefined);
+}
 export declare class BackendClient {
     private client;
     private userId;
     private jwt?;
     private serviceKey?;
     private apiKey?;
+    private credentialManager;
+    private _pendingAuthFlow;
+    private _authFlowResult;
     constructor(config: BackendConfig);
+    /**
+     * Override the API key at runtime. Used by the SSE server to inject the
+     * per-session user's key so that all tool calls are authenticated and
+     * metered against the correct user account.
+     */
+    setApiKey(key: string): void;
+    /**
+     * Start the device auth flow in the background if not already running.
+     * Called automatically when no credentials are found in the interceptor.
+     * Idempotent — only starts once per client lifetime.
+     */
+    private autoStartDeviceAuth;
     private expectsBinaryResponse;
     private toBuffer;
     private decodePayload;
     private extractMessage;
     private normalizeContentType;
     private isBinaryContentType;
-    /** Maps an AxiosError to a concise MCP-friendly Error. */
+    /** Maps an AxiosError to a structured BackendError. */
     private mapError;
     get<T>(path: string, params?: Record<string, any>, timeoutMs?: number): Promise<T>;
     post<T>(path: string, data?: any, timeoutMs?: number): Promise<T>;

package/dist/backend/client.js

@@ -1,6 +1,10 @@
 import axios, { AxiosError } from "axios";
+import { CredentialManager } from "../auth/credentials.js";
+import { DeviceAuthFlow } from "../auth/device-auth.js";
 const DEFAULT_TIMEOUT_MS = 45_000;
-const RATE_LIMIT_RETRY_DELAYS_MS = [1_000, 2_000]; // Two retries on 429
+const RETRY_DELAYS_MS = [1_000, 2_000, 4_000]; // Three retries with backoff
+const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+const RETRYABLE_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "ENOTFOUND", "EAI_AGAIN"]);
 const BINARY_ENDPOINT_PREFIXES = [
     "/visualization/bi-wheel",
     "/visualization/chart-wheel",
@@ -13,29 +17,51 @@ const UPGRADE_URL = "https://openephemeris.com/pay";
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+export class BackendError extends Error {
+    status;
+    code;
+    retryable;
+    upgradeUrl;
+    constructor(message, status, code, retryable, upgradeUrl) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryable = retryable;
+        this.upgradeUrl = upgradeUrl;
+        this.name = "BackendError";
+    }
+}
 export class BackendClient {
     client;
     userId;
     jwt;
     serviceKey;
     apiKey;
+    credentialManager;
+    _pendingAuthFlow = null;
+    _authFlowResult = null;
     constructor(config) {
         this.userId = config.userId || "anonymous";
         this.jwt =
             config.jwt ||
                 config.authToken ||
+                process.env.OPENEPHEMERIS_JWT ||
                 process.env.ASTROMCP_JWT ||
                 process.env.MERIDIAN_AUTH_TOKEN;
         this.serviceKey =
             config.serviceKey ||
+                process.env.OPENEPHEMERIS_SERVICE_KEY ||
                 process.env.ASTROMCP_SERVICE_KEY ||
                 process.env.MERIDIAN_SERVICE_KEY;
         this.apiKey =
             config.apiKey ||
+                process.env.OPENEPHEMERIS_API_KEY ||
                 process.env.ASTROMCP_API_KEY ||
                 process.env.MERIDIAN_API_KEY;
+        this.credentialManager = new CredentialManager();
         this.client = axios.create({
             baseURL: config.baseURL ||
+                process.env.OPENEPHEMERIS_BACKEND_URL ||
                 process.env.ASTROMCP_BACKEND_URL ||
                 process.env.MERIDIAN_BACKEND_URL ||
                 "https://api.openephemeris.com",
@@ -44,8 +70,8 @@ export class BackendClient {
                 "Content-Type": "application/json",
             },
         });
-        // Add auth interceptor (priority: service key > API key > JWT)
-        this.client.interceptors.request.use((req) => {
+        // Add auth interceptor (priority: service key > API key > JWT env > cached JWT)
+        this.client.interceptors.request.use(async (req) => {
             req.headers = req.headers ?? {};
             // Explicit per-request headers win.
             const hasAuthHeader = typeof req.headers.Authorization === "string" &&
@@ -64,10 +90,75 @@ export class BackendClient {
                 else if (this.jwt) {
                     req.headers.Authorization = `Bearer ${this.jwt}`;
                 }
+                else {
+                    // Fall through to cached credentials from device auth flow
+                    const cachedToken = await this.credentialManager.getValidToken();
+                    if (cachedToken) {
+                        req.headers.Authorization = `Bearer ${cachedToken}`;
+                    }
+                    else {
+                        // No credentials anywhere — auto-start device auth
+                        await this.autoStartDeviceAuth();
+                    }
+                }
             }
             return req;
         });
     }
+    /**
+     * Override the API key at runtime. Used by the SSE server to inject the
+     * per-session user's key so that all tool calls are authenticated and
+     * metered against the correct user account.
+     */
+    setApiKey(key) {
+        this.apiKey = key;
+        // Clear any cached JWT/service key so the interceptor uses the new API key
+        this.serviceKey = undefined;
+        this.jwt = undefined;
+    }
+    /**
+     * Start the device auth flow in the background if not already running.
+     * Called automatically when no credentials are found in the interceptor.
+     * Idempotent — only starts once per client lifetime.
+     */
+    async autoStartDeviceAuth() {
+        if (this._pendingAuthFlow)
+            return; // Already started
+        try {
+            const flow = new DeviceAuthFlow();
+            const startResult = await flow.start();
+            this._authFlowResult = {
+                verification_uri: startResult.verification_uri,
+                user_code: startResult.user_code,
+                verification_uri_complete: startResult.verification_uri_complete,
+            };
+            // Print to stderr so it's visible in MCP host logs
+            console.error(`\n🔗 OpenEphemeris: Account connection required.\n` +
+                `   Visit: ${startResult.verification_uri}\n` +
+                `   Code:  ${startResult.user_code}\n` +
+                `   Or:    ${startResult.verification_uri_complete}\n`);
+            // Poll in background (don't await)
+            this._pendingAuthFlow = flow
+                .poll(startResult.device_code, (attempt) => {
+                if (attempt % 12 === 0) {
+                    console.error(`   Still waiting... Enter code ${startResult.user_code} at ${startResult.verification_uri}`);
+                }
+            })
+                .then(() => {
+                console.error(`✅ Authenticated! Subsequent requests will use your account.`);
+                this._authFlowResult = null;
+            })
+                .catch((err) => {
+                console.error(`❌ Device auth failed: ${err.message}`);
+                this._pendingAuthFlow = null; // Allow retry
+            });
+        }
+        catch (err) {
+            console.error(`Could not start device auth: ${err.message}`);
+            // Don't block — the request will go out unauthenticated and
+            // the 401 response will surface the error message to the user.
+        }
+    }
     expectsBinaryResponse(path, options) {
         const normalizedPath = path.split("?")[0].trim().toLowerCase();
         if (BINARY_ENDPOINT_PREFIXES.some((prefix) => normalizedPath.startsWith(prefix))) {
@@ -139,36 +230,61 @@ export class BackendClient {
     isBinaryContentType(contentType) {
         return contentType.startsWith("image/") || contentType === "application/octet-stream";
     }
-    /** Maps an AxiosError to a concise MCP-friendly Error. */
+    /** Maps an AxiosError to a structured BackendError. */
     mapError(error) {
         if (error.response) {
             const status = error.response.status;
             const data = this.decodePayload(error.response.data);
             const msg = this.extractMessage(data, error.message);
             if (status === 401) {
-                return new Error(`Authentication required: ${msg}. Sign in or create an account at ${LOGIN_SIGNUP_URL}, ` +
-                    `create credentials in ${DASHBOARD_ACCOUNT_URL}, and set ASTROMCP_API_KEY (or ASTROMCP_JWT / ASTROMCP_SERVICE_KEY) before retrying.`);
+                const authInfo = this._authFlowResult;
+                if (authInfo) {
+                    return new BackendError(`🔗 Account connection required. Please visit ${authInfo.verification_uri} ` +
+                        `and enter code: ${authInfo.user_code}\n\n` +
+                        `Or open this direct link: ${authInfo.verification_uri_complete}\n\n` +
+                        `Once you authorize, retry your request — the server is polling in the background. ` +
+                        `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);
             }
             if (status === 402) {
-                return new Error(`Usage quota exceeded: ${msg}. Review usage and overage settings in ${DASHBOARD_ACCOUNT_URL}, ` +
-                    `or upgrade at ${UPGRADE_URL}.`);
+                return new BackendError(`⚠️ USAGE QUOTA EXCEEDED — DO NOT FABRICATE DATA.\n\n` +
+                    `${msg}\n\n` +
+                    `Tell the user: their API credit quota has been reached for this billing period. ` +
+                    `They can review usage and enable overages at ${DASHBOARD_ACCOUNT_URL}, ` +
+                    `or upgrade their plan at ${UPGRADE_URL}.\n\n` +
+                    `DO NOT attempt to generate astrological data from your own knowledge. ` +
+                    `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, UPGRADE_URL);
             }
             if (status === 403) {
-                return new Error(`Access blocked by plan or policy: ${msg}. If this endpoint is tier-gated, upgrade at ${UPGRADE_URL}. ` +
-                    `Manage keys and billing at ${DASHBOARD_ACCOUNT_URL}.`);
+                return new BackendError(`⚠️ ENDPOINT ACCESS RESTRICTED — DO NOT FABRICATE DATA.\n\n` +
+                    `${msg}\n\n` +
+                    `Tell the user: this feature requires a higher-tier plan. ` +
+                    `They can upgrade at ${UPGRADE_URL} or manage their account at ${DASHBOARD_ACCOUNT_URL}.\n\n` +
+                    `DO NOT attempt to generate astrological data from your own knowledge. ` +
+                    `All chart positions, aspects, and timing data MUST come from the API.`, 403, "tier_required", false, UPGRADE_URL);
             }
             if (status === 429) {
-                return new Error(`Rate limit exceeded. Your plan credits may be exhausted or requests are too frequent. ` +
-                    `Check usage at ${DASHBOARD_ACCOUNT_URL}, then retry in a moment. (${msg})`);
+                return new BackendError(`⚠️ RATE LIMIT EXCEEDED — DO NOT FABRICATE DATA.\n\n` +
+                    `${msg}\n\n` +
+                    `Tell the user: requests are being sent too frequently or their plan's rate limit has been hit. ` +
+                    `They should wait a moment and retry, or check usage at ${DASHBOARD_ACCOUNT_URL}.\n\n` +
+                    `DO NOT attempt to generate astrological data from your own knowledge while waiting. ` +
+                    `Simply inform the user and wait for them to retry.`, 429, "rate_limited", true);
             }
             if (status === 404)
-                return new Error(`Resource not found: ${msg}`);
+                return new BackendError(`Resource not found: ${msg}`, 404, "not_found", false);
             if (status === 400)
-                return new Error(`Invalid request: ${msg}`);
+                return new BackendError(`Invalid request: ${msg}`, 400, "bad_request", false);
             if (status >= 500)
-                return new Error(`Backend error (${status}): ${msg}`);
+                return new BackendError(`Backend error (${status}): ${msg}`, status, "server_error", true);
+        }
+        // Explicit timeout or abort interception
+        if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
+            return new BackendError(`The computation took too long and timed out. This usually happens when requesting a massive date range (like 20+ years of transits) or an overly complex query. Please narrow your request and try again.`, 408, "timeout", false);
         }
-        return new Error(`Network error: ${error.message}`);
+        return new BackendError(`Network error: ${error.message}`, 0, "network_error", true);
     }
     async get(path, params, timeoutMs) {
         return this.request("GET", path, { params, timeoutMs });
@@ -183,8 +299,8 @@ export class BackendClient {
         const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         const expectsBinary = this.expectsBinaryResponse(path, options);
         let lastError = new Error("Unknown error");
-        // Attempt + retries on 429
-        for (let attempt = 0; attempt <= RATE_LIMIT_RETRY_DELAYS_MS.length; attempt++) {
+        // Attempt + retries on transient failures (429, 502, 503, 504, network errors)
+        for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
             try {
                 const response = await this.client.request({
                     method,
@@ -213,9 +329,11 @@ export class BackendClient {
             }
             catch (err) {
                 if (err instanceof AxiosError) {
-                    if (err.response?.status === 429 && attempt < RATE_LIMIT_RETRY_DELAYS_MS.length) {
-                        const delay = RATE_LIMIT_RETRY_DELAYS_MS[attempt];
-                        await sleep(delay);
+                    const isRetryable = (err.response && RETRYABLE_STATUSES.has(err.response.status)) ||
+                        (!err.response && err.code && RETRYABLE_CODES.has(err.code));
+                    if (isRetryable && attempt < RETRY_DELAYS_MS.length) {
+                        const jitter = Math.random() * 500;
+                        await sleep(RETRY_DELAYS_MS[attempt] + jitter);
                         continue;
                     }
                     lastError = this.mapError(err);
@@ -234,11 +352,12 @@ export class BackendClient {
 }
 // Singleton instance
 export const backendClient = new BackendClient({
-    baseURL: process.env.ASTROMCP_BACKEND_URL ||
+    baseURL: process.env.OPENEPHEMERIS_BACKEND_URL ||
+        process.env.ASTROMCP_BACKEND_URL ||
         process.env.MERIDIAN_BACKEND_URL ||
         "https://api.openephemeris.com",
     userId: process.env.MCP_USER_ID || "anonymous",
-    jwt: process.env.ASTROMCP_JWT || process.env.MERIDIAN_AUTH_TOKEN,
-    serviceKey: process.env.ASTROMCP_SERVICE_KEY || process.env.MERIDIAN_SERVICE_KEY,
-    apiKey: process.env.ASTROMCP_API_KEY || process.env.MERIDIAN_API_KEY,
+    jwt: process.env.OPENEPHEMERIS_JWT || process.env.ASTROMCP_JWT || process.env.MERIDIAN_AUTH_TOKEN,
+    serviceKey: process.env.OPENEPHEMERIS_SERVICE_KEY || process.env.ASTROMCP_SERVICE_KEY || process.env.MERIDIAN_SERVICE_KEY,
+    apiKey: process.env.OPENEPHEMERIS_API_KEY || process.env.ASTROMCP_API_KEY || process.env.MERIDIAN_API_KEY,
 });

package/dist/index.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry } from "./tools/index.js";
 function resolveServerVersion() {
     try {
@@ -24,9 +24,16 @@ function resolveServerVersion() {
 const server = new Server({
     name: "openephemeris-mcp",
     version: resolveServerVersion(),
+    icons: [
+        {
+            src: "https://mcp.openephemeris.com/icon.png",
+            mimeType: "image/png",
+        }
+    ]
 }, {
     capabilities: {
         tools: {},
+        prompts: {},
     },
 });
 // List available tools
@@ -44,6 +51,47 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         })),
     };
 });
+// List available prompts
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: "welcome_to_open_ephemeris",
+                description: "Getting started guide for the Open Ephemeris MCP. Use this to orient yourself to available tools, astrology terminology, and usage.",
+            }
+        ]
+    };
+});
+// Get prompt content
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (request.params.name !== "welcome_to_open_ephemeris") {
+        throw new Error(`Unknown prompt: ${request.params.name}`);
+    }
+    return {
+        description: "Open Ephemeris Agent & Developer Orientation",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "Welcome to the **Open Ephemeris MCP Server**!\n\n" +
+                        "You are now connected to an enterprise-grade astrological and astronomical computation engine powered by NASA JPL DE440 and DE441 ephemeris data. As a generative guide, here is how you can best utilize these tools to help the user:\n\n" +
+                        "### Core Capabilities\n" +
+                        "- **Birth Charts:** Use `ephemeris_natal_chart` for full planetary positions, houses, dignities, and aspects.\n" +
+                        "- **Predictive Timing:** `ephemeris_transits` searches for exact dates when transiting planets hit natal points.\n" +
+                        "- **Location Astrology:** `ephemeris_relocation` projects a natal chart to a new geographic location (Astrocartography).\n" +
+                        "- **Specialized Modalities:** Dedicated tools for `vedic_chart`, `chinese_bazi`, and `human_design_chart`.\n" +
+                        "- **Eclipse Hunter:** `ephemeris_next_eclipse` dynamically scans 20 years for the next total or partial hit at the user's location.\n\n" +
+                        "### Best Practices for AI Agents\n" +
+                        "1. **Coordinate Formatting:** Always convert addresses/city names into `latitude` and `longitude` decimals *before* calling the tools (e.g., Chicago is `41.8781, -87.6298`).\n" +
+                        "2. **Datetime Handling:** Most endpoints accept ISO 8601 strings. If you have a local birth time but the endpoint asks for UTC, explicitly append a `Z` or timezone offset (e.g., `1990-04-15T19:30:00Z`).\n" +
+                        "3. **Token Efficiency:** Our responses are hyper-condensed to save you context space. You don't need to struggle with raw JSON arrays; interpret the condensed strings directly (e.g., `Su 15°Pi30 H10`).\n\n" +
+                        "You're equipped with professional-grade math. Start by asking the user if they'd like to calculate a natal chart, check recent transits, or explore another modality!"
+                }
+            }
+        ]
+    };
+});
 // Handle tool calls
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const toolName = request.params.name;
@@ -51,19 +99,63 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!tool) {
         throw new Error(`Unknown tool: ${toolName}`);
     }
+    const startTime = Date.now();
+    console.error(`[MCP] Executing tool: ${toolName}`);
     try {
         const result = await tool.handler(request.params.arguments ?? {});
+        const durationMs = Date.now() - startTime;
+        console.error(`[MCP] ✅ Success: ${toolName} (${durationMs}ms)`);
+        // Intercept binary backend responses (like Chart Wheels) to return native MCP Images
+        if (result &&
+            typeof result === "object" &&
+            "encoding" in result &&
+            result.encoding === "base64" &&
+            "data_base64" in result &&
+            "content_type" in result) {
+            const binResp = result;
+            console.error(`[MCP] 🎨 Returning image (${binResp.content_length} bytes) for ${toolName}`);
+            return {
+                content: [
+                    {
+                        type: "image",
+                        data: binResp.data_base64,
+                        mimeType: binResp.content_type,
+                    },
+                ],
+            };
+        }
+        const jsonStr = JSON.stringify(result, null, 2);
+        // Safety limit: ~100kb JSON is roughly 20-30k tokens. 
+        // Usually happens if LLMs ask for 50+ years of transits or raw ephemeris arrays.
+        if (jsonStr.length > 100_000) {
+            console.error(`[MCP] ⚠️ Warning: Payload too large (${(jsonStr.length / 1024).toFixed(1)}kb) for ${toolName}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "PAYLOAD_TOO_LARGE",
+                            message: `The requested query produced too much data (${(jsonStr.length / 1024).toFixed(1)}kb). Please significantly narrow your request parameters (e.g., fewer years, smaller coordinate bounding box, etc.) to fit within context limits.`
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(result, null, 2),
+                    text: jsonStr,
                 },
             ],
         };
     }
     catch (error) {
+        const durationMs = Date.now() - startTime;
         const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`[MCP] ❌ Failed: ${toolName} (${durationMs}ms) - ${errorMessage}`);
         return {
             content: [
                 {

package/dist/tools/dev.js

@@ -1,17 +1,19 @@
-import { registerTool } from "./index.js";
+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.ASTROMCP_DEV_ALLOWLIST_PATH;
+    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));
-    // here: .../dist/tools OR .../src/tools
-    const mcpServerRoot = path.resolve(here, "..", "..");
+    let mcpServerRoot = path.resolve(here, "..", "..");
+    if (path.basename(mcpServerRoot) === "dist") {
+        mcpServerRoot = path.resolve(mcpServerRoot, "..");
+    }
     return path.join(mcpServerRoot, "config", "dev-allowlist.json");
 }
 function loadAllowlist() {
@@ -30,11 +32,11 @@ function isAllowedOperation(method, pathname, allow) {
     return allow.some((e) => e.method === method && e.path === pathname);
 }
 registerTool({
-    name: "dev.call",
+    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 ASTROMCP_API_KEY in your environment. See openephemeris.com/dashboard for active plan limits.\n\n" +
+        "— 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" +
@@ -42,9 +44,9 @@ registerTool({
         "  • 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): requires Pro tier ($49+/mo)\n\n" +
+        "  • format=llm (token-optimized output): available on all tiers\n\n" +
         "COMMON CALLS:\n" +
-        "  POST /ephemeris/natal-chart            — Full natal chart (body: {datetime, latitude, longitude})\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" +
@@ -52,15 +54,16 @@ registerTool({
         "  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\n" +
+        "  POST /human-design/chart               — Full HD chart (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: latitude, longitude)\n" +
-        "  GET  /eclipse/next-visible             — Next eclipse visible from a location\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" +
@@ -68,9 +71,9 @@ registerTool({
         "  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\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\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" +
@@ -118,8 +121,13 @@ registerTool({
         additionalProperties: false,
     },
     handler: async (args) => {
-        const method = String(args.method || "").toUpperCase();
-        const pathname = String(args.path || "");
+        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 '/'");
         }
@@ -161,12 +169,12 @@ registerTool({
     },
 });
 registerTool({
-    name: "dev.list_allowed",
+    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.",
+        "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: {},

package/dist/tools/index.d.ts

@@ -23,3 +23,11 @@ export type ToolProfile = "dev" | "legacy";
  * - `legacy`: registers only the generic tools (back-compat).
  */
 export declare function initTools(profile?: ToolProfile): Promise<void>;
+/**
+ * Throws an error if any of the required keys are missing or empty.
+ */
+export declare function validateRequired(args: any, requiredKeys: string[]): void;
+/**
+ * Throws an error if only one of the coordinate pair is provided.
+ */
+export declare function validateCoordinates(args: any, latKey: string, lonKey: string): void;

package/dist/tools/index.js

@@ -14,7 +14,9 @@ export async function initTools(profile) {
     if (toolsInitialized)
         return;
     toolsInitialized = true;
-    const resolvedProfile = (profile || process.env.ASTROMCP_PROFILE || "dev").toLowerCase();
+    const resolvedProfile = (profile || process.env.OPENEPHEMERIS_PROFILE || process.env.ASTROMCP_PROFILE || "dev").toLowerCase();
+    // Always register auth tools (available in all profiles).
+    await import("./auth.js");
     // Always register the generic proxy tools (dev.call + dev.list_allowed).
     await import("./dev.js");
     if (resolvedProfile === "dev") {
@@ -27,5 +29,32 @@ export async function initTools(profile) {
         await import("./specialized/synastry.js");
         await import("./specialized/relocation.js");
         await import("./specialized/electional.js");
+        await import("./specialized/vedic.js");
+        await import("./specialized/bazi.js");
+        await import("./specialized/chart_wheel.js");
+        await import("./specialized/bi_wheel.js");
+    }
+}
+/**
+ * Throws an error if any of the required keys are missing or empty.
+ */
+export function validateRequired(args, requiredKeys) {
+    if (!args)
+        throw new Error("Missing arguments object.");
+    const missing = requiredKeys.filter((k) => args[k] == null || args[k] === "");
+    if (missing.length > 0) {
+        throw new Error(`Missing required arguments: ${missing.join(", ")}`);
+    }
+}
+/**
+ * Throws an error if only one of the coordinate pair is provided.
+ */
+export function validateCoordinates(args, latKey, lonKey) {
+    if (!args)
+        return;
+    const hasLat = args[latKey] != null && args[latKey] !== "";
+    const hasLon = args[lonKey] != null && args[lonKey] !== "";
+    if (hasLat !== hasLon) {
+        throw new Error(`Both ${latKey} and ${lonKey} must be provided together, or both omitted.`);
     }
 }