mcp-jenkins-intelligence
by heniv96
README.md
# MCP Jenkins Intelligence
[](https://opensource.org/licenses/MIT)
[](https://python.org/)
[](https://github.com/jlowin/fastmcp)
[](https://jenkins.io/)
[](https://modelcontextprotocol.io/)
[](https://github.com/heniv96/mcp-jenkins-intelligence/stargazers)
[](https://github.com/heniv96/mcp-jenkins-intelligence/issues)
[](https://github.com/heniv96/mcp-jenkins-intelligence/pulls)
> **The Jenkins Intelligence Platform**
> Transform your Jenkins operations with AI-powered natural language interfaces and comprehensive pipeline analysis.
## Quick Start (Binary Distribution)
**Prefer a ready-to-use binary?** Download the latest release and start using MCP Jenkins Intelligence in seconds!
### Download & Install
```bash
# Option 1: Use the installer script (recommended)
curl -fsSL https://raw.githubusercontent.com/heniv96/mcp-jenkins-intelligence/main/install.sh | bash
# Option 2: Manual download
# Download from: https://github.com/heniv96/mcp-jenkins-intelligence/releases/latest
# Choose the appropriate binary for your platform:
# - mcp-jenkins-server-macos-arm64 (macOS Apple Silicon)
# - mcp-jenkins-server-linux-amd64 (Linux AMD64)
# Make executable: chmod +x mcp-jenkins-server-<platform>
```
### MCP Configuration
Add to your MCP client configuration (Cursor/VSCode):
```json
{
"mcpServers": {
"mcp-jenkins-intelligence": {
"command": "/path/to/mcp-jenkins-server",
"args": [],
"env": {
"JENKINS_URL": "https://your-jenkins-url",
"JENKINS_USERNAME": "your-username",
"JENKINS_TOKEN": "your-token"
}
}
}
}
```
**That's it!** No Python installation, no dependencies - just download and run!
---
## Overview
MCP Jenkins Intelligence is a comprehensive Model Context Protocol (MCP) solution designed for professional DevOps teams. It provides natural language interfaces for complex Jenkins pipeline operations, enabling teams to monitor, analyze, and optimize their CI/CD workflows through AI-powered conversations in VSCode and Cursor.
## Key Features
### **Intelligent Pipeline Analysis**
- **Real-time Monitoring**: Live pipeline status, health metrics, and performance analytics
- **AI-Powered Insights**: Natural language queries for complex pipeline analysis
- **Failure Analysis**: Deep dive into pipeline failures with intelligent root cause analysis
- **Performance Optimization**: Automated suggestions for improving build times and success rates
- **Advanced Analytics**: Comprehensive reporting and performance comparisons
- **Anomaly Detection**: AI-powered detection of unusual pipeline behavior patterns
### **Advanced AI Capabilities**
- **Natural Language Processing**: Conversational interface for complex DevOps operations
- **Smart Diagnostics**: AI-driven pipeline health analysis and troubleshooting guidance
- **Context-Aware Prompts**: Intelligent prompt suggestions for different analysis scenarios
- **Automated Reporting**: Proactive identification of issues and optimization opportunities
### **Enterprise Security & Compliance**
- **Multi-Authentication Support**: Standard Jenkins and Azure AD integration
- **Secure Communication**: TLS encryption for all Jenkins API communications
- **Audit Logging**: Comprehensive audit trails for all pipeline operations
- **Minimal Privilege**: Secure by design with least privilege access patterns
- **Enterprise-Grade Data Protection**: 19+ protection patterns for complete data anonymization
- **Complete Anonymization**: Pipeline names, cluster names, folder names, app names, branch names, organization names, repository names, and code file names are all protected
- **Hash-based Security**: Sensitive data is replaced with secure hashes before AI communication
- **Local Execution**: All data processing happens locally - no data leaves your environment
- **Recursive Protection**: Works on nested data structures and complex objects
- **Access Control Auditing**: Comprehensive permission and access control analysis
### **Advanced Analytics & Reporting**
- **Comprehensive Reports**: Generate detailed reports with metrics and insights
- **Performance Comparisons**: Compare pipeline performance across teams and environments
- **Trend Analysis**: Long-term performance and reliability trend analysis
### **Advanced AI Features**
- **Anomaly Detection**: AI-powered detection of unusual pipeline behavior patterns
- **Comprehensive Insights**: AI-generated insights and recommendations
### **Performance Optimization**
- **Build Time Analysis**: Detailed analysis and optimization suggestions for build times
### **Deployment & Distribution**
- **Multiple Deployment Options**: Development setup or production deployment
- **Cross-Platform Support**: Works on macOS, Linux, and Windows
- **Easy Configuration**: Simple setup with environment variables or MCP config
## Architecture
### MCP Protocol Integration
The following diagram shows how MCP Jenkins Intelligence integrates with VSCode and Cursor AI through the Model Context Protocol:
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ VSCode/ │ │ MCP Protocol │ │ Jenkins │
│ Cursor AI │◄──►│ │◄──►│ Intelligence │
│ │ │ │ │ Server │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ Jenkins API │
└─────────────────────────────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI Analysis │ │ Core Tools │ │ MCP Resources │
│ Engine │ │ (30 tools) │ │ & Prompts │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ • Health │ │ • List │ │ • Status │
│ Analysis │ │ • Details │ │ Resource │
│ • Failure │ │ • Builds │ │ • Summary │
│ Analysis │ │ • Configure │ │ Resource │
│ • AI Queries │ │ • Test │ │ • Dashboard │
│ • Metrics │ │ • Questions │ │ Resource │
│ • Dependencies │ │ • Trigger │ │ • Logs │
│ • Trends │ │ • Stop │ │ Resource │
│ • Security │ │ • Enable/Dis │ │ • Health │
│ • Export │ │ • Config │ │ Resource │
│ • Optimize │ │ • Predict │ │ • Analysis │
│ │ │ • Suggest │ │ Prompts │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
### Modular Architecture
The internal architecture follows a clean, modular design with separation of concerns:
```
┌─────────────────────────────────────────────────────────────────────────┐
│ MCP Layer │
├─────────────────┬─────────────────┬─────────────────────────────────────┤
│ FastMCP Server │ Tool Registry │ Request Router │
└─────────────────┴─────────────────┴─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Modular Services │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────────────┤
│ Models │ Services │ Resources │ Prompts │ │
├─────────────┼─────────────┼─────────────┼─────────────┼─────────────────┤
│ • Pipeline │ • Jenkins │ • Status │ • Analysis │ │
│ • Build │ • Core │ • Summary │ • Failure │ │
│ • Health │ • Control │ • Dashboard │ • Optimize │ │
│ • Failure │ • Monitor │ • Logs │ • Security │ │
│ • Query │ • AI │ • Health │ │ │
│ │ • Security │ │ │ │
└─────────────┴─────────────┴─────────────┴─────────────┴─────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Tool Categories │
├─────────────────┬─────────────────┬─────────────────┬─────────────────┤
│ Core Tools (9) │ Control Tools │ Monitoring (4) │ AI Tools (5) │
│ │ (4) │ │ │
├─────────────────┼─────────────────┼─────────────────┼─────────────────┤
│ • list_pipelines│ • trigger_build │ • get_metrics │ • Predict │
│ • get_details │ • stop_build │ • dependencies │ Failure │
│ • get_builds │ • enable_disable│ • monitor_queue │ • Suggest │
│ • ask_questions │ • get_config │ • analyze_trends│ Optimize │
│ • configure_ │ │ │ • Anomaly │
│ jenkins │ │ │ Detection │
│ • test_ │ │ │ • AI │
│ connection │ │ │ Insights │
│ • analyze_ │ │ │ • Retry │
│ health │ │ │ Logic │
│ • analyze_ │ │ │ │
│ failure │ │ │ │
│ • get_server_ │ │ │ │
│ info │ │ │ │
└─────────────────┴─────────────────┴─────────────────┴─────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Additional Tool Categories │
├─────────────┬─────────────┬─────────────┬─────────────────────────────┤
│ Security │ Jenkinsfile │ Analytics │ Performance │
│ (2) │ (3) │ (2) │ (1) │
├─────────────┼─────────────┼─────────────┼─────────────────────────────┤
│ • scan_ │ • get_ │ • generate_ │ • analyze_ │
│ security │ jenkinsfile│ report │ build_time │
│ │ • reconstruct│ • compare_ │ │
│ │ • suggest_ │ performance│ │
│ │ improvements│ │ │
└─────────────┴─────────────┴─────────────┴─────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ MCP Resources & Prompts │
├─────────────────────────┬─────────────────────────────────────────────┤
│ Resources (5) │ Prompts (4) │
├─────────────────────────┼─────────────────────────────────────────────┤
│ • pipeline://status │ • analyze_pipeline_prompt │
│ • pipeline://{name}/ │ • failure_analysis_prompt │
│ summary │ • optimization_prompt │
│ • pipeline://dashboard │ • security_audit_prompt │
│ • pipeline://{name}/ │ │
│ logs │ │
│ • pipeline://health │ │
└─────────────────────────┴─────────────────────────────────────────────┘
```
### Directory Structure
```
mcp-jenkins-intelligence/
├── server.py # Main MCP server (679 lines)
├── models/
│ ├── __init__.py
│ └── pipeline.py # Pydantic models
├── services/
│ ├── __init__.py
│ ├── jenkins_service.py # Jenkins API wrapper
│ ├── core_tools.py # Core pipeline tools
│ ├── monitoring_tools.py # Monitoring & analytics
│ ├── ai_tools.py # AI intelligence tools
│ ├── security_tools.py # Security & compliance
│ ├── advanced_ai_tools.py # Advanced AI features
│ ├── advanced_security_tools.py # Advanced security tools
│ ├── analytics_tools.py # Analytics & reporting
│ ├── performance_tools.py # Performance optimization
│ ├── execution_analysis_service.py # Execution analysis
│ └── jenkinsfile_retrieval_service.py # Jenkinsfile management
├── resources/
│ ├── __init__.py
│ └── pipeline_resources.py # MCP resources
├── prompts/
│ ├── __init__.py
│ └── pipeline_prompts.py # MCP prompts
├── config/
│ └── settings.py # Configuration management
├── utils/
│ ├── __init__.py
│ └── helpers.py # Helper functions
├── manuals/
│ ├── configuration/
│ │ └── README.md # Configuration guide
│ ├── examples/
│ │ └── mcp-config-standalone.json # Example configuration
│ ├── quick-start/
│ │ └── README.md # Quick start guide
│ └── troubleshooting/
│ └── README.md # Troubleshooting guide
├── dist/ # Built binaries (GitHub Releases)
│ ├── mcp-jenkins-server-macos-arm64 # macOS Apple Silicon binary
│ └── mcp-jenkins-server-linux-amd64 # Linux AMD64 binary
├── install.sh # Automated installer script
├── Makefile # Build automation
├── build.sh # Build test script
├── requirements.txt # Python dependencies
├── pyproject.toml # Project configuration
├── LICENSE # MIT License
└── README.md # This file
```
## Installation & Setup
### Prerequisites
- **Python 3.8+** (for development setup)
- **Jenkins Server** with API access
- **MCP Client** (VSCode with MCP extension or Cursor)
### Binary Installation (Recommended)
1. **Download the binary** for your platform:
```bash
# macOS (Apple Silicon)
curl -L -o mcp-jenkins-server https://github.com/heniv96/mcp-jenkins-intelligence/releases/latest/download/mcp-jenkins-server-macos-arm64
# Linux (AMD64)
curl -L -o mcp-jenkins-server https://github.com/heniv96/mcp-jenkins-intelligence/releases/latest/download/mcp-jenkins-server-linux-amd64
```
2. **Make it executable**:
```bash
chmod +x mcp-jenkins-server
```
3. **Configure your MCP client** (see MCP Configuration section above)
### Development Setup
1. **Clone the repository**:
```bash
git clone https://github.com/heniv96/mcp-jenkins-intelligence.git
cd mcp-jenkins-intelligence
```
2. **Install dependencies**:
```bash
pip install -r requirements.txt
```
3. **Set environment variables**:
```bash
export JENKINS_URL="https://your-jenkins-url"
export JENKINS_USERNAME="your-username"
export JENKINS_TOKEN="your-token"
```
4. **Run the server**:
```bash
python server.py
```
## Configuration
### Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `JENKINS_URL` | Jenkins server URL | Yes | - |
| `JENKINS_USERNAME` | Jenkins username | Yes | - |
| `JENKINS_TOKEN` | Jenkins API token | Yes | - |
| `MCP_SERVER_PORT` | MCP server port | No | 8000 |
### MCP Client Configuration
#### VSCode Configuration
Add to your `settings.json`:
```json
{
"mcp.servers": {
"mcp-jenkins-intelligence": {
"command": "/path/to/mcp-jenkins-server",
"args": [],
"env": {
"JENKINS_URL": "https://your-jenkins-url",
"JENKINS_USERNAME": "your-username",
"JENKINS_TOKEN": "your-token"
}
}
}
}
```
#### Cursor Configuration
Add to your `mcp.json`:
```json
{
"mcpServers": {
"mcp-jenkins-intelligence": {
"command": "/path/to/mcp-jenkins-server",
"args": [],
"env": {
"JENKINS_URL": "https://your-jenkins-url",
"JENKINS_USERNAME": "your-username",
"JENKINS_TOKEN": "your-token"
}
}
}
}
```
## Usage
### Basic Commands
Once configured, you can interact with Jenkins through natural language:
- **"List all pipelines"** - Get a list of all available pipelines
- **"Show me the health of pipeline X"** - Get detailed health analysis
- **"What's wrong with the failed build?"** - Analyze build failures
- **"Optimize the build time for pipeline Y"** - Get optimization suggestions
- **"Generate a report for last week"** - Create comprehensive reports
### Advanced Features
- **AI-Powered Analysis**: Ask complex questions about your pipeline performance
- **Anomaly Detection**: Get alerts about unusual pipeline behavior
- **Security Auditing**: Comprehensive security analysis of your Jenkins setup
- **Performance Optimization**: Detailed build time analysis and suggestions
## API Reference
### Core Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `list_pipelines` | List all available pipelines | `search` (optional) |
| `get_pipeline_details` | Get detailed pipeline information | `pipeline_name` |
| `get_pipeline_builds` | Get recent builds for a pipeline | `pipeline_name`, `limit`, `status` |
| `analyze_pipeline_health` | Analyze pipeline health and performance | `pipeline_name`, `period` |
| `analyze_pipeline_failure` | Analyze specific pipeline failure | `pipeline_name`, `build_number` |
| `ask_pipeline_question` | Ask natural language questions | `question`, `pipeline_names` |
### Monitoring Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `get_pipeline_metrics` | Get detailed pipeline metrics | `pipeline_name`, `period` |
| `get_pipeline_dependencies` | Get pipeline dependencies | `pipeline_name` |
| `monitor_pipeline_queue` | Monitor Jenkins build queue | - |
| `analyze_build_trends` | Analyze build trends across pipelines | `pipeline_names`, `period` |
### AI Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `predict_pipeline_failure` | Predict likely pipeline failures | `pipeline_name` |
| `suggest_pipeline_optimization` | Get optimization suggestions | `pipeline_name` |
| `detect_pipeline_anomalies` | Detect unusual pipeline behavior | `pipeline_name`, `sensitivity` |
| `generate_ai_insights` | Generate comprehensive AI insights | `pipeline_name`, `insight_type` |
## Security
### Data Protection
MCP Jenkins Intelligence implements comprehensive data protection:
- **Complete Anonymization**: All sensitive data is replaced with secure hashes
- **Local Processing**: All data processing happens locally
- **No External Calls**: No data is sent to external AI services
- **Recursive Protection**: Works on nested data structures
- **Access Control Auditing**: Comprehensive permission analysis
### Supported Protection Patterns
- Pipeline names
- Cluster names
- Folder names
- Application names
- Branch names
- Organization names
- Repository names
- Code file names
- Build numbers
- Timestamps
- URLs and paths
- User information
- Token values
- Configuration data
- Log entries
- Error messages
- Stack traces
- Environment variables
- And more...
## Troubleshooting
### Common Issues
1. **Connection Failed**: Check your Jenkins URL and credentials
2. **Permission Denied**: Verify your Jenkins user has appropriate permissions
3. **Binary Not Found**: Ensure the binary is executable and in your PATH
4. **MCP Client Not Responding**: Check your MCP configuration
### Debug Mode
Enable debug logging by setting:
```bash
export DEBUG=1
```
### Getting Help
- Check the [troubleshooting guide](manuals/troubleshooting/README.md)
- Open an [issue](https://github.com/heniv96/mcp-jenkins-intelligence/issues)
- Review the [examples](manuals/examples/)
## Contributing
We welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md) for details.
### Development
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
### Building
```bash
# Install dependencies
pip install -r requirements.txt
# Run tests
python -m pytest
# Build binary
make build
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [FastMCP](https://github.com/jlowin/fastmcp) - The MCP framework
- [Jenkins](https://jenkins.io/) - The CI/CD platform
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
## Changelog
### v1.2.0
- Added comprehensive data protection and anonymization
- Improved binary distribution with cross-platform support
- Enhanced security features and access control auditing
- Added advanced AI capabilities and anomaly detection
- Improved performance optimization tools
- Added comprehensive reporting and analytics
### v1.1.0
- Initial release with core MCP functionality
- Basic pipeline analysis and monitoring
- AI-powered insights and recommendations
---
**Made with ❤️ for the DevOps community**This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues