anyapi-mcp-server 1.5.1 → 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 };
@@ -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/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,10 +8,27 @@ 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.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",
@@ -171,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 ---
@@ -255,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 ---
@@ -401,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.1",
+  "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",