anyapi-mcp-server 1.4.0 → 1.5.0

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/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,7 +7,8 @@ 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);
@@ -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.4.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"
   }
 }