Azure DevOps Sprint MCP服务器
用于Azure DevOps冲刺板和工作项管理的模型上下文协议（MCP）服务器
](https://github.com/yourusername/azure-devops-sprint-mcp)  ](https://www.docker.com/) 
企业级MCP服务器，用于通过自然语言（Claude Desktop）或编程接口管理Azure DevOps工作项、冲刺和板。使用FastMCP构建，专为Azure托管身份验证的生产使用而设计。
✨ 特性
- 15个MCP工具 -完成工作项和冲刺管理
- 多项目支持 -同时处理多个Azure DevOps项目（v2.1中的新功能）
- 健康与监测 -内置服务器健康检查和性能指标
- 企业身份验证 -Azure托管身份、服务主体或PAT支持
- 生产就绪 -错误处理、重试逻辑、缓存和安全强化
- Docker原生 -具有健康检查和双重运输模式的优化集装箱
🚀 快速开始
先决条件
- Linux/macOS：Python 3.10+或Docker
- 视窗：带WSL 2的Docker桌面→ 请参阅Windows/WSL指南
- Azure DevOps组织访问
- 身份验证：Azure CLI(
az login)、服务负责人或PAT
______________________________________________________________________
步骤1：克隆和配置
# Clone repository
git clone https://github.com/yourusername/azure-devops-sprint-mcp.git
cd azure-devops-sprint-mcp
# Create .env file from template
cp .env.example .env
# Edit .env with your settings (required!)
nano .env # or use your preferred editor.env中需要：
AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
AZURE_DEVOPS_PROJECT=YourProject # Recommended______________________________________________________________________
步骤2：选择部署模式
选项A:Docker（推荐）
# Login to Azure for authentication
az login
# Start server with Docker
docker-compose up -d
# View logs
docker-compose logs -f选项B:Python（本地开发）
# Run setup script (creates venv, installs dependencies)
./scripts/setup.sh
# Login to Azure for authentication
az login
# Start server
./scripts/start.sh______________________________________________________________________
快速验证
# Check server is running
curl http://localhost:8000/mcp
# Check Docker logs (if using Docker)
docker-compose logs
# Stop server
docker-compose down # Docker mode
# OR
./scripts/stop.sh # Python mode⚙️ 配置
这 .env 文件支持以下选项：
# Required
AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
# Recommended (default project for multi-project support)
AZURE_DEVOPS_PROJECT=MyProject
# Authentication Methods (choose one)
# 1. Managed Identity (Recommended) - Just run 'az login', no config needed!
# 2. Service Principal (for automation)
# AZURE_CLIENT_ID=your-client-id
# AZURE_CLIENT_SECRET=your-client-secret
# AZURE_TENANT_ID=your-tenant-id
# 3. Personal Access Token (legacy)
# AZURE_DEVOPS_PAT=your-pat-token
# Server Settings (optional)
# MCP_TRANSPORT=http
# PORT=8000推荐： 使用Azure托管身份(az login)无需管理令牌，自动刷新，并在Azure DevOps审计日志中保留您的用户身份。
📖 文档
- 设置和安装 -所有部署模式的完整设置指南
- 使用指南 -工具参考、示例和最佳实践
- WSL+Claude桌面 -Claude Desktop集成的Windows用户指南
- **** -Docker和生产部署指南
- 故障排除 -常见问题和解决方案
- API 参考 -字段、状态、类型和WIQL查询
- 开发指南 -对于贡献者
- 更新日志 -版本历史
🛠️ MCP工具（共15个）
核心工作项工具
get_my_work_items-获取分配的工作项get_work_item_details-获取完整的工作项详细信息update_work_item-更新工作项字段create_work_item-创建新工作项add_comment-向工作项添加注释
Sprint管理工具
get_sprint_work_items-获取冲刺的工作项get_current_sprint-获取当前活动冲刺get_team_iterations-列出所有冲刺/迭代move_to_sprint-在冲刺之间移动工作项
高级查询工具（v2.0中的新功能）
get_work_item_hierarchy-获取父子工作项树search_work_items-跨工作项的全文搜索get_historical_work_items-查询历史状态变化
监控工具（v2.1中的新功能）
health_check-服务器运行状况和身份验证状态get_service_statistics-性能指标和缓存统计数据
MCP资源（3）
sprint://current-当前冲刺概述sprint://{iteration_path}-具体冲刺细节workitem://{id}-带有注释的工作项详细信息
💡 常见用例
每日与Claude Desktop的对话
“显示我今天的活动工作项”
“我们目前的冲刺状态如何？”
“将工作项12345移动到下一个冲刺”
Sprint计划
# Get current sprint capacity
sprint = await sprint_service.get_current_sprint()
print(f"Progress: {sprint['completion_percentage']}%")
# Get work items
items = await sprint_service.get_sprint_work_items()多项目管理（新）
“显示项目A和项目B中的工作项”
# Work with multiple projects
manager = ServiceManager(auth)
items_a = await manager.get_workitem_service("Project-A").get_my_work_items()
items_b = await manager.get_workitem_service("Project-B").get_my_work_items()看 docs/USAGE.md 更多示例。
🔐 认证
服务器支持三种身份验证方法（按顺序尝试）：
1.Azure托管身份(⭐ 推荐）
优点：
- ✅ 使用您的个人Azure凭据
- ✅ 没有要管理或轮换的令牌
- ✅ 自动令牌刷新
- ✅ 以您的用户身份跟踪的所有操作
设置：
# Just login to Azure CLI
az login
# Server automatically uses your credentials
./scripts/start.sh2.服务负责人（自动化）
# Set in .env
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id3.个人访问令牌（仅限开发）
# Set in .env
AZURE_DEVOPS_PAT=your-pat-token看 docs/SETUP.md 详细的身份验证设置。
🐳 Docker部署
快速开始
# Start with docker-compose
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down生产部署
看 用于：
- Azure容器注册表（ACR）部署
- Azure容器实例（ACI）部署
- 健康检查和监测
- 环境配置
重要提示
缓存配置：Azure DevOps SDK缓存存储在 /tmp/.azure-devops （短暂的，在容器重新启动时重新创建）。应用程序的性能缓存(src/cache.py)它位于内存中，为工作项查询提供95%以上的命中率。不需要持久缓存卷，简化了部署并避免了权限问题。
🖥️ Claude桌面集成
Linux/macOS（直接）
编辑 ~/.config/Claude/claude_desktop_config.json:
{
"mcpServers": {
"azure-devops": {
"command": "python",
"args": ["/path/to/azure-devops-sprint-mcp/scripts/run_stdio.py"],
"env": {
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/yourorg",
"AZURE_DEVOPS_PROJECT": "YourProject"
}
}
}
}Windows+WSL（Docker桥）
请参阅综合指南： docs/WSL-CLAUDE-DESKTOP.md
快速摘要：
- 在WSL中启动Docker容器：
docker-compose up -d- 配置克劳德桌面（Windows）：
{
"mcpServers": {
"azure-devops": {
"command": "C:\\Users\\YourUsername\\azure-devops-mcp\\run_docker_stdio.bat"
}
}
}- 重新启动克劳德桌面
📁 项目结构
azure-devops-sprint-mcp/
├── src/ # Core MCP server implementation
│ ├── server.py # FastMCP server (15 tools + 3 resources)
│ ├── auth.py # Multi-method authentication
│ ├── service_manager.py # Multi-project management
│ ├── cache.py # Performance caching
│ ├── validation.py # Security validators
│ └── services/ # Sprint and work item services
├── tests/ # Comprehensive test suite
├── docs/ # Complete documentation
├── scripts/ # Maintenance and bridge scripts
│ ├── setup.sh # First-time setup
│ ├── start.sh # Start server
│ ├── stop.sh # Stop server
│ ├── restart.sh # Restart server
│ ├── run_stdio.py # STDIO bridge (Linux/macOS)
│ ├── run_docker_stdio.py # Docker bridge (Windows/WSL)
│ └── run_docker_stdio.bat # Batch bridge (Windows)
├── examples/ # Example usage scripts
├── docker/ # Docker development files
├── Dockerfile # Production Docker image
├── docker-compose.yml # Docker Compose config
├── pyproject.toml # Package metadata
├── requirements.txt # Dependencies
└── .env.example # Configuration template🧪 发展
设置开发环境
# Clone and setup
git clone https://github.com/yourusername/azure-devops-sprint-mcp.git
cd azure-devops-sprint-mcp
./scripts/setup.sh
# Install dev dependencies
pip install -e ".[dev]"运行测试
# All tests
pytest
# Unit tests only (skip integration)
pytest -m "not integration"
# With coverage
pytest --cov=src代码质量
# Format code
black src tests
# Lint
ruff check src tests
# Type checking
mypy src看 docs/DEVELOPMENT.md 详细的开发指南。
🎯 v2.1的新增功能
- 多项目支持 -同时处理多个Azure DevOps项目
- 用于延迟加载、缓存服务实例的ServiceManager - 每个项目的缓存隔离 - 所有工具均接受可选 project 参数 - 与默认项目向后兼容
- 健康与监测工具
- health_check() -服务器运行状况和身份验证状态 - get_service_statistics() -性能指标和缓存统计信息
- 改进文档
- 将文档重新组织到docs/文件夹中 - 专用Windows/WSL设置指南 - 综合故障排除指南 - 完整的API参考
- 维护脚本
- ./scripts/setup.sh -自动设置 - ./scripts/start.sh -启动服务器（Docker或Python） - ./scripts/stop.sh -停止服务器 - ./scripts/restart.sh -重新启动服务器
看 更改日志.md 查看完整的版本历史记录。
🐛 故障排除
常见问题
身份验证失败：
# Verify Azure login
az account show
# If not logged in:
az login服务器无法启动：
# Check logs
docker-compose logs
# Restart
./scripts/restart.shWindows/WSL问题：
- 确保Docker桌面正在运行
- 在Docker桌面设置中启用WSL集成
- 看 docs/WSL-CLAUDE-DESKTOP.md
看 docs/TROUBLESHOOTING.md 获取全面的故障排除指南。
📊 演出
- ✅ 70%较小的响应 -特定字段选择与展开=“全部”
- ✅ 95%以上的缓存命中率 -基于TTL的内存缓存，具有自动失效功能
- ✅ 亚秒级缓存查询 -内存中的LRU缓存（不需要持久存储）
- ✅ 自动重试 -瞬态误差的指数回退
- ✅ 强制执行查询限制 -没有无边界的结果集
- ✅ 简化部署 -SDK缓存在
/tmp（无卷权限管理）
🤝 贡献
欢迎投稿！请看 docs/DEVELOPMENT.md 用于：
- 开发设置
- 代码风格指南
- 测试要求
- 拉取请求流程
📄 许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
🔗 链接
- 文档： docs/
- 问题： https://github.com/yourusername/azure-devops-sprint-mcp/issues
- Azure DevOps API： https://learn.microsoft.com/rest/api/azure/devops/
- MCP协议： https://modelcontextprotocol.io/
- FastMCP： https://github.com/jlowin/fastmcp
______________________________________________________________________
内置于❤️ 使用FastMCP和Azure DevOps REST API
*2.1版-多项目支持-生产就绪*