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

📚 详细文档

各功能可用工具

数据管理

摄取管理

监控与健康检查

各功能可用资源

各功能可用提示

配置

在 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

可用提示变量

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

提示模板示例

自定义数据探索提示

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 授权。