anyapi-mcp-server 1.8.1 → 2.0.1

package/build/tools/query-api.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { formatToolError, attachRateLimit } from "./shared.js";
+import { callApi } from "../api-client.js";
+import { getOrBuildSchema, schemaToSDL, executeQuery, } from "../graphql-schema.js";
+import { generateSuggestions } from "../query-suggestions.js";
+import { buildStatusMessage, estimateResultTokens, findPrimaryArrayLength } from "../token-budget.js";
+import { isNonJsonResult } from "../response-parser.js";
+import { detectPagination } from "../pagination.js";
+import { storeResponse, loadResponse } from "../data-cache.js";
+import { applyJsonFilter } from "../json-filter.js";
+export function registerQueryApi({ server, config, apiIndex }) {
+    server.tool("query_api", `Fetch data from a ${config.name} API endpoint (GET only), returning only the fields you select via GraphQL. ` +
+        "TIP: Pass the dataKey from inspect_api to reuse the cached response — zero HTTP calls. " +
+        "If you know the field names, call query_api directly — on first hit the schema SDL " +
+        "will be included in the response. If unsure, use inspect_api first for schema discovery.\n" +
+        "Use the exact root field names from the schema — do NOT assume generic names.\n" +
+        "- Raw array response ([...]): '{ items { id name } _count }'\n" +
+        "- Object response ({products: [...]}): '{ products { id name } }' (use actual field names from schema)\n" +
+        "Field names with dashes are converted to underscores (e.g. created-at → created_at). " +
+        "PAGINATION: To paginate the API itself, pass limit/offset inside 'params' (they become query string parameters). " +
+        "TOKEN BUDGET (three modes):\n" +
+        "1. No maxTokens/unlimited: responses over ~10k tokens return an error — use maxTokens or unlimited to proceed.\n" +
+        "2. maxTokens: truncates the deepest largest array to fit the budget.\n" +
+        "3. unlimited: true: returns the full response with no truncation.\n" +
+        "Check _status in the response: 'COMPLETE' means all data returned, 'TRUNCATED' means array was cut to fit budget. " +
+        "Every response includes a _dataKey for subsequent re-queries with different field selections. " +
+        "For write operations (POST/PUT/PATCH/DELETE), use mutate_api instead.", {
+        path: z
+            .string()
+            .describe("API path template (e.g. '/api/card/{id}')"),
+        params: z
+            .record(z.unknown())
+            .optional()
+            .describe("Path and query parameters. Path params like {id} are interpolated; " +
+            "remaining become query string. " +
+            "For API pagination, pass limit/offset here (e.g. { limit: 20, offset: 40 })."),
+        query: z
+            .string()
+            .describe("GraphQL selection query using field names from inspect_api schema " +
+            "(e.g. '{ products { id name } }' — NOT '{ items { ... } }' unless the API returns a raw array)"),
+        dataKey: z
+            .string()
+            .optional()
+            .describe("dataKey from a previous inspect_api or query_api response. " +
+            "If valid, reuses cached data — zero HTTP calls. Falls back to HTTP on miss/expiry."),
+        headers: z
+            .record(z.string())
+            .optional()
+            .describe("Additional HTTP headers for this request. Overrides default --header values."),
+        jsonFilter: z
+            .string()
+            .optional()
+            .describe("Dot-path to extract from the result after GraphQL query executes. " +
+            "Use \".\" for nested access, \"[]\" to traverse arrays. " +
+            "Example: \"data[].attributes.message\" extracts the message field from each element of the data array."),
+        maxTokens: z
+            .number()
+            .min(100)
+            .optional()
+            .describe("Token budget for the response. If exceeded, the deepest largest array is truncated to fit. " +
+            "Select fewer fields to fit more items. Without this or unlimited, responses over ~10k tokens are rejected."),
+        unlimited: z
+            .boolean()
+            .optional()
+            .describe("Set to true to return the full response with no token budget enforcement. " +
+            "Use when you know exactly what fields you need and want all data."),
+    }, async ({ path, params, query, dataKey, headers, jsonFilter, maxTokens, unlimited }) => {
+        try {
+            let rawData;
+            let respHeaders;
+            // Try dataKey cache first
+            const cached = dataKey ? loadResponse(dataKey) : null;
+            let cachedDataAge;
+            if (cached) {
+                rawData = cached.data;
+                respHeaders = cached.responseHeaders;
+                cachedDataAge = Math.round((Date.now() - cached.storedAt) / 1000);
+            }
+            else {
+                const result = await callApi(config, "GET", path, params, undefined, headers);
+                rawData = result.data;
+                respHeaders = result.responseHeaders;
+            }
+            // Store response for future re-queries
+            const newDataKey = storeResponse("GET", path, rawData, respHeaders);
+            // Non-JSON response — skip GraphQL layer
+            if (isNonJsonResult(rawData)) {
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({
+                                rawResponse: rawData,
+                                responseHeaders: respHeaders,
+                                ...(newDataKey ? { _dataKey: newDataKey } : {}),
+                                hint: "This endpoint returned a non-JSON response. GraphQL querying is not available. " +
+                                    "The raw parsed content is shown above.",
+                            }, null, 2) },
+                    ],
+                };
+            }
+            const endpoint = apiIndex.getEndpoint("GET", path);
+            const { schema, fromCache } = getOrBuildSchema(rawData, "GET", path, endpoint?.requestBodySchema);
+            let queryResult = await executeQuery(schema, rawData, query, unlimited ? { unlimited: true } : undefined);
+            if (jsonFilter) {
+                queryResult = applyJsonFilter(queryResult, jsonFilter);
+            }
+            // Token budget: three-mode dispatch
+            let status;
+            let budgetResult;
+            if (unlimited) {
+                const arrayLen = typeof queryResult === "object" && queryResult !== null && !Array.isArray(queryResult)
+                    ? findPrimaryArrayLength(queryResult)
+                    : null;
+                status = arrayLen !== null ? `COMPLETE (${arrayLen} items)` : "COMPLETE";
+                budgetResult = queryResult;
+            }
+            else if (maxTokens !== undefined) {
+                ({ status, result: budgetResult } = buildStatusMessage(queryResult, maxTokens));
+            }
+            else {
+                // No budget, no unlimited → enforce 10k safety limit
+                const estimatedTokens = estimateResultTokens(queryResult);
+                if (estimatedTokens > 10000) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    error: `Response too large (~${estimatedTokens} tokens). To proceed, either:\n` +
+                                        `1. Use inspect_api to inspect the schema and select fewer fields\n` +
+                                        `2. Set maxTokens (e.g. maxTokens: 4000) to truncate automatically\n` +
+                                        `3. Set unlimited: true if you need the full response`,
+                                    estimatedTokens,
+                                }, null, 2),
+                            }],
+                        isError: true,
+                    };
+                }
+                const arrayLen = typeof queryResult === "object" && queryResult !== null && !Array.isArray(queryResult)
+                    ? findPrimaryArrayLength(queryResult)
+                    : null;
+                status = arrayLen !== null ? `COMPLETE (${arrayLen} items)` : "COMPLETE";
+                budgetResult = queryResult;
+            }
+            if (typeof budgetResult === "object" && budgetResult !== null && !Array.isArray(budgetResult)) {
+                const qr = budgetResult;
+                attachRateLimit(qr, respHeaders);
+                if (!fromCache) {
+                    qr._schema = schemaToSDL(schema);
+                    const suggestions = generateSuggestions(schema);
+                    if (suggestions.length > 0) {
+                        qr._suggestedQueries = suggestions;
+                    }
+                }
+                const pagination = detectPagination(rawData, endpoint?.parameters);
+                if (pagination) {
+                    qr._pagination = pagination;
+                }
+                const output = { _status: status, ...qr };
+                if (newDataKey)
+                    output._dataKey = newDataKey;
+                if (cachedDataAge !== undefined)
+                    output._dataAge = `${cachedDataAge}s ago (from cache)`;
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(output, null, 2) },
+                    ],
+                };
+            }
+            const output = { _status: status, data: budgetResult };
+            if (newDataKey)
+                output._dataKey = newDataKey;
+            if (cachedDataAge !== undefined)
+                output._dataAge = `${cachedDataAge}s ago (from cache)`;
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(output, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return formatToolError(error, apiIndex, "GET", path);
+        }
+    });
+}

package/build/tools/shared.js

@@ -0,0 +1,65 @@
+import { ApiError, buildErrorContext } from "../error-context.js";
+import { RetryableError } from "../retry.js";
+import { parseRateLimits } from "../api-client.js";
+export const WRITE_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
+export function formatToolError(error, apiIndex, method, path) {
+    if ((error instanceof ApiError || error instanceof RetryableError) && method && path) {
+        const endpoint = apiIndex.getEndpoint(method, path);
+        const context = buildErrorContext(error, method, path, endpoint);
+        return {
+            content: [{ type: "text", text: JSON.stringify(context, null, 2) }],
+            isError: true,
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+        isError: true,
+    };
+}
+export function attachRateLimit(result, respHeaders) {
+    const rl = parseRateLimits(respHeaders);
+    if (!rl)
+        return;
+    result._rateLimit = rl;
+    if (rl.remaining !== null &&
+        (rl.remaining <= 5 || (rl.limit !== null && rl.remaining / rl.limit <= 0.1))) {
+        result._rateLimitWarning =
+            `Rate limit nearly exhausted (${rl.remaining}${rl.limit !== null ? `/${rl.limit}` : ""} remaining` +
+                `${rl.resetAt ? `, resets ${rl.resetAt}` : ""}). Consider reducing request frequency.`;
+    }
+}
+export function shrinkageError(warnings, keyInfo) {
+    const keyLabel = keyInfo.backupDataKey ? "backupDataKey" : "dataKey";
+    const keyValue = keyInfo.backupDataKey ?? keyInfo.dataKey;
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    error: "Array shrinkage detected: request body has significantly fewer array items than current state",
+                    warnings,
+                    ...(keyValue ? { [keyLabel]: keyValue } : {}),
+                    hint: "This often happens when truncated query results are sent back as the full payload. " +
+                        "Consider using mutate_api with 'patch' mode to apply targeted changes without needing the full data. " +
+                        "Or use query_api with unlimited: true and the " + keyLabel + " to retrieve the full current data. " +
+                        "If this is intentional, use skipBackup: true to bypass this check.",
+                }, null, 2),
+            }],
+        isError: true,
+    };
+}
+export function placeholderError(warnings) {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    error: "Potential placeholder values detected in request body",
+                    warnings,
+                    hint: "The request was blocked to prevent sending placeholder data. " +
+                        "If the body is too large to send inline, use the 'bodyFile' parameter " +
+                        "with an absolute path to a JSON file containing the real content.",
+                }, null, 2),
+            }],
+        isError: true,
+    };
+}

package/build/write-safety.js

@@ -0,0 +1,56 @@
+/**
+ * Compare array field sizes in a PUT/PATCH body against the backup (current state).
+ * Returns warnings when the body has significantly fewer items than the backup,
+ * which usually means truncated query results leaked into the write payload.
+ *
+ * @param body - The request body being sent
+ * @param backupData - The full data from the pre-write backup
+ * @param options.threshold - Ratio below which to warn (default 0.5 = body < 50% of backup)
+ */
+export function detectArrayShrinkage(body, backupData, options) {
+    if (typeof backupData !== "object" || backupData === null || Array.isArray(backupData)) {
+        return [];
+    }
+    const threshold = options?.threshold ?? 0.5;
+    const minBackupLength = 5;
+    const warnings = [];
+    const backup = backupData;
+    // Level 1: direct fields
+    for (const [key, bodyVal] of Object.entries(body)) {
+        const backupVal = backup[key];
+        if (Array.isArray(bodyVal) && Array.isArray(backupVal)) {
+            if (backupVal.length >= minBackupLength &&
+                bodyVal.length / backupVal.length < threshold) {
+                warnings.push({
+                    field: key,
+                    bodyLength: bodyVal.length,
+                    backupLength: backupVal.length,
+                    reason: `Request body has ${bodyVal.length} items in '${key}' but the current resource has ${backupVal.length}. ` +
+                        `This PUT/PATCH will replace the entire array — ${backupVal.length - bodyVal.length} items will be lost.`,
+                });
+            }
+        }
+        // Level 2: one level of nesting
+        if (typeof bodyVal === "object" && bodyVal !== null && !Array.isArray(bodyVal) &&
+            typeof backupVal === "object" && backupVal !== null && !Array.isArray(backupVal)) {
+            const bodyObj = bodyVal;
+            const backupObj = backupVal;
+            for (const [nestedKey, nestedBodyVal] of Object.entries(bodyObj)) {
+                const nestedBackupVal = backupObj[nestedKey];
+                if (Array.isArray(nestedBodyVal) && Array.isArray(nestedBackupVal)) {
+                    if (nestedBackupVal.length >= minBackupLength &&
+                        nestedBodyVal.length / nestedBackupVal.length < threshold) {
+                        warnings.push({
+                            field: `${key}.${nestedKey}`,
+                            bodyLength: nestedBodyVal.length,
+                            backupLength: nestedBackupVal.length,
+                            reason: `Request body has ${nestedBodyVal.length} items in '${key}.${nestedKey}' but the current resource has ${nestedBackupVal.length}. ` +
+                                `This PUT/PATCH will replace the entire array — ${nestedBackupVal.length - nestedBodyVal.length} items will be lost.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return warnings;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyapi-mcp-server",
-  "version": "1.8.1",
+  "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();
-}