@openephemeris/mcp-server 3.0.0

package/dist/backend/client.d.ts

@@ -0,0 +1,33 @@
+export interface BackendConfig {
+    baseURL: string;
+    userId?: string;
+    jwt?: string;
+    serviceKey?: string;
+    apiKey?: string;
+    /** Back-compat: previous name for JWT token (Bearer). */
+    authToken?: string;
+}
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface BackendRequestOptions {
+    params?: Record<string, unknown>;
+    data?: unknown;
+    headers?: Record<string, string>;
+    /** Override per-request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+export declare class BackendClient {
+    private client;
+    private userId;
+    private jwt?;
+    private serviceKey?;
+    private apiKey?;
+    constructor(config: BackendConfig);
+    /** Maps an AxiosError to a concise MCP-friendly Error. */
+    private mapError;
+    get<T>(path: string, params?: Record<string, any>, timeoutMs?: number): Promise<T>;
+    post<T>(path: string, data?: any, timeoutMs?: number): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    request<T>(method: HttpMethod, path: string, options?: BackendRequestOptions): Promise<T>;
+    getUserId(): string;
+}
+export declare const backendClient: BackendClient;

package/dist/backend/client.js

@@ -0,0 +1,167 @@
+import axios, { AxiosError } from "axios";
+const DEFAULT_TIMEOUT_MS = 45_000;
+const RATE_LIMIT_RETRY_DELAYS_MS = [1_000, 2_000]; // Two retries on 429
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class BackendClient {
+    client;
+    userId;
+    jwt;
+    serviceKey;
+    apiKey;
+    constructor(config) {
+        this.userId = config.userId || "anonymous";
+        this.jwt =
+            config.jwt ||
+                config.authToken ||
+                process.env.ASTROMCP_JWT ||
+                process.env.MERIDIAN_AUTH_TOKEN;
+        this.serviceKey =
+            config.serviceKey ||
+                process.env.ASTROMCP_SERVICE_KEY ||
+                process.env.MERIDIAN_SERVICE_KEY;
+        this.apiKey =
+            config.apiKey ||
+                process.env.ASTROMCP_API_KEY ||
+                process.env.MERIDIAN_API_KEY;
+        this.client = axios.create({
+            baseURL: config.baseURL ||
+                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)
+        this.client.interceptors.request.use((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}`;
+                }
+            }
+            return req;
+        });
+    }
+    /** Maps an AxiosError to a concise MCP-friendly Error. */
+    mapError(error) {
+        if (error.response) {
+            const status = error.response.status;
+            const data = error.response.data;
+            const msg = data?.message || data?.detail || error.message;
+            if (status === 429) {
+                return new Error(`Rate limit exceeded. Your plan credits may be exhausted or requests are too frequent. ` +
+                    `Check your usage at openephemeris.com/dashboard, then retry in a moment. (${msg})`);
+            }
+            if (status === 404)
+                return new Error(`Resource not found: ${msg}`);
+            if (status === 400)
+                return new Error(`Invalid request: ${msg}`);
+            if (status === 401 || status === 403)
+                return new Error(`Authentication error: ${msg}. Verify your ASTROMCP_API_KEY.`);
+            if (status >= 500)
+                return new Error(`Backend error (${status}): ${msg}`);
+        }
+        return new Error(`Network error: ${error.message}`);
+    }
+    async get(path, params, timeoutMs) {
+        try {
+            const response = await this.client.get(path, {
+                params,
+                timeout: timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            });
+            return response.data;
+        }
+        catch (err) {
+            if (err instanceof AxiosError)
+                throw this.mapError(err);
+            throw err;
+        }
+    }
+    async post(path, data, timeoutMs) {
+        try {
+            const response = await this.client.post(path, data, {
+                timeout: timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            });
+            return response.data;
+        }
+        catch (err) {
+            if (err instanceof AxiosError)
+                throw this.mapError(err);
+            throw err;
+        }
+    }
+    async delete(path) {
+        try {
+            const response = await this.client.delete(path);
+            return response.data;
+        }
+        catch (err) {
+            if (err instanceof AxiosError)
+                throw this.mapError(err);
+            throw err;
+        }
+    }
+    async request(method, path, options) {
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        let lastError = new Error("Unknown error");
+        // Attempt + retries on 429
+        for (let attempt = 0; attempt <= RATE_LIMIT_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,
+                });
+                return response.data;
+            }
+            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);
+                        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.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,
+});

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,87 @@
+#!/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,
+        })),
+    };
+});
+// 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/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", "uranian", "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>;