Honeycomb MCP Server

Honeycomb MCP サーバー

日本語で読む

概要

このサーバーは、Model Context Protocol (MCP)を使用して、Claude AI が Honeycomb APIと連携できるようにするインターフェースです。

この MCP サーバーを使用すると、Claude AI は Honeycomb のデータセット、クエリ、イベント、ボード、マーカー、SLO、トリガーの取得、作成、更新などの操作を実行できます。

リポジトリについて

このリポジトリでは、Honeycomb MCP サーバーのスタンドアロン実装を提供しています。Claude AI と Honeycomb を連携させ、オブザーバビリティとモニタリングのワークフローを効率化します。

セットアップ

前提条件

• Node.js 18 以降
• Honeycomb API キー

インストール

# Install globally
npm install -g @kajirita2002/honeycomb-mcp-server

# Or use directly with npx
npx @kajirita2002/honeycomb-mcp-server

環境変数の設定

# Set environment variables
export HONEYCOMB_API_KEY="your_honeycomb_api_key"

MCP の設定例

この MCP サーバーを使用する場合は、次の設定を mcp_config.json ファイルに追加してください。

"honeycomb": {
  "command": "npx",
  "args": ["-y", "@kajirita2002/honeycomb-mcp-server"],
  "env": {
    "HONEYCOMB_API_KEY": "your_honeycomb_api_key"
  }
}

サーバーの起動

# Start the server
npm start

利用可能なツール

この MCP サーバーでは、次のツールを利用できます。

認証

1. honeycomb_auth
   • Honeycomb API で認証し、API キーを検証します
   • 入力パラメーターは不要です（環境変数を使用します）

データセットの管理

1. honeycomb_datasets_list

   • Honeycomb 環境内で利用可能なすべてのデータセットを一覧表示します
   • 入力パラメーターは不要です

2. honeycomb_dataset_get

   • 特定のデータセットに関する詳細情報を取得します
   • 入力：
     • datasetSlug（string、必須）：取得するデータセットのスラッグ

カラムの管理

1. honeycomb_columns_list
   • オプションのフィルタリングを使用して、データセット内のすべてのカラムを一覧表示します
   • 入力：
     • datasetSlug（string、必須）：データセットのスラッグ
     • key_name（string、任意）：特定のカラムキー名でフィルタリングします

クエリの管理

1. honeycomb_query_create

   • データセットの新しいクエリを作成します
   • 入力：
     • datasetSlug（string、必須）：データセットのスラッグ
     • query（object、必須）：計算、期間、フィルターを含むクエリ設定オブジェクト

2. honeycomb_query_get

   • 特定のクエリに関する情報を取得します
   • 入力：
     • datasetSlug（string、必須）：データセットのスラッグ
     • queryId（string、必須）：取得するクエリの ID

3. honeycomb_query_result_create

   • クエリを実行して結果を返します（クエリを実行します）
   • 入力：
     • datasetSlug（string、必須）：データセットのスラッグ
     • queryId（string、必須）：実行するクエリの ID
     • disable_series（boolean、任意）：系列データを無効にするかどうか
     • disable_total_by_aggregate（boolean、任意）：合計集計を無効にするかどうか
     • disable_other_by_aggregate（boolean、任意）：その他の集計を無効にするかどうか
     • limit（integer、任意）：結果数の上限

4. honeycomb_query_result_get

   • 以前に実行したクエリの結果を取得します
   • 入力：
     • datasetSlug（string、必須）：データセットのスラッグ
     • queryResultId（string、必須）：取得するクエリ結果の ID

データセット定義

1. honeycomb_dataset_definitions_list
   • ページネーションに対応したデータセット定義の一覧を取得します
   • 入力：
     • page（number、任意）：ページ番号（1 から開始）
     • limit（number、任意）：1 ページあたりの結果数（デフォルト：100、最大：1000）
     • sort_by（string、任意）：並べ替えの基準となるフィールド（例：'name'、'description'）
     • sort_order（string、任意）：並べ替え順（'asc' または 'desc'）

ボード管理

1. honeycomb_boards_list

   • 利用可能なすべてのボードを一覧表示します
   • 入力パラメーターは不要です

2. honeycomb_board_get

   • 特定のボードの詳細情報を取得します
   • 入力：
     • boardId（文字列、必須）：取得するボードの ID

使用例

Claude がこの MCP サーバーを使ってデータセットを一覧表示し、クエリを実行する例を紹介します。

[Claude] Can you show me the available datasets in our Honeycomb environment?

[User] Sure, I'd like to see what datasets we have in Honeycomb.

[Claude] I'll list all the available datasets in your Honeycomb environment.

I'll use the honeycomb_datasets_list tool...

Here are your available datasets:
- production-metrics (slug: prod-metrics)
- staging-services (slug: staging-svc)
- application-logs (slug: app-logs)

Which dataset would you like to explore further?

[User] Let's look at the production-metrics dataset.

[Claude] I'll get details about the production-metrics dataset using honeycomb_dataset_get with the slug "prod-metrics"...

Now I'll create and run a query to show the average response time over the last 24 hours.

I'll use honeycomb_query_create and then honeycomb_query_result_create...

Here are the results showing the average response time trend:
[Query results visualization description]

Input:
{
  "datasetSlug": "application-monitoring",
  "data": {
    "service": "api-gateway",
    "duration_ms": 45.2,
    "status_code": 200,
    "endpoint": "/users",
    "method": "GET"
  }
}

Event created successfully! You can now see this event in the Honeycomb UI under the Application Monitoring dataset.

[Claude] I can also create a query to analyze this data. Let me create a query that shows the average duration by endpoint.

I'll use the honeycomb_query_create tool:

Input:
{
  "datasetSlug": "application-monitoring",
  "query": {
    "calculations": [
      {
        "op": "AVG",
        "column": "duration_ms"
      }
    ],
    "breakdowns": ["endpoint"],
    "time_range": 3600
  }
}

一般的な統合パターン

1. オブザーバビリティの自動化

   [User] Claude, please help me set up a new SLO for API response times.
   
   [Claude] I can help with that. Let me create an SLO to track API response times.
   
   I'll use honeycomb_slo_create with these parameters:
   {
     "datasetSlug": "production-api",
     "name": "API Response Time SLO",
     "description": "Tracks response time for critical API endpoints",
     "sli": {
       "alias": "Response Time < 300ms",
       "conditions": {
         "column": "duration_ms",
         "operator": "<",
         "value": 300
       }
     },
     "time_period_days": 30,
     "target_per_million": 995000
   }
   

2. インシデント調査

   [User] We're seeing elevated error rates in production. Can you help investigate?
   
   [Claude] I'll help investigate the elevated error rates. Let me query the recent error data.
   
   First, I'll use honeycomb_query_result_create:
   {
     "datasetSlug": "production",
     "query": {
       "calculations": [
         {
           "op": "COUNT"
         }
       ],
       "filters": [
         {
           "column": "status_code",
           "operator": ">=",
           "value": 500
         }
       ],
       "breakdowns": ["service", "endpoint"],
       "time_range": 3600,
       "granularity": 60
     }
   }
   

説明「本番アプリケーションのモニタリング」でデータセット「Application Monitoring」を作成しています...

[Claude が honeycomb_datasets_create を使用]

データセットを作成しました。イベントを追加できます。

テスト用のサンプルイベントをデータセットに作成しますか？

[ユーザー] はい、サンプルイベントを追加してください。

[Claude] 「Application Monitoring」データセットにサンプルイベントを追加します。

[Claude が honeycomb_event_create を使用]

成功しました！以下のデータを含むサンプルイベントを「Application Monitoring」データセットに追加しました： { "service": "api-server", "message": "User login successful", "duration_ms": 45, "status_code": 200, "endpoint": "/api/login", "timestamp": "2025-03-25T14:30:00Z" }

このイベントは、45 ミリ秒で完了したユーザーのログイン成功を表しています。

Honeycomb ダッシュボードでこのイベントを確認し、データを分析するクエリを作成できるようになりました。

## Error Handling

This MCP server returns error information in a consistent format. When an error occurs, the following structure is returned:

```json
{
  "error": {
    "message": "Detailed error description",
    "code": "ERROR_CODE"
  }
}

一般的なエラーコード

• AUTH_ERROR：認証に失敗しました。API キーを確認してください。
• NOT_FOUND：要求されたリソースが見つかりませんでした。
• INVALID_PARAMETER：1 つ以上のパラメーターが無効です。
• RATE_LIMIT：Honeycomb API のレート制限に達しました。
• SERVER_ERROR：内部サーバーエラーが発生しました。

トラブルシューティングのヒント

1. 認証に関する問題

   • HONEYCOMB_API_KEY が正しく設定されていることを確認してください
   • API キーに適切な権限があることを確認してください

2. データセットが見つからない

   • データセットのスラッグが正しいことを確認してください（入力ミスがないか確認してください）
   • Honeycomb アカウントにデータセットが存在することを確認してください

3. クエリ実行に関する問題

   • クエリパラメーターが正しい形式になっていることを確認してください
   • クエリ内の列名がデータセット内の列名と一致していることを確認してください

コントリビューション

Honeycomb MCP サーバーへのコントリビューションを歓迎します！コントリビューションの方法は次のとおりです。

開発環境のセットアップ

1. リポジトリをフォークします
2. フォークをクローンします

   git clone https://github.com/your-username/honeycomb-mcp-server.git
   

3. 依存関係をインストールします

   npm install
   

4. 変更を加えます
5. ビルドを実行します

   npm run build
   

6. ローカル環境で変更をテストします

プルリクエストの手順

1. フィーチャーブランチを作成します

   git checkout -b feat-your-feature-name
   

2. Conventional Commits の形式に従って変更をコミットします

   git commit -m "feat: add new feature"
   

3. フォークにプッシュします

   git push origin feat-your-feature-name
   

4. プルリクエストを作成します

コーディング規約

• 新しいコードにはすべて TypeScript を使用します
• 既存のコードスタイルに従います
• パブリック API にはコメントを追加します
• 新しい機能にはテストを作成します

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。