anyapi-mcp-server 1.1.1

package/build/graphql-schema.js

@@ -0,0 +1,334 @@
+import { GraphQLSchema, GraphQLObjectType, GraphQLInputObjectType, GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBoolean, GraphQLList, GraphQLNonNull, graphql as executeGraphQL, printSchema, } from "graphql";
+const DEFAULT_ARRAY_LIMIT = 50;
+const MAX_SAMPLE_SIZE = 10;
+// Schema cache keyed by "METHOD:/path/template"
+const schemaCache = new Map();
+/**
+ * If data is an array, slice it to [offset, offset+limit) and return metadata.
+ * Returns the original data unchanged if it's not an array.
+ */
+export function truncateIfArray(data, limit, offset) {
+    if (!Array.isArray(data)) {
+        return { data, truncated: false, total: null };
+    }
+    const total = data.length;
+    const off = offset ?? 0;
+    const lim = limit ?? DEFAULT_ARRAY_LIMIT;
+    const sliced = data.slice(off, off + lim);
+    return { data: sliced, truncated: sliced.length < total, total };
+}
+function cacheKey(method, pathTemplate) {
+    return `${method}:${pathTemplate}`;
+}
+/**
+ * Sanitize a JSON key into a valid GraphQL field name.
+ * Dashes, dots, spaces become underscores. Leading digits get prefixed.
+ * Leading double underscores are stripped (GraphQL reserves __ for introspection).
+ */
+function sanitizeFieldName(name) {
+    let s = name.replace(/[-. ]/g, "_");
+    if (/^[0-9]/.test(s)) {
+        s = "_" + s;
+    }
+    s = s.replace(/[^_a-zA-Z0-9]/g, "_");
+    s = s.replace(/^_+/, (match) => (match.length === 1 ? "_" : "f_"));
+    if (!s)
+        s = "f_empty";
+    return s;
+}
+/**
+ * Derive a valid GraphQL type name from method + path template.
+ * e.g. "GET:/api/card/{id}" → "GET_api_card_id"
+ */
+function deriveTypeName(method, pathTemplate) {
+    let name = `${method}_${pathTemplate}`
+        .replace(/[^a-zA-Z0-9]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_|_$/g, "");
+    if (name.startsWith("__"))
+        name = name.slice(1);
+    return name || "Unknown";
+}
+function inferScalarType(value) {
+    switch (typeof value) {
+        case "string":
+            return GraphQLString;
+        case "number":
+            return Number.isInteger(value) ? GraphQLInt : GraphQLFloat;
+        case "boolean":
+            return GraphQLBoolean;
+        default:
+            return GraphQLString;
+    }
+}
+/**
+ * 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.
+ */
+function mergeSamples(items) {
+    const merged = {};
+    for (const item of items) {
+        for (const [key, value] of Object.entries(item)) {
+            if (!(key in merged) || merged[key] === null || merged[key] === undefined) {
+                merged[key] = value;
+            }
+            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;
+                }
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Sample and merge multiple array elements for richer type inference.
+ */
+function mergeArraySamples(arr) {
+    const sampleSize = Math.min(arr.length, MAX_SAMPLE_SIZE);
+    const objectSamples = arr
+        .slice(0, sampleSize)
+        .filter((s) => typeof s === "object" && s !== null && !Array.isArray(s));
+    if (objectSamples.length === 0)
+        return null;
+    return mergeSamples(objectSamples);
+}
+/**
+ * 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.
+ */
+function inferType(value, typeName, typeRegistry) {
+    if (value === null || value === undefined) {
+        return GraphQLString;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return new GraphQLList(GraphQLString);
+        }
+        // Sample multiple elements for richer type inference
+        const merged = mergeArraySamples(value);
+        if (merged) {
+            const elementType = inferType(merged, `${typeName}_Item`, typeRegistry);
+            return new GraphQLList(elementType);
+        }
+        const elementType = inferType(value[0], `${typeName}_Item`, typeRegistry);
+        return new GraphQLList(elementType);
+    }
+    if (typeof value === "object") {
+        const existing = typeRegistry.get(typeName);
+        if (existing)
+            return existing;
+        const obj = value;
+        const entries = Object.entries(obj);
+        if (entries.length === 0) {
+            const emptyType = new GraphQLObjectType({
+                name: typeName,
+                fields: { _empty: { type: GraphQLString, resolve: () => null } },
+            });
+            typeRegistry.set(typeName, emptyType);
+            return emptyType;
+        }
+        // Reserve the name before recursing to handle circular structures
+        const placeholder = new GraphQLObjectType({
+            name: typeName,
+            fields: {},
+        });
+        typeRegistry.set(typeName, placeholder);
+        const usedNames = new Set();
+        const fieldConfigs = {};
+        for (const [originalKey, fieldValue] of entries) {
+            let sanitized = sanitizeFieldName(originalKey);
+            if (usedNames.has(sanitized)) {
+                let counter = 2;
+                while (usedNames.has(`${sanitized}_${counter}`))
+                    counter++;
+                sanitized = `${sanitized}_${counter}`;
+            }
+            usedNames.add(sanitized);
+            const childTypeName = `${typeName}_${sanitized}`;
+            const fieldType = inferType(fieldValue, childTypeName, typeRegistry);
+            const key = originalKey;
+            fieldConfigs[sanitized] = {
+                type: fieldType,
+                resolve: (source) => source[key],
+            };
+        }
+        const realType = new GraphQLObjectType({
+            name: typeName,
+            fields: () => fieldConfigs,
+        });
+        typeRegistry.set(typeName, realType);
+        return realType;
+    }
+    return inferScalarType(value);
+}
+/**
+ * Map OpenAPI type strings to GraphQL input types.
+ */
+function mapOpenApiTypeToGraphQLInput(type) {
+    switch (type) {
+        case "string":
+            return GraphQLString;
+        case "integer":
+            return GraphQLInt;
+        case "number":
+            return GraphQLFloat;
+        case "boolean":
+            return GraphQLBoolean;
+        default:
+            return GraphQLString;
+    }
+}
+const WRITE_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
+/**
+ * Build a GraphQL schema from an arbitrary JSON response.
+ *
+ * - Object responses: fields promoted to root Query (query as `{ id name ... }`)
+ * - Array responses: wrapped as `{ items [...], _count }` (query as `{ items { id name } _count }`)
+ * - Scalar responses: wrapped as `{ value }`
+ * - Write operations with requestBodySchema: adds a Mutation type
+ */
+export function buildSchemaFromData(data, method, pathTemplate, requestBodySchema) {
+    const baseName = deriveTypeName(method, pathTemplate);
+    const typeRegistry = new Map();
+    let queryType;
+    // Array response
+    if (Array.isArray(data)) {
+        let itemType = GraphQLString;
+        if (data.length > 0) {
+            const merged = mergeArraySamples(data);
+            if (merged) {
+                itemType = inferType(merged, `${baseName}_Item`, typeRegistry);
+            }
+            else {
+                itemType = inferScalarType(data[0]);
+            }
+        }
+        queryType = new GraphQLObjectType({
+            name: "Query",
+            fields: {
+                items: {
+                    type: new GraphQLList(itemType),
+                    resolve: (source) => source,
+                },
+                _count: {
+                    type: GraphQLInt,
+                    resolve: (source) => source.length,
+                },
+            },
+        });
+    }
+    else if (typeof data === "object" && data !== null) {
+        // Object response
+        const responseType = inferType(data, baseName, typeRegistry);
+        queryType = new GraphQLObjectType({
+            name: "Query",
+            fields: () => {
+                const originalFields = responseType.getFields();
+                const queryFields = {};
+                for (const [fieldName, fieldDef] of Object.entries(originalFields)) {
+                    queryFields[fieldName] = {
+                        type: fieldDef.type,
+                        resolve: fieldDef.resolve,
+                    };
+                }
+                return queryFields;
+            },
+        });
+    }
+    else {
+        // Scalar response
+        queryType = new GraphQLObjectType({
+            name: "Query",
+            fields: {
+                value: {
+                    type: GraphQLString,
+                    resolve: (source) => String(source),
+                },
+            },
+        });
+    }
+    // Build mutation type for write operations with a request body schema
+    if (WRITE_METHODS.has(method) && requestBodySchema) {
+        const mutationName = `${method.toLowerCase()}_${baseName}`;
+        const inputFields = {};
+        for (const [propName, propDef] of Object.entries(requestBodySchema.properties)) {
+            const sanitized = sanitizeFieldName(propName);
+            let type = mapOpenApiTypeToGraphQLInput(propDef.type);
+            if (propDef.required) {
+                type = new GraphQLNonNull(type);
+            }
+            inputFields[sanitized] = {
+                type,
+                ...(propDef.description ? { description: propDef.description } : {}),
+            };
+        }
+        const hasInputFields = Object.keys(inputFields).length > 0;
+        const inputType = hasInputFields
+            ? new GraphQLInputObjectType({
+                name: `${baseName}_Input`,
+                fields: inputFields,
+            })
+            : null;
+        const mutationType = new GraphQLObjectType({
+            name: "Mutation",
+            fields: {
+                [mutationName]: {
+                    type: queryType,
+                    args: inputType ? { input: { type: inputType } } : {},
+                    resolve: (source) => source,
+                },
+            },
+        });
+        return new GraphQLSchema({ query: queryType, mutation: mutationType });
+    }
+    return new GraphQLSchema({ query: queryType });
+}
+/**
+ * Get a cached schema or build + cache a new one from the response data.
+ */
+export function getOrBuildSchema(data, method, pathTemplate, requestBodySchema) {
+    const key = cacheKey(method, pathTemplate);
+    const cached = schemaCache.get(key);
+    if (cached)
+        return cached;
+    const schema = buildSchemaFromData(data, method, pathTemplate, requestBodySchema);
+    schemaCache.set(key, schema);
+    return schema;
+}
+/**
+ * Convert a GraphQL schema to SDL string for display.
+ */
+export function schemaToSDL(schema) {
+    return printSchema(schema);
+}
+/**
+ * Execute a GraphQL selection query against JSON data using a schema.
+ * The query should be a selection set like `{ id name collection { id } }`.
+ * Also supports mutation syntax: `mutation { ... }`.
+ */
+export async function executeQuery(schema, data, query) {
+    const trimmed = query.trim();
+    const fullQuery = trimmed.startsWith("query") || trimmed.startsWith("mutation") || trimmed.startsWith("{")
+        ? trimmed
+        : `{ ${trimmed} }`;
+    const result = await executeGraphQL({
+        schema,
+        source: fullQuery,
+        rootValue: data,
+    });
+    if (result.errors && result.errors.length > 0) {
+        const messages = result.errors.map((e) => e.message).join("; ");
+        throw new Error(`GraphQL query error: ${messages}`);
+    }
+    return result.data;
+}

package/build/index.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "./config.js";
+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();
+initLogger(config.logPath ?? null);
+const apiIndex = new ApiIndex(config.spec);
+const server = new McpServer({
+    name: config.name,
+    version: "1.1.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. " +
+    "Results are paginated with limit (default 20) and offset.", {
+    category: z
+        .string()
+        .optional()
+        .describe("Tag/category to filter by. Omit to see all categories."),
+    search: z
+        .string()
+        .optional()
+        .describe("Search keyword across endpoint paths and descriptions"),
+    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 }'"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Max items to return (default: 20)"),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .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);
+        }
+        else if (category) {
+            data = apiIndex.listAllByCategory(category);
+        }
+        else {
+            data = apiIndex.listAllCategories();
+        }
+        const defaultQuery = isEndpointMode
+            ? "{ 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 { data: sliced, truncated, total } = truncateIfArray(data, limit ?? 20, offset);
+        const queryResult = await executeQuery(schema, sliced, effectiveQuery);
+        if (truncated && typeof queryResult === "object" && queryResult !== null) {
+            queryResult._meta = {
+                total,
+                offset: offset ?? 0,
+                limit: limit ?? 20,
+                hasMore: true,
+            };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(queryResult, null, 2) },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ error: message }) },
+            ],
+            isError: true,
+        };
+    }
+});
+// --- Tool 2: call_api ---
+server.tool("call_api", `Inspect a ${config.name} API endpoint. Makes a real request and returns ONLY the ` +
+    "inferred GraphQL schema (SDL) showing all available fields and their types. " +
+    "No response data is returned — use query_api to fetch actual data. " +
+    "IMPORTANT: Read the returned schema carefully. The root field names in the schema " +
+    "are what you must use in query_api — do NOT assume generic names like 'items'. " +
+    "For example, if the schema shows 'products: [Product]', query as '{ products { id name } }', not '{ items { id name } }'. " +
+    "Also returns accepted parameters (name, location, required) from the API spec, " +
+    "and suggestedQueries with ready-to-use GraphQL queries. " +
+    "Use list_api first to discover endpoints.", {
+    method: z
+        .enum(["GET", "POST", "PUT", "DELETE", "PATCH"])
+        .describe("HTTP method"),
+    path: z
+        .string()
+        .describe("API path template (e.g. '/api/card/{id}'). Use list_api to discover paths."),
+    params: z
+        .record(z.unknown())
+        .optional()
+        .describe("Path and query parameters as key-value pairs. " +
+        "Path params like {id} are interpolated; remaining become query string for GET."),
+    body: z
+        .record(z.unknown())
+        .optional()
+        .describe("Request body for POST/PUT/PATCH"),
+    headers: z
+        .record(z.string())
+        .optional()
+        .describe("Additional HTTP headers for this request (e.g. { \"Authorization\": \"Bearer <token>\" }). " +
+        "Overrides default --header values."),
+}, async ({ method, path, params, body, headers }) => {
+    try {
+        const data = await callApi(config, method, path, params, body, headers);
+        const endpoint = apiIndex.getEndpoint(method, path);
+        const schema = getOrBuildSchema(data, method, path, endpoint?.requestBodySchema);
+        const sdl = schemaToSDL(schema);
+        const result = { graphqlSchema: sdl };
+        if (endpoint && endpoint.parameters.length > 0) {
+            result.parameters = endpoint.parameters.map((p) => ({
+                name: p.name,
+                in: p.in,
+                required: p.required,
+                ...(p.description ? { description: p.description } : {}),
+            }));
+        }
+        // Smart query suggestions
+        const suggestions = generateSuggestions(schema);
+        if (suggestions.length > 0) {
+            result.suggestedQueries = suggestions;
+        }
+        if (Array.isArray(data)) {
+            result.totalItems = data.length;
+            result.hint =
+                "Use query_api with field names from the schema above. " +
+                    "For raw arrays: '{ items { ... } _count }'. " +
+                    "For paginated APIs, pass limit/offset inside params (as query string parameters to the API), " +
+                    "NOT as top-level tool parameters.";
+        }
+        else {
+            result.hint =
+                "Use query_api with the exact root field names from the schema above (e.g. if schema shows " +
+                    "'products: [Product]', query as '{ products { id name } }' — do NOT use '{ items { ... } }'). " +
+                    "For paginated APIs, pass limit/offset inside params (as query string parameters to the API), " +
+                    "NOT as top-level tool parameters.";
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ error: message }) },
+            ],
+            isError: true,
+        };
+    }
+});
+// --- Tool 3: query_api ---
+server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returning only the fields you select via GraphQL. ` +
+    "IMPORTANT: Always run call_api first to discover the actual schema field names. " +
+    "Use the exact root field names from the schema — do NOT assume generic names.\n" +
+    "- Raw array response ([...]): '{ items { id name } _count }'\n" +
+    "- Object response ({products: [...]}): '{ products { id name } }' (use actual field names from schema)\n" +
+    "- Write operations with mutation schema: 'mutation { post_endpoint(input: { ... }) { id name } }'\n" +
+    "Field names with dashes are converted to underscores (e.g. created-at → created_at). " +
+    "PAGINATION: To paginate the API itself, pass limit/offset inside 'params' (they become query string parameters). " +
+    "The top-level limit/offset parameters only slice the already-fetched response locally.", {
+    method: z
+        .enum(["GET", "POST", "PUT", "DELETE", "PATCH"])
+        .describe("HTTP method"),
+    path: z
+        .string()
+        .describe("API path template (e.g. '/api/card/{id}')"),
+    params: z
+        .record(z.unknown())
+        .optional()
+        .describe("Path and query parameters. Path params like {id} are interpolated; " +
+        "remaining become query string for GET. " +
+        "For API pagination, pass limit/offset here (e.g. { limit: 20, offset: 40 })."),
+    body: z
+        .record(z.unknown())
+        .optional()
+        .describe("Request body for POST/PUT/PATCH"),
+    query: z
+        .string()
+        .describe("GraphQL selection query using field names from call_api schema " +
+        "(e.g. '{ products { id name } }' — NOT '{ items { ... } }' unless the API returns a raw array)"),
+    headers: z
+        .record(z.string())
+        .optional()
+        .describe("Additional HTTP headers for this request (e.g. { \"Authorization\": \"Bearer <token>\" }). " +
+        "Overrides default --header values."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Client-side slice: max items from already-fetched response (default: 50). For API pagination, use params instead."),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Client-side slice: items to skip in already-fetched response (default: 0). For API pagination, use params instead."),
+}, async ({ method, path, params, body, query, headers, limit, offset }) => {
+    try {
+        const rawData = await callApi(config, method, path, params, body, headers);
+        const endpoint = apiIndex.getEndpoint(method, path);
+        const schema = getOrBuildSchema(rawData, method, path, endpoint?.requestBodySchema);
+        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,
+            };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(queryResult, null, 2) },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ error: message }) },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${config.name} MCP Server running on stdio`);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/build/logger.js

@@ -0,0 +1,51 @@
+import { appendFile } from "node:fs/promises";
+const SENSITIVE_HEADERS = new Set([
+    "authorization",
+    "x-api-key",
+    "cookie",
+    "set-cookie",
+    "proxy-authorization",
+]);
+const MAX_BODY_LOG_LENGTH = 10_000;
+let logFilePath = null;
+export function initLogger(path) {
+    logFilePath = path;
+}
+export function isLoggingEnabled() {
+    return logFilePath !== null;
+}
+function maskHeaders(headers) {
+    const masked = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (SENSITIVE_HEADERS.has(key.toLowerCase())) {
+            masked[key] = value.length > 4 ? value.slice(0, 4) + "****" : "****";
+        }
+        else {
+            masked[key] = value;
+        }
+    }
+    return masked;
+}
+function truncateBody(body) {
+    const str = typeof body === "string" ? body : JSON.stringify(body);
+    if (str && str.length > MAX_BODY_LOG_LENGTH) {
+        return str.slice(0, MAX_BODY_LOG_LENGTH) + `... [truncated, ${str.length} total chars]`;
+    }
+    return body;
+}
+export async function logEntry(entry) {
+    if (!logFilePath)
+        return;
+    try {
+        const sanitized = {
+            ...entry,
+            requestHeaders: maskHeaders(entry.requestHeaders),
+            responseBody: truncateBody(entry.responseBody),
+        };
+        const line = JSON.stringify(sanitized) + "\n";
+        await appendFile(logFilePath, line, "utf-8");
+    }
+    catch {
+        // Logging failure should never crash the server
+    }
+}