使用说明

Jenkins MCP服务器

用于Jenkins CI/CD集成的模型上下文协议（MCP）服务器，通过MCP兼容客户端中的自然语言查询实现与Jenkins的无缝交互。

🚀 特性

Jenkins集成

作业状态监控 -获取Jenkins作业的实时状态，包括构建号、结果和持续时间
构建日志检索 -获取特定版本的控制台日志以分析故障
作业管理 -列出所有可用作业并触发新构建
队列监视 -监控Jenkins构建队列中的待处理作业
多分支管道支持 -全力支持多分支管道项目
连接调试 -用于测试和调试Jenkins连接的内置工具

支持的MCP客户端

带有MCP扩展的VS代码
光标IDE
克劳德桌面
任何兼容MCP的客户端

📦 安装

先决条件

Python 3.7或更高版本
在启用API的情况下访问Jenkins服务器
用于身份验证的Jenkins API令牌

快速开始

克隆存储库：

git clone https://github.com/your-username/jenkins-mcp-server.git
cd jenkins-mcp-server

创建虚拟环境：

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

安装依赖项：
```
pip install -r requirements.txt
```

设置环境变量：

# Create a .env file or set environment variables
export JENKINS_URL="https://your-jenkins-server.com/"
export JENKINS_USER="your-username"
export JENKINS_API_TOKEN="your-api-token"

运行服务器：
```
python src\index.py --mode http --debug
```
服务器将于启动 http://localhost:5001 默认情况下。

⚙️ 配置

环境变量

变量	必填	描述	示例
`JENKINS_URL`	是	Jenkins服务器URL	`https://jenkins.example.com/`
`JENKINS_USER`	是	Jenkins用户名	`your-username`
`JENKINS_API_TOKEN`	是	Jenkins API令牌	`your-api-token`
`PORT`	否	服务器端口（默认值：5001）	`5001`

Jenkins API令牌设置

登录您的Jenkins服务器
转到您的用户配置文件→ 配置
向下滚动至“API代币”部分
点击“添加新令牌”
复制生成的令牌并将其用作 JENKINS_API_TOKEN

🛠️ 可用工具

作业管理

get_job_status -获取特定Jenkins作业的状态
get_build_logs -检索构建的控制台日志
list_jobs -列出所有可用的Jenkins作业
trigger_job -为作业启动新的构建

监控

get_queue_info -获取排队构建的信息
debug_connections -测试Jenkins连接和配置

📝 使用示例

与VS代码MCP扩展一起使用

在VS代码中安装MCP扩展（使用提供的示例MCP.json）
在MCP设置中配置Jenkins MCP服务器
使用自然语言查询，如：
- “开发部门的建设情况如何？”
- “显示上次失败构建的日志”
- “列出项目中的所有作业”
- “触发主分支的构建”

API直接使用

import requests

# Get job status
response = requests.post('http://localhost:5001/jenkins/get_job_status', 
                        json={'job_name': 'my-project/develop'})
print(response.json())

# Get build logs  
response = requests.post('http://localhost:5001/jenkins/get_build_logs',
                        json={'job_name': 'my-project/develop', 'build_number': 123})
print(response.json())

🧪 测试

运行测试套件：

# Run all tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_jenkins_handlers.py

# Run with coverage
python -m pytest tests/ --cov=src

📁 项目结构

jenkins-mcp-server/
├── src/
│   ├── index.py              # Main MCP server entry point
│   └── tools/
│       ├── jenkins_tools.py  # Tool definitions
│       └── handlers/
│           ├── jenkins_handlers.py  # Jenkins API handlers
│           └── debug_handlers.py    # Debug utilities
├── tests/                    # Test files
├── app.py                   # Flask application entry point
├── requirements.txt         # Python dependencies
├── README.md               # This file
├── CONTRIBUTING.md         # Contribution guidelines
└── LICENSE                 # MIT License

🚗 路线图

🎯 计划的功能

第一阶段：核心改进

[ ] 响应缓存 -实现智能缓存以减少Jenkins服务器负载
- 为可配置的时间间隔缓存作业状态
- 缓存已完成构建的构建日志
- 实施缓存失效策略
[ ] 增强的错误处理 -改进错误消息和恢复机制
[ ] 配置验证 -为Jenkins连接添加启动验证

第二阶段：高级功能

[ ] 管道可视化 -生成Jenkins管道的可视化表示
[ ] 构建比较 -比较不同分支或时间段的构建
[ ] 通知集成 -支持Slack、Teams和电子邮件通知
[ ] 指标仪表板 -建立成功率、持续时间趋势和绩效指标

第3阶段：部署和运营

[ ] 容器化 -Docker支持，易于部署

# Planned Docker setup
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5001
CMD ["python", "app.py"]

[ ] Kubernetes部署 -Helm图表和K8s清单
[ ] 健康监测 -Prometheus指标和健康检查端点
[ ] 认证 -支持OAuth和API密钥身份验证

第四阶段：企业特性

[ ] 多Jenkins支持 -连接到多个Jenkins实例
[ ] 基于角色的访问 -实现基于权限的工具访问
[ ] 审计日志 -跟踪所有API调用和用户操作
[ ] 高可用性 -支持负载平衡和故障转移

🎉 社区贡献

我们欢迎在这些领域作出贡献：

集成 -支持其他CI/CD平台（GitHub Actions、GitLab CI）
插件 -自定义Jenkins插件集成
UI组件 -非MCP使用的Web仪表板
文档 -教程、示例和最佳实践

🤝 贡献

我们欢迎捐款！请看贡献.md 有关以下内容的详细信息：

开发设置
代码风格指南
测试要求
拉取请求流程

快速贡献步骤

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
进行更改并添加测试
运行测试套件： python -m pytest tests/
提交您的更改： git commit -m 'Add amazing feature'
推到分支： git push origin feature/amazing-feature
打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 支持

问题: GitHub问题
讨论: GitHub讨论
文档：检查文档文件夹获取详细指南

🙏 致谢

灵感来自 CircleCI MCP服务器设计模式
与模型上下文协议规格
感谢所有贡献者和开源社区

⭐ 如果你觉得这个存储库有用，请为其加星！ 调试=真


### Running the Server

1. **Using the batch file** (Windows):
   ```batch
   run.bat

直接使用Python:
```
python src/index.py
```

使用环境变量:

export JENKINS_URL="http://your-jenkins-server/"
export JENKINS_USER="your-username"
export JENKINS_API_TOKEN="your-token"
python src/index.py

MCP客户端配置

VS代码

添加到您的 .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "jenkins-url",
      "description": "Jenkins Server URL",
      "default": "http://mycompany.com/"
    },
    {
      "type": "promptString",
      "id": "jenkins-user", 
      "description": "Jenkins Username"
    },
    {
      "type": "promptString",
      "id": "jenkins-token",
      "description": "Jenkins API Token",
      "password": true
    }
  ],
  "servers": {
    "jenkins-mcp-server": {
      "type": "stdio",
      "command": "python",
      "args": ["src/index.py"],
      "env": {
        "JENKINS_URL": "${input:jenkins-url}",
        "JENKINS_USER": "${input:jenkins-user}",
        "JENKINS_API_TOKEN": "${input:jenkins-token}"
      }
    }
  }
}

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "jenkins-mcp-server": {
      "command": "python",
      "args": ["src/index.py"],
      "env": {
        "JENKINS_URL": "http://your-jenkins-server/",
        "JENKINS_USER": "your-username", 
        "JENKINS_API_TOKEN": "your-token"
      }
    }
  }
}

光标IDE

将MCP配置添加到光标中：

{
  "mcpServers": {
    "jenkins-mcp-server": {
      "command": "python",
      "args": ["src/index.py"],
      "env": {
        "JENKINS_URL": "http://your-jenkins-server/",
        "JENKINS_USER": "your-username",
        "JENKINS_API_TOKEN": "your-token"
      }
    }
  }
}

使用示例

使用MCP工具

检查Jenkins作业状态:
```
"Get the status of the MyAwesome job"
```
列出所有Jenkins作业:
```
"List all available Jenkins jobs"
```

获取构建日志:

"Get the console logs for the latest MyAwesome build"

触发作业:
```
"Trigger the MyAwesome job"
```

使用REST API

# Get job status
curl "http://localhost:5001/context/job-status?job=MyAwesome"



## Troubleshooting

1. **Connection issues**: Use the `debug_connections` tool to check Jenkins and Metabase connectivity
2. **Authentication**: Ensure Jenkins API token has necessary permissions
3. **Environment variables**: Verify all required environment variables are set
4. **Port conflicts**: Change the PORT environment variable if 5001 is in use

## License

MIT License