anyapi-mcp-server 1.2.1 → 1.4.0

package/README.md

@@ -1,12 +1,19 @@
 # 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
@@ -35,16 +42,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 +67,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 +90,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}"
       ],
@@ -259,7 +259,7 @@ 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
+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
 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

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,6 +1,17 @@
-import { GraphQLSchema, GraphQLObjectType, GraphQLInputObjectType, GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBoolean, GraphQLList, GraphQLNonNull, graphql as executeGraphQL, printSchema, } from "graphql";
+import { GraphQLSchema, GraphQLObjectType, GraphQLInputObjectType, GraphQLScalarType, GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBoolean, GraphQLList, GraphQLNonNull, graphql as executeGraphQL, printSchema, } from "graphql";
 const DEFAULT_ARRAY_LIMIT = 50;
-const MAX_SAMPLE_SIZE = 10;
+const MAX_SAMPLE_SIZE = 30;
+const MAX_INFER_DEPTH = 4;
+/**
+ * Custom scalar that passes arbitrary JSON values through as-is.
+ * Used for mixed-type arrays, type-conflicting fields, and deeply nested structures.
+ */
+const GraphQLJSON = new GraphQLScalarType({
+    name: "JSON",
+    description: "Arbitrary JSON value (mixed types, deep nesting, or heterogeneous structures)",
+    serialize: (value) => value,
+    parseValue: (value) => value,
+});
 // Schema cache keyed by "METHOD:/path/template"
 const schemaCache = new Map();
 /**
@@ -49,6 +60,30 @@ function deriveTypeName(method, pathTemplate) {
         name = name.slice(1);
     return name || "Unknown";
 }
+/**
+ * Return the base type category of a value for mixed-type detection.
+ */
+function baseTypeOf(value) {
+    if (value === null || value === undefined)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value; // "string" | "number" | "boolean" | "object"
+}
+/**
+ * Check if an array has mixed base types (e.g. string + number, or scalar + object).
+ * Returns true if the array should be treated as JSON scalar.
+ */
+function hasMixedTypes(arr) {
+    const types = new Set();
+    const sampleSize = Math.min(arr.length, MAX_SAMPLE_SIZE);
+    for (let i = 0; i < sampleSize; i++) {
+        const t = baseTypeOf(arr[i]);
+        if (t !== "null")
+            types.add(t);
+    }
+    return types.size > 1;
+}
 function inferScalarType(value) {
     switch (typeof value) {
         case "string":
@@ -65,32 +100,51 @@ function inferScalarType(value) {
  * Merge multiple sample objects into a single "super-object" that contains
  * every key seen across all samples. First non-null value wins for each key.
  * Nested objects are merged recursively.
+ * Tracks fields where different samples have conflicting base types.
  */
 function mergeSamples(items) {
     const merged = {};
+    const conflicts = new Set();
+    const seenTypes = new Map(); // key → first base type
     for (const item of items) {
         for (const [key, value] of Object.entries(item)) {
+            if (value === null || value === undefined)
+                continue;
+            const valueType = baseTypeOf(value);
             if (!(key in merged) || merged[key] === null || merged[key] === undefined) {
                 merged[key] = value;
+                if (!seenTypes.has(key))
+                    seenTypes.set(key, valueType);
             }
-            else if (typeof value === "object" && value !== null && !Array.isArray(value) &&
-                typeof merged[key] === "object" && merged[key] !== null && !Array.isArray(merged[key])) {
-                merged[key] = mergeSamples([
-                    merged[key],
-                    value,
-                ]);
-            }
-            else if (Array.isArray(value) && Array.isArray(merged[key])) {
-                if (merged[key].length === 0 && value.length > 0) {
-                    merged[key] = value;
+            else {
+                const prevType = seenTypes.get(key);
+                if (prevType && prevType !== valueType) {
+                    conflicts.add(key);
+                }
+                if (!conflicts.has(key) &&
+                    typeof value === "object" && value !== null && !Array.isArray(value) &&
+                    typeof merged[key] === "object" && merged[key] !== null && !Array.isArray(merged[key])) {
+                    const sub = mergeSamples([
+                        merged[key],
+                        value,
+                    ]);
+                    merged[key] = sub.merged;
+                    for (const c of sub.conflicts)
+                        conflicts.add(`${key}.${c}`);
+                }
+                else if (Array.isArray(value) && Array.isArray(merged[key])) {
+                    if (merged[key].length === 0 && value.length > 0) {
+                        merged[key] = value;
+                    }
                 }
             }
         }
     }
-    return merged;
+    return { merged, conflicts };
 }
 /**
  * Sample and merge multiple array elements for richer type inference.
+ * Returns the merged object + conflict set, or null if no objects found.
  */
 function mergeArraySamples(arr) {
     const sampleSize = Math.min(arr.length, MAX_SAMPLE_SIZE);
@@ -105,22 +159,35 @@ function mergeArraySamples(arr) {
  * Recursively infer a GraphQL type from a JSON value.
  * For objects, creates a named GraphQLObjectType with explicit resolvers
  * that map sanitized field names back to original JSON keys.
+ *
+ * Falls back to GraphQLJSON for:
+ * - Arrays with mixed element types (string + number + object)
+ * - Fields with conflicting types across samples
+ * - Values nested deeper than MAX_INFER_DEPTH
  */
-function inferType(value, typeName, typeRegistry) {
+function inferType(value, typeName, typeRegistry, conflicts, depth = 0) {
     if (value === null || value === undefined) {
         return GraphQLString;
     }
+    // Beyond max depth, treat as opaque JSON
+    if (depth >= MAX_INFER_DEPTH) {
+        return GraphQLJSON;
+    }
     if (Array.isArray(value)) {
         if (value.length === 0) {
             return new GraphQLList(GraphQLString);
         }
+        // Mixed-type arrays → JSON scalar (e.g. ["field", 4296, { "temporal-unit": "day" }])
+        if (hasMixedTypes(value)) {
+            return GraphQLJSON;
+        }
         // Sample multiple elements for richer type inference
-        const merged = mergeArraySamples(value);
-        if (merged) {
-            const elementType = inferType(merged, `${typeName}_Item`, typeRegistry);
+        const mergeResult = mergeArraySamples(value);
+        if (mergeResult) {
+            const elementType = inferType(mergeResult.merged, `${typeName}_Item`, typeRegistry, mergeResult.conflicts, depth + 1);
             return new GraphQLList(elementType);
         }
-        const elementType = inferType(value[0], `${typeName}_Item`, typeRegistry);
+        const elementType = inferType(value[0], `${typeName}_Item`, typeRegistry, conflicts, depth + 1);
         return new GraphQLList(elementType);
     }
     if (typeof value === "object") {
@@ -154,9 +221,17 @@ function inferType(value, typeName, typeRegistry) {
                 sanitized = `${sanitized}_${counter}`;
             }
             usedNames.add(sanitized);
-            const childTypeName = `${typeName}_${sanitized}`;
-            const fieldType = inferType(fieldValue, childTypeName, typeRegistry);
             const key = originalKey;
+            // Use JSON scalar for fields with type conflicts across samples
+            if (conflicts?.has(originalKey)) {
+                fieldConfigs[sanitized] = {
+                    type: GraphQLJSON,
+                    resolve: (source) => source[key],
+                };
+                continue;
+            }
+            const childTypeName = `${typeName}_${sanitized}`;
+            const fieldType = inferType(fieldValue, childTypeName, typeRegistry, conflicts, depth + 1);
             fieldConfigs[sanitized] = {
                 type: fieldType,
                 resolve: (source) => source[key],
@@ -205,12 +280,18 @@ export function buildSchemaFromData(data, method, pathTemplate, requestBodySchem
     if (Array.isArray(data)) {
         let itemType = GraphQLString;
         if (data.length > 0) {
-            const merged = mergeArraySamples(data);
-            if (merged) {
-                itemType = inferType(merged, `${baseName}_Item`, typeRegistry);
+            // Mixed-type top-level array → items are JSON scalars
+            if (hasMixedTypes(data)) {
+                itemType = GraphQLJSON;
             }
             else {
-                itemType = inferScalarType(data[0]);
+                const mergeResult = mergeArraySamples(data);
+                if (mergeResult) {
+                    itemType = inferType(mergeResult.merged, `${baseName}_Item`, typeRegistry, mergeResult.conflicts, 0);
+                }
+                else {
+                    itemType = inferScalarType(data[0]);
+                }
             }
         }
         queryType = new GraphQLObjectType({

package/build/index.js

@@ -8,7 +8,7 @@ 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();
+const config = await loadConfig();
 initLogger(config.logPath ?? null);
 const apiIndex = new ApiIndex(config.spec);
 const server = new McpServer({
@@ -62,6 +62,14 @@ server.tool("list_api", `List available ${config.name} API endpoints. ` +
         else {
             data = apiIndex.listAllCategories();
         }
+        // Empty results — return directly to avoid GraphQL schema errors on empty arrays
+        if (data.length === 0) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ items: [], _count: 0 }, null, 2) },
+                ],
+            };
+        }
         const defaultQuery = isEndpointMode
             ? "{ items { method path summary tag parameters { name in required description } } _count }"
             : "{ items { tag endpointCount } _count }";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyapi-mcp-server",
-  "version": "1.2.1",
+  "version": "1.4.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",