Elasticsearch MCP Server

Elasticsearch MCP サーバー

Elasticsearch を統合する Model Context Protocol（MCP）サーバーです。複数のチームと環境をサポートします。このサーバーを使うと、AI アシスタントがチームや環境をまたいで、例外の検索、パターンの分析、ログのクエリを安全かつ体系的に行えます。

特長

• 複数チームのサポート：各チームが独自の Elasticsearch クラスターを設定できます
• 複数環境のサポート：チームごとに開発、ステージング、本番環境をサポートします
• 例外の検索：フィルタリングと頻度順の並べ替えが可能な柔軟な例外検索
• 例外の分析：特定の例外を詳細に分析し、原因と解決策を提案します
• 傾向の分析：例外のパターンや頻度の傾向、サービスの健全性を分析します
• ログ検索：さまざまなフィルターを使ってアプリケーションログを検索します
• 接続テスト：チームや環境ごとに Elasticsearch の接続をテストします
• 柔軟な認証：API キーとユーザー名／パスワードによる認証をサポートします
• HTTP および STDIO トランスポート：HTTP+SSE と STDIO の両方のトランスポートプロトコルをサポートします

インストール

npm install

設定

環境変数

• LOG_LEVEL：ログレベル（デフォルト：info）。ロガーが直接処理します
• HTTP_PATH_PREFIX：HTTP パスのプレフィックス（デフォルト：/）
• TEAMS_CONFIG_PATH：チーム設定ファイルのパス（任意）
• PORT：HTTP サーバーのポート（デフォルト：3000）

チームの設定

teams-config.example.json をもとに、teams-config.json ファイルを作成します。

{
  "server": {
    "name": "elasticsearch-mcp",
    "version": "1.0.0"
  },
  "teams": {
    "team-alpha": {
      "teamId": "team-alpha",
      "teamName": "Team Alpha",
      "defaultEnvironment": "production",
      "environments": {
        "staging": {
          "node": "https://alpha-staging-es.company.com",
          "apiKey": "your-api-key"
        },
        "production": {
          "node": "https://alpha-prod-es.company.com",
          "apiKey": "your-api-key"
        }
      },
      "indexPatterns": {
        "exceptions": ["alpha-logs-*", "alpha-exceptions-*"],
        "applications": ["alpha-apm-*", "alpha-metrics-*"],
        "logs": ["alpha-app-logs-*"]
      },
      "maxSearchResults": 50,
      "allowedOperations": ["search_exceptions", "analyze_exception", "analyze_trends", "search_logs", "test_connection"]
    }
  }
}

設定オプション

• teamId：チームの一意の識別子
• teamName：チームの人間が読みやすい名前
• defaultEnvironment：環境が指定されていない場合に使用するデフォルト環境
• environments：環境ごとの Elasticsearch 接続設定
  • node：Elasticsearch クラスターの URL
  • apiKey：認証用の API キー（任意）
  • username/password：基本認証（任意）
  • maxRetries：最大再試行回数（デフォルト：3）
  • requestTimeout：リクエストのタイムアウト（ミリ秒、デフォルト：30000）
• indexPatterns：データの種類ごとのインデックスパターン
  • exceptions：例外／エラーログのパターン
  • applications：アプリケーションのメトリクス／APM データのパターン
  • logs：一般的なアプリケーションログのパターン
• maxSearchResults：返す結果の最大数（デフォルト：50）
• allowedOperations：このチームで許可する操作の一覧（任意）

使い方

STDIO モード（MCP クライアント向け）

npm run dev
# or
npm start

HTTP モード（Web インターフェース向け）

npm run start-http
# or
npm run dev -- --http

HTTP サーバーは次のエンドポイントで利用できます。

• SSE エンドポイント：GET http://localhost:3000/sse
• メッセージエンドポイント：POST http://localhost:3000/messages
• ヘルスチェック：GET http://localhost:3000/health

利用可能なツール

1. search_exceptions 🔍

高度なフィルタリングと並べ替えに対応した、柔軟な例外検索です。

パラメーター：

• environment（任意）：検索する環境
• message（任意）：例外メッセージの内容で絞り込みます
• query（任意）：例外メッセージまたはスタックトレースの検索語
• service（任意）：サービス名で絞り込みます
• severity（任意）：ログの重大度で絞り込みます
• timeRange（任意）：カスタム時間範囲
  • start：開始時刻（ISO 形式）
  • end：終了時刻（ISO 形式）
• timeframe（任意）：定義済みの時間範囲（1h、6h、12h、24h、7d）
• limit（任意）：返す結果の数（デフォルト：20、最大：100）
• sortByFrequency（任意）：頻度順に並べ替えます（頻度の高いものが先）

使用例：

• 「このコミット／プルリクエストに関連する例外はどれですか？」
• 「過去 6 時間の Database 関連の例外をすべて表示してください」
• 「User-Service で最も頻繁に発生している例外を見つけてください」

2. analyze_exception 🔬

特定の例外を原因や解決策の提案とともに詳細に分析します。

パラメーター：

• environment（任意）：分析する環境
• exceptionMessage（必須）：分析する特定の例外メッセージ
• timeframe（任意）：分析対象の期間（デフォルト：24h）

ユースケース：

• 「この例外を分析してください：'NullPointerException in UserService'」
• 「'Connection timeout' エラーの原因は何ですか？」

3. analyze_trends 📈

例外のパターン、発生頻度の傾向、サービスの稼働状況を経時的に分析します。

パラメーター：

• environment（任意）：分析する環境
• timeRange（任意）：分析対象の期間を指定します
• timeframe（任意）：あらかじめ定義された期間（デフォルト：24h）
• analysisType（任意）：分析の種類（exceptions、services、both）
• services（任意）：分析する特定のサービスのリスト

ユースケース：

• 「過去24時間で発生頻度が増加した例外は何ですか？」
• 「最近、例外を多く発生させているサービスはどれですか？」
• 「Payment システムの例外の傾向を表示してください」

4. search_logs 📋

フィルタリング機能を使って、アプリケーションの一般的なログを検索します。

パラメーター：

• environment（任意）：検索する環境
• message（任意）：ログメッセージの内容で絞り込みます
• service（任意）：サービス名で絞り込みます
• timeRange（任意）：検索対象の期間（デフォルトは直近1時間）

ユースケース：

• 「過去1時間の User サービスのログをすべて表示してください」
• 「'payment failed' を含むログを検索してください」

5. test_connection 🔌

チームと環境の Elasticsearch 接続をテストします。

パラメーター：

• environment（任意）：テストする環境

ユースケース：

• 「Production への接続をテストしてください」
• 「Elasticsearch に接続できますか？」

🚀 よく使うプロンプトとユースケース

例外の調査

"Welche Exceptions sind in den letzten 24h häufiger aufgetreten?"
→ Uses: analyze_trends with analysisType="exceptions"

"Mir ist diese Exception 'OutOfMemoryError' aufgefallen, finde mehr über sie heraus"
→ Uses: analyze_exception with exceptionMessage="OutOfMemoryError"

"Welche Exceptions passen zu diesem API-Endpoint /users/profile?"
→ Uses: search_exceptions with query="/users/profile"

サービスの稼働状況の監視

"Welche Services werfen in letzter Zeit mehr Exceptions?"
→ Uses: analyze_trends with analysisType="services"

"Zeige mir alle Exceptions vom Payment-Service der letzten 6 Stunden"
→ Uses: search_exceptions with service="payment-service" and timeframe="6h"

デバッグとトラブルシューティング

"Suche nach Database-Connection-Errors der letzten 24h"
→ Uses: search_exceptions with query="database connection" and timeframe="24h"

"Analysiere die häufigsten Exceptions im User-Service"
→ Uses: search_exceptions with service="user-service" and sortByFrequency=true

🛠️ 開発

コード品質

このプロジェクトでは、高いコード品質基準を維持しています。

# Run all quality checks
npm run check

# Individual checks
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint code analysis
npm run format:check # Prettier formatting check

# Auto-fix issues
npm run lint:fix     # Fix ESLint issues
npm run format       # Format code with Prettier

ビルド

# Build the project
npm run build

# Clean build artifacts
npm run clean

スクリプトの概要

• npm run dev - ホットリロードで開発サーバーを起動します
• npm run build - 本番用にビルドします
• npm run start - 本番用にビルドしてサーバーを起動します
• npm run cli - CLI ツールを実行します
• npm run check - すべての品質チェックを実行します

アーキテクチャ

このサーバーはモジュール式アーキテクチャで構築されています。

• ConfigManager：チーム設定の読み込みと検証を処理します
• ElasticsearchService：Elasticsearch の接続とクエリを管理します
• MCP ツール：さまざまな操作に対応する個別のツール（最適化されたツールを5つ）
• HTTP サーバー：Web インターフェース向けに HTTP+SSE トランスポートを提供します
• STDIO トランスポート：MCP クライアント向けに STDIO トランスポートを提供します

ツール設計の方針

ツールは次の原則に基づいて設計されています。

• 短く覚えやすい名前（11～17文字）
• 役割の明確な分担（検索、分析、傾向分析）
• さまざまなユースケースに対応する柔軟なパラメーター
• ツール間で機能の重複がないこと

セキュリティに関する考慮事項

• 機密性の高い認証情報（API キー、パスワード）は安全に保管してください
• 機密性の高い設定には環境変数を使用してください
• Elasticsearch 接続のネットワークセキュリティを考慮してください
• チームごとに適切なアクセス制御を実装してください
• allowedOperations 設定を使用して、チームの機能を制限してください

エラー処理

このサーバーには、包括的なエラー処理が含まれています。

• 起動時の設定検証
• リトライを伴う接続エラー処理
• 利用できないサービスに対するグレースフルな縮退運転
• トラブルシューティングのための詳細なログ記録

ライセンス

MIT

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 必要に応じてテストを追加します
5. リントとフォーマットを実行します
6. プルリクエストを送信します