agile-analytics-mcp

Agile Analytics 本地 AI 连接器

向 Claude 或其他支持 Model Context Protocol （MCP）的助手询问团队的 Agile Analytics 数据：迭代摘要、周期时间、 流动效率、进行中工作、老化情况和预测。连接器在你的电脑上运行，使用你的凭据读取 Azure DevOps，并 提供与 Agile Analytics 扩展相同的数据，因为它运行的就是 扩展自身的指标代码。

它属于你的 Agile Analytics 订阅：只有在你的组织中安装了扩展，并且已为 相关项目保存工作流映射时，它才会提供回答。不会向 Baytek 发送任何数据。

完整指南：https://ado-analytics.baytekdev.com/docs/local-ai-connector/

开始之前

• 你的电脑上需安装 Node.js 22 或更高版本（node --version）。连接器 通过随 Node.js 附带的 npx 运行。
• Azure DevOps 组织中需已安装 Agile Analytics，并且已为你要查询的项目保存 工作流映射（扩展中的 Configuration → Workflow Mapping）。
• 管理员开关已开启（除非管理员将其关闭，否则默认开启；请参阅下文 “为组织关闭该功能”）。

1. 创建个人访问令牌

在 Azure DevOps 中，打开 User settings → Personal access tokens → New Token。 选择你的组织、过期日期，并且只选择以下三个范围：

• Work Items: Read
• Project and Team: Read
• Extension Data: Read

不需要其他权限。此令牌只允许连接器读取数据，不能更改任何内容。

令牌的存放位置

• Windows：将令牌设为名为 AZURE_DEVOPS_PAT 的用户环境变量（开始 → “编辑你的帐户的环境变量” → 新建）。 不要将令牌放入助手的配置文件。之后重启助手，让它读取新变量。
• **macOS 和 Linux：**桌面助手不会读取你的 shell 配置文件，因此请将令牌放入服务条目的 "env" 区块中，变量名为 AZURE_DEVOPS_PAT（示例如下），并将配置文件设为仅你的用户帐户可读（chmod 600 <file>）。

令牌只会保留在连接器的内存中，绝不会被打印、记录或写入其他位置。

2. 将连接器添加到助手

连接器通过以下命令启动：

npx -y @baytekdev/agile-analytics-mcp

Claude Desktop（设置 → 开发者 → 编辑配置，这会打开 claude_desktop_config.json）：

{
  "mcpServers": {
    "agile-analytics": {
      "command": "npx",
      "args": ["-y", "@baytekdev/agile-analytics-mcp"]
    }
  }
}

在 macOS 和 Linux 上，将令牌添加到同一条目中：

{
  "mcpServers": {
    "agile-analytics": {
      "command": "npx",
      "args": ["-y", "@baytekdev/agile-analytics-mcp"],
      "env": { "AZURE_DEVOPS_PAT": "<your token>" }
    }
  }
}

Claude Code（一条命令，仅为你的用户帐户保存）：

claude mcp add --scope user agile-analytics -- npx -y @baytekdev/agile-analytics-mcp

在 macOS 和 Linux 上，使用 -e 将令牌传入条目：

claude mcp add --scope user agile-analytics -e AZURE_DEVOPS_PAT=<your token> -- npx -y @baytekdev/agile-analytics-mcp

在 Windows 上，Claude Code 会通过 cmd /c 启动 npx：

claude mcp add --scope user agile-analytics -- cmd /c npx -y @baytekdev/agile-analytics-mcp

VS Code（命令面板 → “MCP: Open User Configuration”，这会打开 你的用户级 mcp.json）：

{
  "servers": {
    "agile-analytics": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@baytekdev/agile-analytics-mcp"]
    }
  }
}

在 macOS 和 Linux 上，将 "env": { "AZURE_DEVOPS_PAT": "<your token>" } 添加到 该条目中。不要将令牌放入工作区的 .vscode/mcp.json 或项目的 .mcp.json：这些文件通常会被共享或提交。

3. 提问

请注明组织（dev.azure.com/<org> 部分）、项目和 团队。例如：“组织 contoso 中 Contoso Web 项目的 Platform 团队的迭代摘要”。每个回答都基于工具提供的数据；助手 会将其转换成文字。

改用 Azure CLI 登录

如果你不想创建令牌，连接器可以使用 Azure CLI： 运行一次 az login，并让 AZURE_DEVOPS_PAT 保持未设置状态。此方式适用于 已连接到 Microsoft Entra 的组织；仅使用 Microsoft 帐户的组织无法使用此方式。如需选择 Entra 租户，请在 args 中添加 "--tenant", "<tenant-guid>"（如果不是 GUID，将会被拒绝）。

连接器按以下顺序查找凭据：AZURE_DEVOPS_PAT，然后是 较早使用的 AZURE_DEVOPS_MCP_TEST_PAT（目前仍受支持，之后会移除），最后是 Azure CLI。

工具

• sprint_summary（sprintId，默认最近一个已完成的冲刺）：已交付的工作项和点数、周期时间、结转情况和承诺情况（第一天结束时的承诺数、已完成的承诺数、可靠性、增加和移除的范围）。第一天结束前，承诺情况为 null。
• cycle_time 和 flow_efficiency（sprints 为 3、6 或 12，默认 6）：最近 N 个已完成的冲刺，不包括正在进行的冲刺。
• wip：当前正在进行的冲刺中此刻处于进行中的工作项。
• aging：当前冲刺中的未完成工作，包括从上一冲刺结转的工作项；逐项列出其所处阶段、在该阶段停留的天数和流转天数。weekendBasis（business-days 或 calendar-days）指定计算时长所用的天数口径：优先采用你在扩展中保存的 Aging 选项，否则采用 Aging 视图使用的相同默认值。
• forecast（mode 为 howMany 时使用 windowDays，默认 30；或 mode 为 when 时使用 backlog）：Monte Carlo 视图的默认预测。

每个回答还包含 scope：includesSubTeams（扩展的“包含子团队的工作”选项是否适用于此团队且已开启）和 excludedTeamCount（此回答排除的其他团队工作项数量），因此统计的工作项与扩展相同。

它会读取什么，以及绝不会读取什么

• **Azure DevOps 请求：**固定的只读请求列表（另加一个仅选择 ID 的工作项查询）。其他任何请求都会在发送前被拒绝。
• **工作项字段：**状态、类型、日期、冲刺和区域路径、估算值、看板列和阻塞标记。绝不会读取标题、负责人、标签、描述或评论。
• **团队设置：**此团队的冲刺和工作日，以及哪些团队属于此团队。
• **Agile Analytics 设置：**已保存的工作流映射、“从指标中排除”列表、Item Types 映射、管理员开关、你自己的 WIP 限制和周末偏好、组织和项目的周末默认设置，以及子团队选项：仅读取指定的设置。它绝不会列出所有设置，因此无法查看许可证或其他值。
• 绝不会猜测工作流映射：如果没有已保存的映射，回答为 workflow-not-mapped。

回答仅包含数字、日期、固定词语、ID 和工作项 ID，不包含标题、姓名或评论。

离开你电脑的数据

使用你自己的访问权限向 dev.azure.com 和 extmgmt.dev.azure.com 发送请求。不会向 Baytek 发送任何内容：没有许可证检查、遥测数据或使用次数统计。回答会发送给你的助手；你的助手如何处理这些内容，由你和助手提供商决定。

为组织关闭此功能

组织管理员可以在扩展中为所有人关闭连接器：Configuration → General, "Allow the local AI connector"。除非关闭，否则此选项默认开启。连接器会在每次回答前读取此设置；关闭时，所有工具都会返回 disabled-by-admin；如果无法读取设置，则返回 settings-unreadable，绝不会将其视为“已开启”。连接器会在每个人的电脑上遵循此开关；它不会更改任何人的 Azure DevOps 权限。

错误

错误仅包含代码，例如 {"error":"workflow-not-mapped"}：

• azure-cli-sign-in-required：未找到令牌，且 Azure CLI 尚未登录。请设置 AZURE_DEVOPS_PAT（见步骤 1），或运行 az login。
• workflow-not-mapped：请先在扩展中为此项目保存工作流映射。
• disabled-by-admin：管理员已关闭连接器。
• settings-unreadable：无法读取扩展的设置（是否已安装扩展？令牌是否具有 Extension Data: Read 权限？）。
• ado-request-failed：Azure DevOps 拒绝了请求或请求失败（请检查令牌的范围和有效期）。
• team-not-found、sprint-not-found、no-finished-sprints、invalid-input、request-not-allowed、internal-error。

调用之间会保留的内容

项目的团队列表、每个团队的领域和每个团队的工作日会在内存中保留 10 分钟；不会写入磁盘，关闭助手后就会忘记这些内容。其他所有内容，包括管理员开关和工作流映射，都会在每次调用时重新读取。Azure DevOps 中的团队或领域变更最长可能需要 10 分钟才会显示；重启助手即可立即查看。

此版本不包含

• 老化区间和趋势（p50/p85 区间和每个冲刺的趋势）。

关于此代码库

此代码库用于存放连接器的文档。此软件包已发布到 npm，名称为 @baytekdev/agile-analytics-mcp， 并且是 Agile Analytics for Azure DevOps 的一部分，可在 Visual Studio Marketplace 上获取。 此处未发布源代码。

如有疑问或遇到问题，请在此代码库中提交 issue，或发送邮件至 [email protected]。