lewing.helix.mcp 0.7.4

helix.mcp

An increasingly inaccurately named CLI and MCP server for AI agents investigating .NET CI/CD failures across Helix and Azure DevOps.

Built with Squad — meet the squad.

Why?

AI agents investigating CI failures in dotnet repos (runtime, sdk, aspnetcore, etc.) hit two problems:

1. Raw APIs return too much data. A single Helix console log can be megabytes. The Azure DevOps build timeline returns hundreds of records. Dumping this into a context window wastes tokens and drowns the signal.
2. Every agent starts from scratch. When multiple agents — or the same agent across tool calls — inspect the same build, each one repeats the same API calls and downloads.

hlx solves both:

• Return less, return better. Tools like helix_search and azdo_search_log search in place and return only matching lines with context — agents never download a full log. helix_status returns structured failure summaries instead of raw JSON. Default tail limits (500 lines), filter parameters (failed by default), and maxMatches caps keep responses focused.
• Cache everything, share across processes. A local SQLite cache sits between agents and the APIs. Different MCP server instances (one per IDE window/terminal) share the same cache, so the second agent to inspect a job gets instant results. Smart TTLs track job lifecycle — running jobs cache briefly (15–30s), completed jobs cache for hours.

Zero config — public dotnet CI works out of the box. Install and go.

Context-Efficient Design

Every tool is designed to minimize token consumption in agent context windows:

Investigation Path

• When repo workflows vary, start with helix_ci_guide(repo) for the repo-specific path and search patterns.
• Use helix_parse_uploaded_trx only when the work item uploads structured test results to Helix (runtime CoreCLR, XHarness device tests).
• Otherwise use azdo_test_runs → azdo_test_results for structured results, or helix_search when the signal is in console output.

Cross-Process Caching

 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 mode — multiple processes read/write the same DB safely with busy timeout
• Smart TTLs — running jobs: 15–30s, completed jobs: 1–4h, console logs for running jobs: never cached. AzDO in-progress builds use dual-key freshness with incremental log fetching (delta-append)
• Auth-isolated storage — each unique token gets its own cache directory (cache-{hash}/). Unauthenticated requests use public/. No cross-token leakage
• LRU eviction — 1 GB cap (configurable via HLX_CACHE_MAX_SIZE_MB), artifact files expire after 7 days without access

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

MCP Tools

Helix Tools (9)

AzDO Tools (11)

MCP Resources

MCP resources are URI-addressable data that clients can discover and read without invoking a tool.

These provide the same CI investigation guides available via the helix_ci_guide tool, exposed as client-discoverable resources for browsing and caching.

Authentication

Helix

No auth needed for public Helix jobs (dotnet open-source CI). For private jobs:

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

Token resolution: HELIX_ACCESS_TOKEN env var → stored credential via git credential → error with helpful message.

Azure DevOps

The AzDO tools work anonymously against public projects (for example dnceng-public/public). For private orgs (for example devdiv/DevDiv), authentication is required.

Credential chain (tried in order):

1. AZDO_TOKEN environment variable — both PATs and Entra access tokens are auto-detected:
   • PATs (Personal Access Tokens): sent as Basic auth. Needs Build(read) + Test(read) scopes.
   • Entra/JWT tokens: sent as Bearer auth.
2. Azure CLI credential (AzureCliCredential from Azure.Identity) — uses your az login session. Works for any org your Azure identity has access to.
3. az CLI subprocess — falls back to az account get-access-token if Azure.Identity isn't available.
4. Anonymous — no auth header. Works for public projects only.

When auth fails, the error tells you what was tried and how to fix it:

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

Pass tokens via MCP config:

{
  "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"
      }
    }
  }
}

The HTTP MCP server supports per-request auth via Authorization: Bearer <token> headers, with isolated cache per client. Set HLX_API_KEY to gate server access.

Installation

Use with the dotnet-dnceng plugin (recommended)

The dotnet-dnceng plugin bundles hlx alongside related MCP servers (Azure DevOps, Maestro, binlog) and CI analysis skills — one install, batteries included:

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

This gives your agent helix_* and azdo_* tools plus skills for CI failure analysis, codeflow tracing, and dependency flow debugging.

Run with dnx (no install needed)

dnx lewing.helix.mcp

dnx (new in .NET 10) auto-downloads and runs NuGet tool packages. MCP mode is the default when no subcommand is given.

Install as global tool

dotnet tool install -g lewing.helix.mcp

After installation, hlx is available as a command. See the CLI reference for standalone usage.

Build from source

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

The Microsoft.DotNet.Helix.Client package comes from the dotnet-eng feed. The included nuget.config references it.

MCP Configuration

Add to your MCP client config:

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

If installed as a global tool, use "command": "hlx" with "args": [] instead.

VS Code uses servers. Claude Desktop, Claude Code, and Cursor use mcpServers — the rest is identical.

For HTTP (remote/shared servers):

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

Security

• Safe XML parsing — DTD processing prohibited, XmlResolver disabled, 50 MB character limit (XXE/billion-laughs protection)
• Path traversal protection — all cache/download paths sanitized and validated against designated roots
• URL scheme validation — only HTTP/HTTPS accepted for downloads
• File search toggle — set HLX_DISABLE_FILE_SEARCH=true to disable content search tools
• Credential storage — tokens managed by OS keychain via git credential, never stored in plaintext
• Cache sensitivity — cached CI logs may contain secrets; treat the cache directory as sensitive. Tokens are never cached — only an irreversible 8-char hash is used for directory isolation

Known Issues

• File listing uses ListFiles endpoint — avoids a known bug in the Details endpoint where file URIs are broken for subdirectories and unicode filenames (dotnet/dnceng#6072).

Requirements

• .NET 10 SDK

License

MIT