anyapi-mcp-server 1.8.1 → 2.0.0

package/build/json-patch.js

@@ -0,0 +1,137 @@
+/**
+ * RFC 6902 JSON Patch subset: add, remove, replace operations.
+ * Used by mutate_api to apply targeted changes to large resources
+ * without requiring the LLM to hold the full state in context.
+ */
+/**
+ * Parse a JSON Pointer (RFC 6901) into path segments.
+ * Unescapes ~1 → / and ~0 → ~ per spec.
+ */
+function parsePointer(path) {
+    if (path === "")
+        return [];
+    if (!path.startsWith("/")) {
+        throw new Error(`Invalid JSON Pointer: must start with '/' (got '${path}')`);
+    }
+    return path
+        .slice(1)
+        .split("/")
+        .map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+/**
+ * Walk to the parent of the target path segment.
+ * Returns [parent, lastSegment] for the operation to act on.
+ */
+function walkToParent(root, segments) {
+    let current = root;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const seg = segments[i];
+        if (Array.isArray(current)) {
+            const idx = parseInt(seg, 10);
+            if (isNaN(idx) || idx < 0 || idx >= current.length) {
+                throw new Error(`Array index out of bounds: '${seg}' at /${segments.slice(0, i + 1).join("/")}`);
+            }
+            current = current[idx];
+        }
+        else if (typeof current === "object" && current !== null) {
+            const rec = current;
+            if (!(seg in rec)) {
+                throw new Error(`Path not found: '${seg}' at /${segments.slice(0, i + 1).join("/")}`);
+            }
+            current = rec[seg];
+        }
+        else {
+            throw new Error(`Cannot traverse into ${typeof current} at /${segments.slice(0, i + 1).join("/")}`);
+        }
+    }
+    if (!Array.isArray(current) && (typeof current !== "object" || current === null)) {
+        throw new Error(`Cannot apply operation: parent at /${segments.slice(0, -1).join("/")} is ${typeof current}`);
+    }
+    return [current, segments[segments.length - 1]];
+}
+function applyAdd(root, segments, value) {
+    const [parent, key] = walkToParent(root, segments);
+    if (Array.isArray(parent)) {
+        if (key === "-") {
+            parent.push(value);
+        }
+        else {
+            const idx = parseInt(key, 10);
+            if (isNaN(idx) || idx < 0 || idx > parent.length) {
+                throw new Error(`Array index out of bounds for add: '${key}'`);
+            }
+            parent.splice(idx, 0, value);
+        }
+    }
+    else {
+        parent[key] = value;
+    }
+}
+function applyRemove(root, segments) {
+    const [parent, key] = walkToParent(root, segments);
+    if (Array.isArray(parent)) {
+        const idx = parseInt(key, 10);
+        if (isNaN(idx) || idx < 0 || idx >= parent.length) {
+            throw new Error(`Array index out of bounds for remove: '${key}'`);
+        }
+        parent.splice(idx, 1);
+    }
+    else {
+        const rec = parent;
+        if (!(key in rec)) {
+            throw new Error(`Cannot remove non-existent key: '${key}'`);
+        }
+        delete rec[key];
+    }
+}
+function applyReplace(root, segments, value) {
+    const [parent, key] = walkToParent(root, segments);
+    if (Array.isArray(parent)) {
+        const idx = parseInt(key, 10);
+        if (isNaN(idx) || idx < 0 || idx >= parent.length) {
+            throw new Error(`Array index out of bounds for replace: '${key}'`);
+        }
+        parent[idx] = value;
+    }
+    else {
+        const rec = parent;
+        if (!(key in rec)) {
+            throw new Error(`Cannot replace non-existent key: '${key}'`);
+        }
+        rec[key] = value;
+    }
+}
+/**
+ * Apply a sequence of JSON Patch operations to a deep-cloned copy of the target.
+ * Returns the patched object. Does not mutate the original.
+ */
+export function applyPatch(target, operations) {
+    const cloned = JSON.parse(JSON.stringify(target));
+    for (let i = 0; i < operations.length; i++) {
+        const op = operations[i];
+        const segments = parsePointer(op.path);
+        if (segments.length === 0) {
+            throw new Error(`Operation ${i} (${op.op}): cannot target root`);
+        }
+        switch (op.op) {
+            case "add":
+                if (op.value === undefined) {
+                    throw new Error(`Operation ${i} (add): 'value' is required`);
+                }
+                applyAdd(cloned, segments, op.value);
+                break;
+            case "remove":
+                applyRemove(cloned, segments);
+                break;
+            case "replace":
+                if (op.value === undefined) {
+                    throw new Error(`Operation ${i} (replace): 'value' is required`);
+                }
+                applyReplace(cloned, segments, op.value);
+                break;
+            default:
+                throw new Error(`Operation ${i}: unsupported op '${op.op}'`);
+        }
+    }
+    return cloned;
+}

package/build/oauth.js

@@ -70,9 +70,6 @@ export function storeTokens(tokens) {
 export function getTokens() {
     return currentTokens;
 }
-export function clearTokens() {
-    currentTokens = null;
-}
 export function isTokenExpired() {
     if (!currentTokens)
         return true;

package/build/pagination.js

@@ -28,7 +28,7 @@ function walkPath(data, path) {
     return current;
 }
 /**
- * Known pagination-related query parameter names (used to flag params in call_api).
+ * Known pagination-related query parameter names (used to flag params in inspect_api).
  */
 export const PAGINATION_PARAM_NAMES = new Set([
     "page", "cursor", "after", "before", "limit", "offset", "per_page",

package/build/pre-write-backup.js

@@ -1,7 +1,20 @@
 import { callApi } from "./api-client.js";
 import { storeResponse } from "./data-cache.js";
+/**
+ * Extract parameter names from a path template (e.g., "/items/{id}" → Set(["id"])).
+ */
+export function extractPathParamNames(pathTemplate) {
+    const names = new Set();
+    pathTemplate.replace(/\{([^}]+)\}/g, (_, name) => {
+        names.add(name);
+        return "";
+    });
+    return names;
+}
 /**
  * Create a pre-write backup by fetching the current state of a resource via GET.
+ * Only forwards path parameters — query params are stripped to avoid fetching
+ * a filtered/paginated subset of the resource.
  * Returns a dataKey for the cached snapshot, or undefined on failure.
  * Failure is non-fatal — errors are logged to stderr.
  */
@@ -9,7 +22,12 @@ 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);
+        // Only forward path parameters to avoid fetching a filtered/paginated response
+        const pathParamNames = extractPathParamNames(path);
+        const pathOnlyParams = params
+            ? Object.fromEntries(Object.entries(params).filter(([k]) => pathParamNames.has(k)))
+            : undefined;
+        const { data, responseHeaders } = await callApi(config, "GET", path, pathOnlyParams && Object.keys(pathOnlyParams).length > 0 ? pathOnlyParams : undefined, undefined, headers);
         return storeResponse("GET", path, data, responseHeaders);
     }
     catch (err) {

package/build/token-budget.js

@@ -3,13 +3,12 @@
  * 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) {
+function findPrimaryArray(obj) {
     if (typeof obj !== "object" || obj === null || Array.isArray(obj))
         return null;
     const rec = obj;
@@ -44,40 +43,78 @@ function estimateTokens(value) {
     }
 }
 /**
- * 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.
+ * Public re-export of estimateTokens for use in index.ts.
  */
-export function truncateToTokenBudget(obj, budget) {
-    const arr = findPrimaryArray(obj);
-    if (!arr || arr.length === 0) {
+export function estimateResultTokens(value) {
+    return estimateTokens(value);
+}
+/**
+ * BFS walk of the result tree to find the deepest, largest array by token cost.
+ * Skips `_`-prefixed keys. Returns null if no arrays found.
+ */
+export function findDeepestLargestArray(obj) {
+    if (typeof obj !== "object" || obj === null || Array.isArray(obj))
+        return null;
+    let best = null;
+    // BFS queue: each entry is [currentObject, pathSoFar]
+    const queue = [
+        [obj, []],
+    ];
+    while (queue.length > 0) {
+        const [current, currentPath] = queue.shift();
+        for (const [key, value] of Object.entries(current)) {
+            if (key.startsWith("_"))
+                continue;
+            if (Array.isArray(value)) {
+                const cost = estimateTokens(value);
+                if (!best ||
+                    currentPath.length + 1 > best.path.length ||
+                    (currentPath.length + 1 === best.path.length && cost > best.tokenCost)) {
+                    best = { path: [...currentPath, key], array: value, tokenCost: cost };
+                }
+            }
+            else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+                queue.push([value, [...currentPath, key]]);
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Truncate the deepest largest array in an object to fit within a token budget.
+ * Clones the spine of the path to avoid mutating the original.
+ * Returns the truncated object and original/kept counts.
+ */
+export function truncateDeepArray(obj, budget) {
+    if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
         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)
+    const target = findDeepestLargestArray(obj);
+    if (!target || target.array.length === 0) {
+        return { result: obj, originalCount: 0, keptCount: 0 };
+    }
+    const originalCount = target.array.length;
+    // Check if everything fits as-is
+    const totalTokens = estimateTokens(obj);
+    if (totalTokens <= budget) {
         return { result: obj, originalCount, keptCount: originalCount };
-    for (const [key, value] of Object.entries(obj)) {
-        if (key !== arrayKey) {
-            overhead[key] = value;
-        }
     }
-    const overheadTokens = estimateTokens(overhead);
+    // Compute overhead: tokens of everything except the target array
+    // Build a copy with the target array emptied to measure overhead
+    const emptyClone = cloneSpine(obj, target.path, []);
+    const overheadTokens = estimateTokens(emptyClone);
     const arrayBudget = Math.max(1, budget - overheadTokens);
-    // Check if full array fits
-    const fullTokens = estimateTokens(arr);
-    if (fullTokens <= arrayBudget) {
+    // Check if full array fits within array budget
+    if (target.tokenCost <= 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
+    let bestCount = 1;
     while (lo <= hi) {
         const mid = Math.floor((lo + hi) / 2);
-        const sliceTokens = estimateTokens(arr.slice(0, mid));
+        const sliceTokens = estimateTokens(target.array.slice(0, mid));
         if (sliceTokens <= arrayBudget) {
             bestCount = mid;
             lo = mid + 1;
@@ -86,50 +123,56 @@ export function truncateToTokenBudget(obj, budget) {
             hi = mid - 1;
         }
     }
-    const truncated = { ...obj, [arrayKey]: arr.slice(0, bestCount) };
-    return { result: truncated, originalCount, keptCount: bestCount };
+    const truncatedResult = cloneSpine(obj, target.path, target.array.slice(0, bestCount));
+    return { result: truncatedResult, originalCount, keptCount: bestCount };
 }
 /**
- * Find the key name of the primary array in an object.
+ * Clone the spine of an object along a path, replacing the leaf with a new value.
  */
-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;
-        }
+function cloneSpine(obj, path, leafValue) {
+    if (path.length === 0)
+        return obj;
+    if (path.length === 1) {
+        return { ...obj, [path[0]]: leafValue };
     }
-    return null;
+    const [head, ...rest] = path;
+    return {
+        ...obj,
+        [head]: cloneSpine(obj[head], rest, leafValue),
+    };
 }
 /**
  * Build a status message for the response.
- * If estimated tokens exceed the budget, truncates and returns TRUNCATED status.
- * Otherwise returns COMPLETE status.
+ * When maxTokens is provided, uses truncateDeepArray for deep truncation.
+ * When maxTokens is omitted, returns COMPLETE with no truncation.
  */
-export function buildStatusMessage(queryResult, budget = DEFAULT_BUDGET) {
+export function buildStatusMessage(queryResult, maxTokens) {
     if (typeof queryResult !== "object" || queryResult === null || Array.isArray(queryResult)) {
         return { status: "COMPLETE", result: queryResult };
     }
     const qr = queryResult;
+    // No budget specified — return complete, no truncation
+    if (maxTokens === undefined) {
+        const arrayLen = findPrimaryArrayLength(qr);
+        const status = arrayLen !== null ? `COMPLETE (${arrayLen} items)` : "COMPLETE";
+        return { status, result: qr };
+    }
+    // Budget specified — check if truncation needed
     const totalTokens = estimateTokens(qr);
-    if (totalTokens <= budget) {
+    if (totalTokens <= maxTokens) {
         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);
+    // Need truncation — use deep array truncation
+    const { result, originalCount, keptCount } = truncateDeepArray(qr, maxTokens);
     if (originalCount === 0) {
         // No array found but response is over budget
         return {
-            status: `COMPLETE (response exceeds token budget ${budget} — select fewer fields)`,
+            status: `COMPLETE (response exceeds token budget ${maxTokens} — select fewer fields)`,
             result: qr,
         };
     }
-    const status = `TRUNCATED — ${keptCount} of ${originalCount} items (token budget ${budget}). Select fewer fields to fit more items.`;
+    const status = `TRUNCATED — ${keptCount} of ${originalCount} items (token budget ${maxTokens}). Select fewer fields to fit more items. Other array fields may also be truncated by default limits — check *_count fields for actual totals.`;
     return { status, result };
 }

package/build/tools/auth.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { startAuth, exchangeCode, awaitCallback, storeTokens, getTokens, isTokenExpired, } from "../oauth.js";
+export function registerAuth({ server, config }) {
+    if (!config.oauth)
+        return;
+    server.tool("auth", `Manage OAuth 2.0 authentication for ${config.name}. ` +
+        "Use action 'start' to begin the OAuth flow (returns an authorization URL for " +
+        "authorization_code flow, or completes token exchange for client_credentials). " +
+        "Use action 'exchange' to complete the flow — the callback is captured automatically " +
+        "via a localhost server, or you can provide a 'code' manually. " +
+        "Use action 'status' to check the current token status.", {
+        action: z
+            .enum(["start", "exchange", "status"])
+            .describe("'start' begins auth flow, 'exchange' completes code exchange, 'status' shows token info"),
+        code: z
+            .string()
+            .optional()
+            .describe("Authorization code from the OAuth provider (optional for 'exchange' — " +
+            "if omitted, waits for the localhost callback automatically)"),
+    }, async ({ action, code }) => {
+        try {
+            if (action === "start") {
+                const result = await startAuth(config.oauth);
+                if ("url" in result) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    message: "Open this URL to authorize. A local callback server is listening. " +
+                                        "After you approve, call auth with action 'exchange' to complete authentication.",
+                                    authorizationUrl: result.url,
+                                    flow: config.oauth.flow,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                // client_credentials: tokens obtained directly
+                storeTokens(result.tokens);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                message: "Authentication successful (client_credentials flow).",
+                                tokenType: result.tokens.tokenType,
+                                expiresIn: Math.round((result.tokens.expiresAt - Date.now()) / 1000),
+                                scope: result.tokens.scope ?? null,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            if (action === "exchange") {
+                const tokens = code
+                    ? await exchangeCode(config.oauth, code)
+                    : await awaitCallback(config.oauth);
+                storeTokens(tokens);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                message: "Authentication successful.",
+                                tokenType: tokens.tokenType,
+                                expiresIn: Math.round((tokens.expiresAt - Date.now()) / 1000),
+                                hasRefreshToken: !!tokens.refreshToken,
+                                scope: tokens.scope ?? null,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // action === "status"
+            const tokens = getTokens();
+            if (!tokens) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                authenticated: false,
+                                message: "No tokens stored. Use auth with action 'start' to authenticate.",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const expired = isTokenExpired();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            authenticated: true,
+                            tokenType: tokens.tokenType,
+                            expired,
+                            expiresIn: Math.round((tokens.expiresAt - Date.now()) / 1000),
+                            hasRefreshToken: !!tokens.refreshToken,
+                            scope: tokens.scope ?? null,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ error: message }) },
+                ],
+                isError: true,
+            };
+        }
+    });
+}