anyapi-mcp-server 2.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyapi-mcp-server",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A universal MCP server that connects any REST API (via OpenAPI spec) to AI assistants, with GraphQL-style field selection and automatic schema inference.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/build/response-cache.js

@@ -1,49 +0,0 @@
-const DEFAULT_TTL_MS = 30_000;
-const cache = new Map();
-export function buildCacheKey(method, pathTemplate, params, body, extraHeaders) {
-    const parts = [method, pathTemplate];
-    if (params && Object.keys(params).length > 0) {
-        parts.push(JSON.stringify(params, Object.keys(params).sort()));
-    }
-    if (body && Object.keys(body).length > 0) {
-        parts.push(JSON.stringify(body, Object.keys(body).sort()));
-    }
-    if (extraHeaders && Object.keys(extraHeaders).length > 0) {
-        parts.push(JSON.stringify(extraHeaders, Object.keys(extraHeaders).sort()));
-    }
-    return parts.join("|");
-}
-export function getCached(key) {
-    const entry = cache.get(key);
-    if (!entry)
-        return undefined;
-    if (Date.now() > entry.expiresAt) {
-        cache.delete(key);
-        return undefined;
-    }
-    return entry.data;
-}
-/** Read and immediately evict a cache entry (one-shot consumption). */
-export function consumeCached(key) {
-    const entry = cache.get(key);
-    if (!entry)
-        return undefined;
-    cache.delete(key);
-    if (Date.now() > entry.expiresAt)
-        return undefined;
-    return entry.data;
-}
-export function setCache(key, data, ttlMs = DEFAULT_TTL_MS) {
-    cache.set(key, { data, expiresAt: Date.now() + ttlMs });
-}
-export function evictExpired() {
-    const now = Date.now();
-    for (const [key, entry] of cache) {
-        if (now > entry.expiresAt) {
-            cache.delete(key);
-        }
-    }
-}
-export function clearCache() {
-    cache.clear();
-}

package/build/tools/call-api.js

@@ -1,204 +0,0 @@
-import { z } from "zod";
-import { WRITE_METHODS, formatToolError, attachRateLimit, shrinkageError, placeholderError, } from "./shared.js";
-import { callApi } from "../api-client.js";
-import { getOrBuildSchema, schemaToSDL, computeShapeHash, collectJsonFields, computeFieldCosts, collectArrayLengths, } from "../graphql-schema.js";
-import { generateSuggestions } from "../query-suggestions.js";
-import { isNonJsonResult } from "../response-parser.js";
-import { detectPagination, PAGINATION_PARAM_NAMES } from "../pagination.js";
-import { storeResponse, loadResponse } from "../data-cache.js";
-import { resolveBody } from "../body-file.js";
-import { detectPlaceholders } from "../body-validation.js";
-import { createBackup } from "../pre-write-backup.js";
-import { detectArrayShrinkage } from "../write-safety.js";
-export function registerCallApi({ server, config, apiIndex }) {
-    server.tool("call_api", `Inspect a ${config.name} API endpoint. Makes a real request and returns ONLY the ` +
-        "inferred GraphQL schema (SDL) showing all available fields and their types. " +
-        "No response data is returned — use query_api to fetch actual data. " +
-        "IMPORTANT: Read the returned schema carefully. The root field names in the schema " +
-        "are what you must use in query_api — do NOT assume generic names like 'items'. " +
-        "For example, if the schema shows 'products: [Product]', query as '{ products { id name } }', not '{ items { id name } }'. " +
-        "Also returns accepted parameters (name, location, required) from the API spec, " +
-        "and suggestedQueries with ready-to-use GraphQL queries. " +
-        "Returns a dataKey — pass it to query_api to reuse the cached response (zero HTTP calls). " +
-        "Use list_api first to discover endpoints.", {
-        method: z
-            .enum(["GET", "POST", "PUT", "DELETE", "PATCH"])
-            .describe("HTTP method"),
-        path: z
-            .string()
-            .describe("API path template (e.g. '/api/card/{id}'). Use list_api to discover paths."),
-        params: z
-            .record(z.unknown())
-            .optional()
-            .describe("Path and query parameters as key-value pairs. " +
-            "Path params like {id} are interpolated; remaining become query string for GET."),
-        body: z
-            .record(z.unknown())
-            .optional()
-            .describe("Request body for POST/PUT/PATCH"),
-        bodyFile: z
-            .string()
-            .optional()
-            .describe("Absolute path to a JSON file to use as request body. " +
-            "Mutually exclusive with 'body'. Use for large payloads that cannot be inlined."),
-        headers: z
-            .record(z.string())
-            .optional()
-            .describe("Additional HTTP headers for this request (e.g. { \"Authorization\": \"Bearer <token>\" }). " +
-            "Overrides default --header values."),
-        skipBackup: z
-            .boolean()
-            .optional()
-            .describe("Skip the automatic pre-write backup for PUT/PATCH requests. " +
-            "Default: false (backup is created automatically)."),
-    }, async ({ method, path, params, body, bodyFile, headers, skipBackup }) => {
-        try {
-            // Resolve body from inline or file
-            let resolvedBody;
-            try {
-                resolvedBody = resolveBody(body, bodyFile);
-            }
-            catch (err) {
-                return formatToolError(err, apiIndex);
-            }
-            // Placeholder detection for write methods (except DELETE)
-            if (resolvedBody && WRITE_METHODS.has(method) && method !== "DELETE") {
-                const endpoint = apiIndex.getEndpoint(method, path);
-                const warnings = detectPlaceholders(resolvedBody, endpoint?.requestBodySchema);
-                if (warnings.length > 0)
-                    return placeholderError(warnings);
-            }
-            // Pre-write backup for PUT/PATCH
-            let backupDataKey;
-            if ((method === "PATCH" || method === "PUT") && !skipBackup) {
-                backupDataKey = await createBackup(config, method, path, params, headers);
-            }
-            // Array shrinkage detection: compare body against backup
-            if (backupDataKey && resolvedBody) {
-                const backupEntry = loadResponse(backupDataKey);
-                if (backupEntry) {
-                    const shrinkWarnings = detectArrayShrinkage(resolvedBody, backupEntry.data);
-                    if (shrinkWarnings.length > 0)
-                        return shrinkageError(shrinkWarnings, { backupDataKey });
-                }
-            }
-            const { data, responseHeaders: respHeaders } = await callApi(config, method, path, params, resolvedBody, headers);
-            const dataKey = storeResponse(method, path, data, respHeaders);
-            // Non-JSON response — skip GraphQL layer, return raw parsed data
-            if (isNonJsonResult(data)) {
-                return {
-                    content: [
-                        { type: "text", text: JSON.stringify({
-                                rawResponse: data,
-                                responseHeaders: respHeaders,
-                                dataKey,
-                                hint: "This endpoint returned a non-JSON response. The raw parsed content is shown above. " +
-                                    "GraphQL schema inference is not available for non-JSON responses — use the data directly.",
-                            }, null, 2) },
-                    ],
-                };
-            }
-            const endpoint = apiIndex.getEndpoint(method, path);
-            const bodyHash = WRITE_METHODS.has(method) && resolvedBody ? computeShapeHash(resolvedBody) : undefined;
-            const { schema, shapeHash } = getOrBuildSchema(data, method, path, endpoint?.requestBodySchema, bodyHash);
-            const sdl = schemaToSDL(schema);
-            const result = { graphqlSchema: sdl, shapeHash, responseHeaders: respHeaders };
-            if (dataKey)
-                result.dataKey = dataKey;
-            if (bodyHash)
-                result.bodyHash = bodyHash;
-            if (backupDataKey) {
-                result.backupDataKey = backupDataKey;
-                result.backupHint = "Pre-write snapshot stored. Use query_api with this dataKey to retrieve original data if needed.";
-            }
-            attachRateLimit(result, respHeaders);
-            if (endpoint && endpoint.parameters.length > 0) {
-                result.parameters = endpoint.parameters.map((p) => ({
-                    name: p.name,
-                    in: p.in,
-                    required: p.required,
-                    ...(p.description ? { description: p.description } : {}),
-                    ...(p.in === "query" && PAGINATION_PARAM_NAMES.has(p.name) ? { pagination: true } : {}),
-                }));
-                const paginationParams = endpoint.parameters
-                    .filter((p) => p.in === "query" && PAGINATION_PARAM_NAMES.has(p.name))
-                    .map((p) => p.name);
-                if (paginationParams.length > 0) {
-                    result.paginationParams = paginationParams;
-                }
-            }
-            // Smart query suggestions
-            const suggestions = generateSuggestions(schema);
-            if (suggestions.length > 0) {
-                result.suggestedQueries = suggestions;
-            }
-            // Per-field token costs
-            const fieldCosts = computeFieldCosts(data);
-            result.fieldTokenCosts = fieldCosts;
-            // Actual array lengths for truncation awareness
-            const arrayLengths = collectArrayLengths(data);
-            if (Object.keys(arrayLengths).length > 0) {
-                result.fieldArrayLengths = arrayLengths;
-            }
-            // Budget examples
-            const allFieldsCost = fieldCosts._total;
-            if (Array.isArray(data) && data.length > 0 && fieldCosts._perItem) {
-                const perItem = fieldCosts._perItem;
-                result.budgetExamples = [
-                    `All fields: ~${perItem} tokens/item, ~${allFieldsCost} tokens total`,
-                ];
-            }
-            else if (typeof data === "object" && data !== null) {
-                result.budgetExamples = [
-                    `All fields: ~${allFieldsCost} tokens total`,
-                ];
-            }
-            // Flag JSON scalar fields so the AI knows which fields are opaque
-            const jsonFields = collectJsonFields(schema);
-            if (jsonFields.length > 0) {
-                result.jsonFields = jsonFields;
-                result.jsonFieldsHint =
-                    "These fields contain heterogeneous or deeply nested data that cannot be queried " +
-                        "with GraphQL field selection. Query them as-is and parse the returned JSON directly.";
-            }
-            // Pagination detection from response data
-            const pagination = detectPagination(data, endpoint?.parameters);
-            if (pagination) {
-                result._pagination = pagination;
-            }
-            const paginationParamsList = result.paginationParams ?? [];
-            const paginationSuffix = paginationParamsList.length > 0
-                ? ` This API supports pagination via: ${paginationParamsList.join(", ")}. Pass these inside params.`
-                : "";
-            if (Array.isArray(data)) {
-                result.totalItems = data.length;
-                result.hint =
-                    "Use query_api with field names from the schema above. " +
-                        "For raw arrays: '{ items { ... } _count }'. " +
-                        "For paginated APIs, pass limit/offset inside params (as query string parameters to the API), " +
-                        "NOT as top-level tool parameters. " +
-                        "Use fieldTokenCosts to understand per-field token costs and select fields wisely. " +
-                        "Responses over ~10k tokens require maxTokens (to truncate) or unlimited: true (for full data)." +
-                        paginationSuffix;
-            }
-            else {
-                result.hint =
-                    "Use query_api with the exact root field names from the schema above (e.g. if schema shows " +
-                        "'products: [Product]', query as '{ products { id name } }' — do NOT use '{ items { ... } }'). " +
-                        "For paginated APIs, pass limit/offset inside params (as query string parameters to the API), " +
-                        "NOT as top-level tool parameters. " +
-                        "Use fieldTokenCosts to understand per-field token costs and select fields wisely. " +
-                        "Responses over ~10k tokens require maxTokens (to truncate) or unlimited: true (for full data)." +
-                        paginationSuffix;
-            }
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify(result, null, 2) },
-                ],
-            };
-        }
-        catch (error) {
-            return formatToolError(error, apiIndex, method, path);
-        }
-    });
-}

package/build/tools/explain-api.js

@@ -1,86 +0,0 @@
-import { z } from "zod";
-export function registerExplainApi({ server, config, apiIndex }) {
-    server.tool("explain_api", `Get detailed documentation for a ${config.name} API endpoint from the spec. ` +
-        "Returns all available spec information — summary, description, parameters, " +
-        "request body schema, response codes, deprecation status — without making any HTTP request. " +
-        "Use list_api first to discover endpoints, then explain_api to understand them before calling.", {
-        method: z
-            .enum(["GET", "POST", "PUT", "DELETE", "PATCH"])
-            .describe("HTTP method"),
-        path: z
-            .string()
-            .describe("API path template (e.g. '/api/card/{id}')"),
-    }, async ({ method, path }) => {
-        try {
-            const endpoint = apiIndex.getEndpoint(method, path);
-            if (!endpoint) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: `Endpoint not found: ${method} ${path}`,
-                                hint: "Use list_api to discover available endpoints.",
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            const result = {
-                method: endpoint.method,
-                path: endpoint.path,
-                summary: endpoint.summary,
-            };
-            if (endpoint.description) {
-                result.description = endpoint.description;
-            }
-            if (endpoint.operationId) {
-                result.operationId = endpoint.operationId;
-            }
-            if (endpoint.deprecated) {
-                result.deprecated = true;
-            }
-            result.tag = endpoint.tag;
-            if (endpoint.parameters.length > 0) {
-                result.parameters = endpoint.parameters.map((p) => ({
-                    name: p.name,
-                    in: p.in,
-                    required: p.required,
-                    ...(p.description ? { description: p.description } : {}),
-                }));
-            }
-            if (endpoint.hasRequestBody) {
-                const bodyInfo = {};
-                if (endpoint.requestBodyDescription) {
-                    bodyInfo.description = endpoint.requestBodyDescription;
-                }
-                if (endpoint.requestBodySchema) {
-                    bodyInfo.contentType = endpoint.requestBodySchema.contentType;
-                    bodyInfo.properties = endpoint.requestBodySchema.properties;
-                }
-                result.requestBody = bodyInfo;
-            }
-            if (endpoint.responses && endpoint.responses.length > 0) {
-                result.responses = endpoint.responses;
-            }
-            if (endpoint.externalDocs) {
-                result.externalDocs = endpoint.externalDocs;
-            }
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify(result, null, 2) },
-                ],
-            };
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify({ error: message }) },
-                ],
-                isError: true,
-            };
-        }
-    });
-}