anyapi-mcp-server 1.6.1 → 1.8.0

package/README.md

@@ -94,7 +94,7 @@ See the [Google Workspace guide](docs/google-workspace.md) for a complete OAuth
 
 ## Tools
 
-The server exposes five tools (plus `auth` when OAuth is configured):
+The server exposes four tools (plus `auth` when OAuth is configured):
 
 ### `list_api` — Browse endpoints
 
@@ -102,11 +102,11 @@ 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`.
+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
 
-Fetches data and returns **only the fields you select** via a GraphQL query. Supports both reads and writes (mutations for POST/PUT/DELETE/PATCH).
+Fetches data and returns **only the fields you select** via a GraphQL query. Supports both reads and writes (mutations for POST/PUT/DELETE/PATCH). Pass a `dataKey` from `call_api` to reuse cached data with zero HTTP calls.
 
 ```graphql
 # Read
@@ -116,14 +116,17 @@ Fetches data and returns **only the fields you select** via a GraphQL query. Sup
 mutation { post_endpoint(input: { name: "example" }) { id } }
 ```
 
+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
 
 Returns spec documentation for an endpoint (parameters, request body schema, response codes) **without making an HTTP request**.
 
-### `batch_query` — Parallel requests
-
-Fetches data from up to 10 endpoints concurrently in a single tool call. Each request follows the `query_api` flow.
-
 ### `auth` — OAuth authentication
 
 Only available when `--oauth-*` flags are configured. Manages the OAuth flow:
@@ -140,11 +143,11 @@ list_api          → discover what's available
      ↓
 explain_api       → read the docs for an endpoint
      ↓
-call_api          → inspect the response schema
+call_api          → inspect the response schema (returns dataKey)
      ↓
-query_api         → fetch exactly the fields you need
+query_api         → fetch exactly the fields you need (pass dataKey for zero HTTP calls)
      ↓
-batch_query       → fetch from multiple endpoints at once
+query_api         → re-query with different fields using the same dataKey
 ```
 
 ## How it works
@@ -153,21 +156,20 @@ batch_query       → fetch from multiple endpoints at once
 OpenAPI/Postman spec
         │
         ▼
-   ┌─────────┐  ┌─────────────┐  ┌──────────┐  ┌───────────┐  ┌─────────────┐
-   │list_api │  │ explain_api │  │ call_api │  │ query_api │  │ batch_query │
-   │(browse) │  │   (docs)    │  │ (schema) │  │  (data)   │  │ (parallel)  │
-   └─────────┘  └─────────────┘  └──────────┘  └───────────┘  └─────────────┘
-        │          │ no HTTP          │               │             │
-        ▼          ▼ request          ▼               ▼             ▼
-   Spec index   Spec index     REST API call    REST API call  N concurrent
-   (tags,       (params,       (with retry      (cached if     REST API calls
-    paths)       responses,     + caching)       same as        + GraphQL
-                 body schema)       │            call_api)      execution
-                                    ▼               │
-                               Infer GraphQL        ▼
-                               schema from     Execute GraphQL
-                               JSON response   query against
-                                               response data
+   ┌─────────┐  ┌─────────────┐  ┌──────────┐  ┌───────────┐
+   │list_api │  │ explain_api │  │ call_api │  │ query_api │
+   │(browse) │  │   (docs)    │  │ (schema) │  │  (data)   │
+   └─────────┘  └─────────────┘  └──────────┘  └───────────┘
+        │          │ no HTTP          │               │
+        ▼          ▼ request          ▼               ▼
+   Spec index   Spec index     REST API call    dataKey cache
+   (tags,       (params,       (with retry)     hit → no HTTP
+    paths)       responses,         │            miss → fetch
+                 body schema)       ▼               │
+                               Infer schema +       ▼
+                               return dataKey   Execute GraphQL
+                                                + token budget
+                                                  truncation
 ```
 
 ## Features
@@ -179,10 +181,16 @@ OpenAPI/Postman spec
 - **Multi-sample merging** — samples up to 10 array elements for richer schemas
 - **Mutation support** — write operations get typed GraphQL mutations from OpenAPI body schemas
 - **Smart suggestions** — `call_api` returns ready-to-use queries based on the inferred schema
-- **Response caching** — 30s TTL prevents duplicate calls across `call_api` → `query_api`
+- **Response caching** — filesystem-based cache with 5-min TTL; `dataKey` tokens let `query_api` reuse data with zero HTTP calls
+- **Token budget** — `query_api` accepts `maxTokens` (default 4000) and truncates array results to fit via binary search
+- **Per-field token costs** — `call_api` returns a `fieldTokenCosts` tree so the LLM can make informed field selections
+- **Rate limit tracking** — parses `X-RateLimit-*` headers and warns when limits are nearly exhausted
+- **Pagination detection** — auto-detects cursor, next-page-token, and link-based pagination patterns in responses
+- **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
-- **Pagination** — API-level via `params`, client-side slicing via `limit`/`offset`
+- **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/api-client.js

@@ -1,9 +1,45 @@
 import { withRetry, RetryableError, isRetryableStatus } from "./retry.js";
-import { buildCacheKey, consumeCached, setCache } from "./response-cache.js";
 import { logEntry, isLoggingEnabled } from "./logger.js";
 import { parseResponse } from "./response-parser.js";
 import { ApiError } from "./error-context.js";
 import { getValidAccessToken, refreshTokens } from "./oauth.js";
+import { waitIfNeeded, trackRateLimit } from "./rate-limit-tracker.js";
+function tryParseInt(val) {
+    if (!val)
+        return null;
+    const n = parseInt(val, 10);
+    return isNaN(n) ? null : n;
+}
+export function parseRateLimits(headers) {
+    const lower = {};
+    for (const [k, v] of Object.entries(headers)) {
+        lower[k.toLowerCase()] = v;
+    }
+    const remaining = tryParseInt(lower["x-ratelimit-remaining"]) ??
+        tryParseInt(lower["ratelimit-remaining"]) ??
+        tryParseInt(lower["x-rate-limit-remaining"]);
+    const limit = tryParseInt(lower["x-ratelimit-limit"]) ??
+        tryParseInt(lower["ratelimit-limit"]) ??
+        tryParseInt(lower["x-rate-limit-limit"]);
+    const resetRaw = lower["x-ratelimit-reset"] ??
+        lower["ratelimit-reset"] ??
+        lower["x-rate-limit-reset"];
+    if (remaining === null && limit === null && !resetRaw)
+        return null;
+    let resetAt = null;
+    if (resetRaw) {
+        const asNumber = parseInt(resetRaw, 10);
+        if (!isNaN(asNumber)) {
+            resetAt = asNumber > 1_000_000_000
+                ? new Date(asNumber * 1000).toISOString()
+                : `${asNumber}s`;
+        }
+        else {
+            resetAt = resetRaw;
+        }
+    }
+    return { remaining, limit, resetAt };
+}
 const TIMEOUT_MS = 30_000;
 function interpolatePath(pathTemplate, params) {
     const remaining = { ...params };
@@ -17,22 +53,7 @@ function interpolatePath(pathTemplate, params) {
     });
     return { url, remainingParams: remaining };
 }
-/**
- * @param cacheMode
- *   - "populate" — skip cache read, always fetch, store result (used by call_api)
- *   - "consume"  — read-and-evict cache, fetch on miss, do NOT re-store (used by query_api)
- *   - "none"     — no caching at all (default)
- */
-export async function callApi(config, method, pathTemplate, params, body, extraHeaders, cacheMode = "none") {
-    // --- Cache check (consume mode only) ---
-    const cacheKey = cacheMode !== "none"
-        ? buildCacheKey(method, pathTemplate, params, body, extraHeaders)
-        : "";
-    if (cacheMode === "consume") {
-        const cached = consumeCached(cacheKey);
-        if (cached !== undefined)
-            return cached;
-    }
+export async function callApi(config, method, pathTemplate, params, body, extraHeaders) {
     // --- URL construction ---
     const { url: interpolatedPath, remainingParams } = interpolatePath(pathTemplate, params ?? {});
     let fullUrl = `${config.baseUrl}${interpolatedPath}`;
@@ -97,6 +118,8 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
                         durationMs,
                     });
                 }
+                // Track rate limit headers from every response
+                trackRateLimit(parseRateLimits(responseHeaders));
                 if (!response.ok) {
                     if (isRetryableStatus(response.status)) {
                         const msg = `API error ${response.status} ${response.statusText}: ${bodyText}`;
@@ -125,6 +148,8 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
             }
         });
     };
+    // --- Rate limit pre-check ---
+    await waitIfNeeded();
     // --- Execute with 401 refresh-and-retry ---
     let result;
     try {
@@ -148,9 +173,5 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
             throw error;
         }
     }
-    // --- Cache store (populate mode only) ---
-    if (cacheMode === "populate") {
-        setCache(cacheKey, result);
-    }
     return result;
 }

package/build/api-index.js

@@ -1,6 +1,82 @@
 import yaml from "js-yaml";
 const PAGE_SIZE = 20;
 const HTTP_METHODS = new Set(["get", "post", "put", "delete", "patch"]);
+const MAX_BODY_SCHEMA_DEPTH = 6;
+function extractProperties(schema, spec, depth, visited) {
+    const properties = schema.properties;
+    if (!properties)
+        return undefined;
+    const requiredFields = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const result = {};
+    for (const [propName, propDef] of Object.entries(properties)) {
+        let def = propDef;
+        let refPath;
+        // Resolve property-level $ref
+        if (def["$ref"] && typeof def["$ref"] === "string") {
+            refPath = def["$ref"];
+            if (visited.has(refPath)) {
+                result[propName] = { type: "object", required: requiredFields.has(propName) };
+                continue;
+            }
+            const resolved = resolveRef(refPath, spec);
+            if (resolved)
+                def = resolved;
+        }
+        const prop = {
+            type: def.type ?? "string",
+            required: requiredFields.has(propName),
+        };
+        if (def.description)
+            prop.description = def.description;
+        // Recurse into nested objects
+        if (prop.type === "object" && def.properties && depth < MAX_BODY_SCHEMA_DEPTH) {
+            const branch = new Set(visited);
+            if (refPath)
+                branch.add(refPath);
+            const nested = extractProperties(def, spec, depth + 1, branch);
+            if (nested) {
+                prop.properties = nested;
+                if (Array.isArray(def.required) && def.required.length > 0) {
+                    prop.required_fields = def.required;
+                }
+            }
+        }
+        if (def.items && typeof def.items === "object") {
+            let itemsDef = def.items;
+            let itemsRefPath;
+            if (itemsDef["$ref"] && typeof itemsDef["$ref"] === "string") {
+                itemsRefPath = itemsDef["$ref"];
+                if (!visited.has(itemsRefPath)) {
+                    const resolved = resolveRef(itemsRefPath, spec);
+                    if (resolved)
+                        itemsDef = resolved;
+                }
+            }
+            const itemType = itemsDef.type ?? "string";
+            if (itemType === "object" && itemsDef.properties && depth < MAX_BODY_SCHEMA_DEPTH) {
+                const branch = new Set(visited);
+                if (itemsRefPath)
+                    branch.add(itemsRefPath);
+                const nestedItems = extractProperties(itemsDef, spec, depth + 1, branch);
+                if (nestedItems) {
+                    prop.items = {
+                        type: itemType,
+                        properties: nestedItems,
+                        required: Array.isArray(itemsDef.required) ? itemsDef.required : undefined,
+                    };
+                }
+                else {
+                    prop.items = { type: itemType };
+                }
+            }
+            else {
+                prop.items = { type: itemType };
+            }
+        }
+        result[propName] = prop;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 function extractRequestBodySchema(requestBody, spec) {
     if (!requestBody || typeof requestBody !== "object")
         return undefined;
@@ -26,34 +102,10 @@ function extractRequestBodySchema(requestBody, spec) {
             return undefined;
         schema = resolved;
     }
-    const properties = schema.properties;
-    if (!properties)
+    const result = extractProperties(schema, spec, 0, new Set());
+    if (!result)
         return undefined;
-    const requiredFields = new Set(Array.isArray(schema.required) ? schema.required : []);
-    const result = {};
-    for (const [propName, propDef] of Object.entries(properties)) {
-        let def = propDef;
-        // Resolve property-level $ref
-        if (def["$ref"] && typeof def["$ref"] === "string") {
-            const resolved = resolveRef(def["$ref"], spec);
-            if (resolved)
-                def = resolved;
-        }
-        const prop = {
-            type: def.type ?? "string",
-            required: requiredFields.has(propName),
-        };
-        if (def.description)
-            prop.description = def.description;
-        if (def.items && typeof def.items === "object") {
-            const items = def.items;
-            prop.items = { type: items.type ?? "string" };
-        }
-        result[propName] = prop;
-    }
-    return Object.keys(result).length > 0
-        ? { contentType: "application/json", properties: result }
-        : undefined;
+    return { contentType: "application/json", properties: result };
 }
 function resolveRef(ref, spec) {
     // Handle "#/components/schemas/Foo" style refs

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/data-cache.js

@@ -0,0 +1,96 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { platform, env } from "node:process";
+const TTL_MS = 5 * 60 * 1000; // 5 minutes
+function defaultResponseDir() {
+    if (platform === "win32") {
+        const base = env.LOCALAPPDATA ?? join(env.USERPROFILE ?? "", "AppData", "Local");
+        return join(base, "anyapi-mcp", "responses");
+    }
+    return join(env.HOME ?? "/tmp", ".cache", "anyapi-mcp", "responses");
+}
+let responseDir = defaultResponseDir();
+export function _setResponseDirForTests(dir) {
+    responseDir = dir;
+}
+export function _clearAllForTests() {
+    try {
+        for (const file of readdirSync(responseDir)) {
+            if (file.endsWith(".json")) {
+                try {
+                    unlinkSync(join(responseDir, file));
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    catch { /* dir may not exist */ }
+}
+function ensureDir() {
+    mkdirSync(responseDir, { recursive: true });
+}
+export function cleanupExpired() {
+    try {
+        const now = Date.now();
+        for (const file of readdirSync(responseDir)) {
+            if (!file.endsWith(".json"))
+                continue;
+            try {
+                const content = readFileSync(join(responseDir, file), "utf-8");
+                const entry = JSON.parse(content);
+                if (entry.expiresAt < now) {
+                    unlinkSync(join(responseDir, file));
+                }
+            }
+            catch {
+                /* ignore individual file errors */
+            }
+        }
+    }
+    catch {
+        /* dir may not exist yet */
+    }
+}
+export function storeResponse(method, path, data, responseHeaders) {
+    const dataKey = randomBytes(4).toString("hex");
+    const entry = {
+        method,
+        path,
+        data,
+        responseHeaders,
+        expiresAt: Date.now() + TTL_MS,
+    };
+    try {
+        ensureDir();
+        writeFileSync(join(responseDir, `${dataKey}.json`), JSON.stringify(entry));
+        cleanupExpired();
+    }
+    catch (err) {
+        process.stderr.write(`data-cache: failed to store ${dataKey}: ${err}\n`);
+    }
+    return dataKey;
+}
+export function loadResponse(dataKey) {
+    try {
+        const filePath = join(responseDir, `${dataKey}.json`);
+        const content = readFileSync(filePath, "utf-8");
+        const entry = JSON.parse(content);
+        if (entry.expiresAt < Date.now()) {
+            try {
+                unlinkSync(filePath);
+            }
+            catch { /* ignore */ }
+            return null;
+        }
+        return {
+            method: entry.method,
+            path: entry.path,
+            data: entry.data,
+            responseHeaders: entry.responseHeaders,
+        };
+    }
+    catch {
+        return null;
+    }
+}