api-to-mcp-gateway

关于本项目

把任意 OpenAPI / Swagger 文档转换成一个运行中的 MCP Server —— AI Agent 即可直接调用这些 API，无需为每个接口手写集成代码。

• 解析：从 OpenAPI 文档中提取全部 operation（路径、方法、参数、请求体）

• 转换：每个 operation 映射为一个 MCP tool（{source}_{snake_case} 命名，参数转为 JSON Schema）

• 服务：通过 JSON-RPC 2.0 暴露 tools/list 与 tools/call

• 代理：把 tool 调用拼装为真实 HTTP 请求，注入凭证后转发

⚠️ 定位是目标，不全是现状。 上面「安全 / 可治理 / 可审计 / 按权限」中的**「可审计」「按权限」当前尚未实现**。 每一项的真实状态（已实现 ✅ / 部分 🟡 / 未实现 ❌）以 能力矩阵 为唯一事实源 —— 请以它为准。

工作原理

OpenAPI 文档 ──▶ Parser ──▶ Converter ──▶ ToolRegistry ──▶ MCP Server (JSON-RPC)
                                              │
                                              ▼
                                       API Proxy ──HTTP──▶ 目标 API
                                       AuthManager
                                       RAG Retriever
                                       Agent Orchestrator

技术栈

TypeScript 5（strict）· Node.js 20+ · pnpm workspace monorepo。 JSON-RPC 2.0（自实现，未依赖 MCP SDK）· zod · yaml · Vitest。

Related MCP server: mcpify

快速开始

前置要求

• Node.js ≥ 20

• pnpm 9

安装

pnpm install
pnpm build        # ⚠️ 必需：`pnpm start` 运行的是编译产物 packages/cli/dist/index.js

启动 MCP Server：

pnpm start -- --spec ./specs/petstore.yaml

服务监听 http://127.0.0.1:3000/mcp，可连接 Claude Desktop、Codex 或任意 MCP 客户端。

使用

api2mcp serve  --spec <路径或 URL> [选项]    启动 MCP Server 并代理 API 调用
api2mcp render --spec <路径或 URL> [选项]    输出 MCP tool 定义（给 AI 读的 JSON）

# 多个 API 合到一个 Server（tool 名以 source 前缀区分）
pnpm start -- --spec ./github.yaml --spec ./notion.yaml

# 直接从远程 URL 拉取 spec
pnpm start -- --spec https://example.com/openapi.json

# 不启动服务，只导出 tool 定义
pnpm start -- render --spec ./specs/petstore.yaml --output mcp-tools.json

# 启动前给 API 文档质量打分
pnpm start -- serve --spec ./specs/petstore.yaml --score

完整选项、MCP 客户端接入配置、评分 / 增强 / Agent 模式 → docs/usage.md

现状与路线

能力现状见 能力矩阵 —— 那里逐项标注「已实现 / 部分 / 未实现」并附源码位置。标 ❌ 的项即为路线图，本文不重复罗列（避免两处清单漂移）。

架构、扩展点与已知简化 → docs/architecture.md　｜　安全模型与当前边界 → docs/security.md

配置

认证通过环境变量注入（命名规则 {SOURCE}_TOKEN 或 {SOURCE}_API_KEY）—— 凭证不写进任何文件：

export GITHUB_TOKEN=<你的令牌>
export NOTION_API_KEY=<你的密钥>
pnpm start -- --spec ./github.yaml --spec ./notion.yaml

LLM 相关能力（质量增强 / Agent 模式 / 语义检索）需要 ANTHROPIC_API_KEY 或 OPENAI_API_KEY。 完整的环境变量清单见 docs/usage.md。

项目结构

packages/
  core/       OpenAPI 解析 + tool schema 转换 + 文档质量评分 / 增强
  server/     MCP 运行时：tools · proxy · auth · JSON-RPC
  cli/        CLI 入口（多 spec、远程 URL、render）
  rag/        向量存储 + 语义检索
  agent/      编排器：RAG → LLM → tool 调用 → 循环
specs/        示例 OpenAPI 文档（Petstore）
docs/         公开文档（架构 / 使用 / 安全 / 能力矩阵）

⚠️ core 是根依赖 —— 改动它的公开导出会影响全部下游包。

贡献

欢迎提交 issue 与 pull request。

改动请一并满足：

• 新增 / 修改行为带测试

• 类型闸通过：pnpm -r build

• 测试通过：pnpm --filter @api2mcp/core --filter @api2mcp/agent test

⚠️ vitest 不做类型检查 —— 「测试绿」不等于「能编译」。两者必须分别跑。

许可证

基于 Apache License 2.0 分发 —— 详见 LICENSE。

Copyright 2026 PPACT。任何人都可以自由地使用、复制、修改、分发本软件（含商业用途）， 条件是保留版权与许可证声明、标明改动，并随附 LICENSE 全文。本软件按「原样」提供，不含任何担保。

✅ 取舍说明：Apache-2.0 含显式的专利授权（第 3 条：贡献者向使用者授予专利许可，并随专利诉讼而终止）—— 这是它相对 MIT 的主要增益；代价是许可文本更长，且再分发时有声明保留 / 变更说明义务。

致谢

• Model Context Protocol —— MCP 与 JSON-RPC 2.0 协议

• zod、yaml、Vitest

• 本 README 的结构参考 Best-README-Template