anyapi-mcp-server 1.6.1 → 1.7.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.
 
 ### `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,15 @@ 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"`).
+
 ### `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 +141,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 +154,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 +179,14 @@ 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`
 - **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/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;
+    }
+}