mcp-from-openapi 2.5.1 → 2.6.1

package/README.md

@@ -6,6 +6,7 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/license/apache-2-0)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
+[![CodeQL](https://github.com/agentfront/mcp-from-openapi/actions/workflows/codeql.yml/badge.svg)](https://github.com/agentfront/mcp-from-openapi/actions/workflows/codeql.yml)
 
 ## What This Solves
 
@@ -18,14 +19,14 @@ paths:
   /users/{id}:
     post:
       parameters:
-        - name: id        # path
+        - name: id # path
           in: path
       requestBody:
         content:
           application/json:
             schema:
               properties:
-                id:        # body -- CONFLICT!
+                id: # body -- CONFLICT!
                   type: string
 ```
 
@@ -50,14 +51,20 @@ Now you know exactly how to build the HTTP request.
 
 ## Features
 
-- **Smart Parameter Handling** -- Automatic conflict detection and resolution across path, query, header, cookie, and body
-- **Complete Schemas** -- Input schema combines all parameters; output schema from responses (with oneOf unions)
-- **Security Resolution** -- Framework-agnostic auth for Bearer, Basic, Digest, API Key, OAuth2, OpenID, mTLS, HMAC, AWS Sig V4
-- **SSRF Prevention** -- Blocks internal IPs, localhost, and cloud metadata endpoints by default during `$ref` resolution
+- **Built-in Request Builder** -- `buildHttpRequest()` applies the full OpenAPI serialization table (form/deepObject/pipeDelimited queries, label/matrix paths, multipart, binary, `wholeBody`) so you never hand-write request assembly
+- **Client Compatibility Targets** -- `target: 'claude' | 'openai' | 'gemini' | 'strict'` emits schemas each client actually accepts (inlined refs, closed objects, collapsed unions, demoted formats)
+- **Context-Budget Reports** -- `analyzeToolSet()` estimates the token bill per tool and warns at the thresholds where agent accuracy degrades
+- **Overlays & Lint** -- apply [OpenAPI Overlay](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/curation.md) curation files at load time; `lint()` flags the spec gaps that hurt tool-calling accuracy
+- **Curation-Grade Filtering** -- Filter by tag, method, path glob (`/admin/**`), operationId, a `readOnlyOnly` safety switch, and `x-mcp` extension flags with root < path < operation precedence
+- **Smart Parameter Handling** -- Automatic conflict detection and resolution across path, query, header, cookie, and body; `allOf` bodies flatten, union and binary bodies map cleanly (`wholeBody`, `binary` markers)
+- **Complete Schemas** -- Input schema combines all parameters; output schema from responses (with oneOf unions); clean JSON Schema 2020-12 output (`nullable` unions, normalized `examples`)
+- **MCP-Native Tools** -- `title` and tool `annotations` (readOnly/destructive/idempotent hints) inferred from HTTP semantics, overridable via the `x-mcp` extension family; spec-compliant tool names (64-char cap, stable hash truncation, collision dedup); deterministic tool ordering for prompt-cache friendliness; `toSdkTool()` for one-line SDK registration
+- **Security Resolution** -- Framework-agnostic auth for Bearer, Basic, Digest, API Key, OAuth2, OpenID, mTLS, HMAC, AWS Sig V4; per-scheme `includeSecurityInInput`
+- **SSRF Prevention** -- Blocks internal IPs, localhost, and cloud metadata endpoints by default during `$ref` resolution; one-flag `secureDefaults` posture for untrusted specs
 - **Multiple Input Sources** -- Load from URL, file, YAML string, or JSON object
 - **Rich Metadata** -- Authentication, servers, tags, deprecation, external docs, `x-frontmcp` extension
-- **Production Ready** -- Full TypeScript support, validation, structured errors, 80%+ test coverage
-- **MCP Native** -- Designed specifically for Model Context Protocol integration
+- **Production Ready** -- Full TypeScript support, validation, structured errors, 100% test coverage (enforced)
+- **Runtime Agnostic** -- Works on Node and V8 isolates (Cloudflare Workers) alike
 
 ## Installation
 
@@ -72,86 +79,89 @@ pnpm add mcp-from-openapi
 ## Quick Start
 
 ```typescript
-import { OpenAPIToolGenerator } from 'mcp-from-openapi';
+import { OpenAPIToolGenerator } from "mcp-from-openapi";
 
 // Load an OpenAPI spec
-const generator = await OpenAPIToolGenerator.fromURL('https://api.example.com/openapi.json');
+const generator = await OpenAPIToolGenerator.fromURL(
+  "https://api.example.com/openapi.json",
+);
 
 // Generate MCP tools
 const tools = await generator.generateTools();
 
 // Each tool has everything you need
 tools.forEach((tool) => {
-  console.log(tool.name);          // "createUser"
-  console.log(tool.inputSchema);   // Combined schema for all params
-  console.log(tool.outputSchema);  // Response schema
-  console.log(tool.mapper);        // How to build the HTTP request
-  console.log(tool.metadata);      // Auth, servers, tags, etc.
+  console.log(tool.name); // "createUser"
+  console.log(tool.title); // "Create a user" (from summary/extensions)
+  console.log(tool.annotations); // { readOnlyHint: false, destructiveHint: true, ... }
+  console.log(tool.inputSchema); // Combined schema for all params
+  console.log(tool.outputSchema); // Response schema
+  console.log(tool.mapper); // How to build the HTTP request
+  console.log(tool.metadata); // Auth, servers, tags, etc.
 });
 ```
 
-## Using the Mapper
+## Building Requests
 
-The mapper tells you how to convert tool inputs into an HTTP request:
+`buildHttpRequest()` turns a tool plus input values into a ready-to-send request — style/explode serialization, deepObject queries, multipart, binary, and `wholeBody` handled correctly:
 
 ```typescript
-function buildRequest(tool: McpOpenAPITool, input: Record<string, any>) {
-  let path = tool.metadata.path;
-  const query = new URLSearchParams();
-  const headers: Record<string, string> = {};
-  let body: Record<string, any> | undefined;
-
-  for (const m of tool.mapper) {
-    const value = input[m.inputKey];
-    if (value === undefined) continue;
-
-    switch (m.type) {
-      case 'path':
-        path = path.replace(`{${m.key}}`, encodeURIComponent(value));
-        break;
-      case 'query':
-        query.set(m.key, String(value));
-        break;
-      case 'header':
-        headers[m.key] = String(value);
-        break;
-      case 'body':
-        if (!body) body = {};
-        body[m.key] = value;
-        break;
-    }
-  }
+import { buildHttpRequest } from "mcp-from-openapi";
+
+const request = buildHttpRequest(tool, { id: "42", filter: { tag: "news" } });
+// { url: 'https://api.example.com/users/42?filter[tag]=news',
+//   method: 'GET', headers: {...}, body: undefined, ... }
+
+await fetch(request.url, {
+  method: request.method,
+  headers: request.headers,
+  body: request.body as BodyInit,
+});
+```
 
-  const baseUrl = tool.metadata.servers?.[0]?.url ?? '';
-  const qs = query.toString();
+The `mapper` array stays public for anyone who needs custom request assembly — see [Request Builder](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/request-builder.md) and [Parameter Conflicts](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/parameter-conflicts.md) for its contract.
 
-  return {
-    url: `${baseUrl}${path}${qs ? '?' + qs : ''}`,
-    method: tool.metadata.method.toUpperCase(),
-    headers,
-    body: body ? JSON.stringify(body) : undefined,
-  };
+## Serving with the Official MCP SDK
+
+```typescript
+import { toSdkTool, buildHttpRequest } from "mcp-from-openapi";
+import { fromJsonSchema } from "@modelcontextprotocol/server"; // SDK v2
+
+for (const tool of await generator.generateTools({ target: "claude" })) {
+  server.registerTool(...toSdkTool(tool, { fromJsonSchema }), async (input) => {
+    const request = buildHttpRequest(tool, input);
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body as BodyInit,
+    });
+    return { content: [{ type: "text", text: await response.text() }] };
+  });
 }
 ```
 
 ## Documentation
 
-| Document | Description |
-|----------|-------------|
-| [Getting Started](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/getting-started.md) | Loading specs, generating tools, building requests |
-| [Configuration](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/configuration.md) | LoadOptions, GenerateOptions, RefResolutionOptions |
-| [Parameter Conflicts](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/parameter-conflicts.md) | How conflict detection and resolution works |
-| [Response Schemas](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/response-schemas.md) | Output schemas, status codes, oneOf unions |
-| [Security](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/security.md) | SecurityResolver, all auth types, custom resolvers |
-| [SSRF Prevention](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/ssrf-prevention.md) | Ref resolution security, blocked IPs and hosts |
-| [Format Resolution](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/FORMAT_RESOLUTION.md) | Format-to-schema enrichment (uuid, date-time, email, int32, etc.) |
-| [Naming Strategies](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/naming-strategies.md) | Custom tool naming and conflict resolvers |
-| [SchemaBuilder](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/schema-builder.md) | JSON Schema utility methods |
-| [Error Handling](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/error-handling.md) | Error classes, context, and patterns |
-| [x-frontmcp Extension](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/x-frontmcp.md) | Custom OpenAPI extension for MCP annotations |
-| [API Reference](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/api-reference.md) | Complete types, interfaces, and exports |
-| [Examples](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/examples.md) | MCP server, Zod, filtering, security, and more |
-| [Architecture](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/architecture.md) | System overview, data flow, design patterns |
+| Document                                                                                                    | Description                                                       |
+| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| [Getting Started](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/getting-started.md)         | Loading specs, generating tools, building requests                |
+| [Configuration](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/configuration.md)             | LoadOptions, GenerateOptions, RefResolutionOptions                |
+| [Parameter Conflicts](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/parameter-conflicts.md) | How conflict detection and resolution works                       |
+| [Request Builder](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/request-builder.md)         | `buildHttpRequest` — full OpenAPI parameter serialization         |
+| [Client Targets](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/client-targets.md)           | Per-client schema dialects (Claude, OpenAI, Gemini)               |
+| [Curation](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/curation.md)                       | Token budgets, overlays, lint, trimming, response hints           |
+| [Response Schemas](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/response-schemas.md)       | Output schemas, status codes, oneOf unions                        |
+| [Annotations & Extensions](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/annotations.md)    | Tool title, annotation inference, `x-mcp` extension family        |
+| [Security](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/security.md)                       | SecurityResolver, all auth types, custom resolvers                |
+| [SSRF Prevention](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/ssrf-prevention.md)         | Ref resolution security, blocked IPs and hosts                    |
+| [Format Resolution](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/FORMAT_RESOLUTION.md)     | Format-to-schema enrichment (uuid, date-time, email, int32, etc.) |
+| [Naming Strategies](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/naming-strategies.md)     | Custom tool naming and conflict resolvers                         |
+| [SchemaBuilder](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/schema-builder.md)            | JSON Schema utility methods                                       |
+| [Error Handling](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/error-handling.md)           | Error classes, context, and patterns                              |
+| [x-frontmcp Extension](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/x-frontmcp.md)         | Custom OpenAPI extension for MCP annotations                      |
+| [API Reference](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/api-reference.md)             | Complete types, interfaces, and exports                           |
+| [Examples](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/examples.md)                       | MCP server, Zod, filtering, security, and more                    |
+| [Architecture](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/architecture.md)               | System overview, data flow, design patterns                       |
 
 ## Requirements
 
@@ -161,7 +171,18 @@ function buildRequest(tool: McpOpenAPITool, input: Record<string, any>) {
 
 ## Contributing
 
-Contributions are welcome! Please see our [issues page](https://github.com/agentfront/mcp-from-openapi/issues).
+Contributions are welcome! Start with the
+[contributing guide](https://github.com/agentfront/mcp-from-openapi/blob/main/CONTRIBUTING.md);
+this project follows the
+[Contributor Covenant](https://github.com/agentfront/mcp-from-openapi/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and feature requests go through the
+[issue templates](https://github.com/agentfront/mcp-from-openapi/issues/new/choose).
+
+## Security
+
+Report vulnerabilities privately — see the
+[security policy](https://github.com/agentfront/mcp-from-openapi/blob/main/SECURITY.md).
+When loading untrusted specs, use `secureDefaults: true`.
 
 ## Related Projects
 

package/annotations.d.ts

@@ -0,0 +1,57 @@
+import type { HTTPMethod, OperationObject, ToolAnnotations } from './types';
+/**
+ * Tool-level overrides read from the `x-mcp` extension family on an operation.
+ */
+export interface ExtensionToolOverrides {
+    /**
+     * Operation explicitly excluded from tool generation
+     * (`x-mcp: false`, `x-mcp: { enabled: false }`, or
+     * `x-speakeasy-mcp: { disabled: true }`).
+     */
+    disabled?: boolean;
+    /**
+     * Tool name override (still normalized to MCP name rules).
+     */
+    name?: string;
+    /**
+     * Display title override.
+     */
+    title?: string;
+    /**
+     * LLM-facing description override.
+     */
+    description?: string;
+    /**
+     * Annotation overrides, merged field-by-field over inferred values.
+     */
+    annotations?: ToolAnnotations;
+}
+/**
+ * Default MCP tool annotations per HTTP method, derived from HTTP semantics
+ * (RFC 9110 safety/idempotency): safe methods are read-only and idempotent;
+ * PUT/DELETE are idempotent but may destroy state; POST/PATCH are neither
+ * safe nor idempotent. `openWorldHint` is false throughout — tools generated
+ * from a spec target one known API backend, a closed world.
+ */
+export declare function inferAnnotationsFromMethod(method: HTTPMethod): ToolAnnotations;
+/**
+ * Resolve whether an operation is enabled for tool generation, honoring the
+ * `x-mcp` extension at every level with harsha-compatible precedence:
+ * root (document) < path item < operation. A root-level `x-mcp: false` flips
+ * the whole spec to opt-in; a path or operation level `x-mcp: true` (or
+ * `{ enabled: true }`) re-enables its subtree. At the operation level the
+ * whole extension family participates (`x-speakeasy-mcp: { disabled }` too),
+ * with the family's own precedence.
+ */
+export declare function resolveExtensionEnabled(document: object, pathItem: object, operation: OperationObject): boolean;
+/**
+ * Extract tool overrides from the `x-mcp` extension family on an operation.
+ *
+ * Precedence (ascending — later overrides earlier, field-by-field):
+ *   1. `x-speakeasy-mcp` — `{ disabled, name, title, description, readOnlyHint, ... }`
+ *      (Speakeasy places annotation hints at the top level of the object)
+ *   2. `x-mcp` — `false` to exclude, or `{ enabled, name, title, description, annotations }`
+ *   3. `x-frontmcp` — the canonical extension for this stack; its `annotations`
+ *      (including `annotations.title`) win over the generic variants
+ */
+export declare function extractExtensionOverrides(operation: OperationObject): ExtensionToolOverrides;

package/client-targets.d.ts

@@ -0,0 +1,55 @@
+import type { JsonSchema } from './types';
+/**
+ * Client dialect targets. Every MCP client accepts a different JSON Schema
+ * subset; a target applies the transforms that make schemas valid for it:
+ *
+ * - `strict`  — the safe baseline for all clients: local `$ref`/`$defs`
+ *   inlined, arrays always carry `items`, root-level compositions collapsed
+ * - `claude`  — `strict` (Claude additionally rejects top-level unions on
+ *   `input_schema` and caps tool names at 64 chars — both already covered by
+ *   the generator's defaults)
+ * - `openai`  — `strict` + every object closed (`additionalProperties: false`,
+ *   required by OpenAI strict function calling)
+ * - `gemini`  — `strict` + unions collapsed at every level and unsupported
+ *   `format` values demoted to descriptions (Gemini rejects `$ref`/`$defs`,
+ *   union-heavy schemas, and most string formats)
+ */
+export type ClientTarget = 'claude' | 'openai' | 'gemini' | 'strict';
+/**
+ * Resolve local `$ref` pointers against the schema's own `$defs`/`definitions`
+ * and strip the definition blocks. Cycles and unresolvable pointers become
+ * permissive `{}` nodes with an explanatory description. (Generated schemas
+ * are usually fully dereferenced already — this covers `dereference: false`
+ * flows and hand-fed schemas.)
+ */
+export declare function inlineLocalRefs(schema: JsonSchema): JsonSchema;
+/** Ensure every array schema carries an `items` schema (permissive when absent). */
+export declare function ensureArrayItems(schema: JsonSchema): JsonSchema;
+/**
+ * Collapse ROOT-level compositions only: `allOf` merges; `oneOf`/`anyOf`
+ * become a permissive node that documents the variants and preserves them
+ * under `x-variants`. The nullable wrapper unwraps to its non-null member.
+ */
+export declare function collapseRootCompositions(schema: JsonSchema): JsonSchema;
+/**
+ * Collapse unions at EVERY level (Gemini): nullable wrappers unwrap with a
+ * note; other `oneOf`/`anyOf` keep their first variant and document the
+ * omitted alternatives; `allOf` merges.
+ */
+export declare function collapseNestedUnions(schema: JsonSchema): JsonSchema;
+/** Demote unsupported `format` values into descriptions (Gemini). */
+export declare function demoteFormats(schema: JsonSchema, supported?: Set<string>): JsonSchema;
+/** Close every object node (`additionalProperties: false`) — OpenAI strict mode. */
+export declare function enforceClosedObjects(schema: JsonSchema): JsonSchema;
+/**
+ * OpenAI strict function calling requires EVERY property to be listed in
+ * `required`; optional fields are expressed as required-but-nullable. This
+ * rewrites each object node accordingly (typed optionals gain a `null` type;
+ * untyped optionals are already permissive).
+ */
+export declare function requireAllProperties(schema: JsonSchema): JsonSchema;
+/**
+ * Apply a client target's transform pipeline to a schema. Also exported for
+ * standalone use on schemas that did not come from the generator.
+ */
+export declare function applyClientTarget(schema: JsonSchema, target: ClientTarget): JsonSchema;

package/errors.d.ts

@@ -43,6 +43,20 @@ export declare class ValidationError extends OpenAPIToolError {
 export declare class GenerationError extends OpenAPIToolError {
     constructor(message: string, context?: Record<string, any>);
 }
+/**
+ * Error thrown when an OpenAPI Overlay document is malformed or its JSONPath
+ * target uses unsupported syntax
+ */
+export declare class OverlayError extends OpenAPIToolError {
+    constructor(message: string, context?: Record<string, any>);
+}
+/**
+ * Error thrown when an HTTP request cannot be built from a tool's mapper
+ * (missing required parameters, unserializable values, injection attempts)
+ */
+export declare class RequestBuildError extends OpenAPIToolError {
+    constructor(message: string, context?: Record<string, any>);
+}
 /**
  * Error thrown when a schema is invalid
  */