Druid MCP Server

🚀 Druid MCP Server

Druid MCP Server 是一款全面的 Apache Druid 模型上下文协议（MCP）服务器，它提供了丰富的工具、资源和提示，用于管理和分析 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。

✨ 主要特性

• Spring AI MCP 服务器集成
• 基于工具的架构，符合 MCP 协议
• 支持 STDIO 和 SSE 传输
• 全面的错误处理
• 可定制的提示模板
• 基于功能的包组织

MCP 检查器界面

连接到 MCP 客户端后，您可以通过 MCP 检查器界面检查可用的工具、资源和提示：

可用工具

工具界面展示了所有可用的 Druid 管理功能，这些功能按功能区域组织，包括数据管理、摄取管理以及监控与健康检查。

可用资源

资源界面显示了所有可通过 MCP 协议访问的 Druid 数据源和元数据。

可用提示

提示界面展示了所有适用于各种 Druid 管理任务和数据分析工作流的 AI 辅助指导模板。

📦 安装指南

从 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 集群端点。

💻 使用示例

基础用法

# 构建应用程序
mvn clean package -DskipTests

# 运行应用程序
java -jar target/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 target/druid-mcp-server-1.0.0.jar

📚 详细文档

各功能可用工具

数据管理

功能	工具	描述	参数
数据源	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 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 集群的全面指南。

前提条件

• 启用 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 集成

此服务器使用 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 配置

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 传输：首先手动启动服务器

示例

本仓库包含了丰富的示例，帮助您开始不同的部署场景和传输模式：

🐳 Druid 集群设置

完整的 Docker Compose 配置，用于在本地运行完整的 Apache Druid 集群。非常适合开发、测试以及了解 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 或 电子邮件 联系我们，获取企业支持和定制开发服务
• 开源项目：本项目是开源的，欢迎社区贡献

---

© 2024 iunera。根据 Apache 许可证 2.0 授权。