anyapi-mcp-server 1.8.1 → 2.0.0

package/build/tools/call-api.js

@@ -0,0 +1,204 @@
+import { z } from "zod";
+import { WRITE_METHODS, formatToolError, attachRateLimit, shrinkageError, placeholderError, } from "./shared.js";
+import { callApi } from "../api-client.js";
+import { getOrBuildSchema, schemaToSDL, computeShapeHash, 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, 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 { detectArrayShrinkage } from "../write-safety.js";
+export function registerCallApi({ server, config, apiIndex }) {
+    server.tool("call_api", `Inspect a ${config.name} API endpoint. Makes a real request and returns ONLY the ` +
+        "inferred GraphQL schema (SDL) showing all available fields and their types. " +
+        "No response data is returned — use query_api to fetch actual data. " +
+        "IMPORTANT: Read the returned schema carefully. The root field names in the schema " +
+        "are what you must use in query_api — do NOT assume generic names like 'items'. " +
+        "For example, if the schema shows 'products: [Product]', query as '{ products { id name } }', not '{ items { id name } }'. " +
+        "Also returns accepted parameters (name, location, required) from the API spec, " +
+        "and suggestedQueries with ready-to-use GraphQL queries. " +
+        "Returns a dataKey — pass it to query_api to reuse the cached response (zero HTTP calls). " +
+        "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 as key-value pairs. " +
+            "Path params like {id} are interpolated; remaining become query string for GET."),
+        body: z
+            .record(z.unknown())
+            .optional()
+            .describe("Request body for POST/PUT/PATCH"),
+        bodyFile: z
+            .string()
+            .optional()
+            .describe("Absolute path to a JSON file to use as request body. " +
+            "Mutually exclusive with 'body'. Use for large payloads that cannot be inlined."),
+        headers: z
+            .record(z.string())
+            .optional()
+            .describe("Additional HTTP headers for this request (e.g. { \"Authorization\": \"Bearer <token>\" }). " +
+            "Overrides default --header values."),
+        skipBackup: z
+            .boolean()
+            .optional()
+            .describe("Skip the automatic pre-write backup for PUT/PATCH requests. " +
+            "Default: false (backup is created automatically)."),
+    }, async ({ method, path, params, body, bodyFile, headers, skipBackup }) => {
+        try {
+            // Resolve body from inline or file
+            let resolvedBody;
+            try {
+                resolvedBody = resolveBody(body, bodyFile);
+            }
+            catch (err) {
+                return formatToolError(err, apiIndex);
+            }
+            // Placeholder detection for write methods (except DELETE)
+            if (resolvedBody && WRITE_METHODS.has(method) && 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: compare body 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 });
+                }
+            }
+            const { data, responseHeaders: respHeaders } = await callApi(config, method, path, params, resolvedBody, headers);
+            const dataKey = storeResponse(method, path, data, respHeaders);
+            // Non-JSON response — skip GraphQL layer, return raw parsed data
+            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 bodyHash = WRITE_METHODS.has(method) && resolvedBody ? computeShapeHash(resolvedBody) : undefined;
+            const { schema, shapeHash } = getOrBuildSchema(data, method, path, endpoint?.requestBodySchema, bodyHash);
+            const sdl = schemaToSDL(schema);
+            const result = { graphqlSchema: sdl, shapeHash, responseHeaders: respHeaders };
+            if (dataKey)
+                result.dataKey = dataKey;
+            if (bodyHash)
+                result.bodyHash = bodyHash;
+            if (backupDataKey) {
+                result.backupDataKey = backupDataKey;
+                result.backupHint = "Pre-write snapshot stored. Use query_api with this dataKey to retrieve original data if needed.";
+            }
+            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;
+                }
+            }
+            // Smart query suggestions
+            const suggestions = generateSuggestions(schema);
+            if (suggestions.length > 0) {
+                result.suggestedQueries = suggestions;
+            }
+            // Per-field token costs
+            const fieldCosts = computeFieldCosts(data);
+            result.fieldTokenCosts = fieldCosts;
+            // Actual array lengths for truncation awareness
+            const arrayLengths = collectArrayLengths(data);
+            if (Object.keys(arrayLengths).length > 0) {
+                result.fieldArrayLengths = arrayLengths;
+            }
+            // Budget examples
+            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`,
+                ];
+            }
+            // Flag JSON scalar fields so the AI knows which fields are opaque
+            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.";
+            }
+            // Pagination detection from response data
+            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);
+        }
+    });
+}

package/build/tools/explain-api.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+export function registerExplainApi({ server, config, apiIndex }) {
+    server.tool("explain_api", `Get detailed documentation for a ${config.name} API endpoint from the spec. ` +
+        "Returns all available spec information — summary, description, parameters, " +
+        "request body schema, response codes, deprecation status — without making any HTTP request. " +
+        "Use list_api first to discover endpoints, then explain_api to understand them before calling.", {
+        method: z
+            .enum(["GET", "POST", "PUT", "DELETE", "PATCH"])
+            .describe("HTTP method"),
+        path: z
+            .string()
+            .describe("API path template (e.g. '/api/card/{id}')"),
+    }, async ({ method, path }) => {
+        try {
+            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;
+            }
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, 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/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,
+            };
+        }
+    });
+}