内容
# mcp-api-translator
[](https://www.npmjs.com/package/mcp-api-translator)
[](https://github.com/krishgok/mcp-api-translator/actions/workflows/ci.yml)
[](LICENSE)
[](LICENSING.md)
[](https://modelcontextprotocol.io)
一个生成MCP服务器的**MCP服务器**。给它一个API定义（OpenAPI 3.0/3.1或Postman集合），它为该API搭建一个完整、可运行的、**可拥有的**TypeScript MCP服务器——因此，没有“MCP策略”的服务对AI模型（如Claude、Cursor、Codex等）变得可用和可发现。
它本身就是一个MCP服务器：一个代理连接到它并调用它的工具来分析规范、生成服务器或扩展现有的服务器。
## 添加到您的AI堆栈
无需安装步骤。`npx`获取并运行最新的已发布版本——跨平台，Node 20+。
### 克劳德桌面 / 克劳德代码
添加到 `claude_desktop_config.json` （macOS：`~/Library/Application Support/Claude/`，Windows：`%APPDATA%\Claude\`）或您的 `mcp.json`：
```json
{
"mcpServers": {
"api-translator": {
"command": "npx",
"args": ["-y", "mcp-api-translator"]
}
}
}
```
<details>
<summary><strong>光标</strong></summary>
添加到 `~/.cursor/mcp.json` （或项目范围内的 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"api-translator": {
"command": "npx",
"args": ["-y", "mcp-api-translator"]
}
}
}
```
</details>
<details>
<summary><strong>克莱恩（VS Code）</strong></summary>
打开克莱恩侧边栏 → MCP 服务器 → 配置 → 添加：
```json
{
"mcpServers": {
"api-translator": {
"command": "npx",
"args": ["-y", "mcp-api-translator"],
"disabled": false
}
}
}
```
</details>
<details>
<summary><strong>Continue.dev</strong></summary>
将以下内容添加到 `~/.continue/config.json` 下的 `experimental.modelContextProtocolServers`：
```json
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-api-translator"]
}
}
]
}
}
```
</details>
<details>
<summary><strong>Docker（无需 Node）</strong></summary>
```json
{
"mcpServers": {
"api-translator": {
"command": "docker",
"args": ["run", "--rm", "-i", "ghcr.io/krishgok/mcp-api-translator:latest"]
}
}
}
```
为了让生成器从磁盘读取规范或将生成的项目写入主机路径，请挂载目录：`-v ${PWD}:/workspace` 并将 `/workspace/...` 作为 `specPath` / `outputDir` 传递。
</details>
MCP 配置在启动时读取，因此请退出并重新打开您的客户端（Claude Desktop、Cursor 等）以选择新的服务器 - 其四个工具应该会出现。然后参见[用法](#usage)。
## 为什么存在（以及对该领域的诚实评估）
将 OpenAPI 规范转换为 MCP “工具存根”并非新鲜事 — [FastMCP 的 `from_openapi`](https://gofastmcp.com/integrations/openapi)、[Speakeasy/Gram](https://www.speakeasy.com/blog/generate-mcp-from-openapi) 以及多个 `openapi-mcp-generator` 项目已经完成了机械部分。一个天真的 1:1 端点→工具生成器没有任何真正的优势。
因此，该项目专注于这些工具错误或跳过的内容，即“使我的 API 对 AI 模型可用”的实际价值：
1. **策划，而不是生成。** 200 端点的 API 天真地变成 200 个工具，这会破坏模型的工具选择准确性并增加上下文。`analyze_spec` 首先预览工具列表，每个命令都支持 `includeTags` / `methods` / `pathGlob` / `excludeOperations` 筛选，并警告服务器过大时。
2. **通过追加聚合。** `extend_mcp_server` 将另一个 API 的工具添加到现有的生成项目中，因此您可以构建一个涵盖 GitHub + Stripe + 您内部 API 的 **单个** MCP 服务器。
3. **您拥有的工件。** 输出是一个普通的 TypeScript 项目（不是托管的黑盒）：可读的每个工具文件、基于环境的身份验证、Dockerfile 和 `server.json` + 客户端代码片段，用于发布到 [官方 MCP 注册表](https://registry.modelcontextprotocol.io)。
如果您只需要暂时、内存中暴露一个 API，并且不关心拥有代码，FastMCP 的运行时模式可能更适合您 - 这是这里的一个刻意非目标（参见限制）。
## 技术栈和原理
- **官方 `@modelcontextprotocol/sdk` 上的 TypeScript** — MCP 的一级 SDK；最便携的输出目标（在任何 Node 主机上运行，为 Claude/Cursor/Codex 等提供 `npx` 友好支持）。
- **`@readme/openapi-parser`** 用于 `$ref` 解析的 OpenAPI 3.0/3.1（+ 最佳努力的 Swagger 2.0）；直接解析 Postman v2.1。
- **用于生成工具输入的原始 JSON 架构。** OpenAPI 3.1 架构是 JSON 架构 2020-12，正是 MCP 工具的 `inputSchema` 所期望的 - 因此没有损失的 zod 往返。
- **字符串构建器模板，无模板引擎** — 依赖项最少，每个发射器都可进行快照测试。
## 工具
| 工具 | 它做什么 |
| ------------------------- | ---------------------------------------------------------------------------------- |
| `analyze_spec` | 解析规范并 **预览** 将生成的工具 - 不写入文件。 |
| `generate_mcp_server` | 将完整的 TS MCP 服务器项目生成到 `outputDir`。 |
| `extend_mcp_server` | 将另一个规范的工具追加到现有的生成项目（幂等）。 |
| `list_supported_features` | 报告支持的格式、身份验证方案、传输和限制。 |
所有规范输入都接受内联文本 (`spec`) 或本地路径 (`specPath`)，JSON 或 YAML。
## 用法
您不手动调用工具 - 您询问您的代理，它驱动它们。一个典型的会话：
**1. 预览** - 查看规范将变成什么，而不写入文件：
> _“分析 ./petstore.yaml 并向我展示建议的工具。”_
```js
analyze_spec({ specPath: "./petstore.yaml" });
// → 建议的工具列表、身份验证方案和服务器将需要的环境变量
```
**2. 精炼** - 大API？缩小范围。每个工具都接受相同的筛选器：
> _“仅限 /pets 下的 GET 端点。”_
```js
analyze_spec({ specPath: "./petstore.yaml", methods: ["GET"], pathGlob: "/pets/**" });
// 还包括：includeTags: ["pets"], excludeOperations: ["deletePet"]
```
**3. 生成** - 相同的筛选器，加上输出目录：
> _“将服务器生成到 ./petstore-mcp。”_
```js
generate_mcp_server({ specPath: "./petstore.yaml", outputDir: "./petstore-mcp" });
// 选项：language: "python", transport: "http", force: true
```
**4. 运行它** - 输出是一个正常的项目：
```bash
cd petstore-mcp && npm install && npm run build
cp .env.example .env # 设置 API_BASE_URL + 凭证（从不嵌入代码）
```
在您的客户端中注册它（生成的 `client-config.md` 中有可粘贴的片段），您的代理可以调用 API：`listPets`、`getPetById` 等。
**5. 聚合** （可选）- 将更多 API 添加到同一个服务器：
> _“用 ./github.yaml 扩展 ./petstore-mcp，仅限 issues 标签。”_
```js
extend_mcp_server({
projectDir: "./petstore-mcp",
specPath: "./github.yaml",
includeTags: ["issues"],
});
// 幂等；保留手动编辑的工具文件
```
聚合的 API 不共享凭证：每个 API 还会读取命名空间环境变量（`<NAMESPACE>_API_BASE_URL`、`<NAMESPACE>_API_KEY` 等 - 命名空间源自 API 标题），然后回落到裸变量。扩展摘要和 `.env.example` 列出了确切的名称。
完整的演练与示例输出和故障排除：
[docs/usage-workflow.md](docs/usage-workflow.md)。
## 使用规范的两种方式：生成或服务
- **生成** 可拥有的代码 (`generate_mcp_server`) 当您想要一个可以手动编辑、自我托管和拥有的项目时 - 默认 **TypeScript** 或 **Python** (`language: "python"`).
- **服务** 一个实时运行时代理，当您只需要将 API 暴露给代理 **现在** 时，无需生成文件来构建或维护：
```bash
mcp-api-translator serve --spec ./api.yaml # 挂载一个 API 作为实时 MCP 工具
mcp-api-translator serve --spec ./a.yaml --spec ./b.yaml --methods GET,POST # 聚合多个
```
`serve` 运行与生成器将发出相同的请求计划和基于环境的身份验证，因此行为与生成的输出完全匹配 - 它只是跳过了代码生成步骤。它默认使用stdio，或使用 `--transport http --port 3000` 进行无状态的Streamable HTTP（适用于容器和托管部署 - 请参阅 [docs/deploy-serve.md](docs/deploy-serve.md) 获取Docker/compose配方）。请参阅 [docs/serve-api-proposal.md](docs/serve-api-proposal.md) 获取设计和 [docs/market-analysis.md](docs/market-analysis.md) 获取为什么存在两种模式。
日志是结构化的：容器中的JSON行（由GCP Cloud Logging和AWS CloudWatch原生解析），TTY上的可读文本。使用 `LOG_LEVEL=debug|info|warn|error` （或 `--log-level`）和 `LOG_FORMAT=json|text` 调整；生成的项目也以相同的方式记录 - 请参阅 [docs/deploy-serve.md](docs/deploy-serve.md#logging--observability)。
## 生成的项目布局
```
src/index.ts # stdio 入口（如果 transport http/both，则为 index.http.ts）
src/server.ts # 注册工具（低级服务器 + JSON-Schema 输入）
src/tools/<name>.ts # 每个操作的文件：架构 + 请求计划
src/http/client.ts # 构建请求、获取、错误处理
src/auth.ts # 基于环境的凭证注入
src/logger.ts # 结构化 stderr 日志记录器（容器中的 JSON 行；LOG_LEVEL/LOG_FORMAT）
.env.example # API_BASE_URL + 检测到的凭证
server.json # MCP 注册表清单
client-config.md # 可粘贴的 Claude / Cursor / Codex 配置
.mcp-translator.json # 支持 `extend_mcp_server` 的清单
tool-catalog.json # 可选（toolCatalog: true）：每个工具的名称/摘要/标签用于发现层
```
## 假设和限制
- **输入：** OpenAPI 3.0/3.1 和 Postman v2.1（Swagger 2.0 尽力而为）。尚无 GraphQL/gRPC。
- **输出语言：** TypeScript（默认）和 Python。两者支持 `generate` 和 `extend_mcp_server`（将多个 API 聚合到一个服务器中）。Python 可以使用 `pythonVariant: "fastmcp"`（FastMCP 2.x 而不是低级 SDK）进行调整；两种风格都提供相同的原始 JSON-Schema 工具输入。
- **输出质量跟踪规范质量** - 缺失的 `operationId`s/描述会产生较弱的工具名称和文档。策划有助于；它不能发明语义。
- **身份验证：** API 密钥 / 承载令牌 / 基本身份验证 / 预先获得的 OAuth 令牌，以及 **OAuth2 客户端凭证授予** 和 **刷新令牌授予** （交换预先获得的刷新令牌；获取令牌 + 缓存），所有这些都从环境中读取。**无交互式（授权代码）同意流** 在 v1 中。
- **响应** 作为 JSON/文本返回；无上游流或自动分页。
- **Postman** 参数类型从示例中推断（Postman 携带无正式架构）。
- **非托管服务。** 它运行在本地/自我托管：`generate` 可拥有的代码，或 `serve` 实时进程代理。（无托管云产品 - 请参阅 [docs/serve-api-proposal.md](docs/serve-api-proposal.md) 路线图。）
## 安全性和信任模型
规范被视为 **不受信任的输入**：规范派生的字符串在嵌入生成源之前会进行转义，生成的工具名称仅限于 `[A-Za-z0-9_]`, 所有文件写入都保留在 `outputDir` 下。有两件事仍然是生成的服务器固有的，因此请在指向凭证之前查看输出：
- **生成的服务器调用规范声明的任意 base URL** （或 `API_BASE_URL`）并将您的环境提供的凭证注入这些请求。从不信任的规范生成并使用真实机密，可以将这些机密发送到规范选择的托管方。显式设置 `API_BASE_URL` 时请谨慎。
- **凭证从未嵌入** 生成的项目 - `auth.ts` 在运行时从环境中读取它们，并且 `.env.example` 随空值一起发货。
请参阅 [SECURITY.md](SECURITY.md) 以报告漏洞。
## 开发
```bash
npm install
npm test # 单元测试 + 集成测试（解析器、策划、发出、追加）
npm run typecheck
npm run build
npm run e2e # 从夹具中生成一个示例项目到 build/e2e-out
```
欢迎贡献 - 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。所有提交必须在 [开发者证书来源](https://developercertificate.org/) 下签名 (`git commit -s`)。
## 许可证和归属
`mcp-api-translator` 是 **双重许可** - © 2026 krishgok。请参阅 [LICENSING.md](LICENSING.md) 获取完整详细信息。
- **开源：** [GNU AGPL-3.0-or-later](LICENSE)。如果您运行修改后的版本来提供网络服务，AGPL 需要您向用户提供该版本的完整源代码。
- **商业：** 可提供单独的商业许可证，用于将 `mcp-api-translator` 嵌入专有或闭源产品/服务中，无需 AGPL 义务 - 请参阅 [LICENSING.md](LICENSING.md)。
- **您的生成输出属于您。** 通过运行此工具生成的项目受 [生成输出例外](LICENSING.md#3-generated-output-exception) 保护，不受 AGPL 约束 - 您可以使用您喜欢的许可证。
必须保留分发中的 [`LICENSE`](LICENSE) 和 [`NOTICE`](NOTICE)。许可证 **不** 授予使用 `mcp-api-translator` 名称来支持或推广分叉或派生作品的权利，无需事先书面许可。
