增强型ADO MCP服务器

通过模型上下文协议实现人工智能驱动的Azure DevOps工作项管理。

](https://www.npmjs.com/package/enhanced-ado-mcp-server) ![Tests](mcp_server/test)

______________________________________________________________________

快速安装

先决条件

1.安装Azure CLI （身份验证所需）

窗户： aka.ms/installazure cliwindows
macOS： brew install azure-cli
Linux： docs.microsoft.com/cli/azure/install-azure-cli-linux

安装后： az login

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

下载：
验证： npx --version

______________________________________________________________________

VS代码（推荐）

一键安装：

![Install in VS Code]()

![Install in VS Code Insiders]()

VS Code将提示您：

组织名称 （例如。， mycompany)
区域路径 （例如。， MyProject\Team\Area)

项目名称为 自动提取 从你的区域路径（前面的第一部分 \).

💡 例子： 如果你进入 MyProject\Engineering\Backend 作为区域路径，项目将设置为 MyProject

手动配置：

添加到VS代码 settings.json:

第一步： 按 Ctrl+Shift+P （Windows/Linux）或 Cmd+Shift+P （Mac）\ 第二步： 键入“首选项：打开用户设置（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代码(Ctrl+Shift+P → “开发人员：重新加载窗口”）

注： OData分析查询会自动使用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"
      ]
    }
  }
}

注：项目名称将自动从区域路径（之前的第一段）中提取 \\).

______________________________________________________________________

克劳德桌面/光标

配置文件：

macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %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，而是确保代理只对实际查询中经过验证的工作项进行操作。

// ❌ Basic server: Agent can hallucinate IDs
updateWorkItems([12345, 99999, 54321]);  // ID 99999 might be an item on someone else's board that you don't want to modify by mistake

// ✅ Enhanced server: Query handle prevents hallucination
const handle = queryWIQL("SELECT [System.Id] FROM WorkItems...", { returnQueryHandle: true });
bulkUpdateByQueryHandle(handle, { itemSelector: "all" });  // Only real items

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

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

可靠的工作流程 -复杂的操作被分解为具有预览功能的验证步骤。在执行破坏性操作之前，看看会发生什么。

代理在需要多个步骤的流程中挣扎。使用基本的ado mcp服务器创建和管理一个简单的工作项需要6个单独的工具调用，这很慢也不可靠（我从未见过它正确地进行所有配置），而这个服务器将常见的流组合成对代理友好的单步工具调用。

🔍 智能查询工具

自然语言→ WIQL - query-wiql 将普通英语转换为有效的WIQL
OData分析 -团队速度、趋势、消耗的高级指标和聚合
WIQL+OData -两种查询语言都支持验证和自动更正

更好地使用上下文窗口

使用普通的ado mcp服务器，您最终会通过拉取数百个项目来找到要查找的项目，但它会很快将上下文窗口扩大到最大，使过程缓慢且不可靠。

想要获取速度的汇总统计数据吗？代理人需要手动计算点数，否则会出错并产生幻觉。通过允许服务器端聚合和过滤，增强的ado mcp服务器允许您在不破坏上下文窗口的情况下处理更多数据。

可靠地生成查询需要数千个上下文令牌，这将降低主代理的性能。使用带有采样的专用子代理，可以在对上下文窗口影响最小的情况下实现自然语言到wiql/odata查询的转换。

🤖 AI驱动的分析

明智的见解 （VS代码+GitHub副本）：

工作项完整性评分
人工智能任务适用性分析
自动分解建议
具有可操作修复的层次结构验证

⚡ 安全散装作业

执行前预览 -查看哪些项目将受到影响
项目选择器 -按状态、标签、查询结果中的过时性进行筛选
干运行模式 -安全测试破坏性操作
验证 -所有操作在执行前都经过验证

📊 生产就绪功能

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

将基本服务器用于： 简单的工作项CRUD操作\ 将增强型服务器用于： 生产工作流程、批量操作、人工智能分析和复杂的多步骤流程

______________________________________________________________________

它做什么

21 MCP工具 用于Azure DevOps工作项管理
AI驱动的分析 （工作负载健康状况、查询句柄分析、工具发现）
自然语言查询 （英语→ WIQL/oOData生成）
安全散装作业 （查询句柄模式可防止ID幻觉）
GitHub复制集成 （自动将工作项分配给编码代理）

关键工具

工作项创建（3个工具）：

create-workitem -创建具有父关系的新工作项
assign-copilot -将工作项分配给GitHub Copilot

工作项上下文（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代码+GitHub副本）：

analyze-workload -倦怠风险和工作量健康
analyze-query-handle -基于AI的查询处理结果分析
discover-tools -为您的任务找到合适的工具

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

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

看 docs/feature_specs/ 以获取完整的文档。

______________________________________________________________________

快速示例

用自然语言查询

// AI-powered query generation
callTool("query-wiql", {
  description: "All active bugs created in the last 7 days",
  testQuery: true
});

// Or direct WIQL execution
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. Query with handle
const result = await callTool("query-wiql", {
  wiqlQuery: "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'",
  returnQueryHandle: true
});

// 2. Unified bulk operations (preview + execute)
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  // Preview first
});

// 3. Execute for real
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: false
});

______________________________________________________________________

AI功能（仅VS代码）

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

设置：

打开命令选项板(F1)
跑 “MCP:列出服务器”
选择 “增强版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令牌不适用于此API。这是透明的——你不需要任何特殊的配置。

备选方案： 如果您无法获得分析权限，请使用WIQL查询(query-wiql)而不是OData查询。

📖 详细指南： 看故障排除指南用于全面诊断、解析步骤和迁移模式。

按工具列出的权限要求

工具	所需权限	注释
`query-wiql`	查看工作项	所有团队成员的标准访问权限
`query-odata`	查看分析	必须由管理员明确授予
创建/更新工具	编辑工作项	标准访问
AI分析	查看工作项+GitHub副本	仅VS代码

主要区别： “查看分析”是与“查看工作项”分开的权限。具有工作项访问权限不会自动授予Analytics API访问权限。

缺少工作项类型（$undefined）

修复： 始终指定 workItemType 创建项目时。

需要区域路径（404）

修复： 使用 wit-list-area-paths 查找有效路径。

调试模式

export MCP_DEBUG=1  # macOS/Linux
$env:MCP_DEBUG=1    # PowerShell

调试工具

这 get-prompts 工具是 默认情况下禁用 出于安全原因，在生产中。要启用调试工具（例如，用于测试提示模板）：

export MCP_ENABLE_DEBUG_TOOLS=1  # macOS/Linux
$env:MCP_ENABLE_DEBUG_TOOLS='1'  # PowerShell

注：调试工具公开内部提示模板，只应在开发/测试环境中启用。

______________________________________________________________________

发展

cd mcp_server
npm install
npm run build
npm test

预提交挂钩 自动执行Prettier+ESLint。

______________________________________________________________________

文档

功能规格 -详细的工具文档
资源 -快速参考指南
贡献 -开发指南

______________________________________________________________________

许可证

麻省理工学院

Enhanced Ado MCP

快速接入

详细介绍

增强型ADO MCP服务器

快速安装

先决条件

VS代码（推荐）

克劳德桌面/光标

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

🛡️ 反幻觉建筑

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

🔍 智能查询工具

更好地使用上下文窗口

🤖 AI驱动的分析

⚡ 安全散装作业

📊 生产就绪功能

它做什么

关键工具

快速示例

用自然语言查询

安全散装操作

AI功能（仅VS代码）

故障排除

常见错误

OData 401授权错误（TF400813）

按工具列出的权限要求

缺少工作项类型（$undefined）

需要区域路径（404）

调试模式

调试工具

发展

文档

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP