MCP Prometheus Server

MCP Prometheus Server

概要

Prometheus のメトリクスやクエリに Claude Desktop からアクセスできる、Haskell 製の本番環境向け Model Context Protocol（MCP）サーバー実装です。適切な例外処理、厳密評価のパターン、包括的なエラー復旧など、Haskell のベストプラクティスに基づいて構築されています。

「The Adeon Special」 - v1.0.1 では、よくある落とし穴を避け、スレッドセーフで堅牢な動作を実現する高度な Haskell 技法を取り入れています。

特長

• 🚀 Claude Desktop との連携 - MCP プロトコルをシームレスにサポート
• 📊 Prometheus API を完全サポート - メトリクスのクエリ、検出、調査が可能
• 🔍 強力な 5 つのツール - 即時クエリからメトリクスの検出まで対応
• 🛡️ 本番環境に対応 - 包括的なエラー処理とログ記録
• 🧵 スレッドセーフ - 厳密評価により遅延 I/O によるハングを防止
• 🔧 Haskell のベストプラクティス - 適切な例外処理を採用し、SomeException のアンチパターンは不使用
• 🧪 テストカバレッジ - 単体テストと統合テストを同梱

クイックスタート

オプション 1：ビルド済みバイナリを使用（推奨）

1. リポジトリをクローンします：

git clone https://github.com/drewstreib/mcp-prom-haskell.git
cd mcp-prom-haskell/mcp-prometheus-server

2. ビルド済みバイナリを使用します：

./testbin/mcp-prometheus-server --prometheus-url http://your-prometheus-server:9090

オプション 2：ソースからビルド

make build
# Binary will be in testbin/mcp-prometheus-server

オプション 3：Docker（開発用）

# Start test Prometheus instance
docker-compose up -d prometheus

# Build and run
docker build -t mcp-prometheus-server .
docker run -it --rm \
  --network mcp-prometheus-server_mcp-network \
  -e PROMETHEUS_URL=http://prometheus:9090 \
  mcp-prometheus-server

Claude Desktop の設定

Claude Desktop の設定ファイルに追加します：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json
Linux： ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "prometheus": {
      "command": "/path/to/mcp-prom-haskell/mcp-prometheus-server/testbin/mcp-prometheus-server",
      "args": [
        "--prometheus-url",
        "http://your-prometheus-server:9090"
      ]
    }
  }
}

/path/to/ をリポジトリの実際のパスに置き換えてください。

利用可能なツール

1. prometheus_query

特定の時点で PromQL クエリを即時実行します。

例：「現在の CPU 使用率は？」

rate(node_cpu_seconds_total[5m])

2. prometheus_query_range

傾向の把握や分析のため、指定した時間範囲にわたってクエリを実行します。

例：「過去 1 時間のメモリ使用量を表示して」

node_memory_Active_bytes

3. prometheus_series

指定したラベルセレクターに一致する時系列を検索します。

例：「node-exporter ジョブで利用可能なメトリクスは？」

4. prometheus_metrics

システムで利用可能なすべてのメトリクス名を一覧表示します。

例：「クエリ可能なメトリクスは？」

5. prometheus_labels

メトリクス全体で使われているすべてのラベル名を検出します。

例：「フィルタリングに使えるラベルは？」

Haskell の実装詳細

このサーバーでは、本番環境向けの Haskell のプラクティスを採用しています。

例外処理

• SomeException のアンチパターンは不使用 - 回復可能な特定の例外のみを捕捉します
• I/O 操作には IOException を使用 - stdin/stdout の障害を適切に処理します
• ネットワーク呼び出しには HttpException を使用 - Prometheus 接続エラーの詳細を提示します

スレッドセーフとパフォーマンス

• 厳密評価に BangPatterns を使用 - ログ記録での遅延 I/O によるハングを防止します
• タイムスタンプ付きの構造化ログ - スレッドセーフでアトミックなログ書き込みを行います
• UTF-8 テキスト処理 - 全体で適切な Unicode サポートを提供します

JSON-RPC への準拠

• 通知を適切に処理 - 仕様に従い、通知には応答しません
• 型安全なメッセージ解析 - 包括的なエラー復旧に対応します
• プロトコルバージョンの一致 - Claude Desktop と完全な互換性があります

手動インストール

前提条件

• GHC 9.12+ および Cabal 3.0+
• または GHCup を使用（推奨）：

curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh

ビルド

git clone https://github.com/drewstreib/mcp-prom-haskell.git
cd mcp-prom-haskell/mcp-prometheus-server
make build

テスト

Docker でテストを実行

docker-compose run --rm mcp-prometheus-server-test

手動でテストを実行

# Unit tests only
cabal test

# With integration tests (requires Prometheus)
export PROMETHEUS_URL=http://your-prometheus-server:9090
cabal test

設定

環境変数

• PROMETHEUS_URL - Prometheus サーバーの URL（デフォルト：http://your-prometheus-server:9090）

コマンドラインオプション

mcp-prometheus-server --prometheus-url http://prometheus:9090

開発

プロジェクト構成

mcp-prometheus-server/
├── app/            # Main executable
├── src/            # Library source code
│   ├── MCP/        # MCP protocol implementation
│   └── Prometheus/ # Prometheus client
├── test/           # Test suites
├── Dockerfile      # Docker image definition
└── docker-compose.yml # Development environment

新しいエンドポイントの追加

1. src/Prometheus/Client.hs にクライアント関数を追加します
2. src/MCP/Server.hs にツール定義を追加します
3. test/IntegrationSpec.hs にテストを追加します
4. ドキュメントを更新します

トラブルシューティング

Docker の問題

コンテナがすぐに終了する：MCP サーバーは stdio でのやり取りを想定しています。-it フラグを使用してください。

docker run -it --rm mcp-prometheus-server:latest

Prometheus に接続できない：コンテナが同じネットワーク上にあることを確認してください。

docker network create mcp-net
docker run --network mcp-net ...

ビルドの問題

Cabal の依存関係エラー：パッケージインデックスを更新してください。

cabal update

GHC のバージョン不一致：GHCup を使って正しいバージョンをインストールしてください。

ghcup install ghc 9.6.4
ghcup set ghc 9.6.4

コントリビューション

コントリビューションを歓迎します！予定している機能については ROADMAP.md を参照してください。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 新しい機能のテストを追加します
4. すべてのテストが合格することを確認します
5. プルリクエストを送信します

ライセンス

BSD 3-Clause License の詳細については、LICENSE ファイルを参照してください。

謝辞

• Haskell のベストプラクティス、例外処理のパターン、遅延評価でよくある落とし穴の回避について、貴重なご指導をいただいた Adeon に心より感謝します
• Model Context Protocol を使用して構築
• Prometheus を活用
• Haskell で記述

「Adeon Special」- v1.0.1

このリリースは、よくある落とし穴を回避する、本番環境で使用できる Haskell コードを表しています。

• ✅ SomeException のアンチパターンなし
• ✅ I/O 負荷の高い関数での厳格な評価
• ✅ スレッドセーフなロギングパターン
• ✅ JSON-RPC 通知の適切な処理
• ✅ クラッシュを起こさない包括的なエラー復旧