Bruno MCP Server

🚀 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：從源代碼安裝

1. 克隆倉庫：

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

2. 構建後的服務器將位於 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 許可證。