konflux-ci/konflux-devlake-mcp

Konflux DevLake MCP Server

A MCP server that enables natural language querying of Konflux DevLake databases. This server acts as a bridge between AI assistants and your DevLake database, allowing you to ask questions in plain language and get structured data back.

Documentation

• - Complete system architecture and design patterns
• - Visual diagrams and documentation catalog
• - System diagrams in Mermaid format

Quick Start

Option 1: Python (Development)

1. Install dependencies:

pip install -r requirements.txt

1. Start the server:

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

Option 2: Docker (Production)

1. Build the Docker image:

docker build -t konflux-devlake-mcp:latest .

1. Run the container:

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

1. Push to registry (if needed):

docker tag konflux-devlake-mcp:latest quay.io/flacatus/mcp-lake:1.0.0
docker push quay.io/flacatus/mcp-lake:1.0.0

Configuration

Command Line Arguments

Timeout Configuration

The server includes configurable timeout settings optimized for LLM connections:

These high default values ensure that long-running LLM requests and complex database queries don't timeout prematurely.

Environment Variables (Alternative)

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)

Then run:

python konflux-devlake-mcp.py

Help Command

python konflux-devlake-mcp.py --help

Available Tools

This server provides several specialized tools for working with your DevLake data:

• Database Tools: Connect to your database, list available databases and tables, execute custom SQL queries, and get detailed table schemas
• Incident Analysis: Get unique incidents with automatic deduplication, analyze incident patterns, and track resolution times. Returns data in TOON format for token efficiency.
• Deployment Tracking: Monitor deployment data with advanced filtering, track deployment frequency, and analyze service distribution
• PR Retest Analysis: Comprehensive analysis of pull requests that required manual retest commands (/retest). Provides detailed statistics including:
  • Total count of manual retest comments (excluding bot comments)
  • Number of PRs affected and average retests per PR
  • Top PRs with most retests (including PR title, URL, duration, changes, and status)
  • Analysis of root causes and failure patterns
  • Breakdown by PR category (bug fixes, features, dependencies, etc.)
  • Timeline visualization data
  • Actionable recommendations to reduce retest frequency
  • Returns data in TOON format for token efficiency

Features

• Natural Language Processing: Convert plain English questions into SQL queries automatically
• Security First: Built-in SQL injection detection and comprehensive query validation to protect your data
• DevLake Integration: Specialized tools for analyzing incident, deployment, and PR retest data from Konflux DevLake
• Token-Efficient Responses: Uses TOON format for tool responses (incident tools and PR retest tools), reducing token consumption by 30-60% compared to JSON
• Project & Repository Filtering: Advanced filtering capabilities for analyzing data by DevLake project and repository name
• Flexible Transport: Support for both HTTP and stdio transport protocols with graceful error handling
• Comprehensive Logging: Detailed logging with rotation, error tracking, and intelligent filtering of expected disconnection errors
• LLM-Optimized Timeouts: High default timeout values (10 minutes keep-alive) to support long-running LLM requests and database queries
• Configurable Timeouts: All timeout settings are configurable via environment variables for different deployment scenarios
• Enhanced Error Handling: Graceful handling of client disconnections (ClosedResourceError) and server shutdowns (CancelledError) without noisy error logs

Security

Your data security is our priority:

• SQL Injection Protection: Automatic detection and prevention of potential SQL injection attacks
• Query Validation: Every query is validated and sanitized before execution
• Data Masking: Sensitive information is automatically masked in query results
• Access Control: Database-level access control ensures only authorized operations are performed

Response Format

The server uses TOON format (Token-Optimized Object Notation) for tool responses to reduce token consumption:

• Incident Tools: All responses use TOON format (30-60% token reduction vs JSON)
• PR Retest Analysis Tool: All responses use TOON format (30-60% token reduction vs JSON)
• Deployment Tools: Currently use JSON format
• Database Tools: Currently use JSON format

TOON format is a compact, human-readable serialization format that significantly reduces token costs when working with LLMs while maintaining full data fidelity.

Monitoring

Keep track of your server's health and performance:

• Application Logs: logs/konflux_devlake_mcp_server.log - General server activity and operations
• Error Logs: logs/konflux_devlake_mcp_server_error.log - Detailed error information for troubleshooting
• Health Check: GET http://localhost:3000/health - Monitor server status and connectivity
• Error Handling: The server gracefully handles client disconnections and server shutdowns without logging expected errors (e.g., ClosedResourceError, CancelledError)

Testing

Use Makefile to easily run local tests on MCP tools (requires docker engine and LLM API key):

make install

make test-unit
make test-integration
make test-e2e

make test-all

Linting & pre-commit

Automatically run linters when making a commit:

make install
pre-commit install

pre-commit run --all-files

Configured tools:

• black (python formatting)
• flake8 (python style/lint)
• yamllint (YAML validation)

Contributing

We welcome contributions to improve this project:

1. Fork the repository
2. Create a feature branch for your changes
3. Make your improvements and add tests
4. Submit a pull request with a clear description of your changes

Use Cases

This MCP server is particularly useful for:

• Data Analysts: Quickly query DevLake data without writing complex SQL
• DevOps Teams: Monitor incidents and deployments through natural language queries
• AI Assistants: Enable AI tools to access and analyze your DevLake data with optimized token usage
• Business Intelligence: Generate reports and insights from your DevLake database
• Development Teams: Debug and analyze application performance data, identify PR retest patterns, and optimize CI/CD workflows
• Quality Assurance: Analyze PR retest frequency, identify flaky tests, and improve test reliability

Recent Updates

Version 1.0.0+ Features

• PR Retest Analysis Tool: New comprehensive tool for analyzing pull requests that required manual retest commands
• TOON Format Support: Incident tools and PR retest tools now use TOON format for 30-60% token reduction
• Enhanced Timeout Configuration: High default timeouts (10 minutes) optimized for LLM connections
• Improved Error Handling: Graceful handling of client disconnections and server shutdowns
• Database Timeout Settings: Configurable timeouts for database connections to handle long-running queries
• Project & Repository Filtering: Enhanced filtering capabilities for precise data analysis