内容
# 解耦 OpenAPI MCP 服务器
[](https://smithery.ai/server/@auto-browse/unbundle_openapi_mcp)
本项目提供一个模型上下文协议（MCP）服务器，包含工具用于将 OpenAPI 规范文件拆分为多个文件或提取特定端点到新文件中。它允许 MCP 客户端（如 AI 助手）以编程方式操纵 OpenAPI 规范。
## 前置条件
- Node.js（推荐使用 LTS 版本，如 v18 或 v20）
- npm（随 Node.js 附带）
## 用法
### 通过 Smithery 安装
要通过 [Smithery](https://smithery.ai/server/@auto-browse/unbundle_openapi_mcp) 自动安装用于 Claude Desktop 的解耦 OpenAPI MCP 服务器：
```bash
npx -y @smithery/cli install @auto-browse/unbundle_openapi_mcp --client claude
```
使用此服务器的最简单方法是使用 `npx`，它确保您始终使用最新版本，而无需全局安装。
```bash
npx @auto-browse/unbundle-openapi-mcp@latest
```
或者，您可以全局安装（通常不推荐）：
```bash
npm install -g @auto-browse/unbundle-openapi-mcp
# 然后运行：unbundle-openapi-mcp
```
服务器将启动并监听标准输入/输出（stdio）上的 MCP 请求。
## 客户端配置
要将此服务器与 VS Code、Cline、Cursor 或 Claude Desktop 等 MCP 客户端一起使用，请将其配置添加到相应的设置文件中。推荐的方法使用 `npx`。
### VS Code / Cline / Cursor
将以下内容添加到您的用户 `settings.json`（可通过 `Ctrl+Shift+P` > `Preferences: Open User Settings (JSON)` 访问）或工作区根目录下的 `.vscode/mcp.json` 文件中。
```json
// 在 settings.json 中：
"mcp.servers": {
"unbundle_openapi": { // 您可以选择任何键名
"command": "npx",
"args": [
"@auto-browse/unbundle-openapi-mcp@latest"
]
}
// ... 可以在此处添加其他服务器
},
// 或在 .vscode/mcp.json 中（省略顶级 "mcp.servers"）：
{
"unbundle_openapi": { // 您可以选择任何键名
"command": "npx",
"args": [
"@auto-browse/unbundle-openapi-mcp@latest"
]
}
// ... 可以在此处添加其他服务器
}
```
### Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json` 文件中。
```json
{
"mcpServers": {
"unbundle_openapi": {
// 您可以选择任何键名
"command": "npx",
"args": ["@auto-browse/unbundle-openapi-mcp@latest"]
}
// ... 可以在此处添加其他服务器
}
}
```
添加配置后，请重启您的客户端应用程序以使更改生效。
## 提供的 MCP 工具
### `split_openapi`
**描述：** 执行 `redocly split` 命令，将 OpenAPI 定义文件拆分为多个较小的文件，基于其结构。
**参数：**
- `apiPath`（字符串，必填）：输入 OpenAPI 定义文件的绝对路径（例如 `openapi.yaml`）。
- `outputDir`（字符串，必填）：拆分输出文件应保存的目录的绝对路径。此目录将在必要时创建。
**返回：**
- 成功时：包含 `redocly split` 命令标准输出的文本消息（通常是确认消息）。
- 失败时：包含命令执行错误或异常详细信息的错误消息，标记为 `isError: true`。
**示例用法（概念性 MCP 请求）：**
```json
{
"tool_name": "split_openapi",
"arguments": {
"apiPath": "/path/to/your/openapi.yaml",
"outputDir": "/path/to/output/directory"
}
}
```
### `extract_openapi_endpoints`
**描述：** 从大型 OpenAPI 定义文件中提取特定端点，并创建一个新的较小 OpenAPI 文件，仅包含这些端点及其引用的组件。它通过拆分原始文件、修改结构以仅保留指定的路径，然后绑定结果来实现。
**参数：**
- `inputApiPath`（字符串，必填）：大型输入 OpenAPI 定义文件的绝对路径。
- `endpointsToKeep`（字符串数组，必填）：要包含在最终输出中的精确端点路径（字符串）列表（例如 `["/api", "/api/projects/{id}{.format}"]`）。原始规范中未找到的路径将被忽略。
- `outputApiPath`（字符串，必填）：最终的较小绑定 OpenAPI 文件应保存的绝对路径。目录将在必要时创建。
**返回：**
- 成功时：指示创建文件路径的文本消息和 `redocly bundle` 命令的标准输出。
- 失败时：包含有关失败步骤（拆分、修改、绑定）的详细信息错误消息，标记为 `isError: true`。
**示例用法（概念性 MCP 请求）：**
```json
{
"tool_name": "extract_openapi_endpoints",
"arguments": {
"inputApiPath": "/path/to/large-openapi.yaml",
"endpointsToKeep": ["/users", "/users/{userId}/profile"],
"outputApiPath": "/path/to/extracted-openapi.yaml"
}
}
```
**注意：** 此服务器内部使用 `npx @redocly/cli@latest` 执行底层 `split` 和 `bundle` 命令。`npx` 可能需要互联网连接才能获取 `@redocly/cli`，如果它未被缓存。在 `extract_openapi_endpoints` 过程中会创建临时文件并自动清理。
## 开发
如果您想为此项目做出贡献或从源代码运行服务器：
1. **克隆：** 克隆此存储库。
2. **导航：** `cd unbundle_openapi_mcp`
3. **安装依赖项：** `npm install`
4. **构建：** `npm run build`（将 TypeScript 编译到 `dist/`）
5. **运行：** `npm start`（使用 `dist/` 中的编译代码启动服务器）
