解绑 OpenAPI MCP 服务器

本项目提供了一个模型上下文协议（MCP）服务器，带有工具可以将 OpenAPI 规范文件拆分为多个文件或提取特定端点到新文件中。它允许一个 MCP 客户端（如 AI 助手）以编程方式操作 OpenAPI 规范。

预备条件

• Node.js（推荐 LTS 版本，例如 v18 或 v20）
• npm（随 Node.js 一起提供）

使用方法

通过 Smithery 安装

要通过 Smithery 自动安装 Unbundle OpenAPI MCP 服务器给 Claude Desktop：

npx -y @smithery/cli install @auto-browse/unbundle_openapi_mcp --client claude

最简单的方法是通过 npx 使用此服务器，这确保您始终使用最新版本而无需全局安装。

npx @auto-browse/unbundle-openapi-mcp@latest

或者，您可以全局安装（不一般推荐）：

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 文件中添加。

// 在 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 文件中添加以下内容。

{
	"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 请求）：

{
	"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 请求）：

{
	"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/ 中编译的代码启动服务器）