JinDaGe - bruno-mcp-server MCP Details

article

README

🚀 Bruno MCP 服务器

Bruno MCP 服务器是一个基于 MCP（模型上下文协议）的服务器，它可与 Bruno CLI 集成，用于 API 测试和集合管理，为开发者提供了便捷的 API 测试和管理方案。

🚀 快速开始

通过 NPM 安装（推荐）

# 全局安装
npm install -g bruno-mcp-server

# 或者在项目中本地安装
npm install bruno-mcp-server

从源代码安装

# 克隆仓库
git clone https://github.com/jcr82/bruno-mcp-server.git
cd bruno-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

✨ 主要特性

核心特性

✅ 运行 Bruno 集合中的单个 API 请求
✅ 运行整个集合或特定文件夹
✅ 列出集合中的所有请求
✅ 支持环境变量并进行验证
✅ 生成报告（JSON、JUnit、HTML）
✅ 集合发现和验证
✅ 请求内省和预运行模式
✅ 健康监测和性能指标
✅ 安全特性（路径验证、密钥掩码）
✅ 缓存以实现最佳性能
✅ 模拟 CLI 模式，用于测试和 CI/CD

📦 安装指南

前提条件

Node.js：版本 20 或更高
Bruno 集合：现有的 Bruno API 测试集合

选项 1：NPM 全局安装

npm install -g bruno-mcp-server

此方法将全局安装服务器，使其可作为命令使用。

选项 2：NPM 本地安装

npm install bruno-mcp-server

使用 node_modules/.bin/bruno-mcp-server 将其添加到 MCP 客户端配置中。

选项 3：从源代码安装

克隆仓库：

git clone https://github.com/jcr82/bruno-mcp-server.git
cd bruno-mcp-server
npm install
npm run build

构建后的服务器将位于 dist/index.js。

💻 使用示例

基础用法

1. 运行特定请求

bruno_run_request({
  collectionPath: "/path/to/collection",
  requestName: "Get User",
  environment: "dev",               // 可选 - 环境名称或路径
  envVariables: {                   // 可选
    "API_KEY": "your-key"
  },
  // 报告生成选项（可选）
  reporterJson: "./reports/results.json",    // JSON 报告
  reporterJunit: "./reports/results.xml",    // 用于 CI/CD 的 JUnit XML
  reporterHtml: "./reports/results.html",    // HTML 报告
  dryRun: false                     // 可选 - 验证但不执行 HTTP 调用
})

预运行模式：将 dryRun 设置为 true 以验证请求配置而不执行 HTTP 调用：

bruno_run_request({
  collectionPath: "/path/to/collection",
  requestName: "Create User",
  dryRun: true  // 仅验证配置 - 不进行 HTTP 调用
})

输出：

=== DRY RUN: Request Validation ===

✅ Request validated successfully (HTTP call not executed)

Request: Create User
Method: POST
URL: {{baseUrl}}/api/users

Configuration Summary:
  Headers: 2
  Body: json
  Auth: bearer
  Tests: 3

ℹ️  This was a dry run - no HTTP request was sent.

2. 运行集合

bruno_run_collection({
  collectionPath: "/path/to/collection",
  environment: "dev",                // 可选 - 环境名称或路径
  folderPath: "auth",                // 可选 - 运行特定文件夹
  envVariables: {                    // 可选
    "BASE_URL": "https://api.example.com"
  },
  // 报告生成选项（可选）
  reporterJson: "./reports/collection.json",
  reporterJunit: "./reports/collection.xml",
  reporterHtml: "./reports/collection.html",
  dryRun: false                      // 可选 - 验证但不执行 HTTP 调用
})

集合的预运行模式：

bruno_run_collection({
  collectionPath: "/path/to/collection",
  folderPath: "Users",
  dryRun: true  // 验证所有请求但不进行 HTTP 调用
})

输出：

=== DRY RUN: Collection Validation ===

✅ Collection validated successfully (HTTP calls not executed)

Total Requests: 5

Requests that would be executed:
  ✓ Get All Users - GET {{baseUrl}}/users
  ✓ Get User By ID - GET {{baseUrl}}/users/1
  ✓ Create User - POST {{baseUrl}}/users
  ✓ Update User - PUT {{baseUrl}}/users/1
  ✓ Delete User - DELETE {{baseUrl}}/users/1

ℹ️  This was a dry run - no HTTP requests were sent.

3. 列出请求

bruno_list_requests({
  collectionPath: "/path/to/collection"
})

4. 发现集合

递归搜索目录中的 Bruno 集合：

bruno_discover_collections({
  searchPath: "/path/to/workspace",
  maxDepth: 5  // 可选 - 最大目录深度（默认：5，最大：10）
})

示例输出：

Found 3 Bruno collection(s):

1. /path/to/workspace/api-tests
2. /path/to/workspace/projects/integration-tests
3. /path/to/workspace/e2e-tests

5. 列出环境

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

bruno_list_environments({
  collectionPath: "/path/to/collection"
})

示例输出：

Found 3 environment(s):

• dev
  Path: /path/to/collection/environments/dev.bru
  Variables: 5
    - baseUrl: https://api.dev.example.com
    - apiKey: ***
    - timeout: 5000

• staging
  Path: /path/to/collection/environments/staging.bru
  Variables: 5
    - baseUrl: https://api.staging.example.com
    - apiKey: ***
    - timeout: 10000

• production
  Path: /path/to/collection/environments/production.bru
  Variables: 5
    - baseUrl: https://api.example.com
    - apiKey: ***
    - timeout: 15000

6. 验证环境

验证环境文件的结构和变量：

bruno_validate_environment({
  collectionPath: "/path/to/collection",
  environmentName: "dev"
})

示例输出：

=== Environment Validation: dev ===

✅ Status: Valid

Variables: 5

  baseUrl: https://api.dev.example.com
  apiKey: *** (masked)
  timeout: 5000
  region: us-east-1
  debug: true

Warnings:
  ⚠️  Variable "apiKey" may contain hardcoded sensitive data

7. 获取请求详情

在不执行请求的情况下检查其配置：

bruno_get_request_details({
  collectionPath: "/path/to/collection",
  requestName: "Create User"
})

示例输出：

=== Request Details: Create User ===

Method: POST
URL: {{baseUrl}}/api/users
Auth: bearer

Headers:
  Content-Type: application/json
  Authorization: Bearer {{token}}

Body Type: json
Body Content:
  {
    "name": "John Doe",
    "email": "john@example.com",
    "role": "user"
  }

Tests: 3
  1. Status should be 201
  2. Response should have an ID
  3. Email should match

Metadata:
  Type: http
  Sequence: 1

使用场景：

在执行前检查请求配置
调试请求设置问题
从请求生成文档
理解测试断言
审查请求结构

8. 验证集合

验证 Bruno 集合的结构、语法和完整性：

bruno_validate_collection({
  collectionPath: "/path/to/collection"
})

示例输出：

=== Collection Validation ===

✅ Collection is valid

Summary:
  bruno.json: ✓ Found
  Total Requests: 15
  Valid Requests: 15
  Invalid Requests: 0
  Environments: 3

Warnings:
  ⚠️  Environment "dev": Variable "apiKey" may contain hardcoded sensitive data

🎉 Collection is ready to use!

使用场景：

部署前的预飞行验证
CI/CD 管道检查
尽早发现配置错误
验证集合完整性
集合更新后进行验证

9. 健康检查

检查服务器健康状况、Bruno CLI 可用性，并可选择查看性能指标和缓存统计信息：

bruno_health_check({
  includeMetrics: true,      // 可选 - 包含性能指标
  includeCacheStats: true    // 可选 - 包含缓存统计信息
})

示例输出：

=== Bruno MCP Server Health Check ===

Server Status: Running
Server Version: 0.1.0
Node.js Version: v24.8.0
Platform: darwin arm64
Uptime: 42 seconds

=== Bruno CLI ===
Status: Available
Version: Available (use --version for details)

=== Configuration ===
Logging Level: info
Retry Enabled: Yes
Security Enabled: No restrictions
Secret Masking: Enabled
Cache Enabled: Yes
Cache TTL: 300000ms

=== Performance Metrics ===
Total Executions: 15
Success Rate: 100.00%
Average Duration: 234.56ms

By Tool:
  bruno_run_request:
    Executions: 10
    Success Rate: 100.00%
    Avg Duration: 189.23ms

=== Cache Statistics ===
Request List Cache:
  Size: 3 entries
  Total Hits: 25
  Cached Collections:
    - /path/to/collection1
    - /path/to/collection2
    - /path/to/collection3

=== Status ===
All systems operational

高级用法

报告生成

Bruno MCP 服务器支持生成三种格式的测试报告：

JSON 报告：以 JSON 格式包含详细的测试结果，非常适合进行编程处理。
JUnit XML 报告：与 Jenkins、GitHub Actions 和 GitLab CI 等 CI/CD 系统兼容，非常适合集成到自动化管道中。
HTML 报告：具有 Vue.js 界面的精美交互式 HTML 报告，便于在浏览器中查看。

示例：生成所有报告

bruno_run_collection({
  collectionPath: "./my-api-tests",
  environment: "production",
  reporterJson: "./reports/api-tests.json",
  reporterJunit: "./reports/api-tests.xml",
  reporterHtml: "./reports/api-tests.html"
})

服务器将在生成报告时进行确认：

=== Generated Reports ===
  Wrote json results to ./reports/api-tests.json
  Wrote junit results to ./reports/api-tests.xml
  Wrote html results to ./reports/api-tests.html

📚 详细文档

📚 指南

入门指南 - 逐步指导安装和配置 Bruno MCP 服务器
配置指南 - 完整的配置参考和选项
使用模式 - 常见工作流程和最佳实践
故障排除 - 常见问题的解决方案
CI/CD 集成 - 与 GitHub Actions、GitLab CI、CircleCI 集成
模拟模式 - 无需 Bruno CLI 依赖进行测试

🔧 API 参考

MCP 工具 API - 所有 9 个 MCP 工具的完整参考及示例

🔧 技术细节

项目结构

bruno-mcp-server/
├── src/
│   ├── index.ts        # 主要的 MCP 服务器实现
│   ├── bruno-cli.ts    # Bruno CLI 包装器
│   ├── config.ts       # 配置管理
│   ├── security.ts     # 安全验证实用工具
│   └── performance.ts  # 缓存和指标跟踪
├── dist/               # 编译后的 JavaScript（构建后）
├── bruno-mcp.config.json         # 活动配置
├── bruno-mcp.config.example.json # 示例配置
├── package.json
├── tsconfig.json
└── README.md

错误处理

服务器能够正确处理和报告以下问题：

缺少 Bruno CLI 安装
无效的集合路径
不支持的 Bruno CLI 操作
请求执行失败
输入参数格式错误

安全特性

路径验证：服务器验证所有文件路径，防止目录遍历攻击。可通过配置 security.allowedPaths 限制对特定目录的访问。
输入清理：所有用户输入都经过清理，以防止命令注入和其他安全漏洞。
密钥掩码：敏感数据（API 密钥、密码、令牌）会在日志和错误消息中自动掩码。可通过 security.secretPatterns 自定义检测模式。
环境变量验证：环境变量在传递给 Bruno CLI 之前会进行安全字符和模式验证。

性能特性

请求列表缓存：集合请求列表会在内存中缓存，并可配置 TTL，以减少文件系统操作。缓存命中会被记录以便监控。
执行指标：服务器跟踪性能指标，包括：
- 每个工具的执行持续时间
- 成功/失败率
- 平均响应时间
- 总执行次数

可通过 bruno_health_check 工具并设置 includeMetrics: true 访问这些指标。

📄 许可证

本项目采用 MIT 许可证。

bruno-mcp-server

README

🚀 Bruno MCP 服务器

🚀 快速开始

通过 NPM 安装（推荐）

从源代码安装

✨ 主要特性

核心特性

📦 安装指南

前提条件

选项 1：NPM 全局安装

选项 2：NPM 本地安装

选项 3：从源代码安装

💻 使用示例

基础用法

1. 运行特定请求

2. 运行集合

3. 列出请求

4. 发现集合

5. 列出环境

6. 验证环境

7. 获取请求详情

8. 验证集合

9. 健康检查

高级用法

报告生成

示例：生成所有报告

📚 详细文档

📚 指南

🔧 API 参考

🔧 技术细节

项目结构

错误处理

安全特性

性能特性

📄 许可证

Runtime guide

Hosted runtime

Local runtime / other methods