@openephemeris/mcp-server 3.0.1 → 3.2.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/scripts/dev-allowlist.d.ts

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

package/dist/scripts/dev-allowlist.js

@@ -0,0 +1,287 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import axios from "axios";
+function normalizeTier(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const value = raw.trim().toLowerCase();
+    if (value === "free" ||
+        value === "all" ||
+        value === "free/all" ||
+        value === "anonymous" ||
+        value === "anonymous/all" ||
+        value === "public" ||
+        value === "public/all")
+        return "free";
+    if (value === "dev" || value === "developer")
+        return "developer";
+    if (value === "pro")
+        return "pro";
+    if (value === "production")
+        return "production";
+    if (value === "admin" || value === "internal")
+        return "admin";
+    return null;
+}
+function isCommercialTier(tierNormalized) {
+    // Dev MCP should expose all commercially available tiers up through production.
+    return tierNormalized === "free" || tierNormalized === "developer" || tierNormalized === "pro" || tierNormalized === "production";
+}
+function sha256(text) {
+    return crypto.createHash("sha256").update(text).digest("hex");
+}
+function readJsonFile(filePath) {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    return { raw, json: JSON.parse(raw) };
+}
+function writeJsonFile(filePath, obj) {
+    fs.writeFileSync(filePath, JSON.stringify(obj, null, 2) + "\n", "utf-8");
+}
+function normalizeTag(tag) {
+    return tag.trim().toLowerCase();
+}
+function isDeniedByPrefix(pathname, prefixes) {
+    return prefixes.some((p) => pathname.startsWith(p));
+}
+function hasDeniedTag(tags, denyTags) {
+    const deny = new Set(denyTags.map(normalizeTag));
+    return tags.some((t) => deny.has(normalizeTag(t)));
+}
+function getDefaults() {
+    const here = path.dirname(fileURLToPath(import.meta.url)); // .../mcp-server/scripts
+    const mcpServerRoot = path.resolve(here, "..");
+    const repoRoot = path.resolve(mcpServerRoot, "..");
+    return {
+        mcpServerRoot,
+        repoRoot,
+        allowlistPath: path.join(mcpServerRoot, "config", "dev-allowlist.json"),
+        openapiPath: path.join(repoRoot, "go-sidecar", "openapi.json"),
+    };
+}
+function parseArgs(argv) {
+    const args = {
+        openapiPath: undefined,
+        allowlistPath: undefined,
+        write: false,
+        check: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--openapi")
+            args.openapiPath = argv[++i];
+        else if (a === "--allowlist")
+            args.allowlistPath = argv[++i];
+        else if (a === "--write")
+            args.write = true;
+        else if (a === "--check")
+            args.check = true;
+        else if (a === "--help" || a === "-h") {
+            console.log([
+                "Dev allowlist helper (astromcp-dev-allowlist-v1)",
+                "",
+                "Usage:",
+                "  tsx scripts/dev-allowlist.ts --check",
+                "  tsx scripts/dev-allowlist.ts --write",
+                "",
+                "Options:",
+                "  --openapi <path>    Path to OpenAPI JSON (default: ../go-sidecar/openapi.json)",
+                "  --allowlist <path>  Path to allowlist JSON (default: config/dev-allowlist.json)",
+                "  --check             Validate allowlist against OpenAPI + deny rules (exit 1 on failure)",
+                "  --write             Update allowlist metadata + candidates + auto-allow commercial-tier operations",
+            ].join("\n"));
+            process.exit(0);
+        }
+    }
+    return args;
+}
+function asHttpMethod(m) {
+    const up = m.toUpperCase();
+    if (up === "GET" || up === "POST" || up === "PUT" || up === "PATCH" || up === "DELETE")
+        return up;
+    return null;
+}
+function buildCandidates(openapi, denyPrefixes, denyTags) {
+    const candidatesGet = [];
+    const candidatesNonGet = [];
+    const index = new Map();
+    for (const [pathname, pathItem] of Object.entries(openapi.paths || {})) {
+        // OpenAPI keys can include templated params; we keep as-is.
+        if (denyPrefixes.length && isDeniedByPrefix(pathname, denyPrefixes))
+            continue;
+        for (const [methodKey, operation] of Object.entries(pathItem || {})) {
+            const method = asHttpMethod(methodKey);
+            if (!method)
+                continue;
+            const tags = Array.isArray(operation?.tags) ? operation.tags : [];
+            if (denyTags.length && hasDeniedTag(tags, denyTags))
+                continue;
+            const tier = typeof operation?.["x-meridian-tier"] === "string" ? String(operation["x-meridian-tier"]) : undefined;
+            const tier_normalized = tier ? normalizeTier(tier) ?? undefined : undefined;
+            const candidate = {
+                method,
+                path: pathname,
+                tags,
+                tier,
+                tier_normalized,
+                operationId: typeof operation?.operationId === "string" ? operation.operationId : undefined,
+                summary: typeof operation?.summary === "string" ? operation.summary : undefined,
+            };
+            const key = `${method} ${pathname}`;
+            index.set(key, candidate);
+            if (method === "GET")
+                candidatesGet.push(candidate);
+            else
+                candidatesNonGet.push(candidate);
+        }
+    }
+    candidatesGet.sort((a, b) => (a.path + a.method).localeCompare(b.path + b.method));
+    candidatesNonGet.sort((a, b) => (a.path + a.method).localeCompare(b.path + b.method));
+    return { candidatesGet, candidatesNonGet, index };
+}
+function buildCommercialAllow(candidates, existingAllow) {
+    // Build a lookup of existing notes/metadata to preserve across regen
+    const existingMeta = new Map();
+    for (const e of existingAllow) {
+        if (e.note)
+            existingMeta.set(`${e.method} ${e.path}`, { note: e.note });
+    }
+    const allow = candidates
+        .filter((c) => isCommercialTier(c.tier_normalized))
+        .map((c) => {
+        const key = `${c.method} ${c.path}`;
+        const entry = { method: c.method, path: c.path };
+        const meta = existingMeta.get(key);
+        if (meta?.note)
+            entry.note = meta.note;
+        return entry;
+    });
+    // Deterministic ordering for diffs.
+    allow.sort((a, b) => (a.path + a.method).localeCompare(b.path + b.method));
+    return allow;
+}
+function validateAllowlist(allowlist, index, denyPrefixes, denyTags) {
+    const errors = [];
+    const warnings = [];
+    for (const entry of allowlist.allow) {
+        if (!entry || typeof entry !== "object") {
+            errors.push(`Invalid allow entry (not an object): ${JSON.stringify(entry)}`);
+            continue;
+        }
+        const method = entry.method;
+        const pathname = entry.path;
+        if (!asHttpMethod(method)) {
+            errors.push(`Invalid method in allow entry: ${JSON.stringify(entry)}`);
+            continue;
+        }
+        if (typeof pathname !== "string" || !pathname.startsWith("/")) {
+            errors.push(`Invalid path in allow entry: ${JSON.stringify(entry)}`);
+            continue;
+        }
+        if (denyPrefixes.length && isDeniedByPrefix(pathname, denyPrefixes)) {
+            errors.push(`Allowlisted entry violates deny prefix rule: ${method} ${pathname}`);
+            continue;
+        }
+        const key = `${method.toUpperCase()} ${pathname}`;
+        const candidate = index.get(key);
+        if (!candidate) {
+            errors.push(`Allowlisted entry not found in OpenAPI: ${key}`);
+            continue;
+        }
+        if (!isCommercialTier(candidate.tier_normalized)) {
+            errors.push(`Allowlisted entry is not a commercial-tier operation: ${key} (x-meridian-tier=${candidate.tier ?? "<missing>"})`);
+            continue;
+        }
+        if (denyTags.length && hasDeniedTag(candidate.tags, denyTags)) {
+            errors.push(`Allowlisted entry violates deny tag rule: ${key} (tags=${candidate.tags.join(",")})`);
+            continue;
+        }
+        // Method gating reminder: non-GET is allowed only by explicit allowlist (which it is),
+        // but we keep a warning so reviewers notice.
+        if (method.toUpperCase() !== "GET") {
+            warnings.push(`Non-GET allowlisted: ${key}`);
+        }
+    }
+    return { errors, warnings };
+}
+async function getOpenApiDocument(inputPathOrUrl) {
+    if (inputPathOrUrl.startsWith("http")) {
+        console.log(`Fetching OpenAPI from URL: ${inputPathOrUrl}`);
+        const response = await axios.get(inputPathOrUrl);
+        const json = response.data;
+        return { raw: JSON.stringify(json), json };
+    }
+    const raw = fs.readFileSync(inputPathOrUrl, "utf-8");
+    return { raw, json: JSON.parse(raw) };
+}
+async function main() {
+    const defaults = getDefaults();
+    const args = parseArgs(process.argv.slice(2));
+    const allowlistPath = path.resolve(args.allowlistPath || defaults.allowlistPath);
+    const openapiPathOrUrl = args.openapiPath || process.env.ASTROMCP_OPENAPI_URL || defaults.openapiPath;
+    const { raw: allowRaw, json: allowlist } = readJsonFile(allowlistPath);
+    if (!allowlist || allowlist.schema !== "astromcp-dev-allowlist-v1" || !Array.isArray(allowlist.allow)) {
+        throw new Error(`Invalid allowlist schema at ${allowlistPath}`);
+    }
+    const denyPrefixes = allowlist.deny?.path_prefixes ?? [];
+    const denyTags = allowlist.deny?.tags ?? [];
+    const { raw: openapiRaw, json: openapi } = await getOpenApiDocument(openapiPathOrUrl);
+    if (!openapi || typeof openapi !== "object" || !openapi.paths) {
+        throw new Error(`Invalid OpenAPI document at ${openapiPathOrUrl}`);
+    }
+    const openapiHash = sha256(openapiRaw);
+    const allowlistHash = sha256(allowRaw);
+    const { candidatesGet, candidatesNonGet, index } = buildCandidates(openapi, denyPrefixes, denyTags);
+    const computedAllow = buildCommercialAllow([...candidatesGet, ...candidatesNonGet], allowlist.allow);
+    const allowlistForValidation = args.write ? { ...allowlist, allow: computedAllow } : allowlist;
+    const { errors, warnings } = validateAllowlist(allowlistForValidation, index, denyPrefixes, denyTags);
+    const report = {
+        ok: errors.length === 0,
+        allowlistPath,
+        openapiPath: openapiPathOrUrl,
+        openapi_sha256: openapiHash,
+        allowlist_sha256: allowlistHash,
+        counts: {
+            allow: allowlistForValidation.allow.length,
+            candidates_get: candidatesGet.length,
+            candidates_non_get: candidatesNonGet.length,
+            errors: errors.length,
+            warnings: warnings.length,
+        },
+        errors,
+        warnings,
+    };
+    if (args.write) {
+        const now = new Date().toISOString();
+        const updated = {
+            ...allowlist,
+            generated_from: openapiPathOrUrl,
+            last_generated_at: now,
+            openapi_sha256: openapiHash,
+            allow: computedAllow,
+            candidates_get: candidatesGet.map((c) => ({ method: c.method, path: c.path, tags: c.tags, operationId: c.operationId })),
+            candidates_non_get: candidatesNonGet.map((c) => ({ method: c.method, path: c.path, tags: c.tags, operationId: c.operationId })),
+            validation: {
+                ok: errors.length === 0,
+                errors,
+                warnings,
+            },
+        };
+        writeJsonFile(allowlistPath, updated);
+    }
+    if (args.check) {
+        if (!report.ok) {
+            console.error(JSON.stringify(report, null, 2));
+            process.exit(1);
+        }
+        // Print a small success line for CI.
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(JSON.stringify(report, null, 2));
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/scripts/pack-audit.d.ts

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

package/dist/scripts/pack-audit.js

@@ -0,0 +1,45 @@
+import { execSync } from "node:child_process";
+function main() {
+    const raw = execSync("npm pack --dry-run --json", {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "inherit"],
+    });
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error("Unable to parse npm pack --dry-run --json output.");
+    }
+    const pack = parsed[0];
+    const filePaths = new Set(pack.files.map((f) => f.path));
+    const required = ["dist/index.js", "config/dev-allowlist.json", "README.md", "package.json"];
+    const missing = required.filter((f) => !filePaths.has(f));
+    if (missing.length > 0) {
+        throw new Error(`Pack audit failed: required files missing: ${missing.join(", ")}`);
+    }
+    const bannedPatterns = [
+        /^src\//,
+        /^test\//,
+        /^scripts\//,
+        /^test-output/,
+        /^diff\.txt$/,
+        /^tsconfig(?:\.test)?\.json$/,
+        /^package-lock\.json$/,
+        /^node_modules\//,
+    ];
+    const banned = pack.files
+        .map((f) => f.path)
+        .filter((p) => bannedPatterns.some((re) => re.test(p)));
+    if (banned.length > 0) {
+        throw new Error(`Pack audit failed: unexpected files in tarball: ${banned.join(", ")}`);
+    }
+    const distFiles = pack.files.filter((f) => f.path.startsWith("dist/"));
+    if (distFiles.length === 0) {
+        throw new Error("Pack audit failed: no dist/* files present in tarball.");
+    }
+    console.log(JSON.stringify({
+        ok: true,
+        filename: pack.filename,
+        file_count: pack.files.length,
+        dist_file_count: distFiles.length,
+    }, null, 2));
+}
+main();

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

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