Helix MCP

helix.mcp

为什么？

AI代理在调查.Net repos（运行时、sdk、aspnetcore等）中的CI故障时遇到了两个问题：

1. 原始API返回的数据太多。 单个Helix控制台日志可以是兆字节。Azure DevOps构建时间表返回数百条记录。将其转储到上下文窗口中会浪费令牌并淹没信号。
2. 每个代理人都是从零开始的。 当多个代理（或工具调用中的同一个代理）检查同一个构建时，每个代理重复相同的API调用和下载。

hlx解决了这两个问题：

• 少退，好退。 工具如 helix_search 和 azdo_search_log 就地搜索，只返回与上下文匹配的行——代理永远不会下载完整的日志。 helix_status 返回结构化故障摘要，而不是原始JSON。默认 tail 限制（500行）， filter 参数(failed 默认情况下），以及 maxMatches 上限使反应集中。
• 缓存所有内容，跨进程共享。 本地SQLite缓存位于代理和API之间。不同的MCP服务器实例（每个IDE窗口/终端一个）共享相同的缓存，因此检查作业的第二个代理会立即得到结果。智能TTL跟踪作业生命周期——短暂运行作业缓存（15-30s），完成作业缓存数小时。

零配置 --public.NET CI开箱即用。安装并运行。

上下文高效设计

每个工具都旨在最大限度地减少代理上下文窗口中的令牌消耗：

调查路径

• 当仓库工作流程发生变化时，请从以下内容开始 helix_ci_guide(repo) 对于特定于repo的路径和搜索模式。
• 使用 helix_parse_uploaded_trx 仅当工作项将结构化测试结果上传到Helix时（运行时CoreCLR、XHarness设备测试）。
• 否则使用 azdo_test_runs → azdo_test_results 对于结构化结果，或 helix_search 当信号在控制台输出时。

跨进程缓存

 IDE / Agent processes          hlx stdio MCP servers
┌─────────────┐               ┌──────────────┐
│  VS Code    │──────────────▶│  hlx pid 1   │──┐
│  Copilot CLI│──────────────▶│  hlx pid 2   │──┤
│  Other agent│──────────────▶│  hlx pid 3   │──┤
└─────────────┘               └──────────────┘  │
                                                 ▼
                                          ┌─────────────┐    miss    ┌─────────────────┐
                                          │ Cache Layer  │──────────▶│ Helix / AzDO API│
                                          │  Cache hit?  │◀──────────│                 │
                                          └──────┬───────┘  response └─────────────────┘
                                            hit  │
                                                 ▼
                                     ┌───────────────────────┐
                                     │  SQLite + Disk shared  │
                                     │  ┌─────────┬────────┐ │
                                     │  │SQLite DB │Artifact│ │
                                     │  │WAL mode  │ files  │ │
                                     │  └─────────┴────────┘ │
                                     │                       │
                                     │  Auth isolation:       │
                                     │  cache-a1b2c3/         │
                                     │  cache-d4e5f6/         │
                                     │  public/               │
                                     └───────────────────────┘

• SQLite WAL模式 --多个进程在繁忙超时的情况下安全地读/写同一个数据库
• 智能TTL --运行作业：15-30秒，完成作业：1-4小时，运行作业的控制台日志：从不缓存。AzDO正在构建中，使用双密钥新鲜度和增量日志获取（增量追加）
• 认证隔离存储 --每个唯一的令牌都有自己的缓存目录(cache-{hash}/).使用未经身份验证的请求 public/.无交叉令牌泄漏
• LRU驱逐 --1 GB上限（可通过以下方式配置 HLX_CACHE_MAX_SIZE_MB)，工件文件在7天后过期，无法访问

hlx cache status   # Show cache size, entry count, oldest/newest entries
hlx cache clear    # Wipe all cached data

MCP工具

螺旋工具（9）

AzDO工具（11）

MCP资源

MCP资源是URI可寻址的数据，客户端可以在不调用工具的情况下发现和读取。

这些提供了相同的CI调查指南，可通过 helix_ci_guide 工具，作为客户端可发现的资源用于浏览和缓存。

认证

螺旋

公共Helix作业不需要身份验证（ADO.NET开源CI）。对于私人工作：

hlx login          # Opens browser, prompts for token, stores via git credential
hlx auth-status    # Check current auth status
hlx logout         # Remove stored token

令牌解析： HELIX_ACCESS_TOKEN 环境变量→ 通过存储凭证 git credential → 错误，并显示有用消息。

Azure DevOps

AzDO工具对公共项目匿名工作（例如 dnceng-public/public).对于私人组织（例如 devdiv/DevDiv)，需要身份验证。

凭证链 （按顺序尝试）：

1. AZDO_TOKEN 环境变量 --PAT和Entra访问令牌都是自动检测的：

- PAT（个人访问令牌）：作为基本身份验证发送。需要构建（读取）+测试（读取）范围。 - Entra/JWT令牌：作为Bearer身份验证发送。

1. Azure CLI凭据 (AzureCliCredential 从 Azure.Identity)--使用您的 az login 会议。适用于您的Azure身份可以访问的任何组织。
2. az CLI子流程 --回落到 az account get-access-token 如果是Azure。身份信息不可用。
3. 匿名 --没有身份验证标头。仅适用于公共项目。

当身份验证失败时，错误告诉您尝试了什么以及如何修复：

Can't access devdiv/DevDiv — authentication required (401).

Current auth: anonymous (no credentials found)

To resolve:
• Run 'az login' (if your Azure identity has access to this org)
• Set AZDO_TOKEN to a Personal Access Token with Build(read) + Test(read) scopes

通过MCP配置传递令牌：

{
  "servers": {
    "hlx": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["dnx", "--yes", "lewing.helix.mcp"],
      "env": {
        "HELIX_ACCESS_TOKEN": "your-helix-token",
        "AZDO_TOKEN": "your-azdo-pat-or-entra-token"
      }
    }
  }
}

HTTP MCP服务器支持通过以下方式进行每次请求的身份验证 Authorization: Bearer 头文件，每个客户端都有独立的缓存。集 HLX_API_KEY 以阻止服务器访问。

安装

使用dotnetdnceng插件（推荐）

这 Dott舞者插件 将hlx与相关的MCP服务器（Azure DevOps、Maestro、binlog）和CI分析技能捆绑在一起——一次安装，包括电池：

copilot extensions install lewing/agent-plugins/plugins/dotnet-dnceng

这给了你的经纪人 helix_* 和 azdo_* CI故障分析、代码流跟踪和依赖流调试的工具和技能。

使用dnx运行（无需安装）

dnx lewing.helix.mcp

dnx （.NET 10中的新功能）自动下载并运行NuGet工具包。当没有给出子命令时，MCP模式是默认模式。

作为全局工具安装

dotnet tool install -g lewing.helix.mcp

安装后， hlx 可作为命令使用。看 CLI参考 用于独立使用。

从源代码构建

git clone https://github.com/lewing/helix.mcp.git
cd helix.mcp
dotnet build   # Requires .NET 10 SDK

这 Microsoft.DotNet.Helix.Client 包裹来自 大唐能 饲料。包括 nuget.config 引用它。

MCP配置

添加到MCP客户端配置中：

{
  "servers": {
    "hlx": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["dnx", "--yes", "lewing.helix.mcp"]
    }
  }
}

如果作为全局工具安装，请使用 "command": "hlx" 和 "args": [] 相反。

VS代码使用 servers.Claude桌面、Claude代码和光标使用 mcpServers --其余部分是相同的。

对于HTTP（远程/共享服务器）：

{
  "servers": {
    "hlx": {
      "type": "http",
      "url": "http://localhost:3001"
    }
  }
}

安全

• 安全XML解析 --禁止DTD处理，禁用XmlResolver，50 MB字符限制（XXE/十亿笑保护）
• 路径遍历保护 --所有缓存/下载路径都针对指定根进行了清理和验证
• URL方案验证 --下载只接受HTTP/HTTPS
• 文件搜索切换 --set HLX_DISABLE_FILE_SEARCH=true 禁用内容搜索工具
• 凭据存储 --由操作系统钥匙链管理的令牌 git credential，从不以明文形式存储
• 缓存灵敏度 --缓存的CI日志可能包含机密；将缓存目录视为敏感目录。令牌永远不会被缓存——只有一个不可逆的8字符哈希用于目录隔离

已知问题

• 文件列表用途 ListFiles 端点 --避免了中的已知错误 Details 端点，其中子目录和unicode文件名的文件URI被破坏(点网/数据中心#6072).

需求

• .NET 10 SDK

许可证

麻省理工学院