anyapi-mcp-server 1.4.0 → 1.5.1

package/README.md

@@ -19,6 +19,7 @@ Works with services like **Datadog**, **PostHog**, **Metabase**, **Cloudflare**,
 - **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
@@ -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
@@ -260,8 +264,8 @@ OpenAPI/Postman spec
 ```
 
 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
+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-client.js

@@ -34,7 +34,7 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
     // --- URL construction ---
     const { url: interpolatedPath, remainingParams } = interpolatePath(pathTemplate, params ?? {});
     let fullUrl = `${config.baseUrl}${interpolatedPath}`;
-    if (method === "GET" && Object.keys(remainingParams).length > 0) {
+    if (Object.keys(remainingParams).length > 0) {
         const qs = new URLSearchParams();
         for (const [k, v] of Object.entries(remainingParams)) {
             if (v !== undefined && v !== null) {

package/build/api-index.js

@@ -118,19 +118,21 @@ function postmanUrlToPath(url) {
 export class ApiIndex {
     byTag = new Map();
     allEndpoints = [];
-    constructor(specContent) {
-        let parsed;
-        try {
-            parsed = JSON.parse(specContent);
-        }
-        catch {
-            parsed = yaml.load(specContent);
-        }
-        if (isPostmanCollection(parsed)) {
-            this.parsePostman(parsed);
-        }
-        else {
-            this.parseOpenApi(parsed, parsed);
+    constructor(specContents) {
+        for (const specContent of specContents) {
+            let parsed;
+            try {
+                parsed = JSON.parse(specContent);
+            }
+            catch {
+                parsed = yaml.load(specContent);
+            }
+            if (isPostmanCollection(parsed)) {
+                this.parsePostman(parsed);
+            }
+            else {
+                this.parseOpenApi(parsed, parsed);
+            }
         }
     }
     parseOpenApi(spec, rawSpec) {
@@ -251,6 +253,15 @@ export class ApiIndex {
         }
         tagList.push(endpoint);
     }
+    listAll() {
+        return this.allEndpoints.map((ep) => ({
+            method: ep.method,
+            path: ep.path,
+            summary: ep.summary,
+            tag: ep.tag,
+            parameters: ep.parameters,
+        }));
+    }
     listAllCategories() {
         const categories = [];
         for (const [tag, endpoints] of this.byTag) {
@@ -260,7 +271,9 @@ export class ApiIndex {
         return categories;
     }
     listAllByCategory(category) {
-        const endpoints = this.byTag.get(category) ?? [];
+        const lower = category.toLowerCase();
+        const key = [...this.byTag.keys()].find((k) => k.toLowerCase() === lower);
+        const endpoints = key ? this.byTag.get(key) : [];
         return endpoints.map((ep) => ({
             method: ep.method,
             path: ep.path,
@@ -270,11 +283,18 @@ export class ApiIndex {
         }));
     }
     searchAll(keyword) {
-        const lower = keyword.toLowerCase();
+        let matcher;
+        try {
+            const re = new RegExp(keyword, "i");
+            matcher = (text) => re.test(text);
+        }
+        catch {
+            const lower = keyword.toLowerCase();
+            matcher = (text) => text.toLowerCase().includes(lower);
+        }
         return this.allEndpoints
-            .filter((ep) => ep.path.toLowerCase().includes(lower) ||
-            ep.summary.toLowerCase().includes(lower) ||
-            ep.description.toLowerCase().includes(lower))
+            .filter((ep) => matcher(ep.path) ||
+            matcher(ep.summary))
             .map((ep) => ({
             method: ep.method,
             path: ep.path,

package/build/config.js

@@ -56,7 +56,7 @@ const USAGE = `Usage: anyapi-mcp --name <name> --spec <path-or-url> --base-url <
 
 Required:
   --name       Server name (e.g. "petstore")
-  --spec       Path or URL to OpenAPI spec (JSON or YAML). HTTPS URLs are cached locally.
+  --spec       Path or URL to OpenAPI spec (JSON or YAML) (repeatable for multiple specs)
   --base-url   API base URL (e.g. "https://api.example.com")
 
 Optional:
@@ -65,13 +65,13 @@ Optional:
   --log        Path to request/response log file (NDJSON format)`;
 export async function loadConfig() {
     const name = getArg("--name");
-    const specUrl = getArg("--spec");
+    const specUrls = getAllArgs("--spec");
     const baseUrl = getArg("--base-url");
-    if (!name || !specUrl || !baseUrl) {
+    if (!name || specUrls.length === 0 || !baseUrl) {
         console.error(USAGE);
         process.exit(1);
     }
-    const spec = await loadSpec(interpolateEnv(specUrl));
+    const specs = await Promise.all(specUrls.map((url) => loadSpec(interpolateEnv(url))));
     const headers = {};
     for (const raw of getAllArgs("--header")) {
         const colonIdx = raw.indexOf(":");
@@ -86,7 +86,7 @@ export async function loadConfig() {
     const logPath = getArg("--log");
     return {
         name,
-        spec,
+        specs,
         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,36 +7,34 @@ 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";
+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 apiIndex = new ApiIndex(config.specs);
 const server = new McpServer({
     name: config.name,
     version: "1.2.1",
 });
 // --- Tool 1: list_api ---
 server.tool("list_api", `List available ${config.name} API endpoints. ` +
-    "Call with no arguments to see all categories. " +
-    "Provide 'category' to list endpoints in a tag. " +
-    "Provide 'search' to search across paths and descriptions. " +
-    "The correct query format is auto-selected based on mode. " +
-    "You can optionally override with a custom 'query' parameter. " +
+    "Call with no arguments to see all endpoints. " +
+    "Provide 'category' to filter by tag. " +
+    "Provide 'search' to search across paths and summaries (supports regex). " +
     "Results are paginated with limit (default 20) and offset.", {
     category: z
         .string()
         .optional()
-        .describe("Tag/category to filter by. Omit to see all categories."),
+        .describe("Tag/category to filter by. Case-insensitive."),
     search: z
         .string()
         .optional()
-        .describe("Search keyword across endpoint paths and descriptions"),
+        .describe("Search keyword or regex pattern across endpoint paths and summaries"),
     query: z
         .string()
         .optional()
-        .describe("Optional GraphQL selection query override. If omitted, a sensible default is used automatically:\n" +
-        "Categories (no args): '{ items { tag endpointCount } _count }'\n" +
-        "Endpoints (with category/search): '{ items { method path summary tag parameters { name in required description } } _count }'"),
+        .describe("GraphQL selection query. Default: '{ items { method path summary } _count }'. " +
+        "Available fields: method, path, summary, tag, parameters { name in required description }"),
     limit: z
         .number()
         .int()
@@ -51,7 +49,6 @@ server.tool("list_api", `List available ${config.name} API endpoints. ` +
         .describe("Items to skip (default: 0)"),
 }, async ({ category, search, query, limit, offset }) => {
     try {
-        const isEndpointMode = !!(search || category);
         let data;
         if (search) {
             data = apiIndex.searchAll(search);
@@ -60,7 +57,7 @@ server.tool("list_api", `List available ${config.name} API endpoints. ` +
             data = apiIndex.listAllByCategory(category);
         }
         else {
-            data = apiIndex.listAllCategories();
+            data = apiIndex.listAll();
         }
         // Empty results — return directly to avoid GraphQL schema errors on empty arrays
         if (data.length === 0) {
@@ -70,11 +67,9 @@ server.tool("list_api", `List available ${config.name} API endpoints. ` +
                 ],
             };
         }
-        const defaultQuery = isEndpointMode
-            ? "{ items { method path summary tag parameters { name in required description } } _count }"
-            : "{ items { tag endpointCount } _count }";
+        const defaultQuery = "{ items { method path summary } _count }";
         const effectiveQuery = query ?? defaultQuery;
-        const schema = getOrBuildSchema(data, "LIST", category ?? search ?? "_categories");
+        const { schema } = getOrBuildSchema(data, "LIST", category ?? search ?? "_all");
         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 +130,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 +231,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 +384,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.4.0",
+  "version": "1.5.1",
   "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"
   }
 }