anyapi-mcp-server 1.5.0 → 1.6.0

package/README.md

@@ -28,6 +28,7 @@ Works with services like **Datadog**, **PostHog**, **Metabase**, **Cloudflare**,
 - **Concurrent batch queries** — `batch_query` fetches data from up to 10 endpoints in parallel, returning all results in one tool call
 - **Per-request headers** — override default headers on individual `call_api`/`query_api`/`batch_query` calls
 - **Environment variable interpolation** — use `${ENV_VAR}` in base URLs and headers
+- **Rich error context** — API errors return structured messages (parses RFC 7807, `{ error: { message, code } }`, `{ errors: [...] }`, and more), status-specific suggestions (e.g. "Authentication required" for 401), and relevant spec info (required parameters, request body schema) for 400/422 errors so the LLM can self-correct
 - **Request logging** — optional NDJSON request/response log with sensitive header masking
 
 [![npm](https://img.shields.io/npm/v/anyapi-mcp-server)](https://www.npmjs.com/package/anyapi-mcp-server)
@@ -229,7 +230,7 @@ Fetch data from multiple endpoints concurrently in a single tool call.
 - Accepts an array of 1–10 requests, each with `method`, `path`, `params`, `body`, `query`, and optional `headers`
 - All requests execute in parallel via `Promise.allSettled` — one failure does not affect the others
 - Each request follows the `query_api` flow: HTTP fetch → schema inference → GraphQL field selection
-- Returns an array of results: `{ method, path, data, shapeHash }` on success or `{ method, path, error }` on failure
+- Returns an array of results: `{ method, path, data, shapeHash }` on success or a structured error with status, suggestion, and spec context on failure
 - Run `call_api` first on each endpoint to discover the schema field names
 
 ## Workflow
@@ -267,6 +268,7 @@ OpenAPI/Postman spec
 2. `call_api` makes a real HTTP request, infers a GraphQL schema from the JSON response, and caches both the response (30s TTL) and the schema. Schemas are keyed by endpoint + response shape, so the same path returning different structures gets distinct schemas
 3. `query_api` re-uses the cached response if called within 30s, executes your GraphQL field selection against the data, and returns only the fields you asked for. Includes `_shapeHash` in the response for tracking schema identity
 4. Write operations (POST/PUT/DELETE/PATCH) with OpenAPI request body schemas get a Mutation type with typed `GraphQLInputObjectType` inputs
+5. When an API call fails, the error response includes a parsed error message (extracted from common formats like RFC 7807 Problem Details, `{ error: { message } }`, GraphQL-style `{ errors: [...] }`), the HTTP status code, a status-specific suggestion for what to try next, and — for validation errors (400/422) — the full parameter list and request body schema from the spec
 
 ## Supported Spec Formats
 

package/build/api-client.js

@@ -2,6 +2,7 @@ import { withRetry, RetryableError, isRetryableStatus } from "./retry.js";
 import { buildCacheKey, consumeCached, setCache } from "./response-cache.js";
 import { logEntry, isLoggingEnabled } from "./logger.js";
 import { parseResponse } from "./response-parser.js";
+import { ApiError } from "./error-context.js";
 const TIMEOUT_MS = 30_000;
 function interpolatePath(pathTemplate, params) {
     const remaining = { ...params };
@@ -34,7 +35,7 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
     // --- URL construction ---
     const { url: interpolatedPath, remainingParams } = interpolatePath(pathTemplate, params ?? {});
     let fullUrl = `${config.baseUrl}${interpolatedPath}`;
-    if (method === "GET" && Object.keys(remainingParams).length > 0) {
+    if (Object.keys(remainingParams).length > 0) {
         const qs = new URLSearchParams();
         for (const [k, v] of Object.entries(remainingParams)) {
             if (v !== undefined && v !== null) {
@@ -65,12 +66,12 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
             const response = await fetch(fullUrl, fetchOptions);
             const durationMs = Date.now() - startTime;
             const bodyText = await response.text();
+            const responseHeaders = {};
+            response.headers.forEach((v, k) => {
+                responseHeaders[k] = v;
+            });
             // Log request/response
             if (isLoggingEnabled()) {
-                const responseHeaders = {};
-                response.headers.forEach((v, k) => {
-                    responseHeaders[k] = v;
-                });
                 await logEntry({
                     timestamp: new Date().toISOString(),
                     method,
@@ -84,8 +85,8 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
                 });
             }
             if (!response.ok) {
-                const msg = `API error ${response.status} ${response.statusText}: ${bodyText}`;
                 if (isRetryableStatus(response.status)) {
+                    const msg = `API error ${response.status} ${response.statusText}: ${bodyText}`;
                     let retryAfterMs;
                     const retryAfter = response.headers.get("retry-after");
                     if (retryAfter) {
@@ -95,7 +96,7 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
                     }
                     throw new RetryableError(msg, response.status, retryAfterMs);
                 }
-                throw new Error(msg);
+                throw new ApiError(`API error ${response.status} ${response.statusText}`, response.status, response.statusText, bodyText, responseHeaders);
             }
             return parseResponse(response.headers.get("content-type"), bodyText);
         }

package/build/api-index.js

@@ -118,19 +118,21 @@ function postmanUrlToPath(url) {
 export class ApiIndex {
     byTag = new Map();
     allEndpoints = [];
-    constructor(specContent) {
-        let parsed;
-        try {
-            parsed = JSON.parse(specContent);
-        }
-        catch {
-            parsed = yaml.load(specContent);
-        }
-        if (isPostmanCollection(parsed)) {
-            this.parsePostman(parsed);
-        }
-        else {
-            this.parseOpenApi(parsed, parsed);
+    constructor(specContents) {
+        for (const specContent of specContents) {
+            let parsed;
+            try {
+                parsed = JSON.parse(specContent);
+            }
+            catch {
+                parsed = yaml.load(specContent);
+            }
+            if (isPostmanCollection(parsed)) {
+                this.parsePostman(parsed);
+            }
+            else {
+                this.parseOpenApi(parsed, parsed);
+            }
         }
     }
     parseOpenApi(spec, rawSpec) {
@@ -251,6 +253,15 @@ export class ApiIndex {
         }
         tagList.push(endpoint);
     }
+    listAll() {
+        return this.allEndpoints.map((ep) => ({
+            method: ep.method,
+            path: ep.path,
+            summary: ep.summary,
+            tag: ep.tag,
+            parameters: ep.parameters,
+        }));
+    }
     listAllCategories() {
         const categories = [];
         for (const [tag, endpoints] of this.byTag) {
@@ -260,7 +271,9 @@ export class ApiIndex {
         return categories;
     }
     listAllByCategory(category) {
-        const endpoints = this.byTag.get(category) ?? [];
+        const lower = category.toLowerCase();
+        const key = [...this.byTag.keys()].find((k) => k.toLowerCase() === lower);
+        const endpoints = key ? this.byTag.get(key) : [];
         return endpoints.map((ep) => ({
             method: ep.method,
             path: ep.path,
@@ -270,11 +283,18 @@ export class ApiIndex {
         }));
     }
     searchAll(keyword) {
-        const lower = keyword.toLowerCase();
+        let matcher;
+        try {
+            const re = new RegExp(keyword, "i");
+            matcher = (text) => re.test(text);
+        }
+        catch {
+            const lower = keyword.toLowerCase();
+            matcher = (text) => text.toLowerCase().includes(lower);
+        }
         return this.allEndpoints
-            .filter((ep) => ep.path.toLowerCase().includes(lower) ||
-            ep.summary.toLowerCase().includes(lower) ||
-            ep.description.toLowerCase().includes(lower))
+            .filter((ep) => matcher(ep.path) ||
+            matcher(ep.summary))
             .map((ep) => ({
             method: ep.method,
             path: ep.path,

package/build/config.js

@@ -56,7 +56,7 @@ const USAGE = `Usage: anyapi-mcp --name <name> --spec <path-or-url> --base-url <
 
 Required:
   --name       Server name (e.g. "petstore")
-  --spec       Path or URL to OpenAPI spec (JSON or YAML). HTTPS URLs are cached locally.
+  --spec       Path or URL to OpenAPI spec (JSON or YAML) (repeatable for multiple specs)
   --base-url   API base URL (e.g. "https://api.example.com")
 
 Optional:
@@ -65,13 +65,13 @@ Optional:
   --log        Path to request/response log file (NDJSON format)`;
 export async function loadConfig() {
     const name = getArg("--name");
-    const specUrl = getArg("--spec");
+    const specUrls = getAllArgs("--spec");
     const baseUrl = getArg("--base-url");
-    if (!name || !specUrl || !baseUrl) {
+    if (!name || specUrls.length === 0 || !baseUrl) {
         console.error(USAGE);
         process.exit(1);
     }
-    const spec = await loadSpec(interpolateEnv(specUrl));
+    const specs = await Promise.all(specUrls.map((url) => loadSpec(interpolateEnv(url))));
     const headers = {};
     for (const raw of getAllArgs("--header")) {
         const colonIdx = raw.indexOf(":");
@@ -86,7 +86,7 @@ export async function loadConfig() {
     const logPath = getArg("--log");
     return {
         name,
-        spec,
+        specs,
         baseUrl: interpolateEnv(baseUrl).replace(/\/+$/, ""),
         headers: Object.keys(headers).length > 0 ? headers : undefined,
         logPath: logPath ? resolve(logPath) : undefined,

package/build/error-context.js

@@ -0,0 +1,179 @@
+/**
+ * Rich API error carrying status, raw body, and response headers
+ * for structured error reporting.
+ */
+export class ApiError extends Error {
+    status;
+    statusText;
+    bodyText;
+    responseHeaders;
+    constructor(message, status, statusText, bodyText, responseHeaders = {}) {
+        super(message);
+        this.status = status;
+        this.statusText = statusText;
+        this.bodyText = bodyText;
+        this.responseHeaders = responseHeaders;
+        this.name = "ApiError";
+    }
+}
+/**
+ * Extract a human-readable error message from common API error response formats:
+ * - RFC 7807 Problem Details: { type, title, status, detail }
+ * - Stripe/generic: { error: { message, code } }
+ * - Simple: { error: "message" } or { message: "..." }
+ * - GraphQL-style: { errors: [{ message }] }
+ * - SOAP/Apigee: { fault: { faultstring } }
+ */
+export function extractErrorMessage(bodyText) {
+    if (!bodyText.trim())
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const obj = parsed;
+    // RFC 7807 Problem Details
+    if (typeof obj.detail === "string") {
+        const title = typeof obj.title === "string" ? obj.title : undefined;
+        return title ? `${title}: ${obj.detail}` : obj.detail;
+    }
+    // { error: { message, code? } }
+    if (obj.error && typeof obj.error === "object") {
+        const errObj = obj.error;
+        if (typeof errObj.message === "string") {
+            const code = typeof errObj.code === "string" ? ` (${errObj.code})` : "";
+            return `${errObj.message}${code}`;
+        }
+    }
+    // { error: "message" }
+    if (typeof obj.error === "string") {
+        return obj.error;
+    }
+    // { message: "..." }
+    if (typeof obj.message === "string") {
+        return obj.message;
+    }
+    // { errors: [{ message }] }
+    if (Array.isArray(obj.errors)) {
+        const messages = obj.errors
+            .filter((e) => typeof e === "object" &&
+            e !== null &&
+            typeof e.message === "string")
+            .map((e) => e.message);
+        if (messages.length > 0)
+            return messages.join("; ");
+    }
+    // { fault: { faultstring } }
+    if (obj.fault && typeof obj.fault === "object") {
+        const fault = obj.fault;
+        if (typeof fault.faultstring === "string")
+            return fault.faultstring;
+    }
+    return undefined;
+}
+function getSuggestion(status, endpoint) {
+    switch (status) {
+        case 400: {
+            let msg = "Bad request. Check that all required parameters are provided and the request body matches the expected schema.";
+            if (endpoint) {
+                const required = endpoint.parameters.filter((p) => p.required);
+                if (required.length > 0) {
+                    msg += ` Required parameters: ${required.map((p) => `${p.name} (${p.in})`).join(", ")}.`;
+                }
+                if (endpoint.hasRequestBody && endpoint.requestBodySchema) {
+                    const requiredFields = Object.entries(endpoint.requestBodySchema.properties)
+                        .filter(([, p]) => p.required)
+                        .map(([name]) => name);
+                    if (requiredFields.length > 0) {
+                        msg += ` Required body fields: ${requiredFields.join(", ")}.`;
+                    }
+                }
+            }
+            return msg;
+        }
+        case 401:
+            return "Authentication required. Provide credentials via --header (e.g. --header \"Authorization: Bearer <token>\") or per-request headers parameter.";
+        case 403:
+            return "Forbidden. Your credentials don't have permission for this operation. Verify your API key or token has the required scopes.";
+        case 404: {
+            let msg = "Resource not found. Verify the path and parameter values are correct.";
+            if (endpoint) {
+                const pathParams = endpoint.parameters.filter((p) => p.in === "path");
+                if (pathParams.length > 0) {
+                    msg += ` Check path parameters: ${pathParams.map((p) => p.name).join(", ")}.`;
+                }
+            }
+            msg += " Use list_api to confirm available endpoints.";
+            return msg;
+        }
+        case 405:
+            return "Method not allowed for this endpoint. Use list_api to check which HTTP methods are supported.";
+        case 409:
+            return "Conflict. The resource may already exist or be in a state that prevents this operation.";
+        case 415:
+            return "Unsupported media type. The API may expect a different Content-Type header.";
+        case 422: {
+            let msg = "Validation failed. Check that request body fields match the expected types and formats.";
+            if (endpoint?.requestBodySchema) {
+                const props = Object.entries(endpoint.requestBodySchema.properties)
+                    .map(([name, p]) => `${name}: ${p.type}${p.required ? " (required)" : ""}`)
+                    .join(", ");
+                if (props)
+                    msg += ` Expected fields: ${props}.`;
+            }
+            return msg;
+        }
+        case 429:
+            return "Rate limit exceeded (retries exhausted). Wait before trying again or reduce request frequency.";
+        default:
+            if (status >= 500) {
+                return "Server error. This is likely a temporary issue with the API. Try again later.";
+            }
+            return "Check the API documentation for this endpoint using explain_api.";
+    }
+}
+const MAX_RAW_BODY = 500;
+/**
+ * Build a rich error response object from an API error or exhausted retry error.
+ */
+export function buildErrorContext(error, method, path, endpoint) {
+    const isApiError = error instanceof ApiError;
+    const status = isApiError ? error.status : error.status;
+    const statusText = isApiError ? error.statusText : "";
+    const bodyText = isApiError ? error.bodyText : "";
+    const extracted = bodyText ? extractErrorMessage(bodyText) : undefined;
+    const result = {
+        error: extracted ?? error.message,
+        status,
+        ...(statusText ? { statusText } : {}),
+        endpoint: `${method} ${path}`,
+        suggestion: getSuggestion(status, endpoint),
+    };
+    // Include raw body snippet when structured extraction failed
+    if (!extracted && bodyText.length > 0) {
+        result.rawBody =
+            bodyText.length > MAX_RAW_BODY
+                ? bodyText.slice(0, MAX_RAW_BODY) + "..."
+                : bodyText;
+    }
+    // Include spec info for validation-related errors
+    if ((status === 400 || status === 422) && endpoint) {
+        if (endpoint.parameters.length > 0) {
+            result.specParameters = endpoint.parameters.map((p) => ({
+                name: p.name,
+                in: p.in,
+                required: p.required,
+                ...(p.description ? { description: p.description } : {}),
+            }));
+        }
+        if (endpoint.hasRequestBody && endpoint.requestBodySchema) {
+            result.specRequestBody = endpoint.requestBodySchema;
+        }
+    }
+    return result;
+}

package/build/index.js

@@ -8,36 +8,50 @@ import { callApi } from "./api-client.js";
 import { initLogger } from "./logger.js";
 import { generateSuggestions } from "./query-suggestions.js";
 import { getOrBuildSchema, executeQuery, schemaToSDL, truncateIfArray, computeShapeHash, } from "./graphql-schema.js";
+import { ApiError, buildErrorContext } from "./error-context.js";
+import { RetryableError } from "./retry.js";
 const WRITE_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
 const config = await loadConfig();
 initLogger(config.logPath ?? null);
-const apiIndex = new ApiIndex(config.spec);
+const apiIndex = new ApiIndex(config.specs);
+function formatToolError(error, method, path) {
+    if ((error instanceof ApiError || error instanceof RetryableError) && method && path) {
+        const endpoint = apiIndex.getEndpoint(method, path);
+        const context = buildErrorContext(error, method, path, endpoint);
+        return {
+            content: [{ type: "text", text: JSON.stringify(context, null, 2) }],
+            isError: true,
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+        isError: true,
+    };
+}
 const server = new McpServer({
     name: config.name,
     version: "1.2.1",
 });
 // --- Tool 1: list_api ---
 server.tool("list_api", `List available ${config.name} API endpoints. ` +
-    "Call with no arguments to see all categories. " +
-    "Provide 'category' to list endpoints in a tag. " +
-    "Provide 'search' to search across paths and descriptions. " +
-    "The correct query format is auto-selected based on mode. " +
-    "You can optionally override with a custom 'query' parameter. " +
+    "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. Omit to see all categories."),
+        .describe("Tag/category to filter by. Case-insensitive."),
     search: z
         .string()
         .optional()
-        .describe("Search keyword across endpoint paths and descriptions"),
+        .describe("Search keyword or regex pattern across endpoint paths and summaries"),
     query: z
         .string()
         .optional()
-        .describe("Optional GraphQL selection query override. If omitted, a sensible default is used automatically:\n" +
-        "Categories (no args): '{ items { tag endpointCount } _count }'\n" +
-        "Endpoints (with category/search): '{ items { method path summary tag parameters { name in required description } } _count }'"),
+        .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()
@@ -52,7 +66,6 @@ server.tool("list_api", `List available ${config.name} API endpoints. ` +
         .describe("Items to skip (default: 0)"),
 }, async ({ category, search, query, limit, offset }) => {
     try {
-        const isEndpointMode = !!(search || category);
         let data;
         if (search) {
             data = apiIndex.searchAll(search);
@@ -61,7 +74,7 @@ server.tool("list_api", `List available ${config.name} API endpoints. ` +
             data = apiIndex.listAllByCategory(category);
         }
         else {
-            data = apiIndex.listAllCategories();
+            data = apiIndex.listAll();
         }
         // Empty results — return directly to avoid GraphQL schema errors on empty arrays
         if (data.length === 0) {
@@ -71,11 +84,9 @@ server.tool("list_api", `List available ${config.name} API endpoints. ` +
                 ],
             };
         }
-        const defaultQuery = isEndpointMode
-            ? "{ items { method path summary tag parameters { name in required description } } _count }"
-            : "{ items { tag endpointCount } _count }";
+        const defaultQuery = "{ items { method path summary } _count }";
         const effectiveQuery = query ?? defaultQuery;
-        const { schema } = getOrBuildSchema(data, "LIST", category ?? search ?? "_categories");
+        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) {
@@ -177,13 +188,7 @@ server.tool("call_api", `Inspect a ${config.name} API endpoint. Makes a real req
         };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-            content: [
-                { type: "text", text: JSON.stringify({ error: message }) },
-            ],
-            isError: true,
-        };
+        return formatToolError(error, method, path);
     }
 });
 // --- Tool 3: query_api ---
@@ -261,13 +266,7 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
         };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-            content: [
-                { type: "text", text: JSON.stringify({ error: message }) },
-            ],
-            isError: true,
-        };
+        return formatToolError(error, method, path);
     }
 });
 // --- Tool 4: explain_api ---
@@ -407,9 +406,12 @@ server.tool("batch_query", `Fetch data from multiple ${config.name} API endpoint
             if (outcome.status === "fulfilled") {
                 return outcome.value;
             }
-            const message = outcome.reason instanceof Error
-                ? outcome.reason.message
-                : String(outcome.reason);
+            const reason = outcome.reason;
+            if (reason instanceof ApiError || reason instanceof RetryableError) {
+                const endpoint = apiIndex.getEndpoint(requests[i].method, requests[i].path);
+                return buildErrorContext(reason, requests[i].method, requests[i].path, endpoint);
+            }
+            const message = reason instanceof Error ? reason.message : String(reason);
             return {
                 method: requests[i].method,
                 path: requests[i].path,

package/package.json

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