anyapi-mcp-server 1.5.1 → 1.6.1

package/build/config.js

@@ -62,7 +62,17 @@ Required:
 Optional:
   --header     HTTP header as "Key: Value" (repeatable)
                Supports \${ENV_VAR} interpolation in values
-  --log        Path to request/response log file (NDJSON format)`;
+  --log        Path to request/response log file (NDJSON format)
+
+OAuth 2.0 (all optional, but client-id/client-secret/token-url are required together):
+  --oauth-client-id      OAuth client ID
+  --oauth-client-secret  OAuth client secret
+  --oauth-token-url      OAuth token endpoint URL
+  --oauth-auth-url       OAuth authorization endpoint URL (authorization_code flow)
+  --oauth-scopes         Comma-separated scopes (e.g. "read,write")
+  --oauth-flow           "authorization_code" (default) or "client_credentials"
+  --oauth-param          Extra auth URL param as "key=value" (repeatable)
+               All OAuth values support \${ENV_VAR} interpolation`;
 export async function loadConfig() {
     const name = getArg("--name");
     const specUrls = getAllArgs("--spec");
@@ -84,11 +94,55 @@ export async function loadConfig() {
         headers[key] = interpolateEnv(value);
     }
     const logPath = getArg("--log");
+    // --- OAuth CLI flags ---
+    const oauthClientId = getArg("--oauth-client-id");
+    const oauthClientSecret = getArg("--oauth-client-secret");
+    const oauthTokenUrl = getArg("--oauth-token-url");
+    const oauthAuthUrl = getArg("--oauth-auth-url");
+    const oauthScopes = getArg("--oauth-scopes");
+    const oauthFlow = getArg("--oauth-flow");
+    const oauthParams = getAllArgs("--oauth-param");
+    const hasAnyOAuth = oauthClientId || oauthClientSecret || oauthTokenUrl;
+    if (hasAnyOAuth && !(oauthClientId && oauthClientSecret && oauthTokenUrl)) {
+        console.error("ERROR: --oauth-client-id, --oauth-client-secret, and --oauth-token-url must all be provided together.");
+        process.exit(1);
+    }
+    let oauth;
+    if (oauthClientId && oauthClientSecret && oauthTokenUrl) {
+        const extraParams = {};
+        for (const raw of oauthParams) {
+            const eqIdx = raw.indexOf("=");
+            if (eqIdx === -1) {
+                console.error(`ERROR: Invalid --oauth-param format "${raw}". Expected "key=value"`);
+                process.exit(1);
+            }
+            extraParams[raw.slice(0, eqIdx)] = interpolateEnv(raw.slice(eqIdx + 1));
+        }
+        const flow = (oauthFlow ? interpolateEnv(oauthFlow) : "authorization_code");
+        if (flow !== "authorization_code" && flow !== "client_credentials") {
+            console.error(`ERROR: Invalid --oauth-flow "${flow}". Must be "authorization_code" or "client_credentials".`);
+            process.exit(1);
+        }
+        oauth = {
+            clientId: interpolateEnv(oauthClientId),
+            clientSecret: interpolateEnv(oauthClientSecret),
+            tokenUrl: interpolateEnv(oauthTokenUrl),
+            authUrl: oauthAuthUrl ? interpolateEnv(oauthAuthUrl) : undefined,
+            scopes: oauthScopes
+                ? interpolateEnv(oauthScopes)
+                    .split(/[,\s]+/)
+                    .filter(Boolean)
+                : [],
+            flow,
+            extraParams,
+        };
+    }
     return {
         name,
         specs,
         baseUrl: interpolateEnv(baseUrl).replace(/\/+$/, ""),
         headers: Object.keys(headers).length > 0 ? headers : undefined,
         logPath: logPath ? resolve(logPath) : undefined,
+        oauth,
     };
 }

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. Use the auth tool to authenticate via OAuth, or 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,43 @@ 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";
+import { isNonJsonResult } from "./response-parser.js";
+import { startAuth, exchangeCode, awaitCallback, storeTokens, getTokens, isTokenExpired, initTokenStorage, } from "./oauth.js";
 const WRITE_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
 const config = await loadConfig();
 initLogger(config.logPath ?? null);
 const apiIndex = new ApiIndex(config.specs);
+// --- OAuth: merge spec-derived security info and init token storage ---
+if (config.oauth) {
+    const schemes = apiIndex.getOAuthSchemes();
+    if (schemes.length > 0) {
+        const scheme = schemes[0];
+        if (!config.oauth.authUrl && scheme.authorizationUrl) {
+            config.oauth.authUrl = scheme.authorizationUrl;
+        }
+        if (config.oauth.scopes.length === 0 && scheme.scopes.length > 0) {
+            config.oauth.scopes = scheme.scopes;
+        }
+    }
+    initTokenStorage(config.name);
+}
+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",
@@ -128,12 +161,25 @@ server.tool("call_api", `Inspect a ${config.name} API endpoint. Makes a real req
         "Overrides default --header values."),
 }, async ({ method, path, params, body, headers }) => {
     try {
-        const data = await callApi(config, method, path, params, body, headers, "populate");
+        const { data, responseHeaders: respHeaders } = await callApi(config, method, path, params, body, headers, "populate");
+        // Non-JSON response — skip GraphQL layer, return raw parsed data
+        if (isNonJsonResult(data)) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({
+                            rawResponse: data,
+                            responseHeaders: respHeaders,
+                            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) && body ? computeShapeHash(body) : undefined;
         const { schema, shapeHash } = getOrBuildSchema(data, method, path, endpoint?.requestBodySchema, bodyHash);
         const sdl = schemaToSDL(schema);
-        const result = { graphqlSchema: sdl, shapeHash };
+        const result = { graphqlSchema: sdl, shapeHash, responseHeaders: respHeaders };
         if (bodyHash)
             result.bodyHash = bodyHash;
         if (endpoint && endpoint.parameters.length > 0) {
@@ -171,13 +217,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 ---
@@ -229,7 +269,20 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
         .describe("Client-side slice: items to skip in already-fetched response (default: 0). For API pagination, use params instead."),
 }, async ({ method, path, params, body, query, headers, limit, offset }) => {
     try {
-        const rawData = await callApi(config, method, path, params, body, headers, "consume");
+        const { data: rawData, responseHeaders: respHeaders } = await callApi(config, method, path, params, body, headers, "consume");
+        // Non-JSON response — skip GraphQL layer, return raw parsed data
+        if (isNonJsonResult(rawData)) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({
+                            rawResponse: rawData,
+                            responseHeaders: respHeaders,
+                            hint: "This endpoint returned a non-JSON response. GraphQL querying is not available. " +
+                                "The raw parsed content is shown above.",
+                        }, null, 2) },
+                ],
+            };
+        }
         const endpoint = apiIndex.getEndpoint(method, path);
         const bodyHash = WRITE_METHODS.has(method) && body ? computeShapeHash(body) : undefined;
         const { schema, shapeHash } = getOrBuildSchema(rawData, method, path, endpoint?.requestBodySchema, bodyHash);
@@ -237,6 +290,7 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
         const queryResult = await executeQuery(schema, data, query);
         if (typeof queryResult === "object" && queryResult !== null) {
             queryResult._shapeHash = shapeHash;
+            queryResult._responseHeaders = respHeaders;
             if (bodyHash)
                 queryResult._bodyHash = bodyHash;
             if (truncated) {
@@ -255,13 +309,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 ---
@@ -382,7 +430,17 @@ server.tool("batch_query", `Fetch data from multiple ${config.name} API endpoint
 }, async ({ requests }) => {
     try {
         const settled = await Promise.allSettled(requests.map(async (req) => {
-            const rawData = await callApi(config, req.method, req.path, req.params, req.body, req.headers, "none");
+            const { data: rawData, responseHeaders: respHeaders } = await callApi(config, req.method, req.path, req.params, req.body, req.headers, "none");
+            // Non-JSON response — skip GraphQL layer
+            if (isNonJsonResult(rawData)) {
+                return {
+                    method: req.method,
+                    path: req.path,
+                    data: rawData,
+                    responseHeaders: respHeaders,
+                    nonJson: true,
+                };
+            }
             const endpoint = apiIndex.getEndpoint(req.method, req.path);
             const bodyHash = WRITE_METHODS.has(req.method) && req.body
                 ? computeShapeHash(req.body)
@@ -393,6 +451,7 @@ server.tool("batch_query", `Fetch data from multiple ${config.name} API endpoint
                 method: req.method,
                 path: req.path,
                 data: queryResult,
+                responseHeaders: respHeaders,
                 shapeHash,
                 ...(bodyHash ? { bodyHash } : {}),
             };
@@ -401,9 +460,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,
@@ -426,6 +488,120 @@ server.tool("batch_query", `Fetch data from multiple ${config.name} API endpoint
         };
     }
 });
+// --- Tool 6: auth (only when OAuth is configured) ---
+if (config.oauth) {
+    server.tool("auth", `Manage OAuth 2.0 authentication for ${config.name}. ` +
+        "Use action 'start' to begin the OAuth flow (returns an authorization URL for " +
+        "authorization_code flow, or completes token exchange for client_credentials). " +
+        "Use action 'exchange' to complete the flow — the callback is captured automatically " +
+        "via a localhost server, or you can provide a 'code' manually. " +
+        "Use action 'status' to check the current token status.", {
+        action: z
+            .enum(["start", "exchange", "status"])
+            .describe("'start' begins auth flow, 'exchange' completes code exchange, 'status' shows token info"),
+        code: z
+            .string()
+            .optional()
+            .describe("Authorization code from the OAuth provider (optional for 'exchange' — " +
+            "if omitted, waits for the localhost callback automatically)"),
+    }, async ({ action, code }) => {
+        try {
+            if (action === "start") {
+                const result = await startAuth(config.oauth);
+                if ("url" in result) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    message: "Open this URL to authorize. A local callback server is listening. " +
+                                        "After you approve, call auth with action 'exchange' to complete authentication.",
+                                    authorizationUrl: result.url,
+                                    flow: config.oauth.flow,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                // client_credentials: tokens obtained directly
+                storeTokens(result.tokens);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                message: "Authentication successful (client_credentials flow).",
+                                tokenType: result.tokens.tokenType,
+                                expiresIn: Math.round((result.tokens.expiresAt - Date.now()) / 1000),
+                                scope: result.tokens.scope ?? null,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            if (action === "exchange") {
+                const tokens = code
+                    ? await exchangeCode(config.oauth, code)
+                    : await awaitCallback(config.oauth);
+                storeTokens(tokens);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                message: "Authentication successful.",
+                                tokenType: tokens.tokenType,
+                                expiresIn: Math.round((tokens.expiresAt - Date.now()) / 1000),
+                                hasRefreshToken: !!tokens.refreshToken,
+                                scope: tokens.scope ?? null,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // action === "status"
+            const tokens = getTokens();
+            if (!tokens) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                authenticated: false,
+                                message: "No tokens stored. Use auth with action 'start' to authenticate.",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const expired = isTokenExpired();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            authenticated: true,
+                            tokenType: tokens.tokenType,
+                            expired,
+                            expiresIn: Math.round((tokens.expiresAt - Date.now()) / 1000),
+                            hasRefreshToken: !!tokens.refreshToken,
+                            scope: tokens.scope ?? null,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ error: message }) },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);