Bruno MCP Server

🚀 Bruno MCP Server

Bruno MCP Serverは、APIテストとコレクション管理のためにBruno CLIとの統合を提供するMCP（Model Context Protocol）サーバーです。このサーバーを使用することで、Brunoコレクションから個々の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）
• ✅ コレクションの検出と検証
• ✅ リクエストのイントロスペクションとドライランモード
• ✅ ヘルスモニタリングとパフォーマンスメトリクス
• ✅ セキュリティ機能（パス検証、シークレットマスキング）
• ✅ 最適なパフォーマンスのためのキャッシング
• ✅ テストとCI/CDのためのモックCLIモード

📦 インストール

前提条件

• 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

📚 ドキュメント

📚 ガイド

• Getting Started - Bruno MCP Serverのインストールと構成のステップバイステップガイド
• Configuration - 完全な構成リファレンスとオプション
• Usage Patterns - 一般的なワークフローとベストプラクティス
• Troubleshooting - 一般的な問題の解決策
• CI/CD Integration - GitHub Actions、GitLab CI、CircleCIとの統合
• Mock Mode - Bruno CLI依存関係なしでのテスト

🔧 APIリファレンス

• MCP Tools API - すべての9つのMCPツールの完全なリファレンスと例

🔧 技術詳細

レポート生成

Bruno MCP Serverは、3つの形式でテストレポートを生成することができます。

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

開発

開発モードで実行

npm run dev

テストを実行

npm test

ビルド

npm run build

構成

Bruno MCP Serverは、bruno-mcp.config.jsonファイルを介した構成をサポートしています。サーバーは、このファイルを次の場所で探します（順番に）。

1. 環境変数: BRUNO_MCP_CONFIG
2. 現在の作業ディレクトリ: ./bruno-mcp.config.json
3. ホームディレクトリ: ~/.bruno-mcp.config.json

構成オプション

{
  "brunoCliPath": "/custom/path/to/bru",
  "brunoHome": "/path/to/bruno/home",
  "timeout": {
    "request": 30000,
    "collection": 120000
  },
  "retry": {
    "enabled": true,
    "maxAttempts": 3,
    "backoff": "exponential"
  },
  "security": {
    "allowedPaths": [
      "/path/to/collections",
      "/another/path"
    ],
    "maskSecrets": true,
    "secretPatterns": [
      "password",
      "api[_-]?key",
      "token",
      "secret",
      "authorization"
    ]
  },
  "logging": {
    "level": "info",
    "format": "json"
  },
  "performance": {
    "cacheEnabled": true,
    "cacheTTL": 300000
  }
}

構成の詳細

• brunoCliPath: Bruno CLI実行可能ファイルへのカスタムパス（デフォルト: 自動検出）
• brunoHome: 環境と設定のためのBrunoホームディレクトリ
• timeout.request: 個々のリクエストのタイムアウト（ミリ秒）（デフォルト: 30000）
• timeout.collection: コレクション実行のタイムアウト（ミリ秒）（デフォルト: 120000）
• retry.enabled: 失敗時の自動リトライを有効にする（デフォルト: false）
• retry.maxAttempts: 最大リトライ試行回数（1-10、デフォルト: 3）
• retry.backoff: リトライバックオフ戦略: 'linear'または'exponential'
• security.allowedPaths: 特定のパスに対するファイルシステムアクセスを制限する
• security.maskSecrets: ログとエラーメッセージでシークレットをマスキングする（デフォルト: true）
• security.secretPatterns: シークレット検出のための追加の正規表現パターン
• logging.level: ログレベル: 'debug'、'info'、'warning'、'error'（デフォルト: 'info'）
• logging.format: ログ形式: 'json'または'text'（デフォルト: 'text'）
• performance.cacheEnabled: リクエストリストのキャッシングを有効にする（デフォルト: true）
• performance.cacheTTL: キャッシュの有効期限（ミリ秒）（デフォルト: 300000）

完全な例については、bruno-mcp.config.example.jsonを参照してください。

セキュリティ機能

パス検証

サーバーは、すべてのファイルパスを検証して、ディレクトリトラバーサル攻撃を防止します。security.allowedPathsを構成して、特定のディレクトリへのアクセスを制限します。

入力サニタイズ

すべてのユーザー入力はサニタイズされ、コマンドインジェクションやその他のセキュリティ脆弱性を防止します。

シークレットマスキング

機密データ（APIキー、パスワード、トークン）は、ログとエラーメッセージで自動的にマスキングされます。security.secretPatternsを介して検出パターンをカスタマイズできます。

環境変数検証

環境変数は、安全な文字とパターンについて検証され、Bruno CLIに渡される前に検証されます。

パフォーマンス機能

リクエストリストのキャッシング

コレクションのリクエストリストは、メモリ内にキャッシュされ、TTLを構成できるため、ファイルシステム操作を減らすことができます。キャッシュヒットは、モニタリングのためにログに記録されます。

実行メトリクス

サーバーは、次のパフォーマンスメトリクスを追跡します。

• ツールごとの実行時間
• 成功/失敗率
• 平均応答時間
• 総実行数

includeMetrics: trueを使用してbruno_health_checkツールを介してこれらのメトリクスにアクセスできます。

プロジェクト構造

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操作
• リクエスト実行の失敗
• 不正な入力パラメータ

トラブルシューティング

詳細なトラブルシューティングについては、トラブルシューティングガイドを参照してください。

クイック修正

Bruno CLIが見つからない場合:

1. 依存関係がインストールされていることを確認します: npm install
2. Bruno CLIがインストールされていることを確認します: npx bru --version
3. サーバーは自動的にnode_modules/.bin/bruのローカルインストールを使用します

コレクションが見つからない場合:

• 絶対パスを使用します（相対パスではなく）
• コレクションパスが正しいことを確認します
• ディレクトリにbruno.jsonファイルが含まれていることを確認します

パーミッションの問題:

• MCPサーバーがBrunoコレクションに読み取りアクセス権を持っていることを確認します
• サーバーがBruno CLIを実行できることを確認します

次のステップ

完全な機能ロードマップについては、ROADMAP.mdを参照してください。

完了した機能:

• ✅ Bruno CLIとの統合を備えたコアMCPサーバー
• ✅ リクエストとコレクションの実行
• ✅ 環境サポート
• ✅ レポート生成（JSON、JUnit、HTML形式）
• ✅ コレクションの検出（再帰的検索）
• ✅ 環境管理（一覧表示、検証）
• ✅ リクエストのイントロスペクション（実行せずに調べる）
• ✅ ドライランモード（HTTP実行なしで検証）
• ✅ コレクションの検証（構造、構文、整合性チェック）
• ✅ 複数の場所をサポートする構成システム
• ✅ セキュリティ強化（パス検証、入力サニタイズ、シークレットマスキング）
• ✅ パフォーマンス最適化（リクエストリストのキャッシング、実行メトリクス）
• ✅ ヘルスチェックツール

計画されている機能強化:

• 構造化出力を備えたロギングシステム
• 並列実行サポート
• 高度なフィルタリングと検索機能

コントリビュート

コントリビューションは大歓迎です！問題やプルリクエストを自由に送信してください。

📄 ライセンス

MIT