德鲁伊-MCP服务器
项目介绍
Druid MCP Server
一个全面的模型上下文协议（MCP）服务器，用于Apache Druid，提供广泛的工具、资源和提示，以管理和分析Druid集群。
由iunera开发 - 高级AI和数据分析解决方案
概述
此MCP服务器实现了一个基于特性的架构，每个包代表了Druid管理的一个独立功能区域。该服务器提供了三种主要类型的MCP组件：
- 工具 - 可执行函数，用于执行操作
- 资源 - 数据提供者，用于访问信息
- 提示 - 带有AI辅助的指导模板
视频教程
学习如何使用MCP服务器将AI代理与Apache Druid集成。本教程演示了使用自然语言与Claude、ChatGPT和Gemini等AI助手进行时间序列数据探索、统计分析和数据摄取的过程。
点击上面的缩略图在YouTube上观看视频
特性
- Spring AI MCP服务器集成
- 符合MCP协议的工具架构
- 基于工具的架构：完全符合MCP协议，并自动生成JSON模式
- 多种传输模式：支持STDIO、SSE和可流式传输HTTP，包括OAuth
- 实时通信：具有流媒体能力的服务器发送事件
- 完整的错误处理
- 可定制的提示模板：带有模板定制的AI辅助指导
- 完整的错误处理：优雅的错误处理并提供有意义的响应
架构与组织
- 基于特性的包组织：每个包代表了一个独立的Druid管理区域
- 自动发现：通过注解自动注册工具、资源和提示
- 企业就绪：生产级别的配置和安全特性
MCP检查器界面
当连接到MCP客户端时，可以通过MCP检查器界面查看可用的工具、资源和提示：
可用工具
工具界面显示了所有可用的Druid管理功能，按功能领域组织，包括数据管理、摄取管理和监控及健康状况。
可用资源
资源界面展示了所有可访问的Druid数据源和元数据，这些数据可以通过MCP协议检索。
可用提示
提示界面显示了可用于各种Druid管理任务和数据分析工作流程的所有AI辅助指导模板。
快速开始
LLM的MCP配置
提供了一个现成的MCP配置文件mcp-servers-config.json，可以与LLM客户端一起使用，以连接到这个Druid MCP服务器。
示例
配置包括两种传输选项：
- [STDIO默认](: 查看examples/stdio/README.md - 服务器通过STDIO由MCP客户端启动。
- [可流式传输HTTP（配置文件：http）](: 查看examples/streamable-http/README.md - 每个MCP 2025-06-18只有一个/mcp端点。
使用环境变量的Docker示例：
# STDIO模式（默认）
docker run --rm -i \
-e DRUID_ROUTER_URL=http://your-druid-router:8888 \
-e DRUID_COORDINATOR_URL=http://your-druid-coordinator:8081 \
iunera/druid-mcp-server:latest
# HTTP模式（启用配置文件'http'并暴露/mcp）
docker run -p 18080:8080 \
-e SPRING_PROFILES_ACTIVE=http \
-e DRUID_ROUTER_URL=http://your-druid-router:8888 \
-e DRUID_COORDINATOR_URL=http://your-druid-coordinator:8081 \
iunera/druid-mcp-server:latest
关于Spring配置文件的说明：
- 默认配置文件：stdio（无需设置SPRING_PROFILES_ACTIVE）
- HTTP配置文件：设置SPRING_PROFILES_ACTIVE=http以在/mcp启用可流式传输HTTP
先决条件
- Java 24
- Maven 3.6+
- 运行中的Apache Druid集群，路由器端口为8888
构建和运行
# 构建应用程序
mvn clean package -DskipTests
# 运行应用程序
java -jar target/druid-mcp-server-1.6.0.jar
服务器默认将在8080端口启动。
有关详细的构建指令、测试、Docker设置和开发指南，请参阅development.md。
安全性和认证
- 可流式传输HTTP和SSE传输默认使用OAuth 2.0进行保护。
- 客户端必须在连接时在授权头中发送有效的Bearer令牌。
- 示例：Authorization: Bearer YOUR_JWT_TOKEN
环境变量
DRUID_MCP_SECURITY_OAUTH2_ENABLED:- 描述：启用或禁用OAuth2安全认证。
- 类型：布尔型
- 默认值：
true（默认情况下启用OAuth2） - 用法：设置为
false以禁用OAuth2认证。当禁用时，客户端可以在不提供OAuth2令牌的情况下访问服务器。
- 对于企业单点登录集成（OpenID Connect、Azure AD、Keycloak等），请发送咨询邮件至consulting@iunera.com，并参见联系和支持。
从Maven中央安装
如果您希望使用预构建的JAR而不需要从源代码构建，可以直接从Maven中央下载并运行它。
先决条件
- Java 24 JRE
下载并运行
从Maven中央下载JAR https://repo.maven.apache.org/maven2/com/iunera/druid-mcp-server/
# STDIO模式（默认）
java -jar target/druid-mcp-server-1.6.0.jar
# HTTP模式（配置文件：http） - 在8080端口暴露/mcp
java -Dspring.profiles.active=http \
-jar target/druid-mcp-server-1.6.0.jar
开发者指南
对于详细的开发信息，包括构建指令、测试指南、架构细节和贡献指南，请参阅development.md。
按功能划分的可用工具
MCP服务器通过注解自动发现所有工具。在只读模式下，任何会修改Druid集群的工具都不会被注册，也不会出现在MCP客户端中。以下列表反映了当前的实现。
数据管理
| 功能 | 工具 | 描述 | 参数 |
|---|---|---|---|
| 数据源 | 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 | 验证集群组件之间的连通性 | 无 |
基础安全性
| 功能 | 工具 | 描述 | 参数 |
|---|---|---|---|
| 认证 | listAuthenticationUsers | 列出特定认证器中的所有用户 | authenticatorName (字符串) |
| 认证 | getAuthenticationUser | 获取特定用户的详细信息 | authenticatorName (字符串), userName (字符串) |
| 认证 | createAuthenticationUser | 在Druid认证系统中创建新用户 | authenticatorName (字符串), userName (字符串) |
| 认证 | deleteAuthenticationUser | 从Druid认证系统中删除用户。谨慎使用，因为此操作不可逆。 | authenticatorName (字符串), userName (字符串) |
| 认证 | setUserPassword | 设置或更新Druid认证系统中用户的密码 | authenticatorName (字符串), userName (字符串), password (字符串) |
| 授权 | listAuthorizationUsers | 列出特定授权器中的所有用户 | authorizerName (字符串) |
| 授权 | getAuthorizationUser | 获取特定用户的详细信息，包括其角色 | authorizerName (字符串), userName (字符串) |
| 授权 | listRoles | 列出特定授权器中的所有角色 | authorizerName (字符串) |
| 授权 | getRole | 获取特定角色的详细信息，包括其权限 | authorizerName (字符串), roleName (字符串) |
| 授权 | createAuthorizationUser | 在Druid授权系统中创建新用户 | authorizerName (字符串), userName (字符串) |
| 授权 | deleteAuthorizationUser | 从Druid授权系统中删除用户。谨慎使用，因为此操作不可逆。 | authorizerName (字符串), userName (字符串) |
| 授权 | createRole | 在Druid授权系统中创建新角色 | authorizerName (字符串), roleName (字符串) |
| 授权 | deleteRole | 从Druid授权系统中删除角色。谨慎使用，因为此操作不可逆。 | authorizerName (字符串), roleName (字符串) |
| 授权 | setRolePermissions | 设置角色的权限。提供权限作为JSON数组。 | authorizerName (字符串), roleName (字符串), permissions (字符串) |
| 授权 | assignRoleToUser | 将角色分配给用户 | authorizerName (字符串), userName (字符串), roleName (字符串) |
| 授权 | unassignRoleFromUser | 从用户处取消分配角色 | authorizerName (字符串), userName (字符串), roleName (字符串) |
| 配置 | getAuthenticatorChainAndAuthorizers | 获取配置的认证器链和授权器。此信息对其他安全工具和LLMs来说非常重要，需要首先调用此工具。 | 无 |
按功能划分的可用资源
| 功能 | 资源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 | 集群维护程序 | 无 |
环境变量配置
应用程序可以通过环境变量进行配置，这是推荐的生产环境配置方法。以下是根据application.yaml配置文件推导出的支持环境变量的综合列表。
Druid连接
DRUID_ROUTER_URL: Druid路由器的URL。DRUID_AUTH_USERNAME: Druid认证的用户名。DRUID_AUTH_PASSWORD: