@openephemeris/mcp-server 3.0.1 → 3.1.0

package/dist/backend/client.d.ts

@@ -15,6 +15,12 @@ export interface BackendRequestOptions {
     /** Override per-request timeout in milliseconds. */
     timeoutMs?: number;
 }
+export interface BinaryBackendResponse {
+    content_type: string;
+    content_length: number;
+    encoding: "base64";
+    data_base64: string;
+}
 export declare class BackendClient {
     private client;
     private userId;
@@ -22,6 +28,12 @@ export declare class BackendClient {
     private serviceKey?;
     private apiKey?;
     constructor(config: BackendConfig);
+    private expectsBinaryResponse;
+    private toBuffer;
+    private decodePayload;
+    private extractMessage;
+    private normalizeContentType;
+    private isBinaryContentType;
     /** Maps an AxiosError to a concise MCP-friendly Error. */
     private mapError;
     get<T>(path: string, params?: Record<string, any>, timeoutMs?: number): Promise<T>;

package/dist/backend/client.js

@@ -1,6 +1,12 @@
 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
+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";
@@ -62,12 +68,83 @@ export class BackendClient {
             return req;
         });
     }
+    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 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 || data?.title || error.message;
+            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.`);
@@ -94,45 +171,17 @@ export class BackendClient {
         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;
-        }
+        return this.request("GET", path, { params, timeoutMs });
     }
     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;
-        }
+        return this.request("POST", path, { data, timeoutMs });
     }
     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;
-        }
+        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 429
         for (let attempt = 0; attempt <= RATE_LIMIT_RETRY_DELAYS_MS.length; attempt++) {
@@ -144,8 +193,23 @@ export class BackendClient {
                     data: options?.data,
                     headers: options?.headers,
                     timeout: timeoutMs,
+                    responseType: expectsBinary ? "arraybuffer" : "json",
                 });
-                return response.data;
+                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) {

package/dist/index.js

@@ -36,6 +36,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            annotations: tool.annotations ?? {
+                title: tool.name,
+                readOnlyHint: true,
+                destructiveHint: false,
+            },
         })),
     };
 });

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

@@ -5,7 +5,7 @@ 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"];
+    readonly kind_id: readonly ["planet", "angle", "node", "lilith", "asteroid", "other"];
 };
 export declare const LlmV2PayloadSchema: z.ZodObject<{
     output_mode: z.ZodOptional<z.ZodLiteral<"llm">>;

package/dist/schema-packs/llm.js

@@ -22,7 +22,7 @@ export const LLM_V2_DICT = {
     sign_id: ["ari", "tau", "gem", "can", "leo", "vir", "lib", "sco", "sag", "cap", "aqu", "pis"],
     aspect_id: ["con", "opp", "tri", "sqr", "sex"],
     aspect_angle: [0, 180, 120, 90, 60],
-    kind_id: ["planet", "angle", "node", "lilith", "asteroid", "uranian", "other"],
+    kind_id: ["planet", "angle", "node", "lilith", "asteroid", "other"],
 };
 const PointsSchemaZ = z.tuple(LLM_V2_POINTS_SCHEMA.map((v) => z.literal(v)));
 const AspectsSchemaZ = z.tuple(LLM_V2_ASPECTS_SCHEMA.map((v) => z.literal(v)));

package/dist/tools/dev.js

@@ -36,10 +36,11 @@ registerTool({
         "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" +
         "CREDIT COSTS:\n" +
-        "  • Standard chart (natal, synastry, composite, progressed): 1 credit\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" +
-        "  • Human Design chart: 1 credit\n" +
         "  • Catalog / metadata / health endpoints: 0 credits\n" +
         "  • format=llm (token-optimized output): requires Pro tier ($49+/mo)\n\n" +
         "COMMON CALLS:\n" +
@@ -62,7 +63,7 @@ registerTool({
         "  GET  /eclipse/next-visible             — Next eclipse visible from a location\n" +
         "  GET  /tidal/forcing                    — Gravitational tidal forcing index\n" +
         "  GET  /tidal/forcing/deep-time          — Extended tidal deep-time analysis\n" +
-        "  POST /acg/natal-lines                  — Astrocartography natal lines (lat/lon GeoJSON)\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" +
@@ -71,6 +72,9 @@ registerTool({
         "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
         "  POST /vedic/chart                      — Vedic (Jyotish) natal chart\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).",

package/dist/tools/index.d.ts

@@ -3,6 +3,13 @@ export interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: z.ZodType<any> | Record<string, unknown>;
+    annotations?: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
     handler: (args: any) => Promise<any>;
 }
 export declare const toolRegistry: Record<string, ToolDefinition>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",
@@ -15,24 +15,6 @@
   "directories": {
     "test": "test"
   },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx watch src/index.ts",
-    "start": "node dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "regen:dev-allowlist": "tsx scripts/dev-allowlist.ts --write",
-    "check:dev-allowlist": "tsx scripts/dev-allowlist.ts --check",
-    "regen:schema-packs": "tsx scripts/schema-packs.ts --write",
-    "check:schema-packs": "tsx scripts/schema-packs.ts --check",
-    "sync:readme": "tsx scripts/sync-readme.ts --write",
-    "check:readme": "tsx scripts/sync-readme.ts --check",
-    "check:pack": "tsx scripts/pack-audit.ts",
-    "verify:release": "npm run check:dev-allowlist && npm run check:schema-packs && npm run check:readme && npm run typecheck && npm test && npm run build && npm run check:pack",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm run verify:release"
-  },
   "keywords": [
     "mcp",
     "astrology",
@@ -56,5 +38,20 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.15"
   },
-  "packageManager": "pnpm@10.27.0+sha512.72d699da16b1179c14ba9e64dc71c9a40988cbdc65c264cb0e489db7de917f20dcf4d64d8723625f2969ba52d4b7e2a1170682d9ac2a5dcaeaab732b7e16f04a"
-}
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "regen:dev-allowlist": "tsx scripts/dev-allowlist.ts --write",
+    "check:dev-allowlist": "tsx scripts/dev-allowlist.ts --check",
+    "regen:schema-packs": "tsx scripts/schema-packs.ts --write",
+    "check:schema-packs": "tsx scripts/schema-packs.ts --check",
+    "sync:readme": "tsx scripts/sync-readme.ts --write",
+    "check:readme": "tsx scripts/sync-readme.ts --check",
+    "check:pack": "tsx scripts/pack-audit.ts",
+    "verify:release": "npm run check:dev-allowlist && npm run check:schema-packs && npm run check:readme && npm run typecheck && npm test && npm run build && npm run check:pack"
+  }
+}