# Azure DevOps Multi-Organization MCP Server
This is a specialized Model Context Protocol (MCP) server for Azure DevOps, designed to overcome the limitations of single-organization bindings found in standard implementations.
## 🚀 Value Proposition & Comparison
The primary value of this implementation is **Multi-Organization Support** and **Context Optimization**.
| Feature | Standard / Official AzDO MCP | This Implementation | User Value |
| :--- | :--- | :--- | :--- |
| **Scope** | Single Organization (bound via `AZURE_DEVOPS_ORG` env var) | **Multi-Organization** (Dynamic Routing) | Seamlessly work across `org-1`, `org-2`, and other orgs in a single chat session without restarting the server. |
| **Authentication** | Single PAT in `.env` | **Multiple PATs** in `config.json` | Securely manages distinct credentials for different organizations. |
| **Context Usage** | Returns raw, verbose API responses | **LLM-Optimized Responses** | Aggressively flattens and simplifies JSON output (e.g., removing huge log objects from list views) to prevent "Maximum Length" errors in Claude. |
| **Tool Signature** | `(project, ...args)` | `(organization, project, ...args)` | Explicit control over the target organization for every action. |
## 🛠 Architecture
### 1. The Connection Manager Pattern
Instead of initializing a single connection at startup, this server uses a `ConnectionManager` class.
- **Lazy Loading**: Connections to Azure DevOps are established only when a tool is requested.
- **Caching**: Authenticated connections are cached to ensure performance for subsequent requests.
- **Routing**: Every tool schema includes an `organization` argument. The manager uses this to look up the corresponding Personal Access Token (PAT) from `config.json`.
### 2. Modular Tool Structure
Tools are organized into separate modules for maintainability:
- **`tools/organizations.ts`**: Organization and project discovery tools
- **`tools/pipelines.ts`**: CI/CD pipeline operations (builds, definitions, runs, logs)
- **`tools/repositories.ts`**: Git repository and pull request management
- **`tools/common.ts`**: Shared utilities for enum handling and type conversions
- **`tools/index.ts`**: Central registration orchestrator
### 3. Context Window Optimization
Standard Azure DevOps API responses are extremely verbose, often containing full orchestration plans, logs, and deep nesting. This implementation intercepts these responses in tools like `pipelines_get_builds` and `pipelines_get_build_definitions` to:
- **Limit Results**: Defaults to top 20/50 items instead of hundreds.
- **Flatten Objects**: Maps complex objects to simple key-value pairs (e.g., `{ requestedFor: { displayName: "User" } }` becomes just the display name).
- **Strip Noise**: Removes unused URLs, large configuration blobs, and system metadata.
### 4. Dual Transport Support
- **Stdio Transport**: For local usage with Claude Desktop and VS Code (default)
- **SSE Transport**: For cloud deployment with HTTP endpoints (activated via `PORT` env var)
## 📦 Configuration
### 1. Prerequisites
- Node.js (v18 or higher)
- Azure DevOps Personal Access Tokens (PAT) with appropriate permissions:
- **Code (Read)**: For repository and pull request operations
- **Build (Read & Execute)**: For pipeline and build operations
- **Project and Team (Read)**: For organization and project listing
### 2. Setup `config.json`
Create a `config.json` file in the root directory. This file maps your Organization names (as they appear in the URL, e.g., `dev.azure.com/{org}`) to their PATs.
```json
{
"org-1": "your-pat-token-here",
"org-2": "another-pat-token-here"
}
```
### 3. Build & Run
```bash
npm install
npm run build
```
### 4. Claude Desktop Configuration (Local - Stdio)
Add the server to your `claude_desktop_config.json` for local usage:
```json
{
"mcpServers": {
"azure-devops-multi": {
"command": "node",
"args": [
"/absolute/path/to/mcp-server-azure-devops-multi/dist/index.js"
]
}
}
}
```
### 5. VS Code Configuration (Local - Stdio)
Add the server to your VS Code settings for use with GitHub Copilot Chat:
1. Open VS Code Settings (JSON)
2. Add to `github.copilot.chat.mcp.servers`:
```json
{
"github.copilot.chat.mcp.servers": {
"Azure DevOps Multi": {
"command": "node",
"args": [
"/absolute/path/to/mcp-server-azure-devops-multi/dist/index.js"
]
}
}
}
```
### 6. Cloud Deployment (HTTP/SSE)
The server supports SSE (Server-Sent Events) transport for cloud deployment:
#### Docker Build & Run
```bash
docker build -t azdo-mcp-server .
docker run -p 3000:3000 -v /path/to/config.json:/app/config.json azdo-mcp-server
```
#### Azure Container Apps
```bash
az containerapp create \
--name azdo-mcp-server \
--resource-group <your-rg> \
--environment <your-env> \
--image <your-acr>.azurecr.io/azdo-mcp-server:latest \
--target-port 3000 \
--ingress external \
--env-vars PORT=3000
```
The server automatically switches to SSE transport when `PORT` environment variable is set, exposing:
- `GET /sse` - SSE connection endpoint
- `POST /messages` - Message handling endpoint
## 🧰 Available Tools (18 Total)
### Organization & Projects (2 Tools)
- `list_organizations`: View all configured organizations in `config.json`.
- `list_projects`: List all projects within a specific organization.
### Pipelines & Builds (13 Tools)
- `pipelines_get_builds`: List recent builds with filtering options (optimized for context).
- `pipelines_get_build_definitions`: List build definitions with query options (optimized for context).
- `pipelines_get_build_status`: Get detailed report for a specific build.
- `pipelines_get_build_log`: Retrieve logs for a specific build.
- `pipelines_get_build_timeline`: Get timeline entries for a build.
- `pipelines_run_pipeline`: Trigger a new pipeline run with parameters and variables.
- `pipelines_get_run`: Get details for a specific pipeline run.
- `pipelines_list_runs`: List pipeline runs with filtering options.
- `pipelines_get_run_stage`: Get information about a specific stage in a pipeline run.
- `pipelines_get_run_log`: Get log content for a specific pipeline run.
- `pipelines_update_build_stage`: Update a stage in a build (placeholder - not yet implemented).
- `pipelines_get_definition`: Get a specific build definition by ID.
- `pipelines_get_definition_yaml`: Get the YAML content of a pipeline definition.
### Git Repositories & Pull Requests (5 Tools)
- `git_list_repositories`: List all Git repositories in a project.
- `git_get_repository`: Get details for a specific repository.
- `git_get_pull_requests`: Search and list pull requests with filtering options.
- `git_create_pull_request`: Create a new pull request with title, description, and reviewers.
- `git_get_item`: Get file or folder content from a repository with version control options.
