anyapi-mcp-server 1.6.1 → 1.8.0

package/build/pagination.js

@@ -0,0 +1,123 @@
+/**
+ * Dot-path patterns to search for pagination info in response data.
+ * Each entry: [dotPath, target field in PaginationHint, label for hint text, candidate query param names].
+ */
+const CURSOR_PATTERNS = [
+    [["meta", "page", "after"], "cursor", "meta.page.after", ["page[cursor]", "page[after]", "cursor", "after"]],
+    [["meta", "page", "cursor"], "cursor", "meta.page.cursor", ["page[cursor]", "cursor"]],
+    [["paging", "cursors", "after"], "cursor", "paging.cursors.after", ["after", "cursor"]],
+    [["pagination", "next_cursor"], "cursor", "pagination.next_cursor", ["cursor", "next_cursor"]],
+    [["next_cursor"], "cursor", "next_cursor", ["cursor", "next_cursor"]],
+    [["cursor"], "cursor", "cursor", ["cursor"]],
+    [["nextPageToken"], "nextPageToken", "nextPageToken", ["pageToken", "page_token"]],
+    [["next_page_token"], "nextPageToken", "next_page_token", ["page_token", "pageToken"]],
+    [["links", "next"], "nextUrl", "links.next", []],
+    [["_links", "next", "href"], "nextUrl", "_links.next.href", []],
+    [["has_more"], "hasMore", "has_more", []],
+    [["hasMore"], "hasMore", "hasMore", []],
+];
+function walkPath(data, path) {
+    let current = data;
+    for (const key of path) {
+        if (typeof current !== "object" || current === null || Array.isArray(current))
+            return undefined;
+        current = current[key];
+        if (current === undefined)
+            return undefined;
+    }
+    return current;
+}
+/**
+ * Known pagination-related query parameter names (used to flag params in call_api).
+ */
+export const PAGINATION_PARAM_NAMES = new Set([
+    "page", "cursor", "after", "before", "limit", "offset", "per_page",
+    "page_size", "pageSize", "page_token", "pageToken", "next_page_token",
+    "page[cursor]", "page[after]", "page[before]", "page[size]", "page[number]",
+    "page[offset]", "page[limit]", "starting_after", "ending_before",
+    "start_cursor", "next_cursor",
+]);
+/**
+ * Pick the best query parameter name from candidates by cross-referencing
+ * against the endpoint's actual spec parameters. Falls back to the first candidate.
+ */
+export function resolveParamName(candidates, specParams) {
+    if (candidates.length === 0)
+        return null;
+    if (specParams && specParams.length > 0) {
+        const queryParams = new Set(specParams.filter((p) => p.in === "query").map((p) => p.name));
+        for (const c of candidates) {
+            if (queryParams.has(c))
+                return c;
+        }
+    }
+    return candidates[0];
+}
+/**
+ * Parse query parameters from a next-page URL.
+ */
+function parseNextUrlParams(nextUrl) {
+    try {
+        const url = new URL(nextUrl);
+        const params = {};
+        url.searchParams.forEach((value, key) => {
+            params[key] = value;
+        });
+        return params;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Scan raw response data for common pagination patterns.
+ * Returns a PaginationHint with matched values and usage guidance, or null if not paginated.
+ * When specParams are provided, resolves cursor param names against the endpoint's actual parameters.
+ */
+export function detectPagination(data, specParams) {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return null;
+    const found = { _hint: "" };
+    const hints = [];
+    const nextParams = {};
+    for (const [path, field, label, candidates] of CURSOR_PATTERNS) {
+        if (found[field] !== undefined)
+            continue; // first match wins per field
+        const value = walkPath(data, path);
+        if (value === undefined || value === null)
+            continue;
+        if (field === "hasMore") {
+            if (typeof value === "boolean") {
+                found.hasMore = value;
+                hints.push(`'${label}' = ${value}`);
+            }
+        }
+        else if (typeof value === "string" && value.length > 0) {
+            found[field] = value;
+            if (field === "cursor" || field === "nextPageToken") {
+                const paramName = resolveParamName(candidates, specParams);
+                if (paramName) {
+                    nextParams[paramName] = value;
+                }
+                hints.push(`Use '${label}' value as cursor parameter for the next page`);
+            }
+            else if (field === "nextUrl") {
+                const urlParams = parseNextUrlParams(value);
+                Object.assign(nextParams, urlParams);
+                hints.push(`'${label}' contains the full URL for the next page`);
+            }
+        }
+    }
+    if (hints.length === 0)
+        return null;
+    if (Object.keys(nextParams).length > 0) {
+        found.nextParams = nextParams;
+        found._hint =
+            `Pagination detected. To fetch the next page, call query_api with the same method, path, and query, ` +
+                `but set params to include: ${JSON.stringify(nextParams)}`;
+    }
+    else {
+        found._hint = `Pagination detected: ${hints.join("; ")}.`;
+    }
+    return found;
+}

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/build/query-suggestions.js

@@ -6,11 +6,19 @@ function unwrapType(type) {
         return type.ofType;
     return type;
 }
+function isJsonScalar(type) {
+    const unwrapped = unwrapType(type);
+    return isScalarType(unwrapped) && unwrapped.name === "JSON";
+}
+function getJsonFieldNames(type) {
+    const fields = type.getFields();
+    return Object.keys(fields).filter((name) => isJsonScalar(fields[name].type));
+}
 function getScalarFieldNames(type) {
     const fields = type.getFields();
     return Object.keys(fields).filter((name) => {
         const fieldType = unwrapType(fields[name].type);
-        return isScalarType(fieldType);
+        return isScalarType(fieldType) && fieldType.name !== "JSON";
     });
 }
 function buildDepthLimitedQuery(type, maxDepth, depth = 0) {
@@ -37,13 +45,19 @@ function buildDepthLimitedQuery(type, maxDepth, depth = 0) {
         else if (isListType(fieldType)) {
             const elementType = unwrapType(fieldType.ofType);
             if (isScalarType(elementType)) {
-                parts.push(name);
+                // JSON scalar lists: include without limit args
+                if (elementType.name === "JSON") {
+                    parts.push(name);
+                }
+                else {
+                    parts.push(`${name}(limit: 10)`);
+                }
                 count++;
             }
             else if (isObjectType(elementType) && depth < maxDepth) {
                 const nested = buildDepthLimitedQuery(elementType, maxDepth, depth + 1);
                 if (nested) {
-                    parts.push(`${name} ${nested}`);
+                    parts.push(`${name}(limit: 10) ${nested}`);
                     count++;
                 }
             }
@@ -58,10 +72,10 @@ export function generateSuggestions(schema) {
         return suggestions;
     const fields = queryType.getFields();
     const fieldNames = Object.keys(fields);
-    // Suggestion 1: All scalar fields at root
+    // Suggestion 1: All scalar fields at root (excluding JSON scalars)
     const scalarFields = fieldNames.filter((name) => {
         const type = unwrapType(fields[name].type);
-        return isScalarType(type);
+        return isScalarType(type) && type.name !== "JSON";
     });
     if (scalarFields.length > 0) {
         const selected = scalarFields.slice(0, MAX_FIELDS_PER_LEVEL);
@@ -71,6 +85,17 @@ export function generateSuggestions(schema) {
             description: `Returns ${selected.join(", ")}`,
         });
     }
+    // Suggestion: Dynamic JSON fields
+    const jsonFields = getJsonFieldNames(queryType);
+    if (jsonFields.length > 0) {
+        const selected = jsonFields.slice(0, MAX_FIELDS_PER_LEVEL);
+        suggestions.push({
+            name: "Dynamic JSON fields",
+            query: `{ ${selected.join(" ")} }`,
+            description: `${selected.join(", ")} contain dynamic JSON — returned as-is. ` +
+                "Use jsonFilter param to extract nested values.",
+        });
+    }
     // Suggestion 2: For each list field, suggest with basic subfields
     for (const [name, field] of Object.entries(fields)) {
         const type = unwrapType(field.type);
@@ -81,8 +106,8 @@ export function generateSuggestions(schema) {
                 if (subfields.length > 0) {
                     suggestions.push({
                         name: `List ${name} with basic fields`,
-                        query: `{ ${name} { ${subfields.join(" ")} } }`,
-                        description: `Fetches ${subfields.join(", ")} for each item in ${name}`,
+                        query: `{ ${name}(limit: 10) { ${subfields.join(" ")} } }`,
+                        description: `Fetches ${subfields.join(", ")} for each item in ${name} (paginated — use limit/offset args)`,
                     });
                 }
             }
@@ -98,8 +123,8 @@ export function generateSuggestions(schema) {
                 if (subfields.length > 0) {
                     suggestions.push({
                         name: "Items with count",
-                        query: `{ items { ${subfields.join(" ")} } _count }`,
-                        description: `Array response: fetches ${subfields.join(", ")} with total count`,
+                        query: `{ items(limit: 10) { ${subfields.join(" ")} } _count }`,
+                        description: `Array response: fetches ${subfields.join(", ")} with total count (paginated — use limit/offset args)`,
                     });
                 }
             }

package/build/rate-limit-tracker.js

@@ -0,0 +1,59 @@
+const MAX_WAIT_MS = 30_000;
+let lastInfo = null;
+/**
+ * Store the latest rate limit info from response headers.
+ */
+export function trackRateLimit(info) {
+    if (info)
+        lastInfo = info;
+}
+/**
+ * Parse a reset time value into an epoch millisecond timestamp.
+ * Supports ISO 8601 strings and "Ns" (seconds-from-now) format.
+ */
+function parseResetEpoch(resetAt) {
+    // "Ns" format (e.g. "30s")
+    const secMatch = resetAt.match(/^(\d+)s$/);
+    if (secMatch) {
+        return Date.now() + parseInt(secMatch[1], 10) * 1000;
+    }
+    // ISO 8601 timestamp
+    const ts = Date.parse(resetAt);
+    if (!isNaN(ts))
+        return ts;
+    return null;
+}
+/**
+ * If rate limit is nearly exhausted (remaining <= 1), delay until the reset time.
+ * Capped at MAX_WAIT_MS to avoid indefinite blocking.
+ * Clears tracked state after waiting.
+ */
+export async function waitIfNeeded() {
+    if (!lastInfo)
+        return;
+    if (lastInfo.remaining === null || lastInfo.remaining > 1)
+        return;
+    if (!lastInfo.resetAt) {
+        lastInfo = null;
+        return;
+    }
+    const resetEpoch = parseResetEpoch(lastInfo.resetAt);
+    if (!resetEpoch) {
+        lastInfo = null;
+        return;
+    }
+    const delayMs = resetEpoch - Date.now();
+    if (delayMs <= 0) {
+        lastInfo = null;
+        return;
+    }
+    const waitMs = Math.min(delayMs, MAX_WAIT_MS);
+    lastInfo = null;
+    await new Promise((resolve) => setTimeout(resolve, waitMs));
+}
+/**
+ * Reset tracker state (for testing).
+ */
+export function resetTracker() {
+    lastInfo = null;
+}

package/build/token-budget.js

@@ -0,0 +1,135 @@
+/**
+ * Token budget system for controlling response size.
+ * Truncates array results to fit within a token budget,
+ * leveraging GraphQL field selection for size control.
+ */
+const DEFAULT_BUDGET = 4000;
+/**
+ * Find the primary array in a query result.
+ * Checks `items` first (raw array responses), then falls back to
+ * the first non-`_`-prefixed array field.
+ */
+export function findPrimaryArray(obj) {
+    if (typeof obj !== "object" || obj === null || Array.isArray(obj))
+        return null;
+    const rec = obj;
+    // Check `items` first (raw array responses wrapped by GraphQL schema)
+    if (Array.isArray(rec.items))
+        return rec.items;
+    // Fall back to first non-_-prefixed array field
+    for (const [key, value] of Object.entries(rec)) {
+        if (!key.startsWith("_") && Array.isArray(value)) {
+            return value;
+        }
+    }
+    return null;
+}
+/**
+ * Returns the length of the primary array, or null if no array found.
+ */
+export function findPrimaryArrayLength(obj) {
+    const arr = findPrimaryArray(obj);
+    return arr ? arr.length : null;
+}
+/**
+ * Estimate token count from a JSON value.
+ * Uses JSON.stringify length / 4 as approximation (1 token ~ 4 chars).
+ */
+function estimateTokens(value) {
+    try {
+        return Math.max(1, Math.ceil(JSON.stringify(value).length / 4));
+    }
+    catch {
+        return 1;
+    }
+}
+/**
+ * Truncate the primary array in an object to fit within a token budget.
+ * Uses binary search to find the max number of items that fit.
+ * Returns the truncated object and the original/truncated counts.
+ */
+export function truncateToTokenBudget(obj, budget) {
+    const arr = findPrimaryArray(obj);
+    if (!arr || arr.length === 0) {
+        return { result: obj, originalCount: 0, keptCount: 0 };
+    }
+    const originalCount = arr.length;
+    // Compute overhead tokens (non-array fields)
+    const overhead = {};
+    const arrayKey = findPrimaryArrayKey(obj);
+    if (!arrayKey)
+        return { result: obj, originalCount, keptCount: originalCount };
+    for (const [key, value] of Object.entries(obj)) {
+        if (key !== arrayKey) {
+            overhead[key] = value;
+        }
+    }
+    const overheadTokens = estimateTokens(overhead);
+    const arrayBudget = Math.max(1, budget - overheadTokens);
+    // Check if full array fits
+    const fullTokens = estimateTokens(arr);
+    if (fullTokens <= arrayBudget) {
+        return { result: obj, originalCount, keptCount: originalCount };
+    }
+    // Binary search for max items that fit
+    let lo = 1;
+    let hi = originalCount;
+    let bestCount = 1; // Always keep at least 1
+    while (lo <= hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        const sliceTokens = estimateTokens(arr.slice(0, mid));
+        if (sliceTokens <= arrayBudget) {
+            bestCount = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    const truncated = { ...obj, [arrayKey]: arr.slice(0, bestCount) };
+    return { result: truncated, originalCount, keptCount: bestCount };
+}
+/**
+ * Find the key name of the primary array in an object.
+ */
+function findPrimaryArrayKey(obj) {
+    if (typeof obj !== "object" || obj === null || Array.isArray(obj))
+        return null;
+    const rec = obj;
+    if (Array.isArray(rec.items))
+        return "items";
+    for (const [key, value] of Object.entries(rec)) {
+        if (!key.startsWith("_") && Array.isArray(value)) {
+            return key;
+        }
+    }
+    return null;
+}
+/**
+ * Build a status message for the response.
+ * If estimated tokens exceed the budget, truncates and returns TRUNCATED status.
+ * Otherwise returns COMPLETE status.
+ */
+export function buildStatusMessage(queryResult, budget = DEFAULT_BUDGET) {
+    if (typeof queryResult !== "object" || queryResult === null || Array.isArray(queryResult)) {
+        return { status: "COMPLETE", result: queryResult };
+    }
+    const qr = queryResult;
+    const totalTokens = estimateTokens(qr);
+    if (totalTokens <= budget) {
+        const arrayLen = findPrimaryArrayLength(qr);
+        const status = arrayLen !== null ? `COMPLETE (${arrayLen} items)` : "COMPLETE";
+        return { status, result: qr };
+    }
+    // Need truncation
+    const { result, originalCount, keptCount } = truncateToTokenBudget(qr, budget);
+    if (originalCount === 0) {
+        // No array found but response is over budget
+        return {
+            status: `COMPLETE (response exceeds token budget ${budget} — select fewer fields)`,
+            result: qr,
+        };
+    }
+    const status = `TRUNCATED — ${keptCount} of ${originalCount} items (token budget ${budget}). Select fewer fields to fit more items.`;
+    return { status, result };
+}

package/package.json

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