使用说明

Azure DevOps工作项管理器-MCP服务器（模块化架构）

这是一个模型上下文协议（MCP）服务器，提供管理Azure DevOps工作项的工具。它具有干净、模块化的架构，关注点分离，允许您创建、更新、删除和检索工作项，以及管理项目设置和在Epics和Tasks之间创建层次关系。

🏗️ 模块化架构

ado_builder/
├── core/                          # Core functionality
│   ├── config.py                  # Configuration and authentication
│   └── azure_client.py            # Azure DevOps REST API client
├── services/                      # Business logic
│   ├── formatting.py              # Text processing and HTML formatting
│   └── work_items.py              # Work item management operations
├── resources/                     # Documentation and standards
│   ├── standards.py               # Quality templates and standards
│   └── guides.py                  # User guides and workflows
├── utils/                         # Utility functions
│   └── helpers.py                 # Common helper functions
├── mcp_server.py                  # Main MCP server (modular)
└── test_modular.py                # Comprehensive test suite

⭐ 主要特点

单个工作项：一次创建和管理一个任务和史诗
精简史诗创作：使用自动链接在单个命令中创建具有多个任务的Epic
综合总结：获取所有已创建工作项的带URL的格式化表
专业模板：具有结构化格式的内置描述模板（目标、技术要求、实施步骤、验收标准、业务背景）
HTML格式：描述中的完美HTML格式，可自动从简单文本转换为适当的HTML段落、列表和格式（基于成功的工作项ID 75实现）
详细指导：全面的任务描述，提供明确的实施指导
项目管理：在项目之间切换并管理配置
互动指南：常见工作流的内置提示

🎯 模块化架构的优点

关注点分离：每个模块都有一个明确的责任
可维护性：易于更新单个组件，而不会影响其他组件
可测试性：组件可以通过全面的测试套件单独测试
可重复使用性：模块可以独立导入和使用
可扩展性：易于添加新功能，而不会中断现有功能
清洁进口：具有清晰模块关系的非循环依赖关系

🚀 快速开始

先决条件

Python 3.11+
Azure DevOps个人访问令牌（PAT）
FastMCP （自动安装）

安装

克隆或下载此项目

安装依赖项：

uv add fastmcp
# or
pip install fastmcp

创建一个 .env 包含Azure DevOps配置的文件：

AZURE_DEVOPS_PAT=your_personal_access_token_here
AZURE_DEVOPS_PROJECT=your_project_name
AZURE_DEVOPS_ORGANIZATION_URL=https://dev.azure.com/your_organization

运行MCP服务器：
```
python mcp_server.py
```
在安装了MCP扩展的VS Code中，服务器将自动可用于您的Azure DevOps项目。

🛠️ 可用工具

1. `create_work_item`

在Azure DevOps中创建新的工作项（Task或Epic）。

参数：

work_item_type （string）：“任务”或“史诗”
title （string）：工作项的标题
description （字符串，可选）：工作项的描述（支持HTML格式-必须用于自动转换为HTML段落的换行符）
assigned_to （字符串，可选）：要分配的人的电子邮件地址
priority （int，可选）：优先级（1-4，其中1为最高）
tags （字符串，可选）：以分号分隔的标签

重要： 工作项描述支持完美的HTML格式（描述字段具有Microsoft Azure DevOps文档确认的数据类型=HTML）。 必须使用\n个字符作为换行符 服务器根据工作项ID 75的成功实现，自动将简单的文本格式转换为HTML结构，包括标题、列表、复选框和段落分隔。

例子：

create_work_item(
    work_item_type="Task",
    title="Implement user authentication",
    description="## Objective\nAdd login/logout functionality\n\n## Tasks\n- [ ] Create login form\n- [ ] Implement authentication logic\n- [ ] Add logout functionality\n\n## Acceptance Criteria\n- Users can log in with email/password\n- Session management works correctly",
    assigned_to="user@company.com",
    priority=1,
    tags="feature; security"
)

2. `update_work_item`

更新Azure DevOps中的现有工作项。

参数：

item_id （int）：要更新的工作项的ID
title （字符串，可选）：工作项的新标题
description （字符串，可选）：新描述（支持HTML格式-必须用于自动转换为HTML段落的换行符）
assigned_to （字符串，可选）：要分配的电子邮件地址或“”取消分配
priority （int，可选）：新的优先级（1-4）
tags （string，可选）：新建标签或“”删除所有标签

3. `delete_work_item`

从Azure DevOps中删除工作项。

参数：

item_id （int）：要删除的工作项的ID

4. `get_work_item`

检索有关工作项的详细信息。

参数：

item_id （int）：要检索的工作项的ID

5. `link_task_to_epic`

在Epic和Task之间建立父子层次关系。

参数：

epic_id （int）：Epic工作项（父项）的ID
task_id （int）：任务工作项（子项）的ID

6. `get_current_project`

检索当前配置的Azure DevOps项目名称。

7. `set_project`

更新当前会话的Azure DevOps项目配置。

参数：

new_project_name （string）：要切换到的新项目的名称

8. `create_epic_with_tasks`

创建一个包含多个任务的Epic，并自动链接它们，提供一个包含URL的汇总表。

参数：

epic_title （string）：要创建的Epic的标题
epic_description （字符串，可选）：Epic描述（支持HTML格式-必须用于自动转换为HTML段落的换行符）
task_titles （字符串）：任务标题的逗号分隔列表（例如，“设置API、创建UI、编写测试”）
task_descriptions （字符串，可选）：以逗号分隔的任务描述列表（必须与Task_titles计数匹配-必须用于自动转换为HTML段落的换行符）
assigned_to （字符串，可选）：用于分配所有工作项的电子邮件地址
priority （int，可选）：优先级（1-4，其中1为最高）
tags （字符串，可选）：应用于所有工作项的分号分隔标签

例子：

create_epic_with_tasks(
    epic_title="Epic: User Authentication System",
    epic_description="## Overview\nImplement comprehensive user authentication\n\n## Features\n- [ ] Login/Logout\n- [ ] Password reset\n- [ ] Multi-factor authentication\n\n## Success Criteria\n- [ ] Secure authentication\n- [ ] User-friendly interface\n- [ ] Performance optimized",
    task_titles="Setup authentication framework, Create login API, Implement password reset, Add MFA support",
    task_descriptions="## Objective\nSet up core authentication infrastructure\n\n## Tasks\n- Install auth libraries\n- Configure security, ## Objective\nCreate login and logout endpoints\n\n## Tasks\n- Design API endpoints\n- Implement JWT tokens, ## Objective\nAdd password reset functionality\n\n## Tasks\n- Email verification\n- Reset token generation, ## Objective\nImplement multi-factor authentication\n\n## Tasks\n- SMS/Email 2FA\n- Backup codes",
    assigned_to="developer@company.com",
    priority=2,
    tags="authentication;security;user-management"
)

退货： 一个格式化的汇总表，其中包含：

Epic和任务ID和URL
每个任务的链接状态
下一步指导

🧭 互动提示

MCP服务器包含有用的提示，可指导您完成常见的工作流程：

`epic_management_guide`

Epic和任务管理工作流的交互式指南。

使用案例：

创建具有多个相关任务的新Epic
向现有Epic添加单个任务
学习Epic组织的最佳实践

参数：

action_type：选择“create_epic_with_tasks”或“add_task_to_epic”
epic_title：用于新的Epics（要创建的Epic标题）
epic_id：对于现有Epic（要添加任务的Epic ID）
task_titles：以逗号分隔的任务标题列表
assignee_email：作业的可选电子邮件

📚 知识资源

服务器通过内置资源提供全面的文档：

`ado://guide/user-friendly`

完整的用户指南 -涵盖所有MCP服务器功能、最佳实践、常见工作流程和故障排除提示的综合指南。

`ado://guide/epic-workflow`

Epic&任务工作流程指南 -Epic创建、任务分解、链接策略和团队协作模式的详细分步指南。

这些资源提供：

✅ 分步工作流程
✅ 最佳实践模板
✅ 故障排除指南
✅ 团队协作技巧
✅ 项目管理策略

🎯 工作流程建议

何时使用 `create_epic_with_tasks` （推荐）

✅ 使用多个相关任务启动新功能
✅ 你有一个明确的任务计划清单
✅ 任务不需要高度定制的个人描述
✅ 您需要自动链接和URL摘要
✅ 大多数场景下最快的工作流程

何时使用个人工具(`create_work_item`, `link_task_to_epic`)

✅ 任务需要高度详细、定制的描述
✅ 不同的团队成员需要不同的任务配置
✅ 随着时间的推移，向现有史诗添加任务
✅ 需要手动设置的复杂依赖场景

快速比较

特点	`create_epic_with_tasks`	个人工具
速度	⚡ 非常快	🐌 慢一点
URL摘要	✅ 自动	❌ 手册
自动链接	✅ 是	❌ 手册
定制	🔶 好	✅ 最大值
错误恢复	✅ 简单	🔶 综合体

🔧 VS代码配置

本项目是专门为VS Code与MCP集成而设计的。以下是如何设置它：

先决条件

安装VS代码MCP扩展
- 安装VS Code的MCP扩展
- 确保您已安装Python 3.11+
项目设置
- 克隆/下载此项目
- 安装依赖项： uv sync 或 pip install -r requirements.txt
- 配置您的 .env 包含Azure DevOps凭据的文件

VS代码MCP配置

MCP配置存储在 .vscode/mcp.json:

{
  "servers": {
    "ADO-server": {
      "url": "http://localhost:8000/mcp/",
      "type": "http"
    }
  },
  "inputs": []
}

运行服务器

启动MCP服务器：
```
python mcp_server.py
```
验证连接：
- 服务器运行在 http://localhost:8000/mcp/
- VS Code MCP扩展应自动连接
- 您将在VS Code中看到Azure DevOps工具

环境配置

确保您的 .env 文件包含：

AZURE_DEVOPS_PAT=your_personal_access_token
AZURE_DEVOPS_PROJECT=your_project_name
AZURE_DEVOPS_ORGANIZATION_URL=https://dev.azure.com/your_organization
MCP_SERVER_PORT=8000

VS代码集成功能

🛠️ 工具集成 -VS Code中提供的所有Azure DevOps工具
🧭 互动提示 -Epic和任务管理的指导工作流程
📚 内置文档 -访问用户指南和最佳实践
🔄 实时连接 -与Azure DevOps项目的实时连接
🎯 上下文感知 -工具适应您当前的项目设置

� Azure容器应用部署

此服务器可以部署到Azure容器应用程序，用于云托管和远程访问。

部署的先决条件

Azure容器注册表
- 创建Azure容器注册表
- 启用管理员凭据或使用托管身份
Azure容器应用程序环境
- 创建容器应用程序环境
- 配置外部入口

部署步骤

1.构建和推送Docker镜像

# Build from project root (important: use project root as context)
cd /path/to/ado_builder
docker build --no-cache -f docker/Dockerfile -t ado-mcp-server .

# Tag for your registry
docker tag ado-mcp-server your-registry.azurecr.io/ado-mcp-server:latest

# Push to Azure Container Registry
docker push your-registry.azurecr.io/ado-mcp-server:latest

2.部署到Azure容器应用程序

# Create Container App
az containerapp create \
  --name ado-mcp-server \
  --resource-group your-resource-group \
  --environment your-container-env \
  --image your-registry.azurecr.io/ado-mcp-server:latest \
  --target-port 2500 \
  --ingress external \
  --env-vars \
    AZURE_DEVOPS_ORGANIZATION=your-org \
    AZURE_DEVOPS_PROJECT=your-project \
    AZURE_DEVOPS_TOKEN=your-pat-token

3.更新VS代码配置

更新 .vscode/mcp.json 指向已部署的服务器：

{
  "servers": {
    "ado-mcp-server": {
      "url": "https://your-app-name.region.azurecontainerapps.io/mcp/",
      "type": "http"
    }
  },
  "inputs": []
}

⚠️ 重要部署说明

环境变量

集装箱环境：使用Azure容器应用程序环境变量（不是.env文件）
安全：将敏感令牌存储为容器应用程序机密
配置：环境变量覆盖任何捆绑的.env文件

URL端点

需要尾随屠宰：URL必须以结尾 /mcp/ （不是 /mcp)
超文本传输安全协议：Azure容器应用程序提供自动HTTPS
端口：内部容器端口2500，外部通过Azure入口

Docker构建上下文

建造地点：始终从项目根目录构建
Docker文件路径：使用 -f docker/Dockerfile 从根开始构建时
Dockerignore：确保 .dockerignore 在项目根目录中要排除 .env 文件

常见问题排查

环境变量未加载

# Check Container Apps environment variables
az containerapp show --name your-app --resource-group your-rg --query properties.template.containers[0].env

# Verify no .env file in container
az containerapp logs show --name your-app --resource-group your-rg --tail 20

MCP连接失败
- 验证URL是否以结尾 /mcp/ （尾随斜线）
- 检查运输类型是否 "http" （不是 streamable-http)
- 确认外部入口已启用
Docker构建问题
- 从项目根构建： docker build -f docker/Dockerfile .
- 检查 .dockerignore 排除 .env 文件
- 使用 --no-cache 用于清洁建筑

服务器未启动

# Check container logs
az containerapp logs show --name your-app --resource-group your-rg --follow

# Verify environment variables are set
az containerapp revision show --name your-app --resource-group your-rg

生产注意事项

扩展：根据使用情况配置最小/最大副本
监控：启用应用程序洞察以进行监控
安全：使用Azure密钥库存储PAT令牌
网络：考虑内部访问的ExpressRoute集成
成本：监控使用情况并配置适当的资源限制

�📋 特性

✅ 完整的CRUD操作 -创建、读取、更新、删除工作项
✅ 工作项类型 -任务和史诗支持
✅ 层次关系 -将任务链接到Epics
✅ 项目管理 -在不同项目之间切换
✅ 环境变量 -安全配置管理
✅ 错误处理 -全面的错误消息
✅ 验证 -输入验证和类型检查
✅ 优化代码 -带辅助功能的DRY原则

🔐 安全

使用个人访问令牌进行身份验证
敏感数据的环境变量
源代码中没有硬编码凭据

🐳 Docker支持

所有与Docker相关的文件都位于 docker/ 文件夹。看 docker/README.md 详细说明。

Docker快速入门

塑造形象：

# Using Docker directly
docker build -f docker/Dockerfile -t ado-mcp-server .

# Or using the helper script (Windows)
.\docker\docker-script.ps1 build

# Or using the helper script (Linux/Mac)
./docker/docker-script.sh build

运行容器：

# Using Docker Compose (recommended)
docker-compose -f docker/docker-compose.yml up -d

# Or using Docker directly
docker run -d --name ado-mcp-server -p 8000:8000 --env-file .env ado-mcp-server

# Or using the helper script
.\docker\docker-script.ps1 run    # Windows
./docker/docker-script.sh run     # Linux/Mac

检查服务器状态：

# Server should be accessible at http://localhost:8000/mcp/
# Check VS Code MCP extension for connection status

Docker脚本

使用提供的脚本更轻松地管理Docker：

Windows（PowerShell）：

.\docker\docker-script.ps1 [build|run|stop|logs|shell|clean]

Linux/Mac（Bash）：

./docker/docker-script.sh [build|run|stop|logs|shell|clean]

生产部署

对于生产环境，请使用生产Docker Compose文件：

docker-compose -f docker/docker-compose.prod.yml up -d

这包括：

资源限制（512MB内存，0.5 CPU）
正确的日志配置
健康检查
重新启动策略

环境变量

使用Docker时，请确保设置了以下环境变量：

AZURE_DEVOPS_PAT=your_personal_access_token
AZURE_DEVOPS_PROJECT=your_project_name
AZURE_DEVOPS_ORGANIZATION_URL=https://dev.azure.com/your_organization
MCP_SERVER_PORT=8000

🧪 测试

MCP服务器可以通过HTTP端点进行测试：

# MCP endpoint
curl http://localhost:8000/mcp/

📚 Azure DevOps API

此MCP服务器使用Azure DevOps REST API v7.0：

CRUD操作的工作项API
用于分层链接的关系API
JSON补丁格式用于更新

🔗 依赖项

fastmcp -MCP服务器框架
requests -Azure DevOps API的HTTP客户端
python-dotenv -环境变量管理
uvicorn -用于HTTP传输的ASGI服务器
fastapi -用于健康端点的Web框架

📝 许可证

本项目按原样提供，用于教育和发展目的。

使用说明

Azure DevOps工作项管理器-MCP服务器（模块化架构）

🏗️ 模块化架构

⭐ 主要特点

🎯 模块化架构的优点

🚀 快速开始

先决条件

安装

🛠️ 可用工具

1. create_work_item

2. update_work_item

3. delete_work_item

4. get_work_item

5. link_task_to_epic

6. get_current_project

7. set_project

8. create_epic_with_tasks

🧭 互动提示

epic_management_guide

📚 知识资源

ado://guide/user-friendly

ado://guide/epic-workflow

🎯 工作流程建议

何时使用 create_epic_with_tasks （推荐）

何时使用个人工具(create_work_item, link_task_to_epic)

快速比较

🔧 VS代码配置

先决条件

VS代码MCP配置

运行服务器

环境配置

VS代码集成功能

� Azure容器应用部署

部署的先决条件

部署步骤

1.构建和推送Docker镜像

2.部署到Azure容器应用程序

3.更新VS代码配置

⚠️ 重要部署说明

环境变量

URL端点

Docker构建上下文

常见问题排查

生产注意事项

�📋 特性

🔐 安全

🐳 Docker支持

Docker快速入门

Docker脚本

生产部署

环境变量

🧪 测试

📚 Azure DevOps API

🔗 依赖项

📝 许可证

相关 MCP

GitLab项目管理服务器

Primavera P6 XER文件解析服务器

React开发协议服务

React开发协议服务

Azure DevOps集成工具

项目记忆库管理服务

1. `create_work_item`

2. `update_work_item`

3. `delete_work_item`

4. `get_work_item`

5. `link_task_to_epic`

6. `get_current_project`

7. `set_project`

8. `create_epic_with_tasks`

`epic_management_guide`

`ado://guide/user-friendly`

`ado://guide/epic-workflow`

何时使用 `create_epic_with_tasks` （推荐）

何时使用个人工具(`create_work_item`, `link_task_to_epic`)