ADO Workflows MCP Server

An MCP server exposing ado-workflows as tool calls for AI agents. Enables Copilot and other MCP clients to discover Azure DevOps repositories, manage pull requests, and interact with PR comments and reviews.

Quick Install

<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code"> <img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">

Click a badge above to install with one click, or follow manual installation below.

Features

• Repository Discovery: Scan directories for git repos with Azure DevOps remotes
• PR Lifecycle: Create pull requests, establish PR context from URLs or IDs
• Review Management: Check reviewer votes, detect stale approvals, find PRs needing attention
• Comment Workflows: Analyze, post, reply to, and batch-resolve PR comment threads
• Session Caching: Cache repository context to avoid redundant git CLI lookups
• Error Handling: Actionable errors with suggestions via actionable-errors

MCP Tools

Repository Discovery

Pull Requests

PR Review

PR Comments

Installation

Quick Install (Recommended)

Click one of the badges at the top to automatically install in VS Code!

Manual Installation

cd ado-workflows-mcp
uv sync --all-extras

VS Code / Copilot Configuration

Add to your VS Code settings or .vscode/mcp.json:

{
  "mcp.servers": {
    "ado-workflows": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/grimlor/ado-workflows-mcp", "ado-workflows-mcp"],
      "description": "Azure DevOps workflow automation tools"
    }
  }
}

The server communicates over stdio using the Model Context Protocol.

Authentication

Uses Azure DefaultAzureCredential via the ado-workflows library. Authenticate with any method that DefaultAzureCredential supports:

az login                           # Azure CLI (local dev)
az login --use-device-code         # Headless / SSH

Managed identity, environment variables, and other credential providers work automatically in hosted environments.

Error Handling

All errors are returned as structured ActionableError objects with:

• `error` / `suggestion` — human-readable context
• `ai_guidance` — machine-readable recovery instructions (action_required, checks, steps, command, discovery_tool)

Errors are returned as data, never raised — the MCP transport stays clean.

Typical Workflow

1. repository_discovery        → find the ADO repo
2. set_repository_context      → cache it for the session
3. establish_pr_context        → resolve a PR URL or ID
4. get_pr_review_status        → check approval state
5. analyze_pr_comments         → see active threads
6. post_pr_comment / reply     → leave feedback
7. resolve_pr_comments         → mark threads as fixed

Development

uv run task check                # lint + type + test (all-in-one)
uv run task test                 # Run tests (37 BDD specs)
uv run task cov                  # Run tests with coverage
uv run task lint                 # Lint (with auto-fix)
uv run task format               # Format code
uv run task type                 # Type check

Note: uv run is optional when the venv is activated via direnv.

Project Structure

src/ado_workflows_mcp/
├── server.py              # FastMCP server entry point
├── mcp_instance.py        # MCP singleton
├── tools/
│   ├── repositories.py    # Repository discovery tools
│   ├── repository_context.py  # Session context management
│   ├── pull_requests.py   # PR lifecycle tools
│   ├── pr_review.py       # Review status tools
│   ├── pr_comments.py     # Comment workflow tools
│   └── _helpers.py        # Shared error-handling utilities
└── py.typed               # PEP 561 marker

Testing

37 BDD specs across 10 requirement classes — organized by consumer requirement, not code structure.

Documentation

• Architecture — Tool layers, error propagation, and design decisions

Related

• ado-workflows — Azure DevOps automation library used by this server
• actionable-errors — Three-audience error framework
• demo-assistant-mcp — MCP server for demo script orchestration

License

This project is licensed under the MIT License.