thecturner/jankins

jankins

Token-optimized Jenkins MCP server with smart log handling and failure triage

jankins provides MCP-compliant access to Jenkins with features designed for AI coding assistants:

• 🎯 Token-aware formatting: Summary/full/diff output modes minimize context usage
• 📊 Smart log truncation: Progressive retrieval with byte offsets, regex filtering, and ANSI cleanup
• 🔍 Failure triage: Automated root cause analysis with hypotheses and next steps
• ⚡ Efficient by default: Returns compact summaries unless full detail is requested
• 🛡️ Better error handling: Structured errors with remediation hints and correlation IDs
• 📝 Built-in prompts: Pre-built workflows for common CI/CD tasks

Quick Start

Installation

pip install -e .

Basic Usage

# Set environment variables
export JENKINS_URL=https://jenkins.example.com
export JENKINS_USER=myuser
export JENKINS_API_TOKEN=11234567890abcdef1234567890abcdef

# Start the server
jankins

# Or use CLI flags
jankins --jenkins-url https://jenkins.example.com \
        --jenkins-user myuser \
        --jenkins-token $TOKEN \
        --bind 0.0.0.0:8080

Generate Jenkins API Token

1. Log in to Jenkins
2. Click your username (top right) → Configure
3. Scroll to "API Token" section
4. Click "Add new Token"
5. Give it a name and click "Generate"
6. Copy the token (you won't see it again!)

Configuration

Configuration via environment variables or CLI flags. CLI flags take precedence.

MCP Tools

jankins provides 25+ MCP tools organized by category:

Jobs

• list_jobs: List jobs with prefix filtering and pagination
• get_job: Get detailed job information
• trigger_build: Trigger a new build with parameters
• enable_job / disable_job: Enable or disable a job

Builds

• get_build: Get build information (supports number or "last")
• get_build_changes: Get SCM changes/commits for a build
• get_build_artifacts: List build artifacts

Logs

• get_build_log: Get logs with smart truncation and filtering
  • Supports: filter_regex, redact, start byte offset, max_bytes
  • Returns summary by default with error counts and failing stages
• search_log: Search logs for pattern with context window

SCM & Pipeline

• get_job_scm: Get job SCM configuration
• get_build_scm: Get SCM info (commit, branch) for a build

Health & System

• whoami: Get current user info and permissions
• get_status: Jenkins version and queue depth
• summarize_queue: Compact build queue summary

Advanced Analysis

• triage_failure: Analyze failed builds with:

  • Root cause hypotheses
  • Top error messages
  • Failing stages
  • Suspect commits
  • Recommended next steps

• compare_runs: Compare two builds for:

  • Duration differences
  • Result changes
  • Stage-level diffs (with Blue Ocean)

• get_pipeline_graph: Get pipeline visualization with stages, parallel execution, and timing (Blue Ocean)

• analyze_build_log: Analyze logs with build tool-specific parsers (Maven, Gradle, NPM) for detailed error analysis and recommendations

• retry_flaky_build: Retry flaky builds with configurable attempts and delays

Test Results

• get_test_report: Get test results summary (JUnit, pytest, etc.)
• get_failed_tests: List failed tests with error details and stack traces
• compare_test_results: Compare test results between builds for regression detection
• detect_flaky_tests: Identify flaky tests across multiple builds

Logs (Enhanced)

• tail_log_live: Poll-based live log tailing with progressive byte offsets

Output Formats

All tools support format parameter:

• summary (default): Compact, token-efficient view
• full: Complete data with all fields
• diff: Differences only (for comparisons)
• ids: IDs and URLs only

Example:

{
  "name": "list_jobs",
  "arguments": {
    "format": "summary",
    "page_size": 20
  }
}

Built-in Prompts

jankins includes pre-built prompts for common workflows:

• investigate_failure: Full failure investigation workflow
• tail_errors: Show only warnings and errors from a build
• compare_builds: Compare two builds to find differences
• check_job_health: Check overall job health and stability
• trigger_with_params: Trigger parameterized build with guidance
• search_logs: Search logs for specific patterns

Client Examples

Claude Desktop (stdio mode - recommended)

Add to your MCP settings:

{
  "mcpServers": {
    "jankins": {
      "command": "jankins",
      "env": {
        "JENKINS_URL": "https://jenkins.example.com",
        "JENKINS_USER": "myuser",
        "JENKINS_API_TOKEN": "your-token-here"
      }
    }
  }
}

The default stdio transport communicates via stdin/stdout, which is the standard for MCP clients like Claude Desktop.

HTTP Mode (for HTTP-based MCP clients)

If your client requires HTTP transport:

{
  "mcp": {
    "servers": {
      "jankins": {
        "url": "http://localhost:8080/mcp",
        "headers": {
          "Content-Type": "application/json"
        }
      }
    }
  }
}

Direct HTTP Request

Start in HTTP mode:

jankins --transport http

Then make requests:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_build",
      "arguments": {
        "name": "my-job",
        "number": "last",
        "format": "summary"
      }
    }
  }'

Example Workflows

Investigate a Failing Build

Use the "investigate_failure" prompt with job "backend-api"

This will:

1. Get build status
2. Retrieve error summary from logs
3. Perform failure triage
4. Show suspect commits
5. Provide recommended next steps

Compare Two Builds

{
  "name": "compare_runs",
  "arguments": {
    "name": "backend-api",
    "base": "100",
    "head": "101"
  }
}

Search Logs for Error Pattern

{
  "name": "search_log",
  "arguments": {
    "name": "backend-api",
    "pattern": "OutOfMemoryError",
    "window_lines": 10
  }
}

Get Only Errors from Last Build

{
  "name": "get_build_log",
  "arguments": {
    "name": "backend-api",
    "number": "last",
    "filter_regex": "ERROR|FATAL",
    "redact": true,
    "format": "summary"
  }
}

Error Handling

jankins provides structured errors with:

• Error code: JSON-RPC compliant error codes
• Correlation ID: Track requests across logs
• Hint: Human-readable remediation hint
• Next actions: Specific steps to resolve the issue
• Docs URL: Link to troubleshooting guide

Error taxonomy:

• InvalidParams (-32602): Invalid tool parameters
• Unauthorized (-32001): Authentication failed
• Forbidden (-32002): Insufficient permissions
• NotFound (-32003): Resource not found
• Timeout (-32007): Request timed out
• UpstreamError (-32006): Jenkins server error

Token Optimization

jankins minimizes token usage through:

1. Default summaries: Summary format by default, full on request
2. Field limiting: Only essential fields in summary mode
3. Smart truncation: Progressive log retrieval with byte limits
4. Token estimation: Responses include estimated token count
5. Structured data: Compact tables and lists over verbose text
6. Metadata separation: Performance data in _meta section

Example response structure:

{
  "build_number": 42,
  "result": "FAILURE",
  "duration": "2m 15s",
  "_meta": {
    "correlation_id": "abc-123",
    "took_ms": 250,
    "format": "summary",
    "token_estimate": 180
  }
}

Security

• Explicit configuration: Uses env vars or CLI flags (ignores .env files in working directory)
• Basic auth: Uses Jenkins API tokens (never passwords)
• Optional Origin validation: Enforce allowed origins
• No secret logging: Credentials are redacted in logs
• Secret masking: Jenkins secret masks are preserved/redacted

Note: jankins ignores any .env files in your working directory and only reads the specific environment variables it needs (JENKINS_, MCP_, etc.). This prevents conflicts with project .env files.

Generate API tokens:

Jenkins → User → Configure → API Token → Add new Token

Health Checks

• GET /_health: Basic health check
• GET /_ready: Readiness check (verifies Jenkins connectivity)
• GET /_metrics: Placeholder for Prometheus metrics

Development

Run from Source

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

# Run server
python -m jankins --jenkins-url $URL --jenkins-user $USER --jenkins-token $TOKEN

# With debug logging
python -m jankins --log-level DEBUG --debug-http

Testing

pytest tests/

Docker

See docker-compose.yml for local Jenkins + jankins setup.

docker-compose up

This starts:

• Jenkins LTS on port 8081
• jankins MCP server on port 8080

Feature Comparison

Troubleshooting

"Unauthorized" Error

• Verify JENKINS_USER and JENKINS_API_TOKEN are correct
• Regenerate API token from Jenkins user settings
• Check Jenkins server is accessible

"Timeout" Error

• Increase --timeout value
• Check Jenkins server responsiveness
• Verify network connectivity

"Tool not found" Error

• Ensure server started successfully
• Check MCP client configuration
• Verify tool name spelling

Large Logs Timing Out

• Use max_bytes parameter to limit retrieval
• Use filter_regex to reduce log size
• Use format=summary for overview first

License

MIT

Contributing

Contributions welcome! Please:

1. Add tests for new features
2. Follow existing code style
3. Update documentation
4. Add type hints

Acknowledgments

Built on:

• python-jenkins for Jenkins API
• Model Context Protocol spec
• Starlette for transport layer