# microsoft/azure-devops-mcp architecture

> Architecture diagram of the GitHub repository microsoft/azure-devops-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/azure-devops-mcp
- Repository: https://github.com/microsoft/azure-devops-mcp

## Overview

##### Project type and purpose
- This is an open-source, Node.js/TypeScript “MCP Server” CLI plugin that exposes Azure DevOps REST APIs as a set of tools over stdio.
- It is consumed by VS Code (via GitHub Copilot Agent Mode or any stdio-based client) to enable interactive prompts and commands against Azure DevOps.

##### File structure
- Top-level: configuration for CI/CD (.github/workflows, .azuredevops/pipelines), linting (eslint.config.mjs), formatting (.prettierrc.json), devcontainer, and docs.
- scripts/build-validate-tools.js: build-time validation of the tool definitions.
- src/index.ts: the CLI entrypoint.
- src/prompts.ts & src/auth.ts: core orchestration of user prompts and authentication.
- src/shared: shared domain definitions and validation logic.
- src/tools/*: one file per domain (“core”, “work-items”, “pipelines”, “repositories”, “wiki”, “search”, “advanced-security”, “test-plans”, etc.). Each exports a collection of functions implementing REST calls.
- test/*: Jest tests covering each module.

##### README for additional insights
- Calls out architecture in prose: a “thin abstraction layer” over ADO REST APIs, organized into Domains to reduce loaded tools.
- Usage: loaded by VS Code via npx + stdio, passing an organization name and optional domain filters.

##### Main components and their interactions
a. Host/Client (VS Code Copilot Chat or any stdio-based client)
- Sends JSON-RPC or command prompts over stdio.
b. MCP Server (Node.js process)
- index.ts: bootstraps the server, parses arguments, loads Domains.
- prompts.ts: translates user input into tool invocations.
- auth.ts + org-tenants.ts: manage authentication tokens and tenant resolution.
- tool loader: dynamically imports the selected domain modules from src/tools.
- utils.ts & shared/: support HTTP requests, schema validation, type generation.
- useragent.ts & version.ts: handle client identification and versioning.
c. Domain modules (src/tools/*.ts)
- Each module exports a set of RPC-callable functions that wrap specific Azure DevOps REST endpoints.
d. External Service (Azure DevOps REST API)
- The ultimate target of every tool function.
e. Developer workflows (CI/CD pipelines, GitHub Actions)
- Validate, lint, build, test, version, and release the package to npm.

Relationships:
1. VS Code ⇄ stdio ⇄ MCP Server
2. MCP Server → HTTP client → Azure DevOps REST endpoints
3. Build & test pipelines (GitHub Actions, Azure DevOps pipelines) → push to npm

##### Architectural patterns & design principles
- Plugin/Module pattern: each “tool” is a self-contained module grouped by domain.
- Thin abstraction: no business logic beyond REST call orchestration.
- Domain-based loading: only load the requested domains to reduce tool bloat.

##### Essential elements to capture
- Stdio boundary and JSON-RPC interface
- Dynamic domain-based plugin loader
- Shared utilities and validation layer
- Individual tool modules grouped by domain
- Authentication flow to Azure DevOps
- CI/CD automation for build, test, and release

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client
    VSCode["VS Code Copilot Chat"]:::frontend

    %% MCP Server Container
    subgraph "Node.js/TypeScript MCP Server"
        direction TB
        Index["CLI Entrypoint (index.ts)"]:::server
        Prompts["User Prompt Orchestration (prompts.ts)"]:::server
        Auth["Authentication Flow (auth.ts)"]:::server
        Tenants["Tenant Resolution (org-tenants.ts)"]:::server
        Loader["Dynamic Tool Loader (tools.ts)"]:::server
        Utils["HTTP & Misc Utilities (utils.ts)"]:::util
        UA["User-Agent Handling (useragent.ts)"]:::util
        Ver["Versioning Metadata (version.ts)"]:::util

        subgraph "Shared"
            direction TB
            Domains["Shared Domain Definitions (domains.ts)"]:::util
            Validation["Shared Tool Validation (tool-validation.ts)"]:::util
        end

        subgraph "Domain Modules"
            direction TB
            Core["Core (core.ts)"]:::domain
            Work["Work (work.ts)"]:::domain
            WorkItems["Work-Items (work-items.ts)"]:::domain
            Pipelines["Pipelines (pipelines.ts)"]:::domain
            Repos["Repositories (repositories.ts)"]:::domain
            Wiki["Wiki (wiki.ts)"]:::domain
            Search["Search (search.ts)"]:::domain
            Sec["Advanced Security (advanced-security.ts)"]:::domain
            Tests["Test Plans (test-plans.ts)"]:::domain
        end
    end

    %% External Service
    Azure["Azure DevOps REST API"]:::external

    %% CI/CD Pipelines
    subgraph "CI/CD & Release" 
        direction TB
        style CI stroke-dasharray: 5 5
        GH["GitHub Actions (.github/workflows)"]:::ci
        AZP["Azure DevOps Pipelines (release.yml)"]:::ci
        Scripts["Build-Time Validator (build-validate-tools.js)"]:::ci
        TestsCI["Jest Test Suites (test/src/)"]:::ci
        Npm["npm Registry"]:::external
    end

    %% Connections
    VSCode -->|"stdio / JSON-RPC"| Index
    Index --> Prompts
    Index --> Auth
    Index --> Tenants
    Index --> Loader
    Index --> UA
    Index --> Ver
    Loader --> Core
    Loader --> Work
    Loader --> WorkItems
    Loader --> Pipelines
    Loader --> Repos
    Loader --> Wiki
    Loader --> Search
    Loader --> Sec
    Loader --> Tests
    Auth -->|"OAuth / Token"| Azure
    Core -->|"HTTP REST"| Azure
    Work -->|"HTTP REST"| Azure
    WorkItems -->|"HTTP REST"| Azure
    Pipelines -->|"HTTP REST"| Azure
    Repos -->|"HTTP REST"| Azure
    Wiki -->|"HTTP REST"| Azure
    Search -->|"HTTP REST"| Azure
    Sec -->|"HTTP REST"| Azure
    Tests -->|"HTTP REST"| Azure

    GH --> TestsCI
    GH --> Scripts
    GH --> Npm
    AZP --> Npm

    %% Click Events
    click Index "https://github.com/microsoft/azure-devops-mcp/blob/main/src/index.ts"
    click Prompts "https://github.com/microsoft/azure-devops-mcp/blob/main/src/prompts.ts"
    click Auth "https://github.com/microsoft/azure-devops-mcp/blob/main/src/auth.ts"
    click Tenants "https://github.com/microsoft/azure-devops-mcp/blob/main/src/org-tenants.ts"
    click Loader "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools.ts"
    click Utils "https://github.com/microsoft/azure-devops-mcp/blob/main/src/utils.ts"
    click UA "https://github.com/microsoft/azure-devops-mcp/blob/main/src/useragent.ts"
    click Ver "https://github.com/microsoft/azure-devops-mcp/blob/main/src/version.ts"
    click Domains "https://github.com/microsoft/azure-devops-mcp/blob/main/src/shared/domains.ts"
    click Validation "https://github.com/microsoft/azure-devops-mcp/blob/main/src/shared/tool-validation.ts"
    click Core "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools/core.ts"
    click Work "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools/work.ts"
    click WorkItems "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools/work-items.ts"
    click Pipelines "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools/pipelines.ts"
    click Repos "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools/repositories.ts"
    click Wiki "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools/wiki.ts"
    click Search "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools/search.ts"
    click Sec "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools/advanced-security.ts"
    click Tests "https://github.com/microsoft/azure-devops-mcp/blob/main/src/tools/test-plans.ts"
    click Scripts "https://github.com/microsoft/azure-devops-mcp/blob/main/scripts/build-validate-tools.js"
    click GH "https://github.com/microsoft/azure-devops-mcp/blob/main/.github/workflows/*.yml"
    click AZP "https://github.com/microsoft/azure-devops-mcp/blob/main/.azuredevops/pipelines/release.yml"
    click TestsCI "https://github.com/microsoft/azure-devops-mcp/tree/main/test/src/"

    %% Styles
    classDef frontend fill:#ddeeff,stroke:#3399ff,stroke-width:1px
    classDef server fill:#e0f7fa,stroke:#0288d1,stroke-width:1px
    classDef domain fill:#e8f5e9,stroke:#43a047,stroke-width:1px
    classDef util fill:#fff3e0,stroke:#fb8c00,stroke-width:1px
    classDef external fill:#fce4ec,stroke:#d81b60,stroke-width:1px
    classDef ci fill:#f3e5f5,stroke:#8e24aa,stroke-width:1px,stroke-dasharray:5 5
```
