lewing.helix.mcp 0.3.0

helix.mcp — MCP server and CLI for investigating .NET CI failures (Helix + Azure DevOps)

An MCP server that exposes .NET Helix and Azure DevOps APIs as 23 structured tools with cross-process local caching — purpose-built for AI agents diagnosing CI failures in dotnet repos (runtime, sdk, aspnetcore, etc.). Also works as a standalone CLI for humans.

Built with Squad — meet the squad.

Why hlx?

When an AI agent investigates a CI failure in a dotnet repo, it needs to inspect Helix test artifacts — console logs, TRX test results, binlogs, crash dumps. The raw Helix API returns unstructured blobs that agents must download and parse, burning context window on boilerplate extraction. If multiple agents (or the same agent across tool calls) look at the same job, each one repeats the same API calls and downloads.

hlx solves this by wrapping the Helix API as MCP tools that return structured, pre-parsed data:

• Structured output — helix_status returns categorized failure summaries as JSON; helix_test_results parses TRX files and returns test names, outcomes, and error messages directly. No raw text parsing needed.
• Cross-process caching — API responses and downloaded artifacts are cached in a local SQLite database. Different MCP server instances (one per IDE/agent) share the same cache, so the second agent to inspect a job gets instant results. TTLs are smart — running jobs cache briefly (15–30s), completed jobs cache for hours.
• Context-efficient — helix_search_log, helix_search_file, azdo_search_log, and azdo_search_timeline search in place and return matching lines with context, so agents never need to download a full log. helix_find_files locates artifacts across work items without listing every file.
• Zero config — public dotnet CI jobs work out of the box. Install and go.

ci-analysis replacement: hlx provides 100% coverage of the Helix API surface used by the ci-analysis skill's ~150 lines of PowerShell, with structured caching, failure categorization, and MCP tool support on top.

Architecture

The project is split into three layers:

• HelixTool.Core — Shared library containing HelixService, AzdoService, API clients, and model types. Helix API logic lives at the root; AzDO pipeline integration lives in AzDO/.
• HelixTool — CLI tool built with ConsoleAppFramework. Serves both human-readable terminal commands and a stdio MCP server (hlx mcp). MCP is also the default mode when no subcommand is given.
• HelixTool.Mcp — Standalone MCP HTTP server built with ModelContextProtocol. Returns structured JSON for LLM agents over HTTP.

Both the CLI and MCP server depend on Core but not on each other.

Installation

Run with dnx (no install needed)

dnx (new in .NET 10) auto-downloads and runs NuGet tool packages — no install step required:

dnx lewing.helix.mcp

This is the recommended approach for MCP server configuration (see below). No explicit mcp subcommand is needed — MCP mode is the default when no command is specified.

Install as Global Tool

dotnet tool install -g lewing.helix.mcp

For repo-local installation via a tool manifest:

dotnet new tool-manifest   # if .config/dotnet-tools.json doesn't exist
dotnet tool install --local lewing.helix.mcp

Install from Local Build

dotnet pack src/HelixTool
dotnet tool install -g --add-source src/HelixTool/nupkg lewing.helix.mcp

After installation, hlx is available globally.

Build from Source

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

NuGet feed requirement: The Microsoft.DotNet.Helix.Client SDK package is published to the dotnet-eng Azure Artifacts feed. The included nuget.config references this feed. If you see restore errors for Microsoft.DotNet.Helix.Client, ensure the feed is accessible.

Quick Start

CLI

After installing lewing.helix.mcp as a global or local tool, the hlx command is available:

# Authenticate (one-time setup)
hlx login

# Check a Helix job (shows failed work items by default)
hlx status 02d8bd09-9400-4e86-8d2b-7a6ca21c5009

# Show all work items including passed
hlx status 02d8bd09 all

# Download console log for a failed work item
hlx logs 02d8bd09 "dotnet-watch.Tests.dll.1"

# List uploaded files (binlogs, test results, etc.)
hlx files 02d8bd09 "dotnet-watch.Tests.dll.1"

# Download binlogs from a work item
hlx download 02d8bd09 "dotnet-watch.Tests.dll.1" --pattern "*.binlog"

# Search work items for files by pattern (e.g., binlogs, trx, dmp)
hlx find-files 02d8bd09 --pattern "*.binlog"

# Download a file by direct URL (from hlx files output)
hlx download-url "https://helix..."

# Show detailed info about a specific work item
hlx work-item 02d8bd09 "dotnet-watch.Tests.dll.1"

# Check status of multiple jobs at once
hlx batch-status 02d8bd09 a1b2c3d4

# Search console log for error patterns
hlx search-log 02d8bd09 "dotnet-watch.Tests.dll.1" "error CS"

# Search an uploaded file for a pattern
hlx search-file 02d8bd09 "dotnet-watch.Tests.dll.1" "testhost.log" "error"

# Parse TRX test results from a work item
hlx test-results 02d8bd09 "dotnet-watch.Tests.dll.1"

AzDO CLI

# Get details for a specific AzDO build
hlx azdo build 12345678

# List recent builds, optionally filtered by branch
hlx azdo builds --branch main

# Show build timeline (stages, jobs, tasks)
hlx azdo timeline 12345678

# Read a specific build log (use log ID from timeline output)
hlx azdo log 12345678 42

# List commits/changes in a build
hlx azdo changes 12345678

# List test runs for a build
hlx azdo test-runs 12345678

# Get test results for a specific test run
hlx azdo test-results 12345678 98765

# Search a build log for a pattern
hlx azdo search-log 12345678 42 "error CS"

# Search ALL build logs for a pattern (ranked by failure likelihood)
hlx azdo search-log-all 12345678 --pattern "error CS"

# Search timeline records for a pattern
hlx azdo search-timeline 12345678 "test"

# List build artifacts
hlx azdo artifacts 12345678

# List attachments for a test result
hlx azdo test-attachments 98765 1234

Accepts bare GUIDs or full Helix URLs:

hlx status https://helix.dot.net/api/jobs/02d8bd09-9400-4e86-8d2b-7a6ca21c5009/details

If running from a local build instead of the installed tool, substitute dotnet run --project src/HelixTool -- for hlx.

MCP Server

Stdio (recommended for local use) — launched automatically by MCP clients:

hlx mcp

HTTP (for remote/shared servers):

# Start the HTTP MCP server (default port 5000)
dotnet run --project src/HelixTool.Mcp

# Or on a specific port
dotnet run --project src/HelixTool.Mcp --urls http://localhost:3001

MCP Configuration

Add the following to your MCP client config. The --yes flag ensures dnx doesn't prompt for confirmation:

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

If you've installed lewing.helix.mcp as a global tool, you can use "command": "hlx" with "args": [] instead of dnx.

Config file locations

Note: VS Code uses the servers key (shown above). Claude Desktop, Claude Code, and Cursor use mcpServers instead — the rest of the JSON is identical.

HTTP alternative (for remote/shared servers)

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

MCP Tools

Helix Tools

AzDO Tools

CLI Commands

AzDO CLI Commands

Failure Categorization

Failed work items are automatically classified into one of: Timeout, Crash, BuildFailure, TestFailure, InfrastructureError, AssertionFailure, or Unknown. The category appears in status, work-item, and batch-status output, and is available as failureCategory in JSON and MCP tool responses.

How hlx Enhances the Helix API

hlx isn't a thin API wrapper — it adds a local intelligence layer between agents and the raw Helix REST API. The biggest win for LLM agents is that TRX parsing, remote search, and failure classification work together to return structured, pre-categorized, context-efficient data instead of raw blobs.

Major enhancements

Convenience enhancements

Project Structure

src/
├── HelixTool/              # CLI tool + stdio MCP server
│   └── Program.cs           # Console commands via ConsoleAppFramework + MCP server
├── HelixTool.Core/         # Shared library — Helix API logic + MCP tool definitions
│   ├── HelixService.cs     # Core operations (status, logs, files, download)
│   ├── HelixMcpTools.cs    # MCP tool definitions ([McpServerToolType])
│   ├── HelixIdResolver.cs  # GUID and URL parsing
│   ├── IHelixApiClient.cs  # Helix API abstraction
│   ├── HelixApiClient.cs   # Helix API implementation
│   ├── IHelixApiClientFactory.cs  # Per-request client creation (HTTP multi-auth)
│   ├── IHelixTokenAccessor.cs     # Token resolution abstraction
│   ├── ChainedHelixTokenAccessor.cs # Token resolution chain (env var → stored credential)
│   ├── ICredentialStore.cs  # Credential storage abstraction
│   ├── GitCredentialStore.cs # git credential CLI implementation
│   ├── HelixException.cs   # Typed exceptions
│   ├── AzDO/               # Azure DevOps pipeline integration
│   │   ├── AzdoService.cs           # Core AzDO operations (builds, timelines, logs, tests)
│   │   ├── AzdoMcpTools.cs          # MCP tool definitions ([McpServerToolType])
│   │   ├── AzdoIdResolver.cs        # Build ID and URL parsing (dev.azure.com + visualstudio.com)
│   │   ├── AzdoApiClient.cs         # AzDO REST API implementation
│   │   ├── IAzdoApiClient.cs        # API abstraction
│   │   ├── CachingAzdoApiClient.cs  # Transparent caching wrapper
│   │   ├── IAzdoTokenAccessor.cs    # Token resolution abstraction
│   │   └── AzdoModels.cs            # Response model types
│   └── Cache/              # SQLite-backed response caching
│       ├── SqliteCacheStore.cs       # Cache storage implementation
│       ├── CachingHelixApiClient.cs  # Transparent caching wrapper
│       ├── CacheSecurity.cs          # Path traversal protection
│       ├── CacheOptions.cs           # TTL, size, auth isolation config
│       └── ICacheStore.cs            # Cache store abstraction
├── HelixTool.Mcp/          # MCP HTTP server
│   ├── Program.cs                         # ASP.NET Core + ModelContextProtocol
│   └── HttpContextHelixTokenAccessor.cs   # Per-request token from Authorization header
└── HelixTool.Tests/        # Unit tests (700 tests)

Authentication

Helix

No authentication is needed for public Helix jobs (dotnet open-source CI). For internal/private jobs, use hlx login:

# Interactive login — opens browser to token page, prompts for token
hlx login

# Skip browser launch (e.g., SSH sessions)
hlx login --no-browser

# Check current auth status
hlx auth-status

# Remove stored token
hlx logout

hlx login opens https://helix.dot.net/Account/Tokens in your browser, prompts for a masked token input, validates it against the API, and stores it securely via git credential (OS keychain — macOS Keychain, Windows Credential Manager, or libsecret on Linux).

Token resolution order (backward compatible):

1. HELIX_ACCESS_TOKEN environment variable (highest priority — CI/CD override)
2. Stored credential via git credential (OS keychain, set by hlx login)
3. No token → fails with a helpful message suggesting hlx login

Environment variable (CI/CD)

For CI pipelines or scripts, set the HELIX_ACCESS_TOKEN environment variable instead:

export HELIX_ACCESS_TOKEN=your-token-here

For MCP clients, pass the token in the server config:

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

HTTP MCP server (per-request auth)

The HTTP MCP server (HelixTool.Mcp) supports per-request authentication via the Authorization header:

Authorization: Bearer <token>
Authorization: token <token>

Each authenticated client gets isolated cache storage. If no header is present, the server falls back to the HELIX_ACCESS_TOKEN environment variable. This enables shared/remote MCP server deployments where multiple users connect with different credentials.

API key auth: Set HLX_API_KEY to require an X-Api-Key header on every request. When set, requests without a valid key receive 401 Unauthorized. This is independent of Helix token auth — it gates access to the server itself.

If a job requires authentication and no token is set, hlx will show an actionable error message.

Azure DevOps

No authentication is needed for public AzDO projects (e.g., dnceng-public/public). For internal/private projects:

Token resolution order:

1. AZDO_TOKEN environment variable (highest priority)
2. Azure CLI — az account get-access-token (automatic if Azure CLI is signed in)
3. No token → anonymous access (works for public projects)

For MCP clients, pass the token in the server config:

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

Multi-org support: AzDO tools accept org and project parameters per call, defaulting to dnceng-public / public. No global org configuration is needed.

Caching

Both Helix and AzDO API responses are automatically cached to a local SQLite database — no configuration needed.

Multiple MCP server instances share a single cache safely:

flowchart LR
    subgraph IDEs["IDE / Agent processes"]
        A1["VS Code"]
        A2["Copilot CLI"]
        A3["Other agent"]
    end

    subgraph Stdio["hlx stdio MCP servers"]
        P1["hlx (pid 1)"]
        P2["hlx (pid 2)"]
        P3["hlx (pid 3)"]
    end

    A1 --> P1
    A2 --> P2
    A3 --> P3

    P1 --> Cache
    P2 --> Cache
    P3 --> Cache

    subgraph Cache["CachingHelixApiClient"]
        direction TB
        Check{"Cache\nhit?"}
    end

    Check -- miss --> API["Helix API"]
    API -- response --> Check

    Check -- hit --> Result["Cached response"]

    subgraph Store["SQLite + Disk (shared)"]
        direction TB
        DB["SQLite DB\n(WAL mode)"]
        Artifacts["Artifact files\n(logs, TRX, binlogs)"]
    end

    Cache <--> Store

    subgraph Isolation["Auth isolation"]
        direction LR
        T1["cache-a1b2c3/"]
        T2["cache-d4e5f6/"]
        T3["public/"]
    end

    Store --- Isolation

Concurrency guarantees:

• SQLite WAL mode with busy timeout — multiple processes read/write the same DB safely
• Atomic artifact writes — files are written to a temp path, then renamed into place
• Safe concurrent reads — FileShare.ReadWrite|Delete prevents conflicts during eviction
• Isolated temp dirs — each DownloadFilesAsync call uses its own temp directory

TTL policy — Helix: Running jobs use short TTLs (15–30s). Completed jobs cache for 1–4h. Console logs are never cached while a job is still running.

TTL policy — AzDO: Completed builds cache for 4h. In-progress builds cache for 15s. Build logs cache for 4h (immutable after creation). Test results cache for 1h. Incremental log fetching: In-progress build logs use dual-key freshness — when the 15s freshness marker expires, only new lines are fetched (delta-append) rather than re-downloading the entire log.

Auth isolation: Each unique token gets its own cache directory (cache-{hash}). Unauthenticated requests use public/. The HTTP MCP server isolates per-request tokens automatically.

CLI commands:

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

Security

• Safe XML parsing: TRX files are parsed with DtdProcessing.Prohibit, XmlResolver = null, and a 50 MB character limit to prevent XXE and billion-laughs attacks.
• Path traversal protection: All cache paths and download file names are sanitized via CacheSecurity — directory separators are replaced and .. sequences are stripped. Resolved paths are validated to stay within their designated root.
• URL scheme validation: helix_download_url only accepts HTTP/HTTPS URLs; other schemes are rejected.
• File search toggle: Set HLX_DISABLE_FILE_SEARCH=true to disable helix_search_file, helix_search_log, azdo_search_log, azdo_search_log_across_steps, and helix_test_results. Useful for locked-down deployments where file content inspection is not desired.
• Input validation: Job IDs are resolved through HelixIdResolver (GUIDs and URLs). Batch operations are capped at 50 jobs per request. File search is limited to 50 MB files.
• Credential storage: Tokens stored via hlx login are managed by the OS keychain through git credential (macOS Keychain, Windows Credential Manager, or libsecret on Linux). hlx never stores tokens in plaintext files.

Cached data

The SQLite cache (%LOCALAPPDATA%\hlx\ on Windows, $XDG_CACHE_HOME/hlx/ on Linux/macOS) stores Helix API responses and downloaded artifacts on disk. Cached data includes job metadata, work item details, console logs, and uploaded files like binlogs and TRX results. Console logs and test output from CI runs may inadvertently contain secrets such as connection strings or tokens — treat the cache directory as potentially sensitive.

What is NOT cached: Authentication tokens are never written to the cache. The HELIX_ACCESS_TOKEN is used only for API requests and to derive an 8-character SHA256 hash for cache directory isolation (cache-{hash}/). The hash is not reversible to the original token.

Access control: The cache lives in the current user's profile directory, protected by OS-level file permissions. Each unique Helix token gets its own isolated cache directory; unauthenticated requests use a separate public/ directory. No cross-token data leakage is possible. On shared machines or when switching between security contexts, run hlx cache clear to wipe all cached data. Cached metadata expires via TTL (15s–4h depending on job state), and artifact files expire after 7 days without access.

Requirements

• .NET 10 SDK

Known Issues

• File listing uses ListFiles endpoint — hlx uses the ListFilesAsync endpoint for work item file listing, which correctly returns file URIs for files in subdirectories and files with unicode characters. This avoids the known bug in the Details endpoint where file URIs are broken (dotnet/dnceng#6072).

How to find Helix job IDs

Helix job IDs appear in Azure DevOps build logs. Look for tasks like "Send to Helix" or "Wait for Helix" — the job ID is a GUID in the log output. You can also use the azp CLI to find them.

License

MIT