{"id":50563035,"url":"https://github.com/agentfront/mcp-from-openapi","last_synced_at":"2026-06-04T12:30:31.704Z","repository":{"id":349874509,"uuid":"1128993306","full_name":"agentfront/mcp-from-openapi","owner":"agentfront","description":"Production-ready TypeScript library for converting OpenAPI specifications into MCP (Model Context Protocol) tool","archived":false,"fork":false,"pushed_at":"2026-04-08T01:01:26.000Z","size":256,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T11:27:08.471Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentfront.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-06T13:01:27.000Z","updated_at":"2026-04-08T11:29:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agentfront/mcp-from-openapi","commit_stats":null,"previous_names":["agentfront/mcp-from-openapi"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/agentfront/mcp-from-openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentfront%2Fmcp-from-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentfront%2Fmcp-from-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentfront%2Fmcp-from-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentfront%2Fmcp-from-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentfront","download_url":"https://codeload.github.com/agentfront/mcp-from-openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentfront%2Fmcp-from-openapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33780572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-04T12:30:30.701Z","updated_at":"2026-06-04T12:30:31.685Z","avatar_url":"https://github.com/agentfront.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-from-openapi\n\n\u003e Convert OpenAPI specifications into MCP tool definitions with automatic parameter conflict resolution\n\n[![npm version](https://badge.fury.io/js/mcp-from-openapi.svg)](https://www.npmjs.com/package/mcp-from-openapi)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/license/apache-2-0)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)\n\n## What This Solves\n\nWhen 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.\n\n**The Problem:**\n\n```yaml\npaths:\n  /users/{id}:\n    post:\n      parameters:\n        - name: id        # path\n          in: path\n      requestBody:\n        content:\n          application/json:\n            schema:\n              properties:\n                id:        # body -- CONFLICT!\n                  type: string\n```\n\n**The Solution:**\n\n```typescript\n{\n  inputSchema: {\n    properties: {\n      pathId: { type: \"string\" },    // Automatically renamed\n      bodyId: { type: \"string\" }     // Automatically renamed\n    }\n  },\n  mapper: [\n    { inputKey: \"pathId\", type: \"path\", key: \"id\" },\n    { inputKey: \"bodyId\", type: \"body\", key: \"id\" }\n  ]\n}\n```\n\nNow you know exactly how to build the HTTP request.\n\n## Features\n\n- **Smart Parameter Handling** -- Automatic conflict detection and resolution across path, query, header, cookie, and body\n- **Complete Schemas** -- Input schema combines all parameters; output schema from responses (with oneOf unions)\n- **Security Resolution** -- Framework-agnostic auth for Bearer, Basic, Digest, API Key, OAuth2, OpenID, mTLS, HMAC, AWS Sig V4\n- **SSRF Prevention** -- Blocks internal IPs, localhost, and cloud metadata endpoints by default during `$ref` resolution\n- **Multiple Input Sources** -- Load from URL, file, YAML string, or JSON object\n- **Rich Metadata** -- Authentication, servers, tags, deprecation, external docs, `x-frontmcp` extension\n- **Production Ready** -- Full TypeScript support, validation, structured errors, 80%+ test coverage\n- **MCP Native** -- Designed specifically for Model Context Protocol integration\n\n## Installation\n\n```bash\nnpm install mcp-from-openapi\n# or\nyarn add mcp-from-openapi\n# or\npnpm add mcp-from-openapi\n```\n\n## Quick Start\n\n```typescript\nimport { OpenAPIToolGenerator } from 'mcp-from-openapi';\n\n// Load an OpenAPI spec\nconst generator = await OpenAPIToolGenerator.fromURL('https://api.example.com/openapi.json');\n\n// Generate MCP tools\nconst tools = await generator.generateTools();\n\n// Each tool has everything you need\ntools.forEach((tool) =\u003e {\n  console.log(tool.name);          // \"createUser\"\n  console.log(tool.inputSchema);   // Combined schema for all params\n  console.log(tool.outputSchema);  // Response schema\n  console.log(tool.mapper);        // How to build the HTTP request\n  console.log(tool.metadata);      // Auth, servers, tags, etc.\n});\n```\n\n## Using the Mapper\n\nThe mapper tells you how to convert tool inputs into an HTTP request:\n\n```typescript\nfunction buildRequest(tool: McpOpenAPITool, input: Record\u003cstring, any\u003e) {\n  let path = tool.metadata.path;\n  const query = new URLSearchParams();\n  const headers: Record\u003cstring, string\u003e = {};\n  let body: Record\u003cstring, any\u003e | undefined;\n\n  for (const m of tool.mapper) {\n    const value = input[m.inputKey];\n    if (value === undefined) continue;\n\n    switch (m.type) {\n      case 'path':\n        path = path.replace(`{${m.key}}`, encodeURIComponent(value));\n        break;\n      case 'query':\n        query.set(m.key, String(value));\n        break;\n      case 'header':\n        headers[m.key] = String(value);\n        break;\n      case 'body':\n        if (!body) body = {};\n        body[m.key] = value;\n        break;\n    }\n  }\n\n  const baseUrl = tool.metadata.servers?.[0]?.url ?? '';\n  const qs = query.toString();\n\n  return {\n    url: `${baseUrl}${path}${qs ? '?' + qs : ''}`,\n    method: tool.metadata.method.toUpperCase(),\n    headers,\n    body: body ? JSON.stringify(body) : undefined,\n  };\n}\n```\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Getting Started](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/getting-started.md) | Loading specs, generating tools, building requests |\n| [Configuration](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/configuration.md) | LoadOptions, GenerateOptions, RefResolutionOptions |\n| [Parameter Conflicts](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/parameter-conflicts.md) | How conflict detection and resolution works |\n| [Response Schemas](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/response-schemas.md) | Output schemas, status codes, oneOf unions |\n| [Security](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/security.md) | SecurityResolver, all auth types, custom resolvers |\n| [SSRF Prevention](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/ssrf-prevention.md) | Ref resolution security, blocked IPs and hosts |\n| [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.) |\n| [Naming Strategies](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/naming-strategies.md) | Custom tool naming and conflict resolvers |\n| [SchemaBuilder](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/schema-builder.md) | JSON Schema utility methods |\n| [Error Handling](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/error-handling.md) | Error classes, context, and patterns |\n| [x-frontmcp Extension](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/x-frontmcp.md) | Custom OpenAPI extension for MCP annotations |\n| [API Reference](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/api-reference.md) | Complete types, interfaces, and exports |\n| [Examples](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/examples.md) | MCP server, Zod, filtering, security, and more |\n| [Architecture](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/architecture.md) | System overview, data flow, design patterns |\n\n## Requirements\n\n- Node.js \u003e= 20.0.0\n- TypeScript \u003e= 5.0 (for TypeScript users)\n- Peer dependency: `zod@^4.0.0`\n\n## Contributing\n\nContributions are welcome! Please see our [issues page](https://github.com/agentfront/mcp-from-openapi/issues).\n\n## Related Projects\n\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [OpenAPI Specification](https://www.openapis.org/)\n\n## License\n\n[Apache 2.0](https://github.com/agentfront/mcp-from-openapi/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentfront%2Fmcp-from-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentfront%2Fmcp-from-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentfront%2Fmcp-from-openapi/lists"}