konflux-devlake

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

• Full Architecture Documentation - Complete system architecture and design patterns
• Documentation Index - Visual diagrams and documentation catalog
• Architecture Diagrams - 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

Argument	Description	Example
--transport	Transport protocol (stdio/http)	--transport http
--host	Server host	--host 0.0.0.0
--port	Server port	--port 3000
--db-host	Database host	--db-host localhost
--db-port	Database port	--db-port 3306
--db-user	Database username	--db-user root
--db-password	Database password	--db-password your_password
--db-database	Database name	--db-database lake
--log-level	Logging level	--log-level INFO

Timeout Configuration

The server includes configurable timeout settings optimized for LLM connections:

Environment Variable	Description	Default
SERVER_TIMEOUT_KEEP_ALIVE	HTTP keep-alive timeout in seconds	600 (10 minutes)
SERVER_TIMEOUT_GRACEFUL_SHUTDOWN	Graceful shutdown timeout in seconds	120 (2 minutes)
DB_CONNECT_TIMEOUT	Database connection timeout in seconds	60 (1 minute)
DB_READ_TIMEOUT	Database read timeout in seconds	600 (10 minutes)
DB_WRITE_TIMEOUT	Database write timeout in seconds	120 (2 minutes)

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

OIDC Authentication (Red Hat SSO / Keycloak)

The server supports OIDC authentication for securing MCP endpoints. When enabled, all requests to /mcp endpoints require a valid token.

Environment Variable	Description	Default
OIDC_ENABLED	Enable OIDC authentication	false
OIDC_ISSUER_URL	OIDC issuer URL (e.g., https://sso.redhat.com/auth/realms/redhat-external)	-
OIDC_CLIENT_ID	OIDC client ID / audience	-
OIDC_REQUIRED_SCOPES	Comma-separated list of required scopes	-
OIDC_JWKS_CACHE_TTL	JWKS cache TTL in seconds	3600
OIDC_SKIP_PATHS	Comma-separated paths to skip auth	/health,/security
OIDC_VERIFY_SSL	Verify SSL certificates	true
OIDC_OFFLINE_TOKEN_ENABLED	Accept offline tokens (server exchanges for access token)	false
OIDC_TOKEN_EXCHANGE_CLIENT_ID	Client ID for token exchange (defaults to OIDC_CLIENT_ID)	-
OIDC_ACCESS_TOKEN_CACHE_BUFFER	Seconds before expiry to refresh access token	60

Example: Enable Red Hat SSO authentication with access tokens

export OIDC_ENABLED=true
export OIDC_ISSUER_URL="https://sso.redhat.com/auth/realms/redhat-external"
export OIDC_CLIENT_ID="cloud-services"

Example: Enable offline token mode (server handles token exchange)