anyapi-mcp-server 1.3.0 → 1.5.0

package/README.md

@@ -1,17 +1,25 @@
 # 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.
+### If it has an API, you can MCP it.
 
-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.
+<img src="public/datadog.gif" alt="anyapi-mcp-server demo — Datadog API" width="1200" />
+
+Traditional MCP servers hand-pick a handful of endpoints and call it a day — locking you into whatever subset someone decided was "enough." Why settle for a fraction of an API when you can have **all of it**?
+
+`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
+- **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
@@ -35,16 +43,9 @@ npm install -g anyapi-mcp-server
 | Flag | Description |
 |------|-------------|
 | `--name` | Server name (e.g. `petstore`) |
-
-### Either one of
-
-| Flag | Description |
-|------|-------------|
-| `--spec` | Path to OpenAPI spec file (JSON or YAML) or Postman Collection |
+| `--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. |
 
-You can provide both `--spec` and `--base-url` together. If only `--spec` is given, the base URL is read from the spec. If only `--base-url` is given, endpoints are discovered dynamically.
-
 ### Optional arguments
 
 | Flag | Description |
@@ -67,7 +68,7 @@ Add to your MCP configuration (e.g. `~/.cursor/mcp.json` or Claude Desktop confi
         "-y",
         "anyapi-mcp-server",
         "--name", "cloudflare",
-        "--spec", "/path/to/cloudflare-openapi.json",
+        "--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}"
       ],
@@ -90,8 +91,8 @@ Add to your MCP configuration (e.g. `~/.cursor/mcp.json` or Claude Desktop confi
         "-y",
         "anyapi-mcp-server",
         "--name", "datadog",
-        "--spec", "/path/to/datadog-openapi.json",
-        "--base-url", "https://api.datadoghq.com/api/v1",
+        "--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}"
       ],
@@ -167,6 +168,8 @@ Inspect an API endpoint by making a real request and returning the inferred Grap
 - 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
 
@@ -207,6 +210,7 @@ Fetch data from an API endpoint, returning only the fields you select via GraphQ
 - 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`
 
@@ -225,7 +229,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 }` on success or `{ method, path, error }` on failure
+- 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
 
 ## Workflow
@@ -259,9 +263,9 @@ OpenAPI/Postman spec
                                                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
+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
 
 ## Supported Spec Formats

package/build/api-index.js

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import yaml from "js-yaml";
 const PAGE_SIZE = 20;
 const HTTP_METHODS = new Set(["get", "post", "put", "delete", "patch"]);
@@ -119,10 +118,14 @@ function postmanUrlToPath(url) {
 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);
+    constructor(specContent) {
+        let parsed;
+        try {
+            parsed = JSON.parse(specContent);
+        }
+        catch {
+            parsed = yaml.load(specContent);
+        }
         if (isPostmanCollection(parsed)) {
             this.parsePostman(parsed);
         }

package/build/config.js

@@ -1,4 +1,8 @@
 import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 function getArg(flag) {
     const idx = process.argv.indexOf(flag);
     if (idx === -1 || !process.argv[idx + 1])
@@ -23,25 +27,51 @@ function interpolateEnv(value) {
         return envValue;
     });
 }
-const USAGE = `Usage: anyapi-mcp --name <name> --spec <path> --base-url <url> [--header "Key: Value"]...
+const CACHE_DIR = process.platform === "win32"
+    ? join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "anyapi-mcp")
+    : join(homedir(), ".cache", "anyapi-mcp");
+function isUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+async function loadSpec(specValue) {
+    if (!isUrl(specValue)) {
+        return readFileSync(resolve(specValue), "utf-8");
+    }
+    const hash = createHash("sha256").update(specValue).digest("hex");
+    const ext = /\.ya?ml$/i.test(specValue) ? ".yaml" : ".json";
+    const cachePath = join(CACHE_DIR, hash + ext);
+    if (existsSync(cachePath)) {
+        return readFileSync(cachePath, "utf-8");
+    }
+    const res = await fetch(specValue);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch spec from ${specValue}: ${res.status} ${res.statusText}`);
+    }
+    const body = await res.text();
+    mkdirSync(CACHE_DIR, { recursive: true });
+    writeFileSync(cachePath, body, "utf-8");
+    return body;
+}
+const USAGE = `Usage: anyapi-mcp --name <name> --spec <path-or-url> --base-url <url> [--header "Key: Value"]...
 
 Required:
   --name       Server name (e.g. "petstore")
-  --spec       Path to OpenAPI spec file (JSON or YAML)
+  --spec       Path or URL to OpenAPI spec (JSON or YAML). HTTPS URLs are cached locally.
   --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() {
+export async function loadConfig() {
     const name = getArg("--name");
-    const spec = getArg("--spec");
+    const specUrl = getArg("--spec");
     const baseUrl = getArg("--base-url");
-    if (!name || !spec || !baseUrl) {
+    if (!name || !specUrl || !baseUrl) {
         console.error(USAGE);
         process.exit(1);
     }
+    const spec = await loadSpec(interpolateEnv(specUrl));
     const headers = {};
     for (const raw of getAllArgs("--header")) {
         const colonIdx = raw.indexOf(":");
@@ -56,7 +86,7 @@ export function loadConfig() {
     const logPath = getArg("--log");
     return {
         name,
-        spec: resolve(spec),
+        spec,
         baseUrl: interpolateEnv(baseUrl).replace(/\/+$/, ""),
         headers: Object.keys(headers).length > 0 ? headers : undefined,
         logPath: logPath ? resolve(logPath) : undefined,

package/build/graphql-schema.js

@@ -1,4 +1,5 @@
 import { GraphQLSchema, GraphQLObjectType, GraphQLInputObjectType, GraphQLScalarType, GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBoolean, GraphQLList, GraphQLNonNull, graphql as executeGraphQL, printSchema, } from "graphql";
+import { createHash } from "node:crypto";
 const DEFAULT_ARRAY_LIMIT = 50;
 const MAX_SAMPLE_SIZE = 30;
 const MAX_INFER_DEPTH = 4;
@@ -28,8 +29,8 @@ export function truncateIfArray(data, limit, offset) {
     const sliced = data.slice(off, off + lim);
     return { data: sliced, truncated: sliced.length < total, total };
 }
-function cacheKey(method, pathTemplate) {
-    return `${method}:${pathTemplate}`;
+function cacheKey(method, pathTemplate, hash) {
+    return `${method}:${pathTemplate}:${hash}`;
 }
 /**
  * Sanitize a JSON key into a valid GraphQL field name.
@@ -155,6 +156,51 @@ function mergeArraySamples(arr) {
         return null;
     return mergeSamples(objectSamples);
 }
+/**
+ * Produce a structural fingerprint string from JSON data.
+ * Captures keys + recursive type structure but NOT values.
+ * Sorted keys ensure determinism regardless of object key order.
+ * Bounded by MAX_INFER_DEPTH to match inference behavior.
+ */
+function shapeFingerprint(data, depth = 0) {
+    if (data === null || data === undefined)
+        return "n";
+    if (depth >= MAX_INFER_DEPTH)
+        return "J";
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return "[]";
+        if (hasMixedTypes(data))
+            return "[J]";
+        const mergeResult = mergeArraySamples(data);
+        if (mergeResult)
+            return `[${shapeFingerprint(mergeResult.merged, depth + 1)}]`;
+        return `[${shapeFingerprint(data[0], depth + 1)}]`;
+    }
+    if (typeof data === "object") {
+        const obj = data;
+        const keys = Object.keys(obj).sort();
+        if (keys.length === 0)
+            return "{}";
+        return `{${keys.map((k) => `${k}:${shapeFingerprint(obj[k], depth + 1)}`).join(",")}}`;
+    }
+    switch (typeof data) {
+        case "number":
+            return Number.isInteger(data) ? "i" : "f";
+        case "boolean":
+            return "b";
+        default:
+            return "s";
+    }
+}
+/**
+ * Compute a truncated SHA-256 hash of the structural fingerprint of JSON data.
+ * Returns a 12-character hex string.
+ */
+export function computeShapeHash(data) {
+    const fp = shapeFingerprint(data);
+    return createHash("sha256").update(fp).digest("hex").slice(0, 12);
+}
 /**
  * Recursively infer a GraphQL type from a JSON value.
  * For objects, creates a named GraphQLObjectType with explicit resolvers
@@ -376,15 +422,22 @@ export function buildSchemaFromData(data, method, pathTemplate, requestBodySchem
 }
 /**
  * Get a cached schema or build + cache a new one from the response data.
+ *
+ * @param cacheHash Optional hash to use as the cache key discriminator.
+ *   If provided (e.g. body hash for mutations), it is used instead of the
+ *   response shape hash for cache lookup. The shapeHash is always computed
+ *   from the response data and returned regardless.
  */
-export function getOrBuildSchema(data, method, pathTemplate, requestBodySchema) {
-    const key = cacheKey(method, pathTemplate);
+export function getOrBuildSchema(data, method, pathTemplate, requestBodySchema, cacheHash) {
+    const shapeHash = computeShapeHash(data);
+    const effectiveHash = cacheHash ?? shapeHash;
+    const key = cacheKey(method, pathTemplate, effectiveHash);
     const cached = schemaCache.get(key);
     if (cached)
-        return cached;
+        return { schema: cached, shapeHash };
     const schema = buildSchemaFromData(data, method, pathTemplate, requestBodySchema);
     schemaCache.set(key, schema);
-    return schema;
+    return { schema, shapeHash };
 }
 /**
  * Convert a GraphQL schema to SDL string for display.

package/build/index.js

@@ -7,8 +7,9 @@ import { ApiIndex } from "./api-index.js";
 import { callApi } from "./api-client.js";
 import { initLogger } from "./logger.js";
 import { generateSuggestions } from "./query-suggestions.js";
-import { getOrBuildSchema, executeQuery, schemaToSDL, truncateIfArray, } from "./graphql-schema.js";
-const config = loadConfig();
+import { getOrBuildSchema, executeQuery, schemaToSDL, truncateIfArray, computeShapeHash, } from "./graphql-schema.js";
+const WRITE_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
+const config = await loadConfig();
 initLogger(config.logPath ?? null);
 const apiIndex = new ApiIndex(config.spec);
 const server = new McpServer({
@@ -74,7 +75,7 @@ server.tool("list_api", `List available ${config.name} API endpoints. ` +
             ? "{ items { method path summary tag parameters { name in required description } } _count }"
             : "{ items { tag endpointCount } _count }";
         const effectiveQuery = query ?? defaultQuery;
-        const schema = getOrBuildSchema(data, "LIST", category ?? search ?? "_categories");
+        const { schema } = getOrBuildSchema(data, "LIST", category ?? search ?? "_categories");
         const { data: sliced, truncated, total } = truncateIfArray(data, limit ?? 20, offset);
         const queryResult = await executeQuery(schema, sliced, effectiveQuery);
         if (truncated && typeof queryResult === "object" && queryResult !== null) {
@@ -135,9 +136,12 @@ server.tool("call_api", `Inspect a ${config.name} API endpoint. Makes a real req
     try {
         const data = await callApi(config, method, path, params, body, headers, "populate");
         const endpoint = apiIndex.getEndpoint(method, path);
-        const schema = getOrBuildSchema(data, method, path, endpoint?.requestBodySchema);
+        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 };
+        const result = { graphqlSchema: sdl, shapeHash };
+        if (bodyHash)
+            result.bodyHash = bodyHash;
         if (endpoint && endpoint.parameters.length > 0) {
             result.parameters = endpoint.parameters.map((p) => ({
                 name: p.name,
@@ -233,16 +237,22 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
     try {
         const rawData = await callApi(config, method, path, params, body, headers, "consume");
         const endpoint = apiIndex.getEndpoint(method, path);
-        const schema = getOrBuildSchema(rawData, method, path, endpoint?.requestBodySchema);
+        const bodyHash = WRITE_METHODS.has(method) && body ? computeShapeHash(body) : undefined;
+        const { schema, shapeHash } = getOrBuildSchema(rawData, method, path, endpoint?.requestBodySchema, bodyHash);
         const { data, truncated, total } = truncateIfArray(rawData, limit, offset);
         const queryResult = await executeQuery(schema, data, query);
-        if (truncated && typeof queryResult === "object" && queryResult !== null) {
-            queryResult._meta = {
-                total,
-                offset: offset ?? 0,
-                limit: limit ?? 50,
-                hasMore: true,
-            };
+        if (typeof queryResult === "object" && queryResult !== null) {
+            queryResult._shapeHash = shapeHash;
+            if (bodyHash)
+                queryResult._bodyHash = bodyHash;
+            if (truncated) {
+                queryResult._meta = {
+                    total,
+                    offset: offset ?? 0,
+                    limit: limit ?? 50,
+                    hasMore: true,
+                };
+            }
         }
         return {
             content: [
@@ -380,9 +390,18 @@ server.tool("batch_query", `Fetch data from multiple ${config.name} API endpoint
         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 endpoint = apiIndex.getEndpoint(req.method, req.path);
-            const schema = getOrBuildSchema(rawData, req.method, req.path, endpoint?.requestBodySchema);
+            const bodyHash = WRITE_METHODS.has(req.method) && req.body
+                ? computeShapeHash(req.body)
+                : undefined;
+            const { schema, shapeHash } = getOrBuildSchema(rawData, req.method, req.path, endpoint?.requestBodySchema, bodyHash);
             const queryResult = await executeQuery(schema, rawData, req.query);
-            return { method: req.method, path: req.path, data: queryResult };
+            return {
+                method: req.method,
+                path: req.path,
+                data: queryResult,
+                shapeHash,
+                ...(bodyHash ? { bodyHash } : {}),
+            };
         }));
         const results = settled.map((outcome, i) => {
             if (outcome.status === "fulfilled") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyapi-mcp-server",
-  "version": "1.3.0",
+  "version": "1.5.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",
@@ -31,6 +31,7 @@
   "scripts": {
     "build": "tsc",
     "start": "node build/index.js",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "engines": {
@@ -46,6 +47,7 @@
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
   }
 }