anyapi-mcp-server 1.5.1 → 1.6.1

package/README.md

@@ -8,239 +8,146 @@ Traditional MCP servers hand-pick a handful of endpoints and call it a day — l
 
 `anyapi-mcp-server` is a universal [MCP](https://modelcontextprotocol.io) server that connects **any REST API** to AI assistants like Claude, Cursor, and other LLM-powered tools — just point it at an OpenAPI spec or Postman collection. Every endpoint the API provides becomes available instantly, with **GraphQL-style field selection** and automatic schema inference. No custom server code, no artificial limits.
 
-Works with services like **Datadog**, **PostHog**, **Metabase**, **Cloudflare**, **Stripe**, **GitHub**, **Slack**, **Twilio**, **Shopify**, **HubSpot**, and anything else with a REST API — if it has an API, it just works.
-
-## Features
-
-- **Works with any REST API** — provide an OpenAPI (JSON/YAML) or Postman Collection v2.x spec as a local file or HTTPS URL
-- **Remote spec caching** — HTTPS spec URLs are fetched once and cached locally in ``~/.cache/anyapi-mcp/` (Linux/macOS) or `%LOCALAPPDATA%\anyapi-mcp\` (Windows)`
-- **GraphQL-style queries** — select only the fields you need from API responses
-- **Automatic schema inference** — calls an endpoint once, infers the response schema, then lets you query specific fields
-- **Multi-sample merging** — samples up to 10 array elements to build richer schemas that capture fields missing from individual items
-- **Mutation support** — POST/PUT/DELETE/PATCH endpoints with OpenAPI request body schemas get GraphQL mutation types with typed inputs
-- **Smart query suggestions** — `call_api` returns ready-to-use GraphQL queries based on the inferred schema
-- **Shape-aware schema caching** — schemas are cached by response structure (not just endpoint), so the same path returning different shapes gets distinct schemas; `shapeHash` is returned for cache-aware workflows
-- **Response caching** — 30-second TTL cache prevents duplicate HTTP calls across consecutive `call_api` → `query_api` flows
-- **Retry with backoff** — automatic retries with exponential backoff and jitter for 429/5xx errors, honoring `Retry-After` headers
-- **Multi-format responses** — parses JSON, XML, CSV, and plain text responses automatically
-- **Built-in pagination** — API-level pagination via `params`; client-side slicing with top-level `limit`/`offset`
-- **Spec documentation lookup** — `explain_api` returns rich endpoint docs (parameters, response codes, deprecation, request body schema) without making HTTP requests
-- **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
-- **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)
 
-## Installation
+## Quick start
+
+**1. Install**
 
 ```bash
 npm install -g anyapi-mcp-server
 ```
 
-### Required arguments
-
-| Flag | Description |
-|------|-------------|
-| `--name` | Server name (e.g. `petstore`) |
-| `--spec` | Path or HTTPS URL to OpenAPI spec (JSON or YAML) or Postman Collection. HTTPS URLs are cached locally in ``~/.cache/anyapi-mcp/` (Linux/macOS) or `%LOCALAPPDATA%\anyapi-mcp\` (Windows)`. Supports `${ENV_VAR}` interpolation. |
-| `--base-url` | API base URL (e.g. `https://api.example.com`). Supports `${ENV_VAR}` interpolation. |
-
-### Optional arguments
-
-| Flag | Description |
-|------|-------------|
-| `--header` | HTTP header as `"Key: Value"` (repeatable). Supports `${ENV_VAR}` interpolation in values. |
-| `--log` | Path to request/response log file (NDJSON format). Sensitive headers are masked automatically. |
-
-### Example: Cursor / Claude Desktop configuration
-
-Add to your MCP configuration (e.g. `~/.cursor/mcp.json` or Claude Desktop config):
-
-#### Cloudflare API
+**2. Add to your MCP client** (Cursor, Claude Desktop, etc.)
 
 ```json
 {
   "mcpServers": {
-    "cloudflare": {
+    "your-api": {
       "command": "npx",
       "args": [
         "-y",
         "anyapi-mcp-server",
-        "--name", "cloudflare",
-        "--spec", "https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.json",
-        "--base-url", "https://api.cloudflare.com/client/v4",
-        "--header", "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}"
+        "--name", "your-api",
+        "--spec", "path/to/openapi.json",
+        "--base-url", "https://api.example.com",
+        "--header", "Authorization: Bearer ${API_KEY}"
       ],
       "env": {
-        "CLOUDFLARE_API_TOKEN": "your-cloudflare-api-token"
+        "API_KEY": "your-api-key"
       }
     }
   }
 }
 ```
 
-#### Datadog API
+**3. Use the tools** — discover endpoints with `list_api`, inspect schemas with `call_api`, fetch data with `query_api`.
 
-```json
-{
-  "mcpServers": {
-    "datadog": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "anyapi-mcp-server",
-        "--name", "datadog",
-        "--spec", "https://raw.githubusercontent.com/DataDog/datadog-api-client-typescript/master/.generator/schemas/v1/openapi.yaml",
-        "--base-url", "https://api.datadoghq.com",
-        "--header", "DD-API-KEY: ${DD_API_KEY}",
-        "--header", "DD-APPLICATION-KEY: ${DD_APP_KEY}"
-      ],
-      "env": {
-        "DD_API_KEY": "your-datadog-api-key",
-        "DD_APP_KEY": "your-datadog-app-key"
-      }
-    }
-  }
-}
-```
+## Provider examples
 
-#### Metabase API
+Ready-to-use configurations for popular APIs:
 
-```json
-{
-  "mcpServers": {
-    "metabase": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "anyapi-mcp-server",
-        "--name", "metabase",
-        "--base-url", "https://your-metabase-instance.com/api",
-        "--header", "x-api-key: ${METABASE_API_KEY}"
-      ],
-      "env": {
-        "METABASE_API_KEY": "your-metabase-api-key"
-      }
-    }
-  }
-}
-```
+| Provider | Auth |
+|----------|------|
+| [Cloudflare](docs/cloudflare.md) | API Token or Key + Email |
+| [Datadog](docs/datadog.md) | API Key + App Key |
+| [GitHub](docs/github.md) | Personal Access Token |
+| [Google Workspace](docs/google-workspace.md) | OAuth 2.0 |
+| [Metabase](docs/metabase.md) | API Key |
+| [PostHog](docs/posthog.md) | Personal API Key |
+| [Slack](docs/slack.md) | Bot/User Token |
+
+These work with any API that has an OpenAPI or Postman spec — the above are just examples. Stripe, Twilio, Shopify, HubSpot, and anything else with a REST API will work the same way.
+
+## CLI reference
+
+### Required flags
+
+| Flag | Description |
+|------|-------------|
+| `--name` | Server name (e.g. `cloudflare`) |
+| `--spec` | Path or HTTPS URL to an OpenAPI spec (JSON/YAML) or Postman Collection. Remote URLs are cached locally. Supports `${ENV_VAR}`. |
+| `--base-url` | API base URL (e.g. `https://api.example.com`). Supports `${ENV_VAR}`. |
+
+### Optional flags
+
+| Flag | Description |
+|------|-------------|
+| `--header` | HTTP header as `"Key: Value"` (repeatable). Supports `${ENV_VAR}` in values. |
+| `--log` | Path to NDJSON request/response log. Sensitive headers are masked automatically. |
+
+### OAuth flags
+
+For APIs that use OAuth 2.0 instead of static tokens. If any of the three required flags is provided, all three are required. All flags support `${ENV_VAR}`.
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--oauth-client-id` | Yes* | OAuth client ID |
+| `--oauth-client-secret` | Yes* | OAuth client secret |
+| `--oauth-token-url` | Yes* | Token endpoint URL |
+| `--oauth-auth-url` | No | Authorization endpoint (auto-detected from spec if available) |
+| `--oauth-scopes` | No | Comma-separated scopes |
+| `--oauth-flow` | No | `authorization_code` (default) or `client_credentials` |
+| `--oauth-param` | No | Extra token parameter as `key=value` (repeatable) |
+
+See the [Google Workspace guide](docs/google-workspace.md) for a complete OAuth example.
 
 ## Tools
 
-The server exposes five MCP tools:
+The server exposes five tools (plus `auth` when OAuth is configured):
 
-### `list_api`
+### `list_api` — Browse endpoints
 
-Browse and search available API endpoints from the spec.
+Discover what the API offers. Call with no arguments to see all categories, provide `category` to list endpoints in a tag, or `search` to find endpoints by keyword.
 
-- Call with no arguments to see all categories/tags
-- Provide `category` to list endpoints in a tag
-- Provide `search` to search across paths and descriptions
-- Results are paginated with `limit` (default 20) and `offset`
-- GraphQL selection for categories:
-  ```graphql
-  {
-    items {
-      tag
-      endpointCount
-    }
-    _count
-  }
-  ```
-- GraphQL selection for endpoints:
-  ```graphql
-  {
-    items {
-      method
-      path
-      summary
-    }
-    _count
-  }
-  ```
+### `call_api` — Inspect an endpoint
 
-### `call_api`
+Makes a real HTTP request and returns the **inferred GraphQL schema** (SDL) — not the data itself. Use this to discover the response shape and get `suggestedQueries` you can copy into `query_api`.
 
-Inspect an API endpoint by making a real request and returning the inferred GraphQL schema (SDL). No response data is returned — use `query_api` to fetch actual data.
+### `query_api` — Fetch data
 
-- Returns the full schema SDL showing all available fields and types
-- Returns accepted parameters (name, location, required) from the API spec
-- Returns `suggestedQueries` — ready-to-use GraphQL queries generated from the schema
-- Returns `shapeHash` — a structural fingerprint of the response for cache-aware workflows
-- Returns `bodyHash` for write operations when a request body is provided
-- Accepts optional `headers` to override defaults for this request
-- For write operations (POST/PUT/DELETE/PATCH) with request body schemas, the schema includes a Mutation type
+Fetches data and returns **only the fields you select** via a GraphQL query. Supports both reads and writes (mutations for POST/PUT/DELETE/PATCH).
 
-### `query_api`
+```graphql
+# Read
+{ items { id name status } _count }
 
-Fetch data from an API endpoint, returning only the fields you select via GraphQL.
+# Write
+mutation { post_endpoint(input: { name: "example" }) { id } }
+```
 
-- Object responses:
-  ```graphql
-  {
-    id
-    name
-    collection {
-      id
-      name
-    }
-  }
-  ```
-- Array responses:
-  ```graphql
-  {
-    items {
-      id
-      name
-    }
-    _count
-  }
-  ```
-- Mutation syntax for writes:
-  ```graphql
-  mutation {
-    post_endpoint(input: { ... }) {
-      id
-      name
-    }
-  }
-  ```
-- Supports `limit` and `offset` for client-side slicing of already-fetched data
-- For API-level pagination, pass limit/offset inside `params` instead
-- Accepts optional `headers` to override defaults for this request
-- Response includes `_shapeHash` (and `_bodyHash` for writes) for tracking schema identity
+### `explain_api` — Read the docs
 
-### `explain_api`
+Returns spec documentation for an endpoint (parameters, request body schema, response codes) **without making an HTTP request**.
 
-Get detailed documentation for an endpoint directly from the spec — no HTTP request is made.
+### `batch_query` — Parallel requests
 
-- Returns summary, description, operationId, deprecation status, tag
-- Lists all parameters with name, location (`path`/`query`/`header`), required flag, and description
-- Shows request body schema with property types, required fields, and descriptions
-- Lists response status codes with descriptions (e.g. `200 OK`, `404 Not Found`)
-- Includes external docs link when available
+Fetches data from up to 10 endpoints concurrently in a single tool call. Each request follows the `query_api` flow.
 
-### `batch_query`
+### `auth` — OAuth authentication
 
-Fetch data from multiple endpoints concurrently in a single tool call.
+Only available when `--oauth-*` flags are configured. Manages the OAuth flow:
+- `action: "start"` — returns an authorization URL (or exchanges credentials for `client_credentials`)
+- `action: "exchange"` — completes the authorization code flow (callback is captured automatically)
+- `action: "status"` — shows current token status
 
-- 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
-- Run `call_api` first on each endpoint to discover the schema field names
+Tokens are persisted and refreshed automatically.
 
-## Workflow
+## Typical workflow
 
-1. **Discover** endpoints with `list_api`
-2. **Understand** an endpoint with `explain_api` to see its parameters, request body, and response codes
-3. **Inspect** a specific endpoint with `call_api` to see the inferred response schema and suggested queries
-4. **Query** the endpoint with `query_api` to fetch exactly the fields you need
-5. **Batch** multiple queries with `batch_query` when you need data from several endpoints at once
+```
+list_api          → discover what's available
+     ↓
+explain_api       → read the docs for an endpoint
+     ↓
+call_api          → inspect the response schema
+     ↓
+query_api         → fetch exactly the fields you need
+     ↓
+batch_query       → fetch from multiple endpoints at once
+```
 
-## How It Works
+## How it works
 
 ```
 OpenAPI/Postman spec
@@ -263,19 +170,30 @@ OpenAPI/Postman spec
                                                response data
 ```
 
-1. The spec is loaded at startup (from a local file or fetched from an HTTPS URL with filesystem caching) and parsed into an endpoint index with tags, paths, parameters, and request body schemas
-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
+## Features
 
-## Supported Spec Formats
+- **Any REST API** — provide an OpenAPI (JSON/YAML) or Postman Collection v2.x spec as a file or URL
+- **Remote spec caching** — HTTPS specs are fetched once and cached to `~/.cache/anyapi-mcp/`
+- **GraphQL field selection** — query only the fields you need from any response
+- **Schema inference** — automatically builds GraphQL schemas from live API responses
+- **Multi-sample merging** — samples up to 10 array elements for richer schemas
+- **Mutation support** — write operations get typed GraphQL mutations from OpenAPI body schemas
+- **Smart suggestions** — `call_api` returns ready-to-use queries based on the inferred schema
+- **Response caching** — 30s TTL prevents duplicate calls across `call_api` → `query_api`
+- **Retry with backoff** — automatic retries for 429/5xx with exponential backoff and `Retry-After` support
+- **Multi-format** — parses JSON, XML, CSV, and plain text responses
+- **Pagination** — API-level via `params`, client-side slicing via `limit`/`offset`
+- **Rich errors** — structured error messages with status-specific suggestions and spec context for self-correction
+- **OAuth 2.0** — Authorization Code (with PKCE) and Client Credentials flows with automatic token refresh
+- **Env var interpolation** — `${ENV_VAR}` in base URLs, headers, and spec paths
+- **Request logging** — optional NDJSON log with sensitive header masking
+
+## Supported spec formats
 
 - **OpenAPI 3.x** (JSON or YAML)
 - **OpenAPI 2.0 / Swagger** (JSON or YAML)
 - **Postman Collection v2.x** (JSON)
 
-`$ref` resolution is supported for OpenAPI request body schemas. Postman `:param` path variables are converted to OpenAPI-style `{param}` automatically.
-
 ## License
 
 Proprietary Non-Commercial. Free for personal and educational use. Commercial use requires written permission. See [LICENSE](LICENSE) for details.

package/build/api-client.js

@@ -2,6 +2,8 @@ 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";
+import { getValidAccessToken, refreshTokens } from "./oauth.js";
 const TIMEOUT_MS = 30_000;
 function interpolatePath(pathTemplate, params) {
     const remaining = { ...params };
@@ -43,72 +45,109 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
         }
         fullUrl += `?${qs.toString()}`;
     }
-    const mergedHeaders = {
-        "Content-Type": "application/json",
+    // Check if an explicit Authorization header was provided by the caller
+    const hasExplicitAuth = Object.keys({
         ...config.headers,
         ...extraHeaders,
-    };
-    // --- Retry-wrapped fetch ---
-    const result = await withRetry(async () => {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
-        const startTime = Date.now();
-        try {
-            const fetchOptions = {
-                method,
-                headers: mergedHeaders,
-                signal: controller.signal,
-            };
-            if (body && method !== "GET") {
-                fetchOptions.body = JSON.stringify(body);
+    }).some((k) => k.toLowerCase() === "authorization");
+    const doRequest = async () => {
+        const mergedHeaders = {
+            "Content-Type": "application/json",
+            ...config.headers,
+            ...extraHeaders,
+        };
+        // Inject OAuth bearer token if no explicit Authorization header
+        if (!hasExplicitAuth) {
+            const accessToken = await getValidAccessToken(config.oauth);
+            if (accessToken) {
+                mergedHeaders["Authorization"] = `Bearer ${accessToken}`;
             }
-            const response = await fetch(fullUrl, fetchOptions);
-            const durationMs = Date.now() - startTime;
-            const bodyText = await response.text();
-            // Log request/response
-            if (isLoggingEnabled()) {
+        }
+        return withRetry(async () => {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+            const startTime = Date.now();
+            try {
+                const fetchOptions = {
+                    method,
+                    headers: mergedHeaders,
+                    signal: controller.signal,
+                };
+                if (body && method !== "GET") {
+                    fetchOptions.body = JSON.stringify(body);
+                }
+                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;
                 });
-                await logEntry({
-                    timestamp: new Date().toISOString(),
-                    method,
-                    url: fullUrl,
-                    requestHeaders: mergedHeaders,
-                    requestBody: body,
-                    responseStatus: response.status,
-                    responseHeaders,
-                    responseBody: bodyText,
-                    durationMs,
-                });
-            }
-            if (!response.ok) {
-                const msg = `API error ${response.status} ${response.statusText}: ${bodyText}`;
-                if (isRetryableStatus(response.status)) {
-                    let retryAfterMs;
-                    const retryAfter = response.headers.get("retry-after");
-                    if (retryAfter) {
-                        const seconds = parseInt(retryAfter, 10);
-                        if (!isNaN(seconds))
-                            retryAfterMs = seconds * 1000;
+                // Log request/response
+                if (isLoggingEnabled()) {
+                    await logEntry({
+                        timestamp: new Date().toISOString(),
+                        method,
+                        url: fullUrl,
+                        requestHeaders: mergedHeaders,
+                        requestBody: body,
+                        responseStatus: response.status,
+                        responseHeaders,
+                        responseBody: bodyText,
+                        durationMs,
+                    });
+                }
+                if (!response.ok) {
+                    if (isRetryableStatus(response.status)) {
+                        const msg = `API error ${response.status} ${response.statusText}: ${bodyText}`;
+                        let retryAfterMs;
+                        const retryAfter = response.headers.get("retry-after");
+                        if (retryAfter) {
+                            const seconds = parseInt(retryAfter, 10);
+                            if (!isNaN(seconds))
+                                retryAfterMs = seconds * 1000;
+                        }
+                        throw new RetryableError(msg, response.status, retryAfterMs);
                     }
-                    throw new RetryableError(msg, response.status, retryAfterMs);
+                    throw new ApiError(`API error ${response.status} ${response.statusText}`, response.status, response.statusText, bodyText, responseHeaders);
                 }
-                throw new Error(msg);
+                const parsedData = parseResponse(response.headers.get("content-type"), bodyText);
+                return { data: parsedData, responseHeaders };
             }
-            return parseResponse(response.headers.get("content-type"), bodyText);
-        }
-        catch (error) {
-            if (error instanceof DOMException && error.name === "AbortError") {
-                throw new Error(`Request to ${method} ${pathTemplate} timed out after ${TIMEOUT_MS / 1000}s`);
+            catch (error) {
+                if (error instanceof DOMException && error.name === "AbortError") {
+                    throw new Error(`Request to ${method} ${pathTemplate} timed out after ${TIMEOUT_MS / 1000}s`);
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        });
+    };
+    // --- Execute with 401 refresh-and-retry ---
+    let result;
+    try {
+        result = await doRequest();
+    }
+    catch (error) {
+        if (error instanceof ApiError &&
+            error.status === 401 &&
+            config.oauth &&
+            !hasExplicitAuth) {
+            // Refresh token and retry once
+            try {
+                await refreshTokens(config.oauth);
+                result = await doRequest();
+            }
+            catch {
+                throw error; // Throw the original 401
             }
-            throw error;
         }
-        finally {
-            clearTimeout(timeout);
+        else {
+            throw error;
         }
-    });
+    }
     // --- Cache store (populate mode only) ---
     if (cacheMode === "populate") {
         setCache(cacheKey, result);

package/build/api-index.js

@@ -118,6 +118,7 @@ function postmanUrlToPath(url) {
 export class ApiIndex {
     byTag = new Map();
     allEndpoints = [];
+    oauthSchemes = [];
     constructor(specContents) {
         for (const specContent of specContents) {
             let parsed;
@@ -185,6 +186,46 @@ export class ApiIndex {
                 this.addEndpoint(endpoint);
             }
         }
+        this.extractSecuritySchemes(rawSpec);
+    }
+    extractSecuritySchemes(spec) {
+        // OpenAPI 3.x: components.securitySchemes
+        const components = spec.components;
+        const securitySchemes = components?.securitySchemes;
+        // OpenAPI 2.x (Swagger): securityDefinitions
+        const securityDefs = spec.securityDefinitions;
+        const schemes = securitySchemes ?? securityDefs ?? {};
+        for (const schemeDef of Object.values(schemes)) {
+            if (schemeDef.type !== "oauth2")
+                continue;
+            // OpenAPI 3.x: flows.authorizationCode, flows.clientCredentials, etc.
+            const flows = schemeDef.flows;
+            if (flows) {
+                for (const flow of Object.values(flows)) {
+                    const scopes = flow.scopes
+                        ? Object.keys(flow.scopes)
+                        : [];
+                    this.oauthSchemes.push({
+                        authorizationUrl: flow.authorizationUrl,
+                        tokenUrl: flow.tokenUrl,
+                        scopes,
+                    });
+                }
+                continue;
+            }
+            // OpenAPI 2.x (Swagger): direct fields on the scheme
+            const scopes = schemeDef.scopes
+                ? Object.keys(schemeDef.scopes)
+                : [];
+            this.oauthSchemes.push({
+                authorizationUrl: schemeDef.authorizationUrl,
+                tokenUrl: schemeDef.tokenUrl,
+                scopes,
+            });
+        }
+    }
+    getOAuthSchemes() {
+        return this.oauthSchemes;
     }
     parsePostman(collection) {
         this.walkPostmanItems(collection.item ?? [], []);