anyapi-mcp-server 1.8.1 → 2.0.0

package/build/tools/mutate-api.js

@@ -0,0 +1,222 @@
+import { z } from "zod";
+import { formatToolError, attachRateLimit, shrinkageError, placeholderError, } from "./shared.js";
+import { callApi } from "../api-client.js";
+import { getOrBuildSchema, schemaToSDL, executeQuery, computeShapeHash, } from "../graphql-schema.js";
+import { generateSuggestions } from "../query-suggestions.js";
+import { isNonJsonResult } from "../response-parser.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 { extractPathParamNames } from "../pre-write-backup.js";
+import { detectArrayShrinkage } from "../write-safety.js";
+import { applyPatch } from "../json-patch.js";
+export function registerMutateApi({ server, config, apiIndex }) {
+    server.tool("mutate_api", `Write data to a ${config.name} API endpoint (POST/PUT/PATCH/DELETE). ` +
+        "Two modes:\n" +
+        "1. Direct: provide 'body' or 'bodyFile' with the full request payload.\n" +
+        "2. Patch: provide 'patch' with JSON Patch operations (add/remove/replace). " +
+        "The tool automatically fetches the current resource state, applies your patches, " +
+        "and sends the complete result — you never need to hold the full data.\n" +
+        "Use inspect_api first to understand the endpoint's parameters and body schema. " +
+        "Optionally pass 'query' to select specific fields from the response via GraphQL.", {
+        method: z
+            .enum(["POST", "PUT", "DELETE", "PATCH"])
+            .describe("HTTP method"),
+        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."),
+        body: z
+            .record(z.unknown())
+            .optional()
+            .describe("Request body (direct mode). Mutually exclusive with 'patch' and 'bodyFile'."),
+        bodyFile: z
+            .string()
+            .optional()
+            .describe("Absolute path to a JSON file for the request body (direct mode). " +
+            "Mutually exclusive with 'body' and 'patch'."),
+        patch: z
+            .array(z.object({
+            op: z.enum(["add", "remove", "replace"]),
+            path: z.string().describe("JSON Pointer path (e.g. '/title', '/panels/3/title', '/tags/-' for append)"),
+            value: z.unknown().optional().describe("Value for add/replace operations"),
+        }))
+            .optional()
+            .describe("JSON Patch operations (RFC 6902 subset). The tool GETs the current resource, " +
+            "applies these patches, and sends the result. " +
+            "Mutually exclusive with 'body' and 'bodyFile'."),
+        headers: z
+            .record(z.string())
+            .optional()
+            .describe("Additional HTTP headers. Overrides default --header values."),
+        query: z
+            .string()
+            .optional()
+            .describe("Optional GraphQL selection query on the response " +
+            "(e.g. '{ id name status }' to select specific fields)."),
+        skipBackup: z
+            .boolean()
+            .optional()
+            .describe("Skip the automatic pre-write backup for PUT/PATCH (direct mode only). " +
+            "Default: false."),
+    }, async ({ method, path, params, body, bodyFile, patch, headers, query, skipBackup }) => {
+        try {
+            // Validate mutual exclusivity
+            const modeCount = [body, bodyFile, patch].filter((x) => x !== undefined).length;
+            if (modeCount > 1) {
+                return formatToolError(new Error("Only one of 'body', 'bodyFile', or 'patch' can be provided."), apiIndex);
+            }
+            // --- Patch mode ---
+            if (patch !== undefined) {
+                return await handlePatchMode({ config, apiIndex }, method, path, params, patch, headers, query);
+            }
+            // --- Direct mode ---
+            let resolvedBody;
+            try {
+                resolvedBody = resolveBody(body, bodyFile);
+            }
+            catch (err) {
+                return formatToolError(err, apiIndex);
+            }
+            // Placeholder detection (except DELETE)
+            if (resolvedBody && 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 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 });
+                }
+            }
+            // Execute the request
+            const { data: rawData, responseHeaders: respHeaders } = await callApi(config, method, path, params, resolvedBody, headers);
+            return await buildMutateResponse({ apiIndex }, method, path, rawData, respHeaders, resolvedBody, query, backupDataKey);
+        }
+        catch (error) {
+            return formatToolError(error, apiIndex, method, path);
+        }
+    });
+}
+/**
+ * Patch mode: GET current state, apply patches, send the result.
+ */
+async function handlePatchMode({ config, apiIndex }, method, path, params, operations, headers, query) {
+    if (operations.length === 0) {
+        return formatToolError(new Error("Patch operations array is empty."), apiIndex);
+    }
+    if (method === "DELETE") {
+        return formatToolError(new Error("Patch mode is not supported for DELETE — use direct mode (no body) instead."), apiIndex);
+    }
+    // Fetch current state (path params only, same as createBackup)
+    const pathParamNames = extractPathParamNames(path);
+    const pathOnlyParams = params
+        ? Object.fromEntries(Object.entries(params).filter(([k]) => pathParamNames.has(k)))
+        : undefined;
+    let currentData;
+    let currentHeaders;
+    try {
+        const result = await callApi(config, "GET", path, pathOnlyParams && Object.keys(pathOnlyParams).length > 0 ? pathOnlyParams : undefined, undefined, headers);
+        currentData = result.data;
+        currentHeaders = result.responseHeaders;
+    }
+    catch (err) {
+        return formatToolError(new Error(`Patch mode: failed to GET current state of ${path}: ` +
+            (err instanceof Error ? err.message : String(err))), apiIndex);
+    }
+    // Validate current data is a plain object
+    if (typeof currentData !== "object" || currentData === null || Array.isArray(currentData)) {
+        return formatToolError(new Error(`Patch mode requires the GET response to be a JSON object, ` +
+            `but got ${Array.isArray(currentData) ? "array" : typeof currentData}. ` +
+            `Use direct mode (body/bodyFile) instead.`), apiIndex);
+    }
+    // Store pre-patch state as backup
+    const backupDataKey = storeResponse("GET", path, currentData, currentHeaders);
+    // Apply patches
+    let patchedBody;
+    try {
+        patchedBody = applyPatch(currentData, operations);
+    }
+    catch (err) {
+        return formatToolError(new Error(`Patch failed: ${err instanceof Error ? err.message : String(err)}`), apiIndex);
+    }
+    // Placeholder detection on patched result
+    const endpoint = apiIndex.getEndpoint(method, path);
+    const warnings = detectPlaceholders(patchedBody, endpoint?.requestBodySchema);
+    if (warnings.length > 0)
+        return placeholderError(warnings);
+    // Execute the write with the complete patched body
+    const { data: rawData, responseHeaders: respHeaders } = await callApi(config, method, path, params, patchedBody, headers);
+    return await buildMutateResponse({ apiIndex }, method, path, rawData, respHeaders, patchedBody, query, backupDataKey, operations.length);
+}
+/**
+ * Build the response for mutate_api (shared between direct and patch modes).
+ */
+async function buildMutateResponse({ apiIndex }, method, path, rawData, respHeaders, resolvedBody, query, backupDataKey, patchCount) {
+    const newDataKey = storeResponse(method, path, rawData, respHeaders);
+    // Non-JSON response
+    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. The raw content is shown above.",
+                    }, null, 2) },
+            ],
+        };
+    }
+    const endpoint = apiIndex.getEndpoint(method, path);
+    const bodyHash = resolvedBody ? computeShapeHash(resolvedBody) : undefined;
+    const { schema, fromCache } = getOrBuildSchema(rawData, method, path, endpoint?.requestBodySchema, bodyHash);
+    // If query provided, apply GraphQL field selection
+    let resultData = rawData;
+    if (query) {
+        resultData = await executeQuery(schema, rawData, query);
+    }
+    const output = { _status: "COMPLETE" };
+    if (query && typeof resultData === "object" && resultData !== null && !Array.isArray(resultData)) {
+        Object.assign(output, resultData);
+    }
+    else {
+        output.data = resultData;
+    }
+    attachRateLimit(output, respHeaders);
+    if (!fromCache) {
+        output._schema = schemaToSDL(schema);
+        const suggestions = generateSuggestions(schema);
+        if (suggestions.length > 0) {
+            output._suggestedQueries = suggestions;
+        }
+    }
+    if (newDataKey)
+        output._dataKey = newDataKey;
+    if (backupDataKey) {
+        output._backupDataKey = backupDataKey;
+        output._backupHint = "Pre-write snapshot stored. Use query_api with this dataKey to retrieve original data if needed.";
+    }
+    if (patchCount !== undefined) {
+        output._patchApplied = `${patchCount} operation(s) applied successfully`;
+    }
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(output, null, 2) },
+        ],
+    };
+}

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.0",
   "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",