@openephemeris/mcp-server 3.1.0 → 3.2.0

package/dist/src/backend/client.js

@@ -0,0 +1,335 @@
+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 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",
+    "/comparative/visualization/bi-wheel",
+    "/comparative/visualization/chart-wheel",
+];
+const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
+const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
+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",
+            timeout: DEFAULT_TIMEOUT_MS,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+        // 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" &&
+                req.headers.Authorization.length > 0;
+            const hasServiceKeyHeader = typeof req.headers["X-Service-Key"] === "string" &&
+                req.headers["X-Service-Key"].length > 0;
+            const hasApiKeyHeader = typeof req.headers["X-API-Key"] === "string" &&
+                req.headers["X-API-Key"].length > 0;
+            if (!hasAuthHeader && !hasServiceKeyHeader && !hasApiKeyHeader) {
+                if (this.serviceKey) {
+                    req.headers["X-Service-Key"] = this.serviceKey;
+                }
+                else if (this.apiKey) {
+                    req.headers["X-API-Key"] = this.apiKey;
+                }
+                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;
+        });
+    }
+    /**
+     * 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))) {
+            return true;
+        }
+        const format = options?.params?.format;
+        if (typeof format === "string") {
+            const normalizedFormat = format.trim().toLowerCase();
+            if (normalizedFormat === "png" || normalizedFormat === "svg") {
+                return true;
+            }
+        }
+        const acceptHeader = Object.entries(options?.headers ?? {}).find(([key]) => key.toLowerCase() === "accept")?.[1];
+        if (typeof acceptHeader === "string" && acceptHeader.toLowerCase().includes("image/")) {
+            return true;
+        }
+        return false;
+    }
+    toBuffer(data) {
+        if (data == null)
+            return null;
+        if (Buffer.isBuffer(data))
+            return data;
+        if (data instanceof ArrayBuffer)
+            return Buffer.from(data);
+        if (ArrayBuffer.isView(data)) {
+            return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+        }
+        if (typeof data === "string")
+            return Buffer.from(data);
+        return null;
+    }
+    decodePayload(data) {
+        const asBuffer = this.toBuffer(data);
+        if (!asBuffer) {
+            return data;
+        }
+        const text = asBuffer.toString("utf8").trim();
+        if (!text)
+            return "";
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    extractMessage(data, fallback) {
+        if (typeof data === "string") {
+            const trimmed = data.trim();
+            return trimmed || fallback;
+        }
+        if (data && typeof data === "object") {
+            const obj = data;
+            for (const key of ["message", "detail", "title", "error"]) {
+                const value = obj[key];
+                if (typeof value === "string" && value.trim()) {
+                    return value.trim();
+                }
+            }
+        }
+        return fallback;
+    }
+    normalizeContentType(value) {
+        if (typeof value !== "string")
+            return "";
+        return value.split(";")[0]?.trim().toLowerCase() || "";
+    }
+    isBinaryContentType(contentType) {
+        return contentType.startsWith("image/") || contentType === "application/octet-stream";
+    }
+    /** 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) {
+                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 BackendError(`Usage quota exceeded: ${msg}. Review usage and overage settings in ${DASHBOARD_ACCOUNT_URL}, ` +
+                    `or upgrade at ${UPGRADE_URL}.`, 402, "quota_exceeded", false, UPGRADE_URL);
+            }
+            if (status === 403) {
+                return new BackendError(`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}.`, 403, "tier_required", false, UPGRADE_URL);
+            }
+            if (status === 429) {
+                return new BackendError(`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})`, 429, "rate_limited", true);
+            }
+            if (status === 404)
+                return new BackendError(`Resource not found: ${msg}`, 404, "not_found", false);
+            if (status === 400)
+                return new BackendError(`Invalid request: ${msg}`, 400, "bad_request", false);
+            if (status >= 500)
+                return new BackendError(`Backend error (${status}): ${msg}`, status, "server_error", true);
+        }
+        return new BackendError(`Network error: ${error.message}`, 0, "network_error", true);
+    }
+    async get(path, params, timeoutMs) {
+        return this.request("GET", path, { params, timeoutMs });
+    }
+    async post(path, data, timeoutMs) {
+        return this.request("POST", path, { data, timeoutMs });
+    }
+    async delete(path) {
+        return this.request("DELETE", path);
+    }
+    async request(method, path, options) {
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const expectsBinary = this.expectsBinaryResponse(path, options);
+        let lastError = new Error("Unknown error");
+        // 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,
+                    url: path,
+                    params: options?.params,
+                    data: options?.data,
+                    headers: options?.headers,
+                    timeout: timeoutMs,
+                    responseType: expectsBinary ? "arraybuffer" : "json",
+                });
+                if (!expectsBinary) {
+                    return response.data;
+                }
+                const contentType = this.normalizeContentType(response.headers?.["content-type"]);
+                if (!this.isBinaryContentType(contentType)) {
+                    return this.decodePayload(response.data);
+                }
+                const bytes = this.toBuffer(response.data) ?? Buffer.alloc(0);
+                const payload = {
+                    content_type: contentType || "application/octet-stream",
+                    content_length: bytes.length,
+                    encoding: "base64",
+                    data_base64: bytes.toString("base64"),
+                };
+                return payload;
+            }
+            catch (err) {
+                if (err instanceof AxiosError) {
+                    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);
+                }
+                else {
+                    lastError = err instanceof Error ? err : new Error(String(err));
+                }
+                throw lastError;
+            }
+        }
+        throw lastError;
+    }
+    getUserId() {
+        return this.userId;
+    }
+}
+// Singleton instance
+export const backendClient = new BackendClient({
+    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.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/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/index.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+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 { initTools, toolRegistry } from "./tools/index.js";
+function resolveServerVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkgPath = path.resolve(here, "..", "package.json");
+        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 {
+        // Ignore and fall back to an explicit unknown version.
+    }
+    return "0.0.0-unknown";
+}
+const server = new Server({
+    name: "openephemeris-mcp",
+    version: resolveServerVersion(),
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        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,
+            },
+        })),
+    };
+});
+// Handle tool calls
+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,
+        };
+    }
+});
+// Start server
+async function main() {
+    await initTools();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Open Ephemeris MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/src/schema-packs/llm.d.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+export declare const LLM_V2_POINTS_SCHEMA: readonly ["id", "kind", "src", "lon", "lat", "spd", "rx", "sg", "deg", "hs", "dec", "oob", "ed", "ed_sc", "ad_sc", "on_cusp"];
+export declare const LLM_V2_ASPECTS_SCHEMA: readonly ["a_i", "b_i", "t", "orb", "orb_pct", "app", "str"];
+export declare const LLM_V2_DICT: {
+    readonly sign_id: readonly ["ari", "tau", "gem", "can", "leo", "vir", "lib", "sco", "sag", "cap", "aqu", "pis"];
+    readonly aspect_id: readonly ["con", "opp", "tri", "sqr", "sex"];
+    readonly aspect_angle: readonly [0, 180, 120, 90, 60];
+    readonly kind_id: readonly ["planet", "angle", "node", "lilith", "asteroid", "other"];
+};
+export declare const LlmV2PayloadSchema: z.ZodObject<{
+    output_mode: z.ZodOptional<z.ZodLiteral<"llm">>;
+    schema_version: z.ZodOptional<z.ZodLiteral<"llm">>;
+    chart: z.ZodObject<{
+        chart_type: z.ZodEnum<{
+            natal: "natal";
+            synastry: "synastry";
+        }>;
+        subject: z.ZodOptional<z.ZodObject<{
+            datetime: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            jd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            lat: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            lon: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    rules: z.ZodOptional<z.ZodObject<{
+        zodiac_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        house_system: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        coordinate_system: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        node_source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        lon_range: z.ZodLiteral<"0_360">;
+        aspect_set: z.ZodLiteral<"major_default">;
+        orb_profile: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        strength_basis: z.ZodLiteral<"engine">;
+        point_order_id: z.ZodLiteral<"astro_point_order_v1">;
+        core_set_id: z.ZodLiteral<"core_interp_set_v1">;
+    }, z.core.$strict>>;
+    reliability: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    provenance: z.ZodOptional<z.ZodObject<{
+        engine: z.ZodString;
+        ephemeris_source: z.ZodString;
+        ephemeris_version: z.ZodString;
+        validation_profile: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        precision_level: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        checksum: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    dict: z.ZodObject<{
+        sign_id: z.ZodTuple<any, null>;
+        aspect_id: z.ZodTuple<any, null>;
+        aspect_angle: z.ZodTuple<any, null>;
+        kind_id: z.ZodTuple<any, null>;
+    }, z.core.$strict>;
+    present: z.ZodObject<{
+        point_count: z.ZodNumber;
+        kinds: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strict>;
+    points_schema: z.ZodTuple<any, null>;
+    points: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodEnum<{
+        [x: string]: any;
+    }>, z.ZodNumber, z.ZodNumber, z.ZodNullable<z.ZodNumber>, z.ZodNullable<z.ZodNumber>, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNullable<z.ZodNumber>, z.ZodNullable<z.ZodNumber>, z.ZodNumber, z.ZodEnum<{
+        none: "none";
+        dom: "dom";
+        ex: "ex";
+        det: "det";
+        fall: "fall";
+    }>, z.ZodNullable<z.ZodNumber>, z.ZodNullable<z.ZodNumber>, z.ZodNumber], null>>;
+    angles: z.ZodOptional<z.ZodObject<{
+        asc: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        mc: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        dsc: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        ic: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    houses: z.ZodOptional<z.ZodObject<{
+        system: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        cusps: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aspects_schema: z.ZodTuple<any, null>;
+    aspects: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    patterns: z.ZodOptional<z.ZodObject<{
+        stellium: z.ZodArray<z.ZodUnknown>;
+        t_square: z.ZodArray<z.ZodUnknown>;
+        grand_trine: z.ZodArray<z.ZodUnknown>;
+        kite: z.ZodArray<z.ZodUnknown>;
+        yod: z.ZodArray<z.ZodUnknown>;
+        grand_cross: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$strict>>;
+    extras: z.ZodOptional<z.ZodObject<{
+        fixed_star_conjunctions: z.ZodArray<z.ZodUnknown>;
+        lots: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$strict>>;
+    counts: z.ZodObject<{
+        point_count: z.ZodNumber;
+        aspect_count: z.ZodNumber;
+        aspect_count_unfiltered: z.ZodOptional<z.ZodNumber>;
+        midpoint_count: z.ZodOptional<z.ZodNumber>;
+        declination_aspect_count: z.ZodOptional<z.ZodNumber>;
+        stellium_count: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    analysis: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    human_design: z.ZodOptional<z.ZodObject<{
+        gates_schema: z.ZodArray<z.ZodString>;
+        gates: z.ZodArray<z.ZodArray<z.ZodAny>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type LlmV2Payload = z.infer<typeof LlmV2PayloadSchema>;
+export declare const llmV2JsonSchema: Record<string, unknown>;