mcp-from-openapi

Convert OpenAPI specifications into MCP tool definitions with automatic parameter conflict resolution

What This Solves

When converting OpenAPI specs to MCP tools, you hit parameter conflicts -- the same name appears in different locations (path, query, body). This library resolves them automatically and gives you an explicit mapper for building HTTP requests.

The Problem:

paths:
  /users/{id}:
    post:
      parameters:
        - name: id        # path
          in: path
      requestBody:
        content:
          application/json:
            schema:
              properties:
                id:        # body -- CONFLICT!
                  type: string

The Solution:

{
  inputSchema: {
    properties: {
      pathId: { type: "string" },    // Automatically renamed
      bodyId: { type: "string" }     // Automatically renamed
    }
  },
  mapper: [
    { inputKey: "pathId", type: "path", key: "id" },
    { inputKey: "bodyId", type: "body", key: "id" }
  ]
}

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
• 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

Installation

npm install mcp-from-openapi
# or
yarn add mcp-from-openapi
# or
pnpm add mcp-from-openapi

Quick Start

import { OpenAPIToolGenerator } from 'mcp-from-openapi';

// Load an OpenAPI spec
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.
});

Using the Mapper

The mapper tells you how to convert tool inputs into an HTTP request:

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;
    }
  }

  const baseUrl = tool.metadata.servers?.[0]?.url ?? '';
  const qs = query.toString();

  return {
    url: `${baseUrl}${path}${qs ? '?' + qs : ''}`,
    method: tool.metadata.method.toUpperCase(),
    headers,
    body: body ? JSON.stringify(body) : undefined,
  };
}

Documentation

| Document | Description | |----------|-------------| | Getting Started | Loading specs, generating tools, building requests | | Configuration | LoadOptions, GenerateOptions, RefResolutionOptions | | Parameter Conflicts | How conflict detection and resolution works | | Response Schemas | Output schemas, status codes, oneOf unions | | Security | SecurityResolver, all auth types, custom resolvers | | SSRF Prevention | Ref resolution security, blocked IPs and hosts | | Format Resolution | Format-to-schema enrichment (uuid, date-time, email, int32, etc.) | | Naming Strategies | Custom tool naming and conflict resolvers | | SchemaBuilder | JSON Schema utility methods | | Error Handling | Error classes, context, and patterns | | x-frontmcp Extension | Custom OpenAPI extension for MCP annotations | | API Reference | Complete types, interfaces, and exports | | Examples | MCP server, Zod, filtering, security, and more | | Architecture | System overview, data flow, design patterns |

Requirements

• Node.js >= 20.0.0
• TypeScript >= 5.0 (for TypeScript users)
• Peer dependency: zod@^4.0.0

Contributing

Contributions are welcome! Please see our issues page.

Related Projects

• Model Context Protocol
• OpenAPI Specification

License

Apache 2.0