Unbundle Openapi Specs

Unbundle OpenAPI MCP 服务

此项目提供了一个 Model Context Protocol（MCP）服务，其中包含用于将 OpenAPI 规范文件拆分为多个文件，或将特定端点提取到新文件中的工具。它允许 MCP 客户端（例如 AI 助手）以编程方式处理 OpenAPI 规范。

前提条件

• Node.js（推荐使用 LTS 版本，例如 v18 或 v20）
• npm（随 Node.js 一同安装）

用法

通过 Smithery 安装

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

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
# Then run using: 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 文件中。

// In settings.json:
"mcp.servers": {
  "unbundle_openapi": { // You can choose any key name
    "command": "npx",
    "args": [
      "@auto-browse/unbundle-openapi-mcp@latest"
    ]
  }
  // ... other servers can be added here
},

// Or in .vscode/mcp.json (omit the top-level "mcp.servers"):
{
  "unbundle_openapi": { // You can choose any key name
    "command": "npx",
    "args": [
      "@auto-browse/unbundle-openapi-mcp@latest"
    ]
  }
  // ... other servers can be added here
}

Claude Desktop

将以下内容添加到 claude_desktop_config.json 文件中。

{
	"mcpServers": {
		"unbundle_openapi": {
			// You can choose any key name
			"command": "npx",
			"args": ["@auto-browse/unbundle-openapi-mcp@latest"]
		}
		// ... other servers can be added here
	}
}

添加配置后，请重启客户端应用，使更改生效。

提供的 MCP 工具

split_openapi

描述： 执行 redocly split 命令，根据 OpenAPI 定义文件的结构将其拆分为多个较小的文件。

参数：

• apiPath（string，必需）：输入 OpenAPI 定义文件的绝对路径（例如，openapi.yaml）。
• outputDir（string，必需）：保存拆分输出文件的目录的绝对路径。如果该目录不存在，将会创建。

返回值：

• 成功时：包含 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 命令。如果 @redocly/cli 尚未缓存，npx 可能需要联网获取。执行 extract_openapi_endpoints 期间会创建临时文件，并在完成后自动清理。

开发

如果你想贡献代码或从源代码运行此服务：

1. 克隆： 克隆此代码库。
2. 进入目录： cd unbundle_openapi_mcp
3. 安装依赖： npm install
4. 构建： npm run build（将 TypeScript 编译到 dist/）
5. 运行： npm start（使用 dist/ 中编译后的代码启动服务）