Konflux DevLake MCP服务器
  
支持Konflux DevLake数据库自然语言查询的MCP服务器。该服务器充当AI助手和DevLake数据库之间的桥梁，允许您用简单的语言提问并获得结构化数据。
文档
快速开始
选项1:Python（开发）
- 安装依赖项:
pip install -r requirements.txt- 启动服务器:
python konflux-devlake-mcp.py --transport http --host 0.0.0.0 --port 3000 --db-host localhost --db-port 3306 --db-user root --db-password password --db-database lake选项2：Docker（生产）
- 构建Docker镜像:
docker build -t konflux-devlake-mcp:latest .- 运行容器:
docker run -d \
--name konflux-mcp-server \
-p 3000:3000 \
-e DB_HOST=your_db_host \
-e DB_PORT=3306 \
-e DB_USER=root \
-e DB_PASSWORD=your_password \
-e DB_DATABASE=lake \
-e LOG_LEVEL=INFO \
konflux-devlake-mcp:latest- 推送到注册表（如果需要）:
docker tag konflux-devlake-mcp:latest quay.io/flacatus/mcp-lake:1.0.0
docker push quay.io/flacatus/mcp-lake:1.0.0配置
命令行参数
| 参数 | 描述 | 示例 |
|---|---|---|
--transport | 传输协议（stdio/http） | --transport http |
--host | 服务器主机 | --host 0.0.0.0 |
--port | 服务器端口 | --port 3000 |
--db-host | 数据库主机 | --db-host localhost |
--db-port | 数据库端口 | --db-port 3306 |
--db-user | 数据库用户名 | --db-user root |
--db-password | 数据库密码 | --db-password your_password |
--db-database | 数据库名称 | --db-database lake |
--log-level | 日志记录级别 | --log-level INFO |
超时配置
服务器包括针对LLM连接优化的可配置超时设置：
| 环境变量 | 描述 | 默认值 |
|---|---|---|
SERVER_TIMEOUT_KEEP_ALIVE | HTTP保持活动超时（秒） | 600 （10分钟） |
SERVER_TIMEOUT_GRACEFUL_SHUTDOWN | 优雅的关机超时时间（秒） | 120 （2分钟） |
DB_CONNECT_TIMEOUT | 数据库连接超时（秒） | 60 （1分钟） |
DB_READ_TIMEOUT | 数据库读取超时（秒） | 600 （10分钟） |
DB_WRITE_TIMEOUT | 数据库写入超时（秒） | 120 （2分钟） |
这些高默认值可确保长时间运行的LLM请求和复杂的数据库查询不会过早超时。
OIDC身份验证（红帽SSO/Keycloak）
服务器支持OIDC身份验证，以保护MCP端点的安全。启用后，所有请求 /mcp 终结点需要有效的令牌。
| 环境变量 | 描述 | 默认值 |
|---|---|---|
OIDC_ENABLED | 启用OIDC身份验证 | false |
OIDC_ISSUER_URL | OIDC发行者URL（例如。， https://sso.redhat.com/auth/realms/redhat-external) | - |
OIDC_CLIENT_ID | OIDC客户ID/受众 | - |
OIDC_REQUIRED_SCOPES | 以逗号分隔的所需作用域列表 | - |
OIDC_JWKS_CACHE_TTL | JWKS缓存TTL（秒） | 3600 |
OIDC_SKIP_PATHS | 逗号分隔的路径可跳过身份验证 | /health,/security |
OIDC_VERIFY_SSL | 验证SSL证书 | true |
OIDC_OFFLINE_TOKEN_ENABLED | 接受离线令牌（服务器交换访问令牌） | false |
OIDC_TOKEN_EXCHANGE_CLIENT_ID | 令牌交换的客户端ID（默认为 OIDC_CLIENT_ID) | - |
OIDC_ACCESS_TOKEN_CACHE_BUFFER | 到期前几秒刷新访问令牌 | 60 |
示例：使用访问令牌启用Red Hat SSO身份验证
export OIDC_ENABLED=true
export OIDC_ISSUER_URL="https://sso.redhat.com/auth/realms/redhat-external"
export OIDC_CLIENT_ID="cloud-services"示例：启用离线令牌模式（服务器处理令牌交换）
export OIDC_ENABLED=true
export OIDC_ISSUER_URL="https://sso.redhat.com/auth/realms/redhat-external"
export OIDC_CLIENT_ID="cloud-services"
export OIDC_OFFLINE_TOKEN_ENABLED=true
export OIDC_TOKEN_EXCHANGE_CLIENT_ID="cloud-services"通过离线令牌模式，客户端可以直接使用其长期离线令牌。服务器会自动将其交换为短期访问令牌，并缓存结果。
客户必须包括 Authorization: Bearer 头球令牌可以是：
- JWT访问令牌（直接验证）
- 离线令牌（在以下情况下交换为访问令牌
OIDC_OFFLINE_TOKEN_ENABLED=true)
环境变量（备选）
export DB_HOST=localhost
export DB_PORT=3306
export DB_USER=root
export DB_PASSWORD=your_password
export DB_DATABASE=lake
export TRANSPORT=http
export SERVER_HOST=0.0.0.0
export SERVER_PORT=3000
export LOG_LEVEL=INFO
# Timeout Configuration (for LLM connections)
export SERVER_TIMEOUT_KEEP_ALIVE=600 # HTTP keep-alive timeout in seconds (default: 600)
export SERVER_TIMEOUT_GRACEFUL_SHUTDOWN=120 # Graceful shutdown timeout in seconds (default: 120)
export DB_CONNECT_TIMEOUT=60 # Database connection timeout in seconds (default: 60)
export DB_READ_TIMEOUT=600 # Database read timeout in seconds (default: 600)
export DB_WRITE_TIMEOUT=120 # Database write timeout in seconds (default: 120)然后运行：
python konflux-devlake-mcp.pyHelp命令
python konflux-devlake-mcp.py --help可用工具
此服务器提供了几个专门的工具来处理您的DevLake数据：
- 数据库工具：连接到数据库，列出可用的数据库和表，执行自定义SQL查询，并获取详细的表模式
- 事件分析：通过自动重复数据删除获取独特事件，分析事件模式并跟踪解决时间。为了提高令牌效率，以TOON格式返回数据。
- 部署跟踪：使用高级筛选监控部署数据，跟踪部署频率，并分析服务分布
- PR复检分析：对需要手动重新测试命令的拉取请求进行全面分析(
/retest).提供详细的统计数据，包括：
- 手动重新测试评论总数（不包括机器人评论） - 受影响的PR数量和每个PR的平均复测次数 - 重测次数最多的PR（包括PR标题、URL、持续时间、更改和状态） - 根本原因和故障模式分析 - 按PR类别细分（错误修复、功能、依赖关系等） - 时间线可视化数据 - 降低复测频率的可行建议 - 以TOON格式返回数据以提高令牌效率
特性
- 自然语言处理：将普通英语问题自动转换为SQL查询
- 安全第一：内置SQL注入检测和全面的查询验证，以保护您的数据
- DevLake集成：用于分析Konflux DevLake事件、部署和PR重新测试数据的专用工具
- 令牌高效响应：使用TOON格式进行工具响应（事件工具和PR重新测试工具），与JSON相比，令牌消耗减少了30-60%
- 项目和存储库筛选：按DevLake项目和存储库名称分析数据的高级过滤功能
- 柔性运输：支持HTTP和stdio传输协议，具有优雅的错误处理能力
- 综合录井：详细的日志记录，包括旋转、错误跟踪和预期断开错误的智能过滤
- LLM优化超时：高默认超时值（10分钟保持活动），以支持长时间运行的LLM请求和数据库查询
- 可配置超时：所有超时设置都可以通过不同部署场景的环境变量进行配置
- 增强的错误处理：优雅地处理客户端断开连接(
ClosedResourceError)服务器关闭(CancelledError)无噪声错误日志
安全
您的数据安全是我们的首要任务：
- OIDC身份验证：通过Red Hat SSO/Keycloak进行可选的基于JWT的身份验证
- SQL注入保护：自动检测和预防潜在的SQL注入攻击
- 查询验证：每个查询在执行前都经过验证和净化
- 数据脱敏：查询结果中会自动屏蔽敏感信息
- 访问控制：数据库级访问控制确保只执行授权操作
响应格式
服务器使用 TOON格式 （令牌优化对象表示法）用于工具响应，以减少令牌消耗：
- 事件工具：所有响应都使用TOON格式（与JSON相比，令牌减少30-60%）
- PR复检分析工具：所有响应都使用TOON格式（与JSON相比，令牌减少30-60%）
- 部署工具：目前使用JSON格式
- 数据库工具：目前使用JSON格式
TOON格式是一种紧凑的、人类可读的序列化格式，在使用LLM时显著降低了令牌成本，同时保持了完整的数据保真度。
监控
跟踪服务器的运行状况和性能：
- 应用程序日志:
logs/konflux_devlake_mcp_server.log-一般服务器活动和操作 - 错误记录:
logs/konflux_devlake_mcp_server_error.log-用于故障排除的详细错误信息 - 健康检查:
GET http://localhost:3000/health-监控服务器状态和连接 - 错误处理：服务器优雅地处理客户端断开连接和服务器关闭，而不会记录预期的错误（例如。，
ClosedResourceError,CancelledError)
测试
使用Makefile可以轻松地在MCP工具上运行本地测试（需要docker引擎和LLM API密钥）：
make install
make test-unit
make test-integration
make test-e2e
make test-all临摹与预承诺
提交时自动运行linters：
make install
pre-commit install
pre-commit run --all-files配置的工具：
- 黑色（python格式）
- flake8（python风格/lint）
- yamllint（YAML验证）
贡献
我们欢迎为改进该项目做出贡献：
- 克隆该仓库
- 为您的更改创建功能分支
- 进行改进并添加测试
- 提交一个拉取请求，明确描述您的更改
用例
此MCP服务器特别适用于：
- 数据分析师：无需编写复杂的SQL即可快速查询DevLake数据
- DevOps团队：通过自然语言查询监控事件和部署
- AI助理：使AI工具能够访问和分析您的DevLake数据，并优化令牌使用
- 商业智能：从DevLake数据库生成报告和见解
- 开发团队：调试和分析应用程序性能数据，确定PR重新测试模式，并优化CI/CD工作流程
- 质量保证：分析PR复测频率，识别片状测试，提高测试可靠性
最近的更新
版本1.0.0+功能
- PR复检分析工具：用于分析需要手动重新测试命令的拉取请求的新综合工具
- TOON格式支持：事件工具和PR重新测试工具现在使用TOON格式，可减少30-60%的令牌
- 增强的超时配置：针对LLM连接优化的高默认超时（10分钟）
- 改进了错误处理：妥善处理客户端断开连接和服务器关闭
- 数据库超时设置：数据库连接处理长时间运行查询的可配置超时
- 项目和存储库筛选：增强过滤功能，实现精确的数据分析