Bruno API MCP 服务器

一个将 Bruno API 集合暴露为 MCP 工具的模型上下文协议 (MCP) 服务器。该服务器允许您通过 MCP 协议与您的 Bruno API 集合进行交互，使您的 API 集合能够被 AI 代理和其他 MCP 客户端访问。

为什么这很重要：源代码和数据协同工作

当开发人员需要集成 API 时，他们通常会面临三个核心挑战：

1. 跨系统边界的调试：在独立的代码和数据环境中诊断问题需要不断地切换上下文，导致故障排除效率低下。
2. 创建自定义工具：每个第三方 API 集成都需要构建和维护自定义工具，造成开发负担和技术债务。
3. 构建服务 UI：为每个后端服务开发用户界面会增加显著的复杂性和维护成本。

这个服务器通过将您的源代码与数据共置来解决这些精确的问题。它将 Bruno API 集合转换为模型上下文协议工具，使您能够：

• 在以前分离的环境中进行全面上下文调试
• 将任何 API 转换为无需额外自定义开发的代理就绪工具
• 构建可以通过 AI 接口控制的无头服务

对于需要加速 API 集成同时减少维护开销的开发团队来说，这种方法从根本上改变了可能性——使以前复杂的集成变得简单且易于访问。

功能

• 自动将 Bruno API 集合转换为 MCP 工具
• 用于不同 API 配置的环境管理
• 带有 SSE 传输的 HTTP
• 跨域支持
• 内置的 API 集合管理工具

使用方法

1. 安装依赖项：

   npm install
   

2. 使用您的 Bruno API 集合启动服务器：

   node --loader ts-node/esm src/index.ts --bruno-path /path/to/bruno/collection [--environment env_name] [--include-tools tool1,tool2,tool3] [--exclude-tools tool4,tool5]
   

   选项：

   • --bruno-path 或 -b：Bruno API 集合目录的路径（必填）
   • --environment 或 -e：要使用的环境名称（可选）
   • --include-tools：以逗号分隔的要包含的工具名称列表，过滤掉所有其他工具（可选）
   • --exclude-tools：以逗号分隔的要排除的工具名称列表（可选）

   支持以下两种格式用于工具过滤选项：

   --include-tools tool1,tool2,tool3    # 空格分隔格式
   --include-tools=tool1,tool2,tool3    # 等号分隔格式
   

3. 从客户端连接：

   • 本地连接：http://localhost:8000/sse
   • 从 Windows 到 WSL：http://<WSL_IP>:8000/sse
   • 获取您的 WSL IP：hostname -I | awk '{print $1}'

预定义脚本

仓库中包含了几个针对常见用例的预定义 npm 脚本：

# Start the server with default settings
npm start

# Start with CFI API path
npm run start:cfi

# Start with local environment
npm run start:local

# Start with only specific tools included
npm run start:include-tools

# Start with specific tools excluded
npm run start:exclude-tools

开发

运行测试

运行所有测试：

npm test

运行特定测试文件：

npm test test/bruno-parser-auth.test.ts

调试

服务器使用 debug 库进行详细日志记录。您可以通过设置 DEBUG 环境变量来启用不同的调试命名空间：

# Debug everything
DEBUG=* npm start

# Debug specific components
DEBUG=bruno-parser npm start    # Debug Bruno parser operations
DEBUG=bruno-request npm start   # Debug request execution
DEBUG=bruno-tools npm start     # Debug tool creation and registration

# Debug multiple specific components
DEBUG=bruno-parser,bruno-request npm start

# On Windows CMD:
set DEBUG=bruno-parser,bruno-request && npm start

# On Windows PowerShell:
$env:DEBUG='bruno-parser,bruno-request'; npm start

可用的调试命名空间：

• bruno-parser: Bruno API 集合解析和环境处理
• bruno-request: 请求执行和响应处理
• bruno-tools: 工具创建和注册到 MCP 服务器

工具

列出环境

列出您的 Bruno API 集合中的所有可用环境：

• 不需要参数
• 返回：
  • 可用环境列表
  • 当前活动环境

回显

回显您发送的消息（适用于测试）：

• 参数：message (字符串)

Bruno API 集合结构

您的 Bruno API 集合应遵循标准的 Bruno 结构：

collection/
├── collection.bru       # Collection settings
├── environments/       # Environment configurations
│   ├── local.bru
│   └── remote.bru
└── requests/          # API requests
    ├── request1.bru
    └── request2.bru

集合中的每个请求将自动转换为 MCP 工具，使其可通过 MCP 协议使用。

使用自定义参数与工具

在调用从您的 Bruno API 集合生成的工具时，您可以通过提供以下内容来自定义请求：

环境覆盖

您可以为特定请求指定不同的环境：

{
  "environment": "us-dev"
}

这将使用指定环境中的变量而不是默认环境中的变量。

变量替换

您可以为单个请求覆盖特定变量：

{
  "variables": {
    "dealId": "abc123",
    "customerId": "xyz789",
    "apiKey": "your-api-key"
  }
}

这些变量将在 URL、头部和请求体中被替换。例如，如果您的请求 URL 是：

{{baseUrl}}/api/deal/{{dealId}}

并且您提供了 { "variables": { "dealId": "abc123" } }，则实际使用的 URL 将是：

https://api.example.com/api/deal/abc123

查询参数

您可以直接添加或覆盖查询参数：

{
  "query": {
    "limit": "10",
    "offset": "20",
    "search": "keyword"
  }
}

无论原始请求中是否定义了这些查询参数，这都会将它们添加到 URL 中。例如，如果您的请求 URL 是：

{{baseUrl}}/api/deals

并且您提供了 { "query": { "limit": "10", "search": "keyword" } }，则实际使用的 URL 将是：

https://api.example.com/api/deals?limit=10&search=keyword

这种方法比使用变量来覆盖查询参数更清晰和明确。

自定义正文参数

您还可以在请求正文中提供自定义参数：

{
  "body": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

完整示例

这里是一个结合了所有四种定制类型的完整示例：

{
  "environment": "staging",
  "variables": {
    "dealId": "abc123",
    "apiKey": "test-key-staging"
  },
  "query": {
    "limit": "5",
    "sort": "created_at"
  },
  "body": {
    "status": "approved",
    "amount": 5000
  }
}

许可证

MIT