Ado Workflows

CI coverage PyPI License: MIT

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

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

Tool	Description
repository_discovery	Scan a directory for git repos with Azure DevOps remotes, select the best match
set_repository_context	Cache repository context for the session (avoids redundant git CLI lookups)
get_repository_context_status	Inspect current cached context state for debugging
clear_repository_context	Reset cached context, forcing fresh discovery

Pull Requests

Tool	Description
establish_pr_context	Parse a PR URL or resolve a numeric PR ID into reusable context
create_pull_request	Create a new PR from branch names with optional title, description, and draft mode

PR Review

Tool	Description
get_pr_review_status	Fetch reviewer votes, commit history, and detect stale approvals
analyze_pending_reviews	Discover PRs needing review attention across a repository

PR Comments

Tool	Description
analyze_pr_comments	Categorize comment threads by status with author statistics
post_pr_comment	Post a new comment thread to a PR
reply_to_pr_comment	Reply to an existing comment thread
resolve_pr_comments	Batch-resolve comment threads (partial-success semantics)

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.

Requirement Class	Specs	Coverage
TestRepositoryDiscovery	3	Success, working-dir failure, SDK failure
TestSetRepositoryContext	3	Valid context, missing fields, SDK failure
TestGetRepositoryContextStatus	3	Populated, empty, error
TestClearRepositoryContext	2	Reset + clear state
TestEstablishPRContext	3	URL parse, ID resolve, SDK failure
TestCreatePullRequest	3	Success, missing branch, SDK failure
TestGetPRReviewStatus	3	Success, invalid PR, SDK failure
TestAnalyzePendingReviews	3	Results, empty, SDK failure
TestAnalyzePRComments	3	Categorized, no threads, SDK failure
TestPostPRComment	3	Valid post, empty content, SDK failure
TestReplyToPRComment	3	Valid reply, missing thread, SDK failure
TestResolvePRComments	3	Batch resolve, empty list, SDK failure

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.