ado-install

用途

ado-install 用于在 Cursor 中配置 Azure DevOps 的本地 MCP 服务器（npx @azure-devops/mcp），使用 PAT（个人访问令牌）认证。它明确不使用远程服务器（mcp.dev.azure.com），因为 Cursor 不支持其基于 Entra ID 的 OAuth。

每个 mcp.json 条目绑定一个「组织 + 用户邮箱」组合，因此可以同时启用多个账号，每个账号使用各自的 PAT。

主要能力

询问 Azure DevOps 组织名称（仅名称，不含完整 URL）和该组织关联的 ADO 用户邮箱。
检测操作系统：macOS 对应 macos.md，Windows 对应 windows.md。
检查 Node/npx 前置条件（node -v、npx -v，建议 Node 20+），缺失时提示用户先安装。
计算账号标识：环境别名 {ALIAS} 为「组织大写_邮箱@前部分大写」，非字母数字字符替换为下划线；服务器键 {SERVER_KEY} 为短名称，用于 mcp.json。
提示用户先在 Azure DevOps 创建 PAT。
读取已有 .cursor/mcp.json 并合并新条目，不删除既有配置；若文件存在但 JSON 无效，则先备份（如 mcp.json.bak）并请求确认后再重建。
写入或更新 .cursor/mcp.json，保存前校验 {SERVER_KEY} 长度 ≤ 17 字符。
仅向用户展示对应系统指南的第 1 步（编码并保存：macOS 用 Keychain，Windows 用用户变量），代理不索取也不在聊天中存储 PAT。
用户确认后自动执行系统指南中的代理步骤：macOS 在 ~/.zshrc 中 export 并配置 LaunchAgent（Dock/Spotlight）；Windows 在 PowerShell 的 $PROFILE 中添加一行。
内部执行系统指南中的验证命令，仅向用户报告成功或带诊断的错误。
配置变量后要求用户完全重启 Cursor（Cmd+Q / 关闭应用）。

使用方式

用户手动创建 PAT：用指定邮箱登录 Azure DevOps，访问 https://dev.azure.com/{ORG}/_usersSettings/tokens，New Token，按需选择最小作用域（Work Items → Read，如需创建/编辑则 Write；Code → Read；Build → Read 可选），复制原始 token（仅显示一次）。
编码：@azure-devops/mcp 使用 --authentication pat 时要求 PERSONAL_ACCESS_TOKEN 为「:PAT」的 base64（非原始 PAT）。
- macOS / Linux / Git Bash：echo -n ":PAT_EN_CRUDO" | base64
- Windows PowerShell：[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(":PAT_EN_CRUDO")) 结果存入 ADO_PAT_{ALIAS}。
命名规则：Cursor 对 {SERVER_KEY}:{tool_name} 有 60 字符限制（含分隔符 :）。@azure-devops/mcp 最长工具名为 42 字符（repo_list_pull_requests_by_repo_or_project），因此 {SERVER_KEY} 必须 ≤ 17 字符（60 − 1 − 42 = 17）。
- 环境别名 {ALIAS} 用于 ADO_PAT_{ALIAS}、Keychain 和 Windows 变量，可以较长。
- 服务器键 {SERVER_KEY} 仅用于 mcp.json，需短且唯一。算法：固定前缀 ado-（4 字符），{org} 为组织小写仅字母数字并截断，加 - 分隔符，{user} 为邮箱本地部分小写仅字母数字并截断；校验 len ≤ 17，超出时先缩短 {user} 再缩短 {org}。
- 冲突（其他账号）：若键已存在且 org 或邮箱不同，添加数字后缀（如 ado-bay-jua2），必要时截短 {user}。
- 重复执行（同一账号）：org 与邮箱完全相同时更新/覆盖现有条目，不重复创建；视为 token 轮换，在 Keychain（macOS）或用户变量（Windows）中重新生成值，复用相同 {SERVER_KEY} 和 ADO_PAT_{ALIAS}。
- 迁移：若已存在长键（如 ado-bayteq-juanca-altamirano），在 mcp.json 中重命名为短键，ADO_PAT_{ALIAS} 不变。
.cursor/mcp.json 模板（多账号）：每个账号为独立条目，添加第二个账号时保留既有条目。

{
  "mcpServers": {
    "{SERVER_KEY}": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "{ORG}", "--authentication", "pat"],
      "env": {
        "PERSONAL_ACCESS_TOKEN": "${env:ADO_PAT_{ALIAS}}"
      }
    }
  }
}

双账号示例：

{
  "mcpServers": {
    "ado-fab-mar": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "Fabrikam", "--authentication", "pat"],
      "env": {
        "PERSONAL_ACCESS_TOKEN": "${env:ADO_PAT_FABRIKAM_MARIA}"
      }
    },
    "ado-cli-car": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "ClienteOrg", "--authentication", "pat"],
      "env": {
        "PERSONAL_ACCESS_TOKEN": "${env:ADO_PAT_CLIENTEORG_CARLOS}"
      }
    }
  }
}

注意：{SERVER_KEY} ≤ 17 字符；{ALIAS} 可较长（仅用于 env/Keychain）。不要内联提交密钥，始终使用 ${env:ADO_PAT_{ALIAS}}。不要同时运行远程和本地。每个 MCP 服务器会单独出现在 Cursor 的 Settings → MCP 中。

验证

重启前的验证由代理执行（见 macos.md 或 windows.md 中的「Verificación del agente」），不向用户展示这些命令。
重启 Cursor 后，检查 Settings → MCP → 服务器 {SERVER_KEY} 为绿色且无命名问题警告。
在聊天中做功能测试：使用服务器 {SERVER_KEY} 列出 {ORG} 的项目或工作项。

常见错误

「Some tools have naming issues…」：{SERVER_KEY} 过长（> 19），按算法在 mcp.json 中重命名键。
「PERSONAL_ACCESS_TOKEN is not set or empty」：变量 ADO_PAT_{ALIAS} 不可见，检查别名拼写并重启。
HTTP 302 / sign-in：使用了原始 PAT 而非 base64，重新编码并保存。
远程 MCP 失败：Cursor + 远程 OAuth 问题，仅使用本地 MCP。
终端可用但 Cursor 不可用：应用打开时未加载用户环境变量，参见系统指南。
第二个账号未出现在 MCP：更新 mcp.json 时条目被删除，确保合并而非替换。

平台参考

macOS：Keychain 存储 + LaunchAgent + .zshrc → macos.md
Windows：持久用户变量 → windows.md
两个平台均需为每个新增的 ADO_PAT_{ALIAS} 变量重复存储流程。

安全

切勿将 PAT 粘贴到聊天、提交或 mcp.json 中。
每个 PAT 绑定特定邮箱；某账号的 PAT 在该用户无访问权限的其他组织中无效。
若 PAT 泄露，使用对应用户在 https://dev.azure.com/{ORG}/_usersSettings/tokens 撤销，并仅重新生成该 token。
轮换 PAT 时，仅更新受影响的 ADO_PAT_{ALIAS} 变量，其他账号不受影响。

技能介绍

用途

主要能力

使用方式

验证

常见错误

平台参考

安全