anyapi-mcp-server 1.7.0 → 1.8.0

package/README.md

@@ -102,7 +102,7 @@ Discover what the API offers. Call with no arguments to see all categories, prov
 
 ### `call_api` — Inspect an endpoint
 
-Makes a real HTTP request and returns the **inferred GraphQL schema** (SDL) — not the data itself. Use this to discover the response shape and get `suggestedQueries` you can copy into `query_api`. Also returns per-field token costs (`fieldTokenCosts`) and a `dataKey` for cache reuse.
+Makes a real HTTP request and returns the **inferred GraphQL schema** (SDL) — not the data itself. Use this to discover the response shape and get `suggestedQueries` you can copy into `query_api`. Also returns per-field token costs (`fieldTokenCosts`) and a `dataKey` for cache reuse. For PUT/PATCH requests, automatically creates a pre-write backup (returns `backupDataKey`). Supports `bodyFile` for large payloads and blocks requests with detected placeholder values.
 
 ### `query_api` — Fetch data
 
@@ -120,6 +120,8 @@ Key parameters:
 - **`maxTokens`** — token budget for the response (default 4000). Arrays are truncated to fit.
 - **`dataKey`** — reuse cached data from a previous `call_api` or `query_api` response.
 - **`jsonFilter`** — dot-path to extract nested values after the GraphQL query (e.g. `"data[].attributes.name"`).
+- **`bodyFile`** — absolute path to a JSON file to use as request body (mutually exclusive with `body`). Use for large payloads that can't be sent inline.
+- **`skipBackup`** — skip the automatic pre-write backup for PUT/PATCH requests (default: `false`).
 
 ### `explain_api` — Read the docs
 
@@ -187,6 +189,8 @@ OpenAPI/Postman spec
 - **JSON filter** — `query_api` accepts a `jsonFilter` dot-path for post-query extraction (e.g. `"data[].name"`)
 - **Retry with backoff** — automatic retries for 429/5xx with exponential backoff and `Retry-After` support
 - **Multi-format** — parses JSON, XML, CSV, and plain text responses
+- **Safe writes** — PUT/PATCH requests automatically snapshot the resource before writing (`backupDataKey`); placeholder values (e.g. `PLACEHOLDER`, `TODO`, `file://`) are detected and blocked before sending
+- **File-based body** — `bodyFile` parameter accepts an absolute path to a JSON file, enabling large payloads that can't be sent inline
 - **Rich errors** — structured error messages with status-specific suggestions and spec context for self-correction
 - **OAuth 2.0** — Authorization Code (with PKCE) and Client Credentials flows with automatic token refresh
 - **Env var interpolation** — `${ENV_VAR}` in base URLs, headers, and spec paths

package/build/body-file.js

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { resolve, isAbsolute } from "node:path";
+import { platform } from "node:process";
+/**
+ * Resolve request body from either an inline `body` object or a `bodyFile` path.
+ * Throws if both are provided, if the path is relative, or if the file is unreadable/invalid JSON.
+ */
+export function resolveBody(body, bodyFile) {
+    if (body && bodyFile) {
+        throw new Error("Cannot specify both 'body' and 'bodyFile'. Use one or the other.");
+    }
+    if (!bodyFile)
+        return body;
+    // Validate absolute path
+    const isAbsolutePath = isAbsolute(bodyFile) ||
+        (platform === "win32" && /^[A-Za-z]:[\\/]/.test(bodyFile));
+    if (!isAbsolutePath) {
+        throw new Error(`bodyFile must be an absolute path, got: ${bodyFile}`);
+    }
+    const fullPath = resolve(bodyFile);
+    let content;
+    try {
+        content = readFileSync(fullPath, "utf-8");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to read bodyFile '${fullPath}': ${msg}`);
+    }
+    try {
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("bodyFile must contain a JSON object (not an array or primitive)");
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            throw new Error(`bodyFile '${fullPath}' contains invalid JSON: ${err.message}`);
+        }
+        throw err;
+    }
+}

package/build/body-validation.js

@@ -0,0 +1,102 @@
+const CONTENT_FIELD_NAMES = new Set([
+    "html_content",
+    "html",
+    "content",
+    "body",
+    "template",
+    "description",
+    "text",
+    "message",
+    "markup",
+    "source",
+    "html_body",
+    "plain_content",
+    "rich_content",
+]);
+const EXACT_KEYWORDS = new Set(["placeholder", "todo", "tbd", "fixme", "xxx"]);
+const PATTERN_REGEXES = [
+    /^file:\/\//,
+    /^<[^>]+>$/,
+    /^\[[^\]]+\]$/,
+    /^content of /i,
+    /^see (above|below|file)/i,
+];
+function isContentField(name) {
+    return CONTENT_FIELD_NAMES.has(name) || name.includes("html");
+}
+function checkKeywordPatterns(value) {
+    const lower = value.trim().toLowerCase();
+    if (EXACT_KEYWORDS.has(lower)) {
+        return `Suspicious keyword: "${value.trim()}"`;
+    }
+    for (const re of PATTERN_REGEXES) {
+        if (re.test(value.trim())) {
+            return `Suspicious pattern: "${value.trim()}"`;
+        }
+    }
+    return null;
+}
+function hasHtmlSchemaHint(fieldName, schema) {
+    if (!schema?.properties)
+        return false;
+    const prop = schema.properties[fieldName];
+    if (!prop?.description)
+        return false;
+    const desc = prop.description.toLowerCase();
+    return /html|content|template|body|markup/.test(desc);
+}
+/**
+ * Detect placeholder values in a request body that likely indicate
+ * the LLM failed to emit real content.
+ */
+export function detectPlaceholders(body, schema) {
+    if (!body || typeof body !== "object")
+        return [];
+    const warnings = [];
+    const keys = Object.keys(body);
+    // Pass 1: keyword patterns on string fields (shallow + 1 level nested)
+    for (const [key, value] of Object.entries(body)) {
+        if (typeof value === "string") {
+            const reason = checkKeywordPatterns(value);
+            if (reason && (isContentField(key) || keys.length <= 2)) {
+                warnings.push({ field: key, value, reason });
+            }
+        }
+        else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            // One level nested
+            for (const [nestedKey, nestedValue] of Object.entries(value)) {
+                if (typeof nestedValue === "string") {
+                    const reason = checkKeywordPatterns(nestedValue);
+                    if (reason && (isContentField(nestedKey) || keys.length <= 2)) {
+                        warnings.push({
+                            field: `${key}.${nestedKey}`,
+                            value: nestedValue,
+                            reason,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Pass 2: short value for known content fields
+    for (const [key, value] of Object.entries(body)) {
+        if (typeof value !== "string")
+            continue;
+        if (value.length >= 50)
+            continue;
+        const fieldIsContent = isContentField(key);
+        const schemaHasHtml = hasHtmlSchemaHint(key, schema);
+        if ((fieldIsContent || schemaHasHtml) && (schemaHasHtml || key.includes("html"))) {
+            // Don't duplicate warnings already found in pass 1
+            const alreadyWarned = warnings.some((w) => w.field === key);
+            if (!alreadyWarned) {
+                warnings.push({
+                    field: key,
+                    value,
+                    reason: `Suspiciously short value (${value.length} chars) for a content/HTML field`,
+                });
+            }
+        }
+    }
+    return warnings;
+}

package/build/index.js

@@ -16,6 +16,9 @@ import { startAuth, exchangeCode, awaitCallback, storeTokens, getTokens, isToken
 import { detectPagination, PAGINATION_PARAM_NAMES } from "./pagination.js";
 import { applyJsonFilter } from "./json-filter.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";
 const WRITE_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
 const config = await loadConfig();
 initLogger(config.logPath ?? null);
@@ -171,14 +174,57 @@ server.tool("call_api", `Inspect a ${config.name} API endpoint. Makes a real req
         .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."),
-}, async ({ method, path, params, body, headers }) => {
+    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 {
-        const { data, responseHeaders: respHeaders } = await callApi(config, method, path, params, body, headers);
+        // Resolve body from inline or file
+        let resolvedBody;
+        try {
+            resolvedBody = resolveBody(body, bodyFile);
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
+        // 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 {
+                    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,
+                };
+            }
+        }
+        // Pre-write backup for PUT/PATCH
+        let backupDataKey;
+        if ((method === "PATCH" || method === "PUT") && !skipBackup) {
+            backupDataKey = await createBackup(config, method, path, params, headers);
+        }
+        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)) {
@@ -195,12 +241,16 @@ server.tool("call_api", `Inspect a ${config.name} API endpoint. Makes a real req
             };
         }
         const endpoint = apiIndex.getEndpoint(method, path);
-        const bodyHash = WRITE_METHODS.has(method) && body ? computeShapeHash(body) : undefined;
+        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, dataKey, responseHeaders: respHeaders };
         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) => ({
@@ -319,6 +369,11 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
         .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."),
     query: z
         .string()
         .describe("GraphQL selection query using field names from call_api schema " +
@@ -345,11 +400,45 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
         .optional()
         .describe("Token budget for the response (default: 4000). If exceeded, array results are truncated to fit. " +
         "Select fewer fields to fit more items."),
-}, async ({ method, path, params, body, query, dataKey, headers, jsonFilter, maxTokens }) => {
+    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, query, dataKey, headers, jsonFilter, maxTokens, skipBackup }) => {
     try {
         const budget = maxTokens ?? 4000;
+        // Resolve body from inline or file
+        let resolvedBody;
+        try {
+            resolvedBody = resolveBody(body, bodyFile);
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
+        // 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 {
+                    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,
+                };
+            }
+        }
         let rawData;
         let respHeaders;
+        let backupDataKey;
         // Try dataKey cache first
         const cached = dataKey ? loadResponse(dataKey) : null;
         if (cached) {
@@ -357,7 +446,11 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
             respHeaders = cached.responseHeaders;
         }
         else {
-            const result = await callApi(config, method, path, params, body, headers);
+            // Pre-write backup for PUT/PATCH
+            if ((method === "PATCH" || method === "PUT") && !skipBackup) {
+                backupDataKey = await createBackup(config, method, path, params, headers);
+            }
+            const result = await callApi(config, method, path, params, resolvedBody, headers);
             rawData = result.data;
             respHeaders = result.responseHeaders;
         }
@@ -378,14 +471,17 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
             };
         }
         const endpoint = apiIndex.getEndpoint(method, path);
-        const bodyHash = WRITE_METHODS.has(method) && body ? computeShapeHash(body) : undefined;
+        const bodyHash = WRITE_METHODS.has(method) && resolvedBody ? computeShapeHash(resolvedBody) : undefined;
         const { schema, shapeHash, fromCache } = getOrBuildSchema(rawData, method, path, endpoint?.requestBodySchema, bodyHash);
         let queryResult = await executeQuery(schema, rawData, query);
         if (jsonFilter) {
             queryResult = applyJsonFilter(queryResult, jsonFilter);
         }
-        // Apply token budget
-        const { status, result: budgetResult } = buildStatusMessage(queryResult, budget);
+        // Apply token budget (skip for write operations — mutation responses shouldn't be truncated)
+        const isWrite = WRITE_METHODS.has(method);
+        const { status, result: budgetResult } = isWrite
+            ? { status: "COMPLETE", result: queryResult }
+            : buildStatusMessage(queryResult, budget);
         if (typeof budgetResult === "object" && budgetResult !== null && !Array.isArray(budgetResult)) {
             const qr = budgetResult;
             attachRateLimit(qr, respHeaders);
@@ -404,15 +500,24 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
             }
             // _status as first key
             const output = { _status: status, _dataKey: newDataKey, ...qr };
+            if (backupDataKey) {
+                output._backupDataKey = backupDataKey;
+                output._backupHint = "Pre-write snapshot stored. Use query_api with this dataKey to retrieve original data if needed.";
+            }
             return {
                 content: [
                     { type: "text", text: JSON.stringify(output, null, 2) },
                 ],
             };
         }
+        const output = { _status: status, _dataKey: newDataKey, data: budgetResult };
+        if (backupDataKey) {
+            output._backupDataKey = backupDataKey;
+            output._backupHint = "Pre-write snapshot stored. Use query_api with this dataKey to retrieve original data if needed.";
+        }
         return {
             content: [
-                { type: "text", text: JSON.stringify({ _status: status, _dataKey: newDataKey, data: budgetResult }, null, 2) },
+                { type: "text", text: JSON.stringify(output, null, 2) },
             ],
         };
     }

package/build/pre-write-backup.js

@@ -0,0 +1,20 @@
+import { callApi } from "./api-client.js";
+import { storeResponse } from "./data-cache.js";
+/**
+ * Create a pre-write backup by fetching the current state of a resource via GET.
+ * Returns a dataKey for the cached snapshot, or undefined on failure.
+ * Failure is non-fatal — errors are logged to stderr.
+ */
+export async function createBackup(config, method, path, params, headers) {
+    if (method !== "PATCH" && method !== "PUT")
+        return undefined;
+    try {
+        const { data, responseHeaders } = await callApi(config, "GET", path, params, undefined, headers);
+        return storeResponse("GET", path, data, responseHeaders);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`pre-write-backup: GET ${path} failed: ${msg}\n`);
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyapi-mcp-server",
-  "version": "1.7.0",
+  "version": "1.8.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",