增强型ADO-MCP

Name: 增强型ADO-MCP
Author: AmeliaRose802

作者：AmeliaRose8023 星标更新：2025-11-12

安装使用来源：spider==github.com

项目介绍

技术文档摘要

增强版ADO MCP服务器

通过模型上下文协议（Model Context Protocol）实现基于AI的Azure DevOps工作项管理。

快速安装

先决条件

1. 安装Azure CLI（用于认证）

Windows: aka.ms/installazurecliwindows
macOS: brew install azure-cli
Linux: docs.microsoft.com/cli/azure/install-azure-cli-linux

安装后：az login

2. 安装npx（Node.js 18+自带）

下载：nodejs.org/download
验证：npx --version

Visual Studio Code（推荐）

一键安装：

VS Code会提示您输入：

组织名称（例如：mycompany）
区域路径（例如：MyProject\Team\Area）

项目名称会从您的区域路径中自动提取（路径中的第一部分）。

💡 示例： 如果您输入 MyProject\Engineering\Backend 作为区域路径，项目将被设置为 MyProject

手动配置：

添加到VS Code的 settings.json：

步骤1： 按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（Mac） 步骤2： 输入 "首选项：打开用户设置（JSON）" 步骤3： 添加以下配置：

{
  "github.copilot.chat.mcp.servers": {
    "enhanced-ado-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "enhanced-ado-mcp-server",
        "YOUR_ORG",
        "--area-path",
        "YOUR_PROJECT\\YOUR_TEAM"
      ]
    }
  }
}

步骤4： 替换占位符：

YOUR_ORG → 您的组织名称（例如：contoso）
YOUR_PROJECT\\YOUR_TEAM → 您的区域路径（例如：MyProject\Engineering\Backend）

步骤5： 重新加载VS Code（Ctrl+Shift+P → "开发者：重新加载窗口"）

注意： OData Analytics查询会自动使用Azure CLI认证以确保最大兼容性。其他操作则使用服务器配置的认证方法（默认为交互式OAuth）。如有需要，您可以使用 --authentication 标志覆盖此设置。

实际示例：

{
  "github.copilot.chat.mcp.servers": {
    "enhanced-ado-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "enhanced-ado-mcp-server",
        "contoso",
        "--area-path",
        "ContosoApp\\Engineering\\Backend"
      ]
    }
  }
}

多团队设置：

{
  "github.copilot.chat.mcp.servers": {
    "enhanced-ado-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "enhanced-ado-mcp-server",
        "contoso",
        "--area-path", "ContosoApp\\Engineering\\Frontend",
        "--area-path", "ContosoApp\\Engineering\\Backend",
        "--area-path", "ContosoApp\\DevOps"
      ]
    }
  }
}

注意： 项目名称会从区域路径中自动提取（路径中的第一部分）。

Claude Desktop / Cursor

配置文件：

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "enhanced-ado-mcp": {
      "command": "npx",
      "args": ["-y", "enhanced-ado-mcp-server", "YOUR_ORG", "--area-path", "YOUR_PROJECT\\YOUR_TEAM"]
    }
  }
}

多区域支持（可选）：

{
  "mcpServers": {
    "enhanced-ado-mcp": {
      "command": "npx",
      "args": [
        "-y", 
        "enhanced-ado-mcp-server", 
        "YOUR_ORG", 
        "--area-path", "YOUR_PROJECT\\TEAM_A",
        "--area-path", "YOUR_PROJECT\\TEAM_B"
      ]
    }
  }
}

为什么选择增强版ADO MCP服务器？

虽然基础版ADO MCP服务器提供了核心Azure DevOps功能，但增强版为生产流程提供了显著优势：

🛡️ 防幻觉架构

查询处理模式 - AI代理无法幻觉工作项ID。我们的查询处理系统确保代理仅操作来自实际查询的有效工作项，而不是暴露可能被发明的原始ID。

// ❌ 基础服务器：代理可以幻觉ID
updateWorkItems([12345, 99999, 54321]);  // ID 99999可能是其他人板上的项目，您不希望误修改

// ✅ 增强服务器：查询处理防止幻觉
const handle = queryWIQL("SELECT [System.Id] FROM WorkItems...", { returnQueryHandle: true });
bulkUpdateByQueryHandle(handle, { itemSelector: "all" });  // 只有真实项目

代理似乎不太可能幻觉字母数字查询处理。即使他们这样做，幻觉处理几乎不可能是有效的活动处理，因此服务器将拒绝更新。

🎯 更好的多步操作用户体验

可靠的流程 - 复杂的操作被分解成经过验证的步骤，并具有预览能力。在执行破坏性操作之前，您可以确切地看到会发生什么。

代理难以处理需要多个步骤的流程。使用基础ado mcp服务器创建并父化一个简单的工单需要6个独立的工具调用，这很慢且不可靠（我从未见过它正确配置），而这个服务器将常见的流程组合成代理友好的单一工具调用。

🔍 智能查询工具

自然语言 → WIQL - wit-generate-wiql-query 将纯英文转换为有效的WIQL
OData Analytics - 团队速度、趋势、燃尽图等高级指标和聚合
WIQL + OData - 支持两种查询语言，并提供验证和自动修正

更好地利用上下文窗口

使用普通的ado mcp服务器，您最终会通过拉取数百个项目来找到您正在寻找的项目，但这很快就会耗尽上下文窗口，使过程变得缓慢且不可靠。

想要获取速度的聚合统计？代理需要手动计数点数，这会导致错误和幻觉。通过允许服务器端聚合和过滤，增强版ado mcp服务器让您可以在不打破上下文窗口的情况下处理更多数据。

可靠生成查询需要数千个上下文令牌，这会降低主代理的性能。使用专用子代理进行采样，可以将自然语言转换为wiql/odata查询，同时对上下文窗口的影响最小。

🤖 AI驱动分析

智能洞察（VS Code + GitHub Copilot）：

工作项完整性评分
AI分配适宜性分析
自动分解建议
层级验证及可操作修复

⚡ 安全批量操作

预览后再执行 - 查看哪些项目将受到影响
项目选择器 - 根据状态、标签、过时情况筛选查询结果
干运行模式 - 安全测试破坏性操作
验证 - 执行前验证所有操作

📊 生产就绪特性

606通过测试，全面覆盖
分页 - 高效处理大型结果集
错误分类 - 清晰、可操作的错误消息
自动发现 - 自动查找GitHub Copilot GUID
结构化日志 - 调试模式用于故障排除

使用基础服务器进行： 简单的工作项CRUD操作
使用增强服务器进行： 生产流程、批量操作、AI驱动分析以及复杂的多步流程

功能概述

21个MCP工具用于Azure DevOps工作项管理
AI驱动分析（工作负载健康、查询处理分析、工具发现）
自然语言查询（英文 → WIQL/OData生成）
安全批量操作（查询处理模式防止ID幻觉）
GitHub Copilot集成（自动分配工单给编码代理）

关键工具

工单创建（3个工具）：

create-workitem - 创建工单，可选父项
assign-copilot - 分配现有工单给GitHub Copilot
clone-workitem - 克隆/复制工单

工单上下文（2个工具）：

get-context - 获取工单详细信息
extract-security-links - 提取安全扫描指令

查询工具（2个工具）：

query-wiql - 执行WIQL或从自然语言生成
query-odata - 执行OData分析或从自然语言生成

查询处理管理（4个工具）：

analyze-bulk - 通过查询处理分析工单
list-handles - 列出所有活动查询处理
inspect-handle - 获取查询处理详细信息
get-context-bulk - 批量上下文检索

批量操作（4个工具）：

execute-bulk-operations - 统一的批量操作（更新字段、标签、评论、链接、状态转换、AI增强）
link-workitems - 创建工单之间的关系
undo-bulk - 撤销先前的操作
undo-forensic - 按用户/时间戳撤销更改

AI分析（3个工具 - 需要VS Code + GitHub Copilot）：

analyze-workload - 烧伤风险及工作负载健康
analyze-query-handle - AI驱动的查询处理结果分析
discover-tools - 寻找适合任务的工具

配置与发现（4个工具）：

get-config - 查看当前服务器配置
get-prompts - 访问提示模板
list-agents - 列出可用的专业代理
get-team-members - 发现团队成员（自动过滤GitHub Copilot）

详见 docs/feature_specs/ 完整文档。

快速示例

使用自然语言查询

// AI驱动的查询生成
callTool("query-wiql", {
  description: "过去7天内创建的所有活跃bug",
  testQuery: true
});

// 或直接执行WIQL
callTool("query-wiql", {
  wiqlQuery: "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'Bug' AND [System.State] = 'Active' AND [System.CreatedDate] >= @Today - 7",
  returnQueryHandle: true
});

安全批量操作

// 1. 查询带处理
const result = await callTool("query-wiql", {
  wiqlQuery: "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'",
  returnQueryHandle: true
});

// 2. 统一的批量操作（预览 + 执行）
await callTool("execute-bulk-operations", {
  queryHandle: result.query_handle,
  actions: [
    { type: "add-tag", tags: "needs-review" },
    { type: "comment", comment: "Flagged for review" }
  ],
  itemSelector: { states: ["Active"], tags: ["critical"] },
  dryRun: true  // 首先预览
});

// 3. 实际执行
await callTool("wit-unified-bulk-operations-by-query-handle", {
  queryHandle: result.query_handle,
  actions: [
    { type: "add-tag", tags: "needs-review" },
    { type: "comment", comment: "Flagged for review" }
  ],
  itemSelector: { states: ["Active"], tags: ["critical"] },
  dryRun: false
});

AI功能（仅限VS Code）

AI驱动的工具需要VS Code与GitHub Copilot和语言模型访问。

设置：

打开命令面板（F1）
运行 "MCP: 列出服务器"
选择 "enhanced-ado-mcp"
点击 "配置模型访问"
勾选所有免费模型（标记为 0x 令牌）

服务器会自动选择最快的免费模型。无需任何配置。

故障排除

常见错误

OData 401授权错误（TF400813）
根本原因： 此错误通常意味着您缺乏Azure DevOps中的“查看分析”权限，或者您未登录Azure CLI。

解决方法：

首先，确保Azure CLI已登录： 在终端中运行 az login
验证您是否拥有分析权限：
- 前往：https://dev.azure.com/{YOUR_ORG}/{YOUR_PROJECT}/_settings/security
- 在成员列表中搜索您的电子邮件地址
- 检查是否有“查看分析”权限
如果缺少权限： 联系您的Azure DevOps管理员请求在项目级别授予“查看分析”权限

技术细节：
OData Analytics查询会自动使用Azure CLI认证（自v1.10.1起），因为Analytics API需要Azure CLI令牌。OAuth令牌从交互式认证中不起作用。这会透明地发生——您不需要任何特殊配置。

替代方案： 如果您无法获得分析权限，请使用WIQL查询（wit-wiql-query）代替OData查询。

缺失工作项类型（$undefined）
解决方法： 创建项目时始终指定 workItemType。

区域路径必需（404）
解决方法： 使用 wit-list-area-paths 查找有效路径。

调试模式

export MCP