anyapi-mcp-server 1.1.1

package/LICENSE

@@ -0,0 +1,32 @@
+anyapi-mcp-server - Proprietary Non-Commercial License
+
+Copyright (c) 2026 quiloos39
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software for personal, educational, or
+non-commercial purposes only, subject to the following conditions:
+
+1. COMMERCIAL USE PROHIBITED. The Software may not be used, in whole or in
+   part, for any commercial purpose without prior written permission from the
+   copyright holder. "Commercial purpose" includes, but is not limited to:
+   - Selling, licensing, or sublicensing the Software or derivative works
+   - Using the Software in a product or service sold to customers
+   - Using the Software to generate revenue, directly or indirectly
+   - Using the Software in a commercial organization's operations
+
+2. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+3. Derivative works must include this same license and may not be released
+   under a different license.
+
+4. For commercial licensing inquiries, contact the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# anyapi-mcp-server
+
+A universal [Model Context Protocol (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.
+
+Instead of building a custom MCP server for every API, `anyapi-mcp-server` reads your spec file and dynamically creates tools with **GraphQL-style field selection** and automatic schema inference.
+
+## Features
+
+- **Works with any REST API** — provide an OpenAPI (JSON/YAML) or Postman Collection v2.x spec
+- **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
+- **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`
+- **Per-request headers** — override default headers on individual `call_api`/`query_api` calls
+- **Environment variable interpolation** — use `${ENV_VAR}` in base URLs and headers
+- **Request logging** — optional NDJSON request/response log with sensitive header masking
+
+## Installation
+
+```bash
+npm install -g anyapi-mcp-server
+```
+
+Or use directly with `npx`:
+
+```bash
+npx anyapi-mcp-server --name petstore --spec ./petstore.yaml --base-url https://petstore.swagger.io/v2
+```
+
+## Usage
+
+```
+anyapi-mcp --name <name> --spec <path> --base-url <url> [--header "Key: Value"]... [--log <path>]
+```
+
+### Required arguments
+
+| Flag | Description |
+|------|-------------|
+| `--name` | Server name (e.g. `petstore`) |
+| `--spec` | Path to OpenAPI spec file (JSON or YAML) or Postman Collection |
+| `--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):
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "anyapi-mcp-server",
+        "--name", "petstore",
+        "--spec", "/path/to/petstore.yaml",
+        "--base-url", "https://petstore.swagger.io/v2"
+      ]
+    }
+  }
+}
+```
+
+With authentication headers:
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "anyapi-mcp-server",
+        "--name", "my-api",
+        "--spec", "/path/to/openapi.json",
+        "--base-url", "https://api.example.com",
+        "--header", "Authorization: Bearer ${API_TOKEN}"
+      ],
+      "env": {
+        "API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+The server exposes three MCP tools:
+
+### `list_api`
+
+Browse and search available API endpoints from the spec.
+
+- 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`
+- Uses GraphQL selection: `{ items { tag endpointCount } _count }` for categories, `{ items { method path summary } _count }` for endpoints
+
+### `call_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.
+
+- 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
+- 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
+
+### `query_api`
+
+Fetch data from an API endpoint, returning only the fields you select via GraphQL.
+
+- Object responses: `{ id name collection { id name } }`
+- Array responses: `{ items { id name } _count }`
+- Mutation syntax for writes: `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
+
+## Workflow
+
+1. **Discover** endpoints with `list_api`
+2. **Inspect** a specific endpoint with `call_api` to see its schema and suggested queries
+3. **Query** the endpoint with `query_api` to fetch exactly the fields you need
+
+## How It Works
+
+```
+OpenAPI/Postman spec
+        │
+        ▼
+   ┌─────────┐     ┌──────────┐     ┌────────────┐
+   │ list_api │     │ call_api │────▶│ query_api  │
+   │ (browse) │     │ (schema) │     │ (data)     │
+   └─────────┘     └──────────┘     └────────────┘
+                        │                 │
+                        ▼                 ▼
+                   REST API call     REST API call
+                   (with retry       (cached if same
+                    + caching)        as call_api)
+                        │                 │
+                        ▼                 ▼
+                   Infer GraphQL     Execute GraphQL
+                   schema from       query against
+                   JSON response     response data
+```
+
+1. The spec file is parsed at startup 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
+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
+4. Write operations (POST/PUT/DELETE/PATCH) with OpenAPI request body schemas get a Mutation type with typed `GraphQLInputObjectType` inputs
+
+## 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

@@ -0,0 +1,105 @@
+import { withRetry, RetryableError, isRetryableStatus } from "./retry.js";
+import { buildCacheKey, getCached, setCache } from "./response-cache.js";
+import { logEntry, isLoggingEnabled } from "./logger.js";
+import { parseResponse } from "./response-parser.js";
+const TIMEOUT_MS = 30_000;
+function interpolatePath(pathTemplate, params) {
+    const remaining = { ...params };
+    const url = pathTemplate.replace(/\{([^}]+)\}/g, (_, paramName) => {
+        const value = remaining[paramName];
+        if (value === undefined) {
+            throw new Error(`Missing required path parameter: ${paramName}`);
+        }
+        delete remaining[paramName];
+        return encodeURIComponent(String(value));
+    });
+    return { url, remainingParams: remaining };
+}
+export async function callApi(config, method, pathTemplate, params, body, extraHeaders) {
+    // --- Cache check ---
+    const cacheKey = buildCacheKey(method, pathTemplate, params, body, extraHeaders);
+    const cached = getCached(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    // --- URL construction ---
+    const { url: interpolatedPath, remainingParams } = interpolatePath(pathTemplate, params ?? {});
+    let fullUrl = `${config.baseUrl}${interpolatedPath}`;
+    if (method === "GET" && Object.keys(remainingParams).length > 0) {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(remainingParams)) {
+            if (v !== undefined && v !== null) {
+                qs.append(k, String(v));
+            }
+        }
+        fullUrl += `?${qs.toString()}`;
+    }
+    const mergedHeaders = {
+        "Content-Type": "application/json",
+        ...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);
+            }
+            const response = await fetch(fullUrl, fetchOptions);
+            const durationMs = Date.now() - startTime;
+            const bodyText = await response.text();
+            // Log request/response
+            if (isLoggingEnabled()) {
+                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;
+                    }
+                    throw new RetryableError(msg, response.status, retryAfterMs);
+                }
+                throw new Error(msg);
+            }
+            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`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    });
+    // --- Cache store ---
+    setCache(cacheKey, result);
+    return result;
+}

package/build/api-index.js

@@ -0,0 +1,263 @@
+import { readFileSync } from "node:fs";
+import yaml from "js-yaml";
+const PAGE_SIZE = 20;
+const HTTP_METHODS = new Set(["get", "post", "put", "delete", "patch"]);
+function extractRequestBodySchema(requestBody, spec) {
+    if (!requestBody || typeof requestBody !== "object")
+        return undefined;
+    const rb = requestBody;
+    // Handle $ref at the requestBody level
+    if (rb["$ref"] && typeof rb["$ref"] === "string") {
+        const resolved = resolveRef(rb["$ref"], spec);
+        if (!resolved)
+            return undefined;
+        return extractRequestBodySchema(resolved, spec);
+    }
+    const content = rb.content;
+    if (!content)
+        return undefined;
+    const jsonContent = content["application/json"];
+    if (!jsonContent?.schema)
+        return undefined;
+    let schema = jsonContent.schema;
+    // Resolve top-level $ref
+    if (schema["$ref"] && typeof schema["$ref"] === "string") {
+        const resolved = resolveRef(schema["$ref"], spec);
+        if (!resolved)
+            return undefined;
+        schema = resolved;
+    }
+    const properties = schema.properties;
+    if (!properties)
+        return undefined;
+    const requiredFields = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const result = {};
+    for (const [propName, propDef] of Object.entries(properties)) {
+        let def = propDef;
+        // Resolve property-level $ref
+        if (def["$ref"] && typeof def["$ref"] === "string") {
+            const resolved = resolveRef(def["$ref"], spec);
+            if (resolved)
+                def = resolved;
+        }
+        const prop = {
+            type: def.type ?? "string",
+            required: requiredFields.has(propName),
+        };
+        if (def.description)
+            prop.description = def.description;
+        if (def.items && typeof def.items === "object") {
+            const items = def.items;
+            prop.items = { type: items.type ?? "string" };
+        }
+        result[propName] = prop;
+    }
+    return Object.keys(result).length > 0
+        ? { contentType: "application/json", properties: result }
+        : undefined;
+}
+function resolveRef(ref, spec) {
+    // Handle "#/components/schemas/Foo" style refs
+    if (!ref.startsWith("#/"))
+        return undefined;
+    const parts = ref.slice(2).split("/");
+    let current = spec;
+    for (const part of parts) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function isPostmanCollection(parsed) {
+    const obj = parsed;
+    return !!(obj.info &&
+        typeof obj.info === "object" &&
+        obj.info.schema &&
+        typeof obj.info.schema === "string" &&
+        obj.info.schema.includes("schema.getpostman.com"));
+}
+/**
+ * Extract path template from Postman URL.
+ * Converts Postman's :param to OpenAPI-style {param}.
+ */
+function postmanUrlToPath(url) {
+    let raw;
+    if (typeof url === "string") {
+        raw = url;
+    }
+    else if (url.raw) {
+        raw = url.raw;
+    }
+    else if (url.path) {
+        raw = "/" + url.path.join("/");
+    }
+    else {
+        return "/";
+    }
+    // Strip protocol + host, keep path only
+    try {
+        const parsed = new URL(raw);
+        raw = parsed.pathname + parsed.search;
+    }
+    catch {
+        // Not a full URL — might be just a path or use {{baseUrl}}
+        raw = raw.replace(/^\{\{[^}]+\}\}/, "");
+        if (!raw.startsWith("/")) {
+            const slashIdx = raw.indexOf("/");
+            raw = slashIdx >= 0 ? raw.slice(slashIdx) : "/" + raw;
+        }
+    }
+    // Strip query string
+    const qIdx = raw.indexOf("?");
+    if (qIdx >= 0)
+        raw = raw.slice(0, qIdx);
+    // Convert :param to {param}
+    raw = raw.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}");
+    return raw || "/";
+}
+export class ApiIndex {
+    byTag = new Map();
+    allEndpoints = [];
+    constructor(specPath) {
+        const raw = readFileSync(specPath, "utf-8");
+        const isYaml = /\.ya?ml$/i.test(specPath);
+        const parsed = isYaml ? yaml.load(raw) : JSON.parse(raw);
+        if (isPostmanCollection(parsed)) {
+            this.parsePostman(parsed);
+        }
+        else {
+            this.parseOpenApi(parsed, parsed);
+        }
+    }
+    parseOpenApi(spec, rawSpec) {
+        for (const [path, methods] of Object.entries(spec.paths)) {
+            for (const [method, operation] of Object.entries(methods)) {
+                if (!HTTP_METHODS.has(method))
+                    continue;
+                const op = operation;
+                const tag = op.tags?.[0] ?? "untagged";
+                const parameters = (op.parameters ?? []).map((p) => ({
+                    name: p.name,
+                    in: p.in,
+                    required: p.required ?? false,
+                    description: p.description,
+                }));
+                const requestBodySchema = extractRequestBodySchema(op.requestBody, rawSpec);
+                const endpoint = {
+                    method: method.toUpperCase(),
+                    path,
+                    summary: op.summary ?? `${method.toUpperCase()} ${path}`,
+                    description: op.description ?? "",
+                    tag,
+                    parameters,
+                    hasRequestBody: !!op.requestBody,
+                    requestBodySchema,
+                };
+                this.addEndpoint(endpoint);
+            }
+        }
+    }
+    parsePostman(collection) {
+        this.walkPostmanItems(collection.item ?? [], []);
+    }
+    walkPostmanItems(items, folderPath) {
+        for (const item of items) {
+            if (item.item) {
+                // Folder — recurse with folder name as tag context
+                this.walkPostmanItems(item.item, [...folderPath, item.name ?? "unnamed"]);
+            }
+            else if (item.request) {
+                this.parsePostmanRequest(item, folderPath);
+            }
+        }
+    }
+    parsePostmanRequest(item, folderPath) {
+        const req = item.request;
+        const method = (req.method ?? "GET").toUpperCase();
+        if (!HTTP_METHODS.has(method.toLowerCase()))
+            return;
+        const path = req.url ? postmanUrlToPath(req.url) : "/";
+        const tag = folderPath.length > 0 ? folderPath.join("/") : "untagged";
+        const description = typeof req.description === "string" ? req.description : "";
+        // Extract query params
+        const parameters = [];
+        if (typeof req.url === "object" && req.url.query) {
+            for (const q of req.url.query) {
+                if (q.disabled)
+                    continue;
+                parameters.push({
+                    name: q.key,
+                    in: "query",
+                    required: false,
+                    description: q.description,
+                });
+            }
+        }
+        // Extract path variables
+        if (typeof req.url === "object" && req.url.variable) {
+            for (const v of req.url.variable) {
+                parameters.push({
+                    name: v.key,
+                    in: "path",
+                    required: true,
+                    description: v.description,
+                });
+            }
+        }
+        const endpoint = {
+            method,
+            path,
+            summary: item.name ?? `${method} ${path}`,
+            description,
+            tag,
+            parameters,
+            hasRequestBody: !!req.body,
+        };
+        this.addEndpoint(endpoint);
+    }
+    addEndpoint(endpoint) {
+        this.allEndpoints.push(endpoint);
+        let tagList = this.byTag.get(endpoint.tag);
+        if (!tagList) {
+            tagList = [];
+            this.byTag.set(endpoint.tag, tagList);
+        }
+        tagList.push(endpoint);
+    }
+    listAllCategories() {
+        const categories = [];
+        for (const [tag, endpoints] of this.byTag) {
+            categories.push({ tag, endpointCount: endpoints.length });
+        }
+        categories.sort((a, b) => a.tag.localeCompare(b.tag));
+        return categories;
+    }
+    listAllByCategory(category) {
+        const endpoints = this.byTag.get(category) ?? [];
+        return endpoints.map((ep) => ({
+            method: ep.method,
+            path: ep.path,
+            summary: ep.summary,
+            tag: ep.tag,
+            parameters: ep.parameters,
+        }));
+    }
+    searchAll(keyword) {
+        const lower = keyword.toLowerCase();
+        return this.allEndpoints
+            .filter((ep) => ep.path.toLowerCase().includes(lower) ||
+            ep.summary.toLowerCase().includes(lower) ||
+            ep.description.toLowerCase().includes(lower))
+            .map((ep) => ({
+            method: ep.method,
+            path: ep.path,
+            summary: ep.summary,
+            tag: ep.tag,
+            parameters: ep.parameters,
+        }));
+    }
+    getEndpoint(method, path) {
+        return this.allEndpoints.find((ep) => ep.method === method.toUpperCase() && ep.path === path);
+    }
+}

package/build/config.js

@@ -0,0 +1,64 @@
+import { resolve } from "node:path";
+function getArg(flag) {
+    const idx = process.argv.indexOf(flag);
+    if (idx === -1 || !process.argv[idx + 1])
+        return undefined;
+    return process.argv[idx + 1];
+}
+function getAllArgs(flag) {
+    const values = [];
+    for (let i = 0; i < process.argv.length; i++) {
+        if (process.argv[i] === flag && process.argv[i + 1]) {
+            values.push(process.argv[i + 1]);
+        }
+    }
+    return values;
+}
+function interpolateEnv(value) {
+    return value.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+        const envValue = process.env[varName];
+        if (envValue === undefined) {
+            throw new Error(`Environment variable ${varName} is not set`);
+        }
+        return envValue;
+    });
+}
+const USAGE = `Usage: anyapi-mcp --name <name> --spec <path> --base-url <url> [--header "Key: Value"]...
+
+Required:
+  --name       Server name (e.g. "petstore")
+  --spec       Path to OpenAPI spec file (JSON or YAML)
+  --base-url   API base URL (e.g. "https://api.example.com")
+
+Optional:
+  --header     HTTP header as "Key: Value" (repeatable)
+               Supports \${ENV_VAR} interpolation in values
+  --log        Path to request/response log file (NDJSON format)`;
+export function loadConfig() {
+    const name = getArg("--name");
+    const spec = getArg("--spec");
+    const baseUrl = getArg("--base-url");
+    if (!name || !spec || !baseUrl) {
+        console.error(USAGE);
+        process.exit(1);
+    }
+    const headers = {};
+    for (const raw of getAllArgs("--header")) {
+        const colonIdx = raw.indexOf(":");
+        if (colonIdx === -1) {
+            console.error(`ERROR: Invalid header format "${raw}". Expected "Key: Value"`);
+            process.exit(1);
+        }
+        const key = raw.slice(0, colonIdx).trim();
+        const value = raw.slice(colonIdx + 1).trim();
+        headers[key] = interpolateEnv(value);
+    }
+    const logPath = getArg("--log");
+    return {
+        name,
+        spec: resolve(spec),
+        baseUrl: interpolateEnv(baseUrl).replace(/\/+$/, ""),
+        headers: Object.keys(headers).length > 0 ? headers : undefined,
+        logPath: logPath ? resolve(logPath) : undefined,
+    };
+}