Druid Mcp Server

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-brokeryour-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_USERNAMEdruid.auth.username 设置
  • 密码:通过 DRUID_AUTH_PASSWORDdruid.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}
  1. 在运行时加载它:
java -Dspring.config.additional-location=classpath:custom-prompts.properties \
-jar target/druid-mcp-server-1.0.0.jar

可用提示变量

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

变量 描述 示例
{environment} 当前环境名称 productionstagingdev
{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 授权。

  • 0 关注
  • 0 收藏,8 浏览
  • system 提出于 2025-09-23 16:57

相似服务问题