https://github.com/agentfront/mcp-from-openapi
Production-ready TypeScript library for converting OpenAPI specifications into MCP (Model Context Protocol) tool
https://github.com/agentfront/mcp-from-openapi
Last synced: 7 days ago
JSON representation
Production-ready TypeScript library for converting OpenAPI specifications into MCP (Model Context Protocol) tool
- Host: GitHub
- URL: https://github.com/agentfront/mcp-from-openapi
- Owner: agentfront
- License: apache-2.0
- Created: 2026-01-06T13:01:27.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-08T01:01:26.000Z (2 months ago)
- Last Synced: 2026-05-17T11:27:08.471Z (25 days ago)
- Language: TypeScript
- Size: 250 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: docs/security.md
Awesome Lists containing this project
README
# mcp-from-openapi
> Convert OpenAPI specifications into MCP tool definitions with automatic parameter conflict resolution
[](https://www.npmjs.com/package/mcp-from-openapi)
[](https://opensource.org/license/apache-2-0)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
## 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:**
```yaml
paths:
/users/{id}:
post:
parameters:
- name: id # path
in: path
requestBody:
content:
application/json:
schema:
properties:
id: # body -- CONFLICT!
type: string
```
**The Solution:**
```typescript
{
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
```bash
npm install mcp-from-openapi
# or
yarn add mcp-from-openapi
# or
pnpm add mcp-from-openapi
```
## Quick Start
```typescript
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:
```typescript
function buildRequest(tool: McpOpenAPITool, input: Record) {
let path = tool.metadata.path;
const query = new URLSearchParams();
const headers: Record = {};
let body: Record | 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](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 |
## 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](https://github.com/agentfront/mcp-from-openapi/issues).
## Related Projects
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [OpenAPI Specification](https://www.openapis.org/)
## License
[Apache 2.0](https://github.com/agentfront/mcp-from-openapi/blob/main/LICENSE)