anyapi-mcp-server 1.8.1 → 2.0.1

package/build/tools/inspect-api.js

@@ -0,0 +1,213 @@
+import { z } from "zod";
+import { formatToolError, attachRateLimit } from "./shared.js";
+import { callApi } from "../api-client.js";
+import { getOrBuildSchema, schemaToSDL, collectJsonFields, computeFieldCosts, collectArrayLengths, } from "../graphql-schema.js";
+import { generateSuggestions } from "../query-suggestions.js";
+import { isNonJsonResult } from "../response-parser.js";
+import { detectPagination, PAGINATION_PARAM_NAMES } from "../pagination.js";
+import { storeResponse } from "../data-cache.js";
+export function registerInspectApi({ server, config, apiIndex }) {
+    server.tool("inspect_api", `Understand a ${config.name} API endpoint before using it. ` +
+        "For GET endpoints: makes a real request and returns the inferred GraphQL schema (SDL), " +
+        "suggested queries, per-field token costs, and a dataKey for cached re-queries. " +
+        "For write endpoints (POST/PUT/PATCH/DELETE): returns spec documentation only — " +
+        "parameters, request body schema, response codes — WITHOUT making any HTTP request. " +
+        "Always safe to call. Use list_api first to discover endpoints.", {
+        method: z
+            .enum(["GET", "POST", "PUT", "DELETE", "PATCH"])
+            .describe("HTTP method"),
+        path: z
+            .string()
+            .describe("API path template (e.g. '/api/card/{id}'). Use list_api to discover paths."),
+        params: z
+            .record(z.unknown())
+            .optional()
+            .describe("Path and query parameters (GET only). " +
+            "Path params like {id} are interpolated; remaining become query string."),
+        headers: z
+            .record(z.string())
+            .optional()
+            .describe("Additional HTTP headers (GET only). " +
+            "Overrides default --header values."),
+    }, async ({ method, path, params, headers }) => {
+        try {
+            // Non-GET: return spec documentation only (no HTTP request)
+            if (method !== "GET") {
+                return handleSpecDocs(apiIndex, method, path);
+            }
+            // GET: make request and infer schema
+            const { data, responseHeaders: respHeaders } = await callApi(config, method, path, params, undefined, headers);
+            const dataKey = storeResponse(method, path, data, respHeaders);
+            // Non-JSON response — skip GraphQL layer
+            if (isNonJsonResult(data)) {
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({
+                                rawResponse: data,
+                                responseHeaders: respHeaders,
+                                dataKey,
+                                hint: "This endpoint returned a non-JSON response. The raw parsed content is shown above. " +
+                                    "GraphQL schema inference is not available for non-JSON responses — use the data directly.",
+                            }, null, 2) },
+                    ],
+                };
+            }
+            const endpoint = apiIndex.getEndpoint(method, path);
+            const { schema, shapeHash } = getOrBuildSchema(data, method, path, endpoint?.requestBodySchema);
+            const sdl = schemaToSDL(schema);
+            const result = { graphqlSchema: sdl, shapeHash, responseHeaders: respHeaders };
+            if (dataKey)
+                result.dataKey = dataKey;
+            attachRateLimit(result, respHeaders);
+            if (endpoint && endpoint.parameters.length > 0) {
+                result.parameters = endpoint.parameters.map((p) => ({
+                    name: p.name,
+                    in: p.in,
+                    required: p.required,
+                    ...(p.description ? { description: p.description } : {}),
+                    ...(p.in === "query" && PAGINATION_PARAM_NAMES.has(p.name) ? { pagination: true } : {}),
+                }));
+                const paginationParams = endpoint.parameters
+                    .filter((p) => p.in === "query" && PAGINATION_PARAM_NAMES.has(p.name))
+                    .map((p) => p.name);
+                if (paginationParams.length > 0) {
+                    result.paginationParams = paginationParams;
+                }
+            }
+            const suggestions = generateSuggestions(schema);
+            if (suggestions.length > 0) {
+                result.suggestedQueries = suggestions;
+            }
+            const fieldCosts = computeFieldCosts(data);
+            result.fieldTokenCosts = fieldCosts;
+            const arrayLengths = collectArrayLengths(data);
+            if (Object.keys(arrayLengths).length > 0) {
+                result.fieldArrayLengths = arrayLengths;
+            }
+            const allFieldsCost = fieldCosts._total;
+            if (Array.isArray(data) && data.length > 0 && fieldCosts._perItem) {
+                const perItem = fieldCosts._perItem;
+                result.budgetExamples = [
+                    `All fields: ~${perItem} tokens/item, ~${allFieldsCost} tokens total`,
+                ];
+            }
+            else if (typeof data === "object" && data !== null) {
+                result.budgetExamples = [
+                    `All fields: ~${allFieldsCost} tokens total`,
+                ];
+            }
+            const jsonFields = collectJsonFields(schema);
+            if (jsonFields.length > 0) {
+                result.jsonFields = jsonFields;
+                result.jsonFieldsHint =
+                    "These fields contain heterogeneous or deeply nested data that cannot be queried " +
+                        "with GraphQL field selection. Query them as-is and parse the returned JSON directly.";
+            }
+            const pagination = detectPagination(data, endpoint?.parameters);
+            if (pagination) {
+                result._pagination = pagination;
+            }
+            const paginationParamsList = result.paginationParams ?? [];
+            const paginationSuffix = paginationParamsList.length > 0
+                ? ` This API supports pagination via: ${paginationParamsList.join(", ")}. Pass these inside params.`
+                : "";
+            if (Array.isArray(data)) {
+                result.totalItems = data.length;
+                result.hint =
+                    "Use query_api with field names from the schema above. " +
+                        "For raw arrays: '{ items { ... } _count }'. " +
+                        "For paginated APIs, pass limit/offset inside params (as query string parameters to the API), " +
+                        "NOT as top-level tool parameters. " +
+                        "Use fieldTokenCosts to understand per-field token costs and select fields wisely. " +
+                        "Responses over ~10k tokens require maxTokens (to truncate) or unlimited: true (for full data)." +
+                        paginationSuffix;
+            }
+            else {
+                result.hint =
+                    "Use query_api with the exact root field names from the schema above (e.g. if schema shows " +
+                        "'products: [Product]', query as '{ products { id name } }' — do NOT use '{ items { ... } }'). " +
+                        "For paginated APIs, pass limit/offset inside params (as query string parameters to the API), " +
+                        "NOT as top-level tool parameters. " +
+                        "Use fieldTokenCosts to understand per-field token costs and select fields wisely. " +
+                        "Responses over ~10k tokens require maxTokens (to truncate) or unlimited: true (for full data)." +
+                        paginationSuffix;
+            }
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return formatToolError(error, apiIndex, method, path);
+        }
+    });
+}
+/**
+ * Return spec documentation for non-GET endpoints (no HTTP request).
+ */
+function handleSpecDocs(apiIndex, method, path) {
+    const endpoint = apiIndex.getEndpoint(method, path);
+    if (!endpoint) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: `Endpoint not found: ${method} ${path}`,
+                        hint: "Use list_api to discover available endpoints.",
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    const result = {
+        method: endpoint.method,
+        path: endpoint.path,
+        summary: endpoint.summary,
+    };
+    if (endpoint.description) {
+        result.description = endpoint.description;
+    }
+    if (endpoint.operationId) {
+        result.operationId = endpoint.operationId;
+    }
+    if (endpoint.deprecated) {
+        result.deprecated = true;
+    }
+    result.tag = endpoint.tag;
+    if (endpoint.parameters.length > 0) {
+        result.parameters = endpoint.parameters.map((p) => ({
+            name: p.name,
+            in: p.in,
+            required: p.required,
+            ...(p.description ? { description: p.description } : {}),
+        }));
+    }
+    if (endpoint.hasRequestBody) {
+        const bodyInfo = {};
+        if (endpoint.requestBodyDescription) {
+            bodyInfo.description = endpoint.requestBodyDescription;
+        }
+        if (endpoint.requestBodySchema) {
+            bodyInfo.contentType = endpoint.requestBodySchema.contentType;
+            bodyInfo.properties = endpoint.requestBodySchema.properties;
+        }
+        result.requestBody = bodyInfo;
+    }
+    if (endpoint.responses && endpoint.responses.length > 0) {
+        result.responses = endpoint.responses;
+    }
+    if (endpoint.externalDocs) {
+        result.externalDocs = endpoint.externalDocs;
+    }
+    result.hint = "Use mutate_api to execute this endpoint. " +
+        "Provide the request body via 'body' (inline), 'bodyFile' (file path), " +
+        "or 'patch' (JSON Patch operations for targeted changes to existing resources).";
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+}

package/build/tools/list-api.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { getOrBuildSchema, truncateIfArray, executeQuery, } from "../graphql-schema.js";
+export function registerListApi({ server, config, apiIndex }) {
+    server.tool("list_api", `List available ${config.name} API endpoints. ` +
+        "Call with no arguments to see all endpoints. " +
+        "Provide 'category' to filter by tag. " +
+        "Provide 'search' to search across paths and summaries (supports regex). " +
+        "Results are paginated with limit (default 20) and offset.", {
+        category: z
+            .string()
+            .optional()
+            .describe("Tag/category to filter by. Case-insensitive."),
+        search: z
+            .string()
+            .optional()
+            .describe("Search keyword or regex pattern across endpoint paths and summaries"),
+        query: z
+            .string()
+            .optional()
+            .describe("GraphQL selection query. Default: '{ items { method path summary } _count }'. " +
+            "Available fields: method, path, summary, tag, parameters { name in required description }"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("Max items to return (default: 20)"),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Items to skip (default: 0)"),
+    }, async ({ category, search, query, limit, offset }) => {
+        try {
+            let data;
+            if (search) {
+                data = apiIndex.searchAll(search);
+            }
+            else if (category) {
+                data = apiIndex.listAllByCategory(category);
+            }
+            else {
+                data = apiIndex.listAll();
+            }
+            if (data.length === 0) {
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({ items: [], _count: 0 }, null, 2) },
+                    ],
+                };
+            }
+            const defaultQuery = "{ items { method path summary } _count }";
+            const effectiveQuery = query ?? defaultQuery;
+            const { schema } = getOrBuildSchema(data, "LIST", category ?? search ?? "_all");
+            const { data: sliced, truncated, total } = truncateIfArray(data, limit ?? 20, offset);
+            const queryResult = await executeQuery(schema, sliced, effectiveQuery);
+            if (truncated && typeof queryResult === "object" && queryResult !== null) {
+                queryResult._meta = {
+                    total,
+                    offset: offset ?? 0,
+                    limit: limit ?? 20,
+                    hasMore: true,
+                };
+            }
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(queryResult, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ error: message }) },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/mutate-api.js

@@ -0,0 +1,222 @@
+import { z } from "zod";
+import { formatToolError, attachRateLimit, shrinkageError, placeholderError, } from "./shared.js";
+import { callApi } from "../api-client.js";
+import { getOrBuildSchema, schemaToSDL, executeQuery, computeShapeHash, } from "../graphql-schema.js";
+import { generateSuggestions } from "../query-suggestions.js";
+import { isNonJsonResult } from "../response-parser.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";
+import { extractPathParamNames } from "../pre-write-backup.js";
+import { detectArrayShrinkage } from "../write-safety.js";
+import { applyPatch } from "../json-patch.js";
+export function registerMutateApi({ server, config, apiIndex }) {
+    server.tool("mutate_api", `Write data to a ${config.name} API endpoint (POST/PUT/PATCH/DELETE). ` +
+        "Two modes:\n" +
+        "1. Direct: provide 'body' or 'bodyFile' with the full request payload.\n" +
+        "2. Patch: provide 'patch' with JSON Patch operations (add/remove/replace). " +
+        "The tool automatically fetches the current resource state, applies your patches, " +
+        "and sends the complete result — you never need to hold the full data.\n" +
+        "Use inspect_api first to understand the endpoint's parameters and body schema. " +
+        "Optionally pass 'query' to select specific fields from the response via GraphQL.", {
+        method: z
+            .enum(["POST", "PUT", "DELETE", "PATCH"])
+            .describe("HTTP method"),
+        path: z
+            .string()
+            .describe("API path template (e.g. '/api/card/{id}')"),
+        params: z
+            .record(z.unknown())
+            .optional()
+            .describe("Path and query parameters. Path params like {id} are interpolated; " +
+            "remaining become query string."),
+        body: z
+            .record(z.unknown())
+            .optional()
+            .describe("Request body (direct mode). Mutually exclusive with 'patch' and 'bodyFile'."),
+        bodyFile: z
+            .string()
+            .optional()
+            .describe("Absolute path to a JSON file for the request body (direct mode). " +
+            "Mutually exclusive with 'body' and 'patch'."),
+        patch: z
+            .array(z.object({
+            op: z.enum(["add", "remove", "replace"]),
+            path: z.string().describe("JSON Pointer path (e.g. '/title', '/panels/3/title', '/tags/-' for append)"),
+            value: z.unknown().optional().describe("Value for add/replace operations"),
+        }))
+            .optional()
+            .describe("JSON Patch operations (RFC 6902 subset). The tool GETs the current resource, " +
+            "applies these patches, and sends the result. " +
+            "Mutually exclusive with 'body' and 'bodyFile'."),
+        headers: z
+            .record(z.string())
+            .optional()
+            .describe("Additional HTTP headers. Overrides default --header values."),
+        query: z
+            .string()
+            .optional()
+            .describe("Optional GraphQL selection query on the response " +
+            "(e.g. '{ id name status }' to select specific fields)."),
+        skipBackup: z
+            .boolean()
+            .optional()
+            .describe("Skip the automatic pre-write backup for PUT/PATCH (direct mode only). " +
+            "Default: false."),
+    }, async ({ method, path, params, body, bodyFile, patch, headers, query, skipBackup }) => {
+        try {
+            // Validate mutual exclusivity
+            const modeCount = [body, bodyFile, patch].filter((x) => x !== undefined).length;
+            if (modeCount > 1) {
+                return formatToolError(new Error("Only one of 'body', 'bodyFile', or 'patch' can be provided."), apiIndex);
+            }
+            // --- Patch mode ---
+            if (patch !== undefined) {
+                return await handlePatchMode({ config, apiIndex }, method, path, params, patch, headers, query);
+            }
+            // --- Direct mode ---
+            let resolvedBody;
+            try {
+                resolvedBody = resolveBody(body, bodyFile);
+            }
+            catch (err) {
+                return formatToolError(err, apiIndex);
+            }
+            // Placeholder detection (except DELETE)
+            if (resolvedBody && method !== "DELETE") {
+                const endpoint = apiIndex.getEndpoint(method, path);
+                const warnings = detectPlaceholders(resolvedBody, endpoint?.requestBodySchema);
+                if (warnings.length > 0)
+                    return placeholderError(warnings);
+            }
+            // Pre-write backup for PUT/PATCH
+            let backupDataKey;
+            if ((method === "PATCH" || method === "PUT") && !skipBackup) {
+                backupDataKey = await createBackup(config, method, path, params, headers);
+            }
+            // Array shrinkage detection against backup
+            if (backupDataKey && resolvedBody) {
+                const backupEntry = loadResponse(backupDataKey);
+                if (backupEntry) {
+                    const shrinkWarnings = detectArrayShrinkage(resolvedBody, backupEntry.data);
+                    if (shrinkWarnings.length > 0)
+                        return shrinkageError(shrinkWarnings, { backupDataKey });
+                }
+            }
+            // Execute the request
+            const { data: rawData, responseHeaders: respHeaders } = await callApi(config, method, path, params, resolvedBody, headers);
+            return await buildMutateResponse({ apiIndex }, method, path, rawData, respHeaders, resolvedBody, query, backupDataKey);
+        }
+        catch (error) {
+            return formatToolError(error, apiIndex, method, path);
+        }
+    });
+}
+/**
+ * Patch mode: GET current state, apply patches, send the result.
+ */
+async function handlePatchMode({ config, apiIndex }, method, path, params, operations, headers, query) {
+    if (operations.length === 0) {
+        return formatToolError(new Error("Patch operations array is empty."), apiIndex);
+    }
+    if (method === "DELETE") {
+        return formatToolError(new Error("Patch mode is not supported for DELETE — use direct mode (no body) instead."), apiIndex);
+    }
+    // Fetch current state (path params only, same as createBackup)
+    const pathParamNames = extractPathParamNames(path);
+    const pathOnlyParams = params
+        ? Object.fromEntries(Object.entries(params).filter(([k]) => pathParamNames.has(k)))
+        : undefined;
+    let currentData;
+    let currentHeaders;
+    try {
+        const result = await callApi(config, "GET", path, pathOnlyParams && Object.keys(pathOnlyParams).length > 0 ? pathOnlyParams : undefined, undefined, headers);
+        currentData = result.data;
+        currentHeaders = result.responseHeaders;
+    }
+    catch (err) {
+        return formatToolError(new Error(`Patch mode: failed to GET current state of ${path}: ` +
+            (err instanceof Error ? err.message : String(err))), apiIndex);
+    }
+    // Validate current data is a plain object
+    if (typeof currentData !== "object" || currentData === null || Array.isArray(currentData)) {
+        return formatToolError(new Error(`Patch mode requires the GET response to be a JSON object, ` +
+            `but got ${Array.isArray(currentData) ? "array" : typeof currentData}. ` +
+            `Use direct mode (body/bodyFile) instead.`), apiIndex);
+    }
+    // Store pre-patch state as backup
+    const backupDataKey = storeResponse("GET", path, currentData, currentHeaders);
+    // Apply patches
+    let patchedBody;
+    try {
+        patchedBody = applyPatch(currentData, operations);
+    }
+    catch (err) {
+        return formatToolError(new Error(`Patch failed: ${err instanceof Error ? err.message : String(err)}`), apiIndex);
+    }
+    // Placeholder detection on patched result
+    const endpoint = apiIndex.getEndpoint(method, path);
+    const warnings = detectPlaceholders(patchedBody, endpoint?.requestBodySchema);
+    if (warnings.length > 0)
+        return placeholderError(warnings);
+    // Execute the write with the complete patched body
+    const { data: rawData, responseHeaders: respHeaders } = await callApi(config, method, path, params, patchedBody, headers);
+    return await buildMutateResponse({ apiIndex }, method, path, rawData, respHeaders, patchedBody, query, backupDataKey, operations.length);
+}
+/**
+ * Build the response for mutate_api (shared between direct and patch modes).
+ */
+async function buildMutateResponse({ apiIndex }, method, path, rawData, respHeaders, resolvedBody, query, backupDataKey, patchCount) {
+    const newDataKey = storeResponse(method, path, rawData, respHeaders);
+    // Non-JSON response
+    if (isNonJsonResult(rawData)) {
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({
+                        rawResponse: rawData,
+                        responseHeaders: respHeaders,
+                        ...(newDataKey ? { _dataKey: newDataKey } : {}),
+                        hint: "This endpoint returned a non-JSON response. The raw content is shown above.",
+                    }, null, 2) },
+            ],
+        };
+    }
+    const endpoint = apiIndex.getEndpoint(method, path);
+    const bodyHash = resolvedBody ? computeShapeHash(resolvedBody) : undefined;
+    const { schema, fromCache } = getOrBuildSchema(rawData, method, path, endpoint?.requestBodySchema, bodyHash);
+    // If query provided, apply GraphQL field selection
+    let resultData = rawData;
+    if (query) {
+        resultData = await executeQuery(schema, rawData, query);
+    }
+    const output = { _status: "COMPLETE" };
+    if (query && typeof resultData === "object" && resultData !== null && !Array.isArray(resultData)) {
+        Object.assign(output, resultData);
+    }
+    else {
+        output.data = resultData;
+    }
+    attachRateLimit(output, respHeaders);
+    if (!fromCache) {
+        output._schema = schemaToSDL(schema);
+        const suggestions = generateSuggestions(schema);
+        if (suggestions.length > 0) {
+            output._suggestedQueries = suggestions;
+        }
+    }
+    if (newDataKey)
+        output._dataKey = newDataKey;
+    if (backupDataKey) {
+        output._backupDataKey = backupDataKey;
+        output._backupHint = "Pre-write snapshot stored. Use query_api with this dataKey to retrieve original data if needed.";
+    }
+    if (patchCount !== undefined) {
+        output._patchApplied = `${patchCount} operation(s) applied successfully`;
+    }
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(output, null, 2) },
+        ],
+    };
+}