Druid MCP Server

🚀 Druid MCP 服務器

Druid MCP 服務器是一款全面的模型上下文協議（MCP）服務器，專為 Apache Druid 設計。它提供了豐富的工具、資源和提示信息，可用於管理和分析 Druid 集群，助力用戶高效處理數據。

由 iunera 開發 - 提供先進的人工智能和數據分析解決方案

🚀 快速開始

前提條件

• Java 24
• Maven 3.6 及以上版本
• 運行中的 Apache Druid 集群，路由器端口為 8888

構建並運行

# 構建應用程序
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，可直接從 Docker Hub 拉取預構建的 Docker 鏡像，無需在本地安裝 Java。

前提條件

• 已安裝並運行 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 服務器
• 採用基於工具的架構，符合 MCP 協議
• 支持 STDIO 和 SSE 傳輸協議
• 具備全面的錯誤處理機制
• 提供可定製的提示模板
• 基於功能進行包組織

MCP 檢查器界面

當連接到 MCP 客戶端時，你可以通過 MCP 檢查器界面查看可用的工具、資源和提示信息：

可用工具

工具界面展示了所有可用的 Druid 管理功能，這些功能按功能區域組織，包括數據管理、攝入管理以及監控與健康檢查。

可用資源

資源界面顯示了所有可通過 MCP 協議訪問的 Druid 數據源和元數據。

可用提示

提示界面展示了所有可用於各種 Druid 管理任務和數據分析工作流的 AI 輔助指導模板。

💻 使用示例

基礎用法

本服務器使用 Spring AI 的 MCP 服務器框架，支持 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 訪問

高級用法

MCP 配置用於 LLM

在 mcp-servers-config.json 中提供了一個可直接使用的 MCP 配置文件，可用於 LLM 客戶端連接此 Druid MCP 服務器。該配置包含兩種傳輸選項：

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 傳輸協議：需手動先啟動服務器。

📚 詳細文檔

按功能劃分的可用工具

數據管理

功能	工具	描述	參數
數據源	listDatasources	列出所有可用的 Druid 數據源名稱	無
數據源	showDatasourceDetails	顯示特定數據源的詳細信息，包括列信息	datasourceName（字符串）
數據源	killDatasource	永久刪除數據源，移除所有數據和元數據	datasourceName（字符串），interval（字符串）
查找表	listLookups	從協調器列出所有可用的 Druid 查找表	無
查找表	getLookupConfig	獲取特定查找表的配置	tier（字符串），lookupName（字符串）
查找表	updateLookupConfig	更新特定查找表的配置	tier（字符串），lookupName（字符串），config（字符串）
段	listAllSegments	列出所有數據源中的所有段	無
段	getSegmentMetadata	獲取特定段的元數據	datasourceName（字符串），segmentId（字符串）
段	getSegmentsForDatasource	獲取特定數據源的所有段	datasourceName（字符串）
查詢	queryDruidSql	對 Druid 數據源執行 SQL 查詢	sqlQuery（字符串）
保留策略	viewRetentionRules	查看所有數據源或特定數據源的保留規則	datasourceName（字符串，可選）
保留策略	updateRetentionRules	更新數據源的保留規則	datasourceName（字符串），rules（字符串）
壓縮	viewAllCompactionConfigs	查看所有數據源的壓縮配置	無
壓縮	viewCompactionConfigForDatasource	查看特定數據源的壓縮配置	datasourceName（字符串）
壓縮	editCompactionConfigForDatasource	編輯數據源的壓縮配置	datasourceName（字符串），config（字符串）
壓縮	deleteCompactionConfigForDatasource	刪除數據源的壓縮配置	datasourceName（字符串）
壓縮	viewCompactionStatus	查看所有數據源的壓縮狀態	無
壓縮	viewCompactionStatusForDatasource	查看特定數據源的壓縮狀態	datasourceName（字符串）

攝入管理

功能	工具	描述	參數
攝入規範	createBatchIngestionTemplate	創建批量攝入模板	datasourceName（字符串），inputSource（字符串），timestampColumn（字符串）
攝入規範	createIngestionSpec	創建並提交攝入規範	specJson（字符串）
監控器	listSupervisors	列出所有流式攝入監控器	無
監控器	getSupervisorStatus	獲取特定監控器的狀態	supervisorId（字符串）
監控器	suspendSupervisor	暫停流式監控器	supervisorId（字符串）
監控器	startSupervisor	啟動或恢復流式監控器	supervisorId（字符串）
監控器	terminateSupervisor	終止流式監控器	supervisorId（字符串）
任務	listTasks	列出所有攝入任務	無
任務	getTaskStatus	獲取特定任務的狀態	taskId（字符串）
任務	shutdownTask	關閉正在運行的任務	taskId（字符串）

監控與健康檢查

功能	工具	描述	參數
基本健康	checkClusterHealth	檢查集群的整體健康狀態	無
基本健康	getServiceStatus	獲取特定 Druid 服務的狀態	serviceType（字符串）
基本健康	getClusterConfiguration	獲取集群的配置信息	無
診斷	runDruidDoctor	運行全面的集群診斷	無
診斷	analyzePerformanceIssues	分析集群的性能問題	無
診斷	generateHealthReport	生成詳細的健康報告	無
功能測試	testQueryFunctionality	測試跨服務的查詢功能	無
功能測試	testIngestionFunctionality	測試攝入功能	無
功能測試	validateClusterConnectivity	驗證集群組件之間的連接性	無

按功能劃分的可用資源

功能	資源 URI 模式	描述	參數
數據源	druid://datasource/{datasourceName}	訪問數據源信息和元數據	datasourceName（字符串）
數據源	druid://datasource/{datasourceName}/details	訪問包括架構在內的詳細數據源信息	datasourceName（字符串）
查找表	druid://lookup/{tier}/{lookupName}	訪問查找表的配置和數據	tier（字符串），lookupName（字符串）
段	druid://segment/{segmentId}	訪問段的元數據和信息	segmentId（字符串）

按功能劃分的可用提示

功能	提示名稱	描述	參數
數據分析	data-exploration	探索 Druid 數據源中數據的指南	datasource（字符串，可選）
數據分析	query-optimization	幫助優化 Druid SQL 查詢以提高性能	query（字符串）
集群管理	health-check	全面的集群健康評估指南	無
集群管理	cluster-overview	集群狀態的概述和分析	無
攝入管理	ingestion-troubleshooting	解決攝入問題的指南	issue（字符串，可選）
攝入管理	ingestion-setup	設置新攝入管道的指南	dataSource（字符串，可選）
保留策略管理	retention-management	管理數據保留策略	datasource（字符串，可選）
壓縮	compaction-suggestions	優化段壓縮配置	datasource（字符串，可選），currentConfig（字符串，可選），performanceMetrics（字符串，可選）
壓縮	compaction-troubleshooting	解決壓縮問題的指南	issue（字符串），datasource（字符串，可選）
操作	emergency-response	應急響應程序和指南	無
操作	maintenance-mode	集群維護程序	無

配置

在 src/main/resources/application.properties 中配置你的 Druid 連接：

# Spring AI MCP 服務器配置
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 集群的全面指南。

前提條件

• 啟用 SSL 的 Druid 集群，具有 HTTPS 端點
• 用於 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

可用提示變量

所有提示模板都支持以下變量：

變量	描述	示例
{environment}	當前環境名稱	production，staging，dev
{organizationName}	組織名稱	Your Organization
{contactInfo}	聯繫信息	your-team@company.com
{watermark}	生成的水印	Generated by Druid MCP Server v1.0.0
{datasource}	數據源名稱（特定上下文）	sales_data
{query}	SQL 查詢（特定上下文）	SELECT * FROM sales_data

提示模板示例

自定義數據探索提示

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 服務器採用基於功能的架構，其中每個包代表 Druid 管理的一個不同功能區域。服務器提供三種主要類型的 MCP 組件：

• 工具：用於執行操作的可執行函數
• 資源：用於訪問信息的數據提供者
• 提示：AI 輔助指導模板

視頻教程

瞭解如何使用 MCP 服務器將 AI 代理與 Apache Druid 集成。本教程演示瞭如何使用 Claude、ChatGPT 和 Gemini 等 AI 助手通過自然語言進行時間序列數據探索、統計分析和數據攝入。 點擊上面的縮略圖在 YouTube 上觀看視頻

📄 許可證

© 2024 iunera。本項目根據 Apache 許可證 2.0 授權。

示例

本倉庫包含全面的示例，幫助你開始不同的部署場景和傳輸模式：

🐳 Druid 集群設置

用於在本地運行完整 Apache Druid 集群的完整 Docker Compose 配置。非常適合開發、測試以及瞭解 Druid 集群架構。

特性：

• 包含所有組件（協調器、代理、歷史服務器、中間管理器、路由器）的完整 Druid 集群
• PostgreSQL 元數據存儲和 ZooKeeper 協調
• 預配置了示例數據和攝入示例
• 集成了 Druid MCP 服務器，可立即進行測試

📡 STDIO 傳輸協議配置

STDIO（標準輸入/輸出）傳輸模式的配置示例 - 這是與 Claude Desktop 等 LLM 客戶端集成的推薦方法。

特性：

• 開發和生產環境的配置模板
• 認證和 SSL 設置示例
• 流行 MCP 客戶端的集成指南
• 故障排除和安全最佳實踐

🐳📡 使用 Docker 的 STDIO 傳輸協議

使用 Docker 和 STDIO 傳輸模式運行 Druid MCP 服務器的配置示例。這種方法結合了 Docker 部署的便利性和 STDIO 傳輸協議，用於 LLM 客戶端集成。

特性：

• 用於開發和生產環境的基於 Docker 的 MCP 配置文件
• 客戶端機器無需安裝 Java
• Docker Compose 設置，簡化部署
• 用於 Druid 連接的環境變量配置
• 通過 Docker 環境變量支持認證和 SSL

🌐 SSE 傳輸協議配置

SSE（服務器發送事件）傳輸模式的配置示例，提供基於 HTTP 的通信，適用於 Web 應用程序和 REST API 集成。

特性：

• 基於 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 服務器由 iunera 開發和維護，iunera 是一家領先的先進人工智能和數據分析解決方案提供商。

iunera 專注於：

• 人工智能驅動的分析：用於數據分析的前沿人工智能解決方案
• 企業數據平臺：可擴展的數據基礎設施和分析平臺（Druid、Flink、Kubernetes、Kafka、Spring）
• 模型上下文協議（MCP）解決方案：針對各種數據系統的高級 MCP 服務器實現
• 定製人工智能開發：滿足企業需求的定製人工智能解決方案

作為 Apache Druid 的資深開發者，iunera 在生產級企業場景中部署和維護了大量基於 Apache Druid 的解決方案。

如需瞭解更多關於我們的服務和解決方案，請訪問 www.iunera.com。

聯繫與支持

如有需要，請通過以下方式聯繫我們：

• 網站：https://www.iunera.com
• 專業服務：通過 www.iunera.com 或 電子郵件 聯繫我們，獲取企業支持和定製開發服務
• 開源項目：本項目是開源的，歡迎社區貢獻