Druid MCP Server

🚀 Druid MCP Server

Apache Druid用の包括的なモデルコンテキストプロトコル（MCP）サーバーです。Druidクラスターの管理と分析に必要な幅広いツール、リソース、およびプロンプトを提供します。

開発元: iunera - 高度なAIとデータ分析ソリューション

🚀 クイックスタート

前提条件

• Java 24
• Maven 3.6以上
• ポート8888でルーターを起動しているApache Druidクラスター

ビルドと実行

# アプリケーションをビルドする
mvn clean package -DskipTests

# アプリケーションを実行する
java -jar target/druid-mcp-server-1.0.0.jar

サーバーはデフォルトでポート8080で起動します。 詳細なビルド手順、テスト、Dockerセットアップ、および開発ガイドについては、development.mdを参照してください。

Maven Centralからのインストール

ソースからビルドせずに、事前にビルドされたJARを使用する場合は、Maven Centralから直接ダウンロードして実行できます。

前提条件

• Java 24 JREのみ

ダウンロードと実行

# アプリケーション用のディレクトリを作成する
mkdir druid-mcp-server && cd druid-mcp-server

# Maven CentralからJARをダウンロードする
curl -L -o druid-mcp-server-1.0.0.jar \
  "https://repo.maven.apache.org/maven2/com/iunera/druid-mcp-server/1.0.0/druid-mcp-server-1.0.0.jar"

# SSEトランスポート（HTTPベース、デフォルト）で実行する
java -jar druid-mcp-server-1.0.0.jar

# または、STDIOトランスポート（LLMクライアントに推奨）で実行する
java -Dspring.ai.mcp.server.stdio=true \
     -Dspring.main.web-application-type=none \
     -Dlogging.pattern.console= \
     -jar druid-mcp-server-1.0.0.jar

Dockerを使用したインストール

Dockerを使用する場合は、ローカルにJavaをインストールすることなく、Docker Hubから事前にビルドされたDockerイメージを直接実行できます。

前提条件

• Dockerがインストールされ、実行中であること

イメージの取得と実行

# 最新のDockerイメージを取得する
docker pull iunera/druid-mcp-server:latest

# SSEトランスポート（HTTPベース、デフォルト）で実行する
docker run -p 8080:8080 \
  -e DRUID_BROKER_URL=http://your-druid-broker:8082 \
  -e DRUID_COORDINATOR_URL=http://your-druid-coordinator:8081 \
  iunera/druid-mcp-server:latest

# または、STDIOトランスポート（LLMクライアントに推奨）で実行する
docker run --rm -i \
  -e SPRING_AI_MCP_SERVER_STDIO=true \
  -e SPRING_MAIN_WEB_APPLICATION_TYPE=none \
  -e LOGGING_PATTERN_CONSOLE= \
  -e DRUID_BROKER_URL=http://your-druid-broker:8082 \
  -e DRUID_COORDINATOR_URL=http://your-druid-coordinator:8081 \
  iunera/druid-mcp-server:latest

your-druid-broker と your-druid-coordinator を実際のDruidクラスターのエンドポイントに置き換えてください。

✨ 主な機能

• Spring AI MCP Serverとの統合
• MCPプロトコル準拠のツールベースのアーキテクチャ
• STDIOとSSEトランスポートのサポート
• 包括的なエラーハンドリング
• カスタマイズ可能なプロンプトテンプレート
• 機能ベースのパッケージ組織

MCPインスペクターインターフェイス

MCPクライアントに接続すると、MCPインスペクターインターフェイスを通じて利用可能なツール、リソース、およびプロンプトを調べることができます。

利用可能なツール

ツールインターフェイスには、データ管理、インジェスト管理、モニタリングとヘルスなどの機能領域別に整理された、利用可能なすべてのDruid管理機能が表示されます。

利用可能なリソース

リソースインターフェイスには、MCPプロトコルを通じて取得できる、アクセス可能なすべてのDruidデータソースとメタデータが表示されます。

利用可能なプロンプト

プロンプトインターフェイスには、さまざまなDruid管理タスクやデータ分析ワークフローに利用可能な、AI支援のガイダンステンプレートがすべて表示されます。

📚 ドキュメント

概要

このMCPサーバーは、各パッケージがDruid管理の異なる機能領域を表す機能ベースのアーキテクチャを実装しています。サーバーは3種類の主要なMCPコンポーネントを提供します。

• ツール - 操作を実行するための実行可能関数
• リソース - 情報にアクセスするためのデータプロバイダー
• プロンプト - AI支援のガイダンステンプレート

ビデオウォークスルー

MCPサーバーを使用してAIエージェントをApache Druidと統合する方法を学びましょう。このチュートリアルでは、Claude、ChatGPT、GeminiなどのAIアシスタントを使用した自然言語による時系列データの探索、統計分析、およびデータインジェストをデモンストレーションします。

上のサムネイルをクリックして、YouTubeでビデオを見る

機能別の利用可能なツール

データ管理

インジェスト管理

モニタリングとヘルス

機能別の利用可能なリソース

機能別の利用可能なプロンプト

設定

Druid接続を src/main/resources/application.properties で設定します。

# Spring AI MCP Serverの設定
spring.ai.mcp.server.name=druid-mcp-server
spring.ai.mcp.server.version=1.0.0

# Druidの設定
druid.router.url=http://localhost:8888

# サーバーの設定
server.port=8080

# 注意: STDIOトランスポートの場合は、バナーとコンソールログを無効にする必要があります
spring.main.banner-mode=off

環境変数による設定

ユーザー名やパスワードなどの機密情報については、プロパティファイルにハードコードする代わりに、環境変数を使用できます。

サポートされる環境変数

• DRUID_AUTH_USERNAME: Druid認証のユーザー名
• DRUID_AUTH_PASSWORD: Druid認証のパスワード
• DRUID_ROUTER_URL: デフォルトのDruidルーターURLを上書きする
• DRUID_SSL_ENABLED: SSL/TLSサポートを有効にする (true/false)
• DRUID_SSL_SKIP_VERIFICATION: SSL証明書の検証をスキップする (true/false)

認証付きSSL暗号化クラスター

このセクションでは、ユーザー名とパスワード認証を使用してSSL暗号化されたDruidクラスターに接続するための包括的なガイダンスを提供します。

前提条件

• HTTPSエンドポイントを持つSSL有効化されたDruidクラスター
• Druid認証に有効なユーザー名とパスワードの資格情報
• 適切に構成されたSSL証明書（またはテスト用に検証をスキップする機能）

設定方法

方法1: 環境変数（本番環境に推奨）

MCPサーバーを起動する前に、以下の環境変数を設定します。

# HTTPSを使用したDruidクラスターのURL
export DRUID_ROUTER_URL="https://your-druid-cluster.example.com:8888"

# 認証資格情報
export DRUID_AUTH_USERNAME="your-username"
export DRUID_AUTH_PASSWORD="your-password"

# SSL設定
export DRUID_SSL_ENABLED="true"
export DRUID_SSL_SKIP_VERIFICATION="false"  # テスト用のみ "true" を使用

# MCPサーバーを起動する
java -jar target/druid-mcp-server-1.0.0.jar

方法2: アプリケーションプロパティ

src/main/resources/application.properties を更新します。

# Druidクラスターの設定
druid.router.url=https://your-druid-cluster.example.com:8888

# 認証
druid.auth.username=your-username
druid.auth.password=your-password

# SSL設定
druid.ssl.enabled=true
druid.ssl.skip-verification=false

方法3: ランタイムシステムプロパティ

構成をJVMシステムプロパティとして渡します。

java -Ddruid.router.url="https://your-druid-cluster.example.com:8888" \
     -Ddruid.auth.username="your-username" \
     -Ddruid.auth.password="your-password" \
     -Ddruid.ssl.enabled=true \
     -Ddruid.ssl.skip-verification=false \
     -jar target/druid-mcp-server-1.0.0.jar

SSL設定オプション

本番環境のSSL設定

有効なSSL証明書を持つ本番環境の場合は、次のように設定します。

export DRUID_ROUTER_URL="https://druid-prod.company.com:8888"
export DRUID_SSL_ENABLED="true"
export DRUID_SSL_SKIP_VERIFICATION="false"

サーバーはシステムのデフォルトのトラストストアを使用してSSL証明書を検証します。

開発/テスト環境のSSL設定

自己署名証明書を使用した開発またはテスト環境の場合は、次のように設定します。

export DRUID_ROUTER_URL="https://druid-dev.local:8888"
export DRUID_SSL_ENABLED="true"
export DRUID_SSL_SKIP_VERIFICATION="true"  # 警告: テスト用のみ!

⚠️ セキュリティ警告: DRUID_SSL_SKIP_VERIFICATION=true を本番環境で使用しないでください。これはSSL証明書の検証を無効にするため、セキュリティ上のリスクがあります。

認証方法

MCPサーバーは、ユーザー名とパスワードを使用したHTTP基本認証をサポートしています。

• ユーザー名: DRUID_AUTH_USERNAME または druid.auth.username で設定する
• パスワード: DRUID_AUTH_PASSWORD または druid.auth.password で設定する 資格情報は自動的にBase64でエンコードされ、Authorization: Basic ヘッダーを使用して各リクエストとともに送信されます。

完全な設定例

例1: 本番環境

#!/bin/bash
# 本番環境の設定スクリプト

# Druidクラスターの設定
export DRUID_ROUTER_URL="https://druid.production.company.com:8888"

# 認証
export DRUID_AUTH_USERNAME="druid-mcp-user"
export DRUID_AUTH_PASSWORD="secure-password-123"

# SSL設定（本番環境）
export DRUID_SSL_ENABLED="true"
export DRUID_SSL_SKIP_VERIFICATION="false"

# MCPサーバーを起動する
java -jar target/druid-mcp-server-1.0.0.jar

例2: 開発環境

#!/bin/bash
# 開発環境の設定スクリプト

# 自己署名証明書を持つローカルのDruidクラスター
export DRUID_ROUTER_URL="https://localhost:8888"

# テスト用の資格情報
export DRUID_AUTH_USERNAME="admin"
export DRUID_AUTH_PASSWORD="admin123"

# SSL設定（開発環境 - 検証をスキップする）
export DRUID_SSL_ENABLED="true"
export DRUID_SSL_SKIP_VERIFICATION="true"

# MCPサーバーを起動する
java -jar target/druid-mcp-server-1.0.0.jar

例3: SSLを使用したMCPクライアントの設定

mcp-servers-config.json を更新して、環境変数を含めます。

{
  "mcpServers": {
    "druid-mcp-server": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "target/druid-mcp-server-1.0.0.jar"
      ],
      "env": {
        "DRUID_ROUTER_URL": "https://your-druid-cluster.example.com:8888",
        "DRUID_AUTH_USERNAME": "your-username",
        "DRUID_AUTH_PASSWORD": "your-password",
        "DRUID_SSL_ENABLED": "true",
        "DRUID_SSL_SKIP_VERIFICATION": "false"
      }
    }
  }
}

MCPプロンプトのカスタマイズ

サーバーは、src/main/resources/ にある prompts.properties ファイルを通じて、広範なプロンプトカスタマイズ機能を提供します。

プロンプト設定の構造

prompts.properties ファイルには以下が含まれます。

1. グローバル設定: プロンプトの有効/無効化とウォーターマークの設定
2. 機能トグル: 利用可能なプロンプトを制御する
3. カスタム変数: 組織固有の情報
4. テンプレート定義: 各機能の完全なプロンプトテンプレート

プロンプトの上書き

-D フラグを使用したJavaシステムプロパティを使用して、任意のプロンプトテンプレートを上書きできます。

方法1: システムプロパティ（ランタイム上書き）

java -Dprompts.druid-data-exploration.template="Your custom template here" \
     -jar target/druid-mcp-server-1.0.0.jar

方法2: カスタムプロパティファイル

1. カスタムプロパティファイル（例: custom-prompts.properties）を作成します。

# カスタムプロンプトテンプレート
prompts.druid-data-exploration.template=My custom data exploration prompt:\n\
1. Custom step one\n\
2. Custom step two\n\
{datasource_section}\n\
Environment: {environment}

2. ランタイムで読み込みます。

java -Dspring.config.additional-location=classpath:custom-prompts.properties \
     -jar target/druid-mcp-server-1.0.0.jar

利用可能なプロンプト変数

すべてのプロンプトテンプレートは、以下の変数をサポートしています。

プロンプトテンプレートの例

カスタムデータ探索プロンプト

prompts.druid-data-exploration.template=Welcome to {organizationName} Druid Analysis!\n\n\
Please help me explore our data:\n\
{datasource_section}\n\
Environment: {environment}\n\
Contact: {contactInfo}\n\n\
{watermark}

カスタムクエリ最適化プロンプト

prompts.druid-query-optimization.template=Query Performance Analysis for {organizationName}\n\n\
Query to optimize: {query}\n\n\
Please provide:\n\
1. Performance bottleneck analysis\n\
2. Optimization recommendations\n\
3. Best practices for our {environment} environment\n\n\
{watermark}

特定のプロンプトの無効化

個々のプロンプトを無効にするには、その有効フラグをfalseに設定します。

mcp.prompts.data-exploration.enabled=false
mcp.prompts.query-optimization.enabled=false

または、すべてのプロンプトをグローバルに無効にすることもできます。

mcp.prompts.enabled=false

MCP統合

このサーバーはSpring AIのMCP Serverフレームワークを使用しており、STDIOとSSEの両方のトランスポートをサポートしています。ツール、リソース、およびプロンプトは、MCPプロトコルを通じて自動的に登録され、公開されます。

トランスポートモード

STDIOトランスポート（LLMクライアントに推奨）

java -Dspring.ai.mcp.server.stdio=true \
     -Dspring.main.web-application-type=none \
     -Dlogging.pattern.console= \
     -jar target/druid-mcp-server-1.0.0.jar

SSEトランスポート（HTTPベース）

java -jar target/druid-mcp-server-1.0.0.jar
# サーバーは http://localhost:8080 で利用可能

LLM用のMCP設定

LLMクライアントがこのDruid MCPサーバーに接続するために使用できる、すぐに使えるMCP設定ファイルが mcp-servers-config.json に提供されています。 この設定には、両方のトランスポートオプションが含まれています。

STDIOトランスポート（推奨）

詳細は examples/stdio/README.md を参照してください。

{
  "mcpServers": {
    "druid-mcp-server": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "target/druid-mcp-server-1.0.0.jar"
      ]
    }
  }
}

SSEトランスポート

詳細は examples/sse/README.md を参照してください。

{
  "mcpServers": {
    "druid-mcp-server-sse": {
      "url": "http://localhost:8080"
    }
  }
}

LLMクライアントでの使用方法

1. まずサーバーをビルドします: ビルド手順については development.md を参照してください。
2. STDIOトランスポートの場合: MCPサーバーはLLMクライアントによって自動的に起動されます。
3. SSEトランスポートの場合: まず手動でサーバーを起動します。

サンプル

このリポジトリには、さまざまなデプロイメントシナリオやトランスポートモードでの使用を始めるのに役立つ包括的なサンプルが含まれています。

🐳 Druidクラスターのセットアップ

ローカルで完全なApache Druidクラスターを実行するための完全なDocker Compose構成です。開発、テスト、およびDruidクラスターアーキテクチャの学習に最適です。

特徴:

• すべてのコンポーネント（コーディネーター、ブローカー、ヒストリカル、ミドルマネージャー、ルーター）を備えた完全なDruidクラスター
• PostgreSQLメタデータストレージとZooKeeperコーディネーション
• サンプルデータとインジェストサンプルで事前構成されている
• 即時テスト用の統合Druid MCPサーバー

📡 STDIOトランスポートの設定

STDIO（標準入出力）トランスポートモードの設定例です。Claude DesktopなどのLLMクライアントとの統合に推奨される方法です。

特徴:

• 開発と本番環境の設定テンプレート
• 認証とSSL設定の例
• 人気のMCPクライアントとの統合ガイド
• トラブルシューティングとセキュリティのベストプラクティス

🐳📡 Dockerを使用したSTDIOトランスポート

Dockerを使用してDruid MCPサーバーをSTDIOトランスポートモードで実行するための設定例です。このアプローチは、Dockerデプロイの利便性とLLMクライアント統合用のSTDIOトランスポートを組み合わせています。

特徴:

• 開発と本番環境用のDockerベースのMCP設定ファイル
• クライアントマシンにJavaをインストールする必要がない
• 簡素化されたデプロイ用のDocker Composeセットアップ
• Druid接続用の環境変数設定
• Docker環境変数を介した認証とSSLサポート

🌐 SSEトランスポートの設定

SSE（サーバー送信イベント）トランスポートモードの設定例です。WebアプリケーションやREST API統合に適したHTTPベースの通信を提供します。

特徴:

• HTTPベースのMCPサーバー設定
• カスタムポートと本番デプロイの例
• Webクライアント統合パターン
• STDIOトランスポートモードとの比較

関連プロジェクト

このDruid MCPサーバーは、iuneraによって開発されたApache Druidツールと拡張機能の包括的なエコシステムの一部です。これらの補完的なプロジェクトは、Druidクラスター管理とデータインジェストのさまざまな側面を強化します。

🔧 Druidクラスター構成

Apache Druidクラスターの高度な構成管理とデプロイメントツールです。このプロジェクトは以下を提供します。

• 自動クラスターセットアップ: さまざまなデプロイメントシナリオ用の合理化された構成テンプレート
• 構成管理: 本番用Druidクラスターのベストプラクティスとテンプレート
• デプロイメント自動化: 一貫したクラスターデプロイ用のツールとスクリプト
• 環境固有の構成: 開発、ステージング、および本番環境用の最適化された構成

Druid MCPサーバーとの統合: このプロジェクトによって提供されるクラスター構成は、Druid MCPサーバーのモニタリングと管理機能とシームレスに連携し、包括的なクラスターライフサイクル管理を可能にします。

📊 コードインジェストDruid拡張機能

コード関連のデータとメトリクスをインジェストして分析するための特殊なApache Druid拡張機能です。この拡張機能により、以下が可能になります。

• コードメトリクスのインジェスト: コード分析データとソフトウェアメトリクス用の特殊なパーサー
• 開発者アナリティクス: コード品質、複雑さ、および開発パターンを分析するためのツール
• CI/CD統合: 継続的インテグレーションとデプロイメントパイプラインとのシームレスな統合
• カスタムデータ形式: さまざまなコード分析ツールと形式のサポート

Druid MCPサーバーとの統合: この拡張機能は、MCPサーバーのインジェスト管理ツールを通じて管理できるインジェスト機能を拡張し、コードアナリティクスのユースケースに対する特殊なサポートを提供します。

一緒に使用する理由

• 完全なエコシステム: クラスターセットアップから特殊なデータインジェストと管理まで
• 一貫したアーキテクチャ: すべてのプロジェクトが同様の設計原則と統合パターンに従っています
• 強化された機能: 各プロジェクトがDruidエコシステムの異なる側面を拡張します
• 本番環境対応: エンタープライズデプロイ用の実績のある構成と拡張機能

ロードマップ

• 読み取り専用モード: Druidに読み取り専用モード（R）を実装し、すべてのツールでの作成、更新、削除を禁止する
• SSEモードでの認証: Oauth認証を導入する
• Druid自動コンパクション: インテリジェントな自動コンパクション設定
• MCP自動補完: サンプリングによる強化された自動補完機能
• 適切なオブザーバビリティ: 包括的なメトリクスとトレーシング
• 強化されたモニタリング: 高度なクラスターモニタリングとアラート機能
• 高度なアナリティクス: 機械学習による洞察と推奨事項
• セキュリティの強化: 高度な認証と承認機能
• Kubernetesサポート: Kubernetesでの適切なデプロイメント

iuneraについて

このDruid MCPサーバーは、高度なAIとデータ分析ソリューションのリーディングプロバイダーである iunera によって開発およびメンテナンスされています。

iuneraは以下に特化しています。

• AIパワードアナリティクス: データ分析用の最先端の人工知能ソリューション
• エンタープライズデータプラットフォーム: スケーラブルなデータインフラストラクチャと分析プラットフォーム（Druid、Flink、Kubernetes、Kafka、Spring）
• モデルコンテキストプロトコル（MCP）ソリューション: さまざまなデータシステム用の高度なMCPサーバー実装
• カスタムAI開発: エンタープライズニーズに合わせたAIソリューション

Apache Druidの専門家として、iuneraはApache Druidに基づく多数のソリューションを本番環境のエンタープライズレベルのシナリオで展開および管理しています。

サービスとソリューションの詳細については、www.iunera.comを訪問してください。

お問い合わせとサポート

お困りのことがありましたら、以下の方法でお問い合わせください。

• Webサイト: https://www.iunera.com
• プロフェッショナルサービス: www.iunera.com または メール でお問い合わせして、エンタープライズサポートとカスタム開発を依頼してください
• オープンソース: このプロジェクトはオープンソースであり、コミュニティからの貢献を歓迎します

© 2024 iunera。Apache License 2.0の下でライセンスされています。