pip install jenkins-ai-optimizer

Developer → Jenkins UI → Browse jobs → Find failed build →
Download logs → Search manually → Google errors → Debug
⏱️ Time: 30-60 minutes per failure

Developer → Ask AI: "Why did my build fail?" →
AI analyzes automatically → Get actionable diagnosis
⏱️ Time: 10-30 seconds

┌─────────────────────────────────────────────────────────────────┐
│                        AI Assistant (Claude)                    │
│                     Natural Language Interface                  │
└─────────────────────────────┬───────────────────────────────────┘
                              │  MCP Protocol (SSE/stdio)
                              ▼
┌────────────────────────────────────────────────────────────────┐
│                    Jenkins MCP Enterprise Server               │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────────┐   │
│  │ Tool Factory │  │ DI Container │  │ Multi-Jenkins Mgr   │   │
│  └──────────────┘  └──────────────┘  └─────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              Tool Registry (10+ Tools)                   │  │
│  │  • Diagnostics  • Logs       • Search   • Subbuilds      │  │
│  │  • Trigger      • Parameters • Ripgrep  • Navigation     │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────────┐   │
│  │ Cache Mgr    │  │ Vector Mgr   │  │ Cleanup Scheduler   │   │
│  └──────────────┘  └──────────────┘  └─────────────────────┘   │
└───────────┬──────────────────────────────────────┬─────────────┘
            │                                      │
            ▼                                      ▼
┌──────────────────────┐              ┌────────────────────────┐
│   Jenkins Instances  │              │   Qdrant Vector DB     │
│  • Production        │              │  • Semantic Search     │
│  • Staging           │              │  • Log Embeddings      │
│  • Development       │              │  • 6333 (HTTP/REST)    │
│  • API: REST/JSON    │              │  • 6334 (gRPC)         │
└──────────────────────┘              └────────────────────────┘

git clone https://github.com/karadHub/jenkins-ai-optimizer.git
cd jenkins-ai-optimizer

# Copy example configuration
cp config/mcp-config.example.yml config/mcp-config.yml

# Edit with your Jenkins credentials
# Windows: notepad config/mcp-config.yml
# Linux/Mac: nano config/mcp-config.yml

jenkins_instances:
  production:
    url: "https://jenkins.company.com"
    username: "your.email@company.com"
    token: "11a1b2c3d4e5f6789012345678901234" # From Jenkins: User → Configure → API Token
    display_name: "Production Jenkins"
    timeout: 30
    verify_ssl: true
    max_log_size: 100000000 # 100MB

  staging:
    url: "https://jenkins-staging.company.com"
    username: "your.email@company.com"
    token: "another-api-token-here"
    display_name: "Staging Environment"
    timeout: 30
    verify_ssl: true

default_instance:
  id: "production"

vector:
  disable_vector_search: false
  host: "http://qdrant:6333"
  collection_name: "jenkins-logs"
  embedding_model: "all-MiniLM-L6-v2"

# Linux/Mac
./start-jenkins.sh

# Windows (PowerShell)
docker-compose up -d

# Check service health
curl http://localhost:3008/health
# Expected: OK

# Check Qdrant
curl http://localhost:6333/health
# Expected: {"title":"qdrant - vector search engine","version":"..."}

# View logs
docker-compose logs -f jenkins_mcp_enterprise-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in editable mode with dev tools
pip install -e .[dev]

# Configure (same as Docker setup)
cp config/mcp-config.example.yml config/mcp-config.yml
# Edit config/mcp-config.yml with your Jenkins details

# Start Qdrant separately (optional, for vector search)
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant:latest

# Run the server
python -m jenkins_mcp_enterprise.server --transport stdio --config config/mcp-config.yml

# Or with HTTP transport
python -m jenkins_mcp_enterprise.server --transport http --config config/mcp-config.yml

jenkins_instances:
  prod-main:
    url: "https://jenkins-prod.company.com"
    username: "ci-bot@company.com"
    token: "prod-token-here"
    display_name: "Production Main"
    description: "Primary production Jenkins"
    timeout: 30
    verify_ssl: true
    max_log_size: 104857600 # 100MB
    default_timeout: 120

  prod-backup:
    url: "https://jenkins-prod-dr.company.com"
    username: "ci-bot@company.com"
    token: "prod-backup-token"
    display_name: "Production DR"
    timeout: 30
    verify_ssl: true

  staging:
    url: "https://jenkins-staging.company.com"
    username: "dev-bot@company.com"
    token: "staging-token"
    display_name: "Staging"
    timeout: 20
    verify_ssl: false # Self-signed cert

settings:
  fallback_instance: "prod-main"
  enable_health_checks: true
  health_check_interval: 300 # 5 minutes

error_patterns:
  compilation:
    - pattern: "error: .* undeclared"
      severity: high
      category: "Compilation Error"
      guidance: "Check for missing imports or variable declarations"

  timeout:
    - pattern: "timeout|timed out|took too long"
      severity: medium
      category: "Timeout"
      guidance: "Increase timeout values or investigate performance bottlenecks"

  permission:
    - pattern: "permission denied|access denied|403 Forbidden"
      severity: high
      category: "Permission Error"
      guidance: "Verify service account permissions and file access rights"

diagnose_build_failure(
    job_name="Deploy-Production",
    build_number=47,
    instance_id="production"  # Auto-resolved if only one instance
)

{
  "build_info": {
    "job_name": "Deploy-Production",
    "build_number": 47,
    "status": "FAILURE",
    "duration_ms": 342500
  },
  "failure_analysis": {
    "category": "Timeout",
    "severity": "medium",
    "matched_patterns": ["Connection timeout after 300 seconds"],
    "guidance": "Increase timeout values or investigate network connectivity",
    "extracted_data": {
      "timeout_value": "300",
      "service": "database-prod.company.internal"
    }
  },
  "recommendations": [
    "Check database server health and response times",
    "Verify network connectivity to database-prod.company.internal",
    "Consider increasing connection timeout in deployment configuration"
  ]
}

{
  "mcpServers": {
    "jenkins-optimizer": {
      "url": "http://localhost:3008/sse"
    }
  }
}

import requests

# Health check
response = requests.get("http://localhost:3008/health")
print(response.text)  # "OK"

# Call tools via MCP protocol (requires MCP client library)
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def diagnose_build():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "jenkins_mcp_enterprise.server", "--transport", "stdio"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            result = await session.call_tool(
                "diagnose_build_failure",
                arguments={
                    "job_name": "Deploy-Production",
                    "build_number": 47
                }
            )
            print(result)

# Enable in config/mcp-config.yml
vector:
  disable_vector_search: false
  host: "http://qdrant:6333"
  collection_name: "jenkins-logs"
  embedding_model: "all-MiniLM-L6-v2"
  chunk_size: 50 # Lines per chunk
  chunk_overlap: 5
  top_k_default: 5

# In diagnostic-parameters.yml
error_patterns:
  custom_service:
    - pattern: 'ServiceX: ERROR \[(?P<code>\d+)\]'
      severity: high
      category: "ServiceX Failure"
      guidance: "Check ServiceX documentation for error code {code}"
      extract_fields:
        - error_code: '\[(\d+)\]'
        - service_name: "(ServiceX)"

# Through AI assistant
"Analyze the complete build tree for Main-Pipeline build #150,
including all sub-builds and their status"

# Returns hierarchical tree with:
# - Build status at each level
# - Failure points highlighted
# - Build durations
# - Artifact locations

cache:
  cache_dir: "/tmp/mcp-jenkins"
  max_size_mb: 1000 # 1GB total cache
  retention_days: 7
  compression: true # gzip compression for logs

cleanup:
  interval_hours: 24
  retention_days: 7
  max_concurrent: 5 # Parallel cleanup tasks

# Clone and setup
git clone https://github.com/karadHub/jenkins-ai-optimizer.git
cd jenkins-ai-optimizer

# Create environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install with dev dependencies
pip install -e .[dev]

# Run tests
pytest

# Run linting
ruff check .

# Format code
ruff format .

# Check Docker containers
docker-compose ps

# View server logs
docker-compose logs jenkins_mcp_enterprise-server

# Common issues:
# 1. Port 3008 in use → Change in docker-compose.yml
# 2. Config file missing → Copy from config/mcp-config.example.yml
# 3. Invalid Jenkins credentials → Verify token in Jenkins

# Check Qdrant health
curl http://localhost:6333/health

# Verify Qdrant container
docker-compose logs qdrant

# Check configuration
# Ensure DISABLE_VECTOR_SEARCH=false in docker-compose.yml
# Verify QDRANT_HOST=http://qdrant:6333

# Test Jenkins API manually
curl -u "username:token" https://your-jenkins.com/api/json

# Common issues:
# 1. Incorrect URL → Verify in config/mcp-config.yml
# 2. Invalid token → Regenerate in Jenkins → User → Configure → API Token
# 3. SSL certificate issues → Set verify_ssl: false (staging only!)
# 4. Firewall blocking → Check network connectivity

# Check server health
curl http://localhost:3008/health

# Verify Claude config file location:
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

# Check Claude Desktop logs
# Windows: %APPDATA%\Claude\logs\
# Mac: ~/Library/Logs/Claude/

# Ensure MCP server URL is correct: http://localhost:3008/sse

# Monitor resource usage
docker stats jenkins_mcp_enterprise-server-1

# Check cache size
du -sh /tmp/mcp-jenkins  # Linux/Mac
# Windows: Check Docker volume size

# Optimize:
# 1. Reduce cache retention: retention_days: 3
# 2. Lower max_log_size: max_log_size: 50000000 (50MB)
# 3. Disable vector search if unused: disable_vector_search: true