anyapi-mcp-server 1.2.0 → 1.3.0

package/README.md

@@ -16,7 +16,9 @@ Instead of building a custom MCP server for every API, `anyapi-mcp-server` reads
 - **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
+- **Spec documentation lookup** — `explain_api` returns rich endpoint docs (parameters, response codes, deprecation, request body schema) without making HTTP requests
+- **Concurrent batch queries** — `batch_query` fetches data from up to 10 endpoints in parallel, returning all results in one tool call
+- **Per-request headers** — override default headers on individual `call_api`/`query_api`/`batch_query` calls
 - **Environment variable interpolation** — use `${ENV_VAR}` in base URLs and headers
 - **Request logging** — optional NDJSON request/response log with sensitive header masking
 
@@ -126,7 +128,7 @@ Add to your MCP configuration (e.g. `~/.cursor/mcp.json` or Claude Desktop confi
 
 ## Tools
 
-The server exposes three MCP tools:
+The server exposes five MCP tools:
 
 ### `list_api`
 
@@ -206,11 +208,33 @@ Fetch data from an API endpoint, returning only the fields you select via GraphQ
 - For API-level pagination, pass limit/offset inside `params` instead
 - Accepts optional `headers` to override defaults for this request
 
+### `explain_api`
+
+Get detailed documentation for an endpoint directly from the spec — no HTTP request is made.
+
+- Returns summary, description, operationId, deprecation status, tag
+- Lists all parameters with name, location (`path`/`query`/`header`), required flag, and description
+- Shows request body schema with property types, required fields, and descriptions
+- Lists response status codes with descriptions (e.g. `200 OK`, `404 Not Found`)
+- Includes external docs link when available
+
+### `batch_query`
+
+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
+- Run `call_api` first on each endpoint to discover the schema field names
+
 ## 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
+2. **Understand** an endpoint with `explain_api` to see its parameters, request body, and response codes
+3. **Inspect** a specific endpoint with `call_api` to see the inferred response schema and suggested queries
+4. **Query** the endpoint with `query_api` to fetch exactly the fields you need
+5. **Batch** multiple queries with `batch_query` when you need data from several endpoints at once
 
 ## How It Works
 
@@ -218,20 +242,21 @@ Fetch data from an API endpoint, returning only the fields you select via GraphQ
 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
+   ┌─────────┐  ┌─────────────┐  ┌──────────┐  ┌───────────┐  ┌─────────────┐
+   │list_api │  │ explain_api │  │ call_api │  │ query_api │  │ batch_query │
+   │(browse) │  │   (docs)    │  │ (schema) │  │  (data)   │  │ (parallel)  │
+   └─────────┘  └─────────────┘  └──────────┘  └───────────┘  └─────────────┘
+        │          │ no HTTP          │               │             │
+        ▼          ▼ request          ▼               ▼             ▼
+   Spec index   Spec index     REST API call    REST API call  N concurrent
+   (tags,       (params,       (with retry      (cached if     REST API calls
+    paths)       responses,     + caching)       same as        + GraphQL
+                 body schema)       │            call_api)      execution
+                                    ▼               │
+                               Infer GraphQL        ▼
+                               schema from     Execute GraphQL
+                               JSON response   query against
+                                               response data
 ```
 
 1. The spec file is parsed at startup into an endpoint index with tags, paths, parameters, and request body schemas

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

@@ -13,7 +13,7 @@ initLogger(config.logPath ?? null);
 const apiIndex = new ApiIndex(config.spec);
 const server = new McpServer({
     name: config.name,
-    version: "1.2.0",
+    version: "1.2.1",
 });
 // --- Tool 1: list_api ---
 server.tool("list_api", `List available ${config.name} API endpoints. ` +
@@ -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.0",
+  "version": "1.3.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",