# Azure DevOps MCP Server

A production-ready **Model Context Protocol (MCP)** server that enables AI assistants like Claude to interact with Azure DevOps. This server provides tools for managing work items, repositories, wikis, and automating development workflows.

## ✨ Features

### 🎫 Work Item Management
- **Get Work Items**: Fetch work items by ID with full details
- **Query Work Items**: Use WIQL or simple filters to find work items
- **Create Work Items**: Create Tasks, Bugs, PBIs, Features, and Epics
- **Update Work Items**: Modify state, description, assignments, and more

### 📁 Repository Operations
- **List Repositories**: Get all repos in a project
- **Analyze Repositories**: Detect tech stack, frameworks, and structure
- **Read Files**: Get file content from any branch
- **Browse Structure**: Navigate the folder hierarchy

### 📚 Wiki Management
- **List Wikis**: Get all wikis in a project
- **Read Pages**: Fetch wiki page content
- **Create/Update Pages**: Manage wiki documentation

### 🤖 AI Workflow Automation
- **Analyze Work Items**: Extract requirements and technical hints
- **Suggest Repositories**: Match work items to appropriate repos
- **Generate Plans**: Create implementation plans from work items
- **Track Progress**: Update work items with progress

## 🚀 Quick Start

### Prerequisites

- Python 3.10 or higher
- Azure DevOps account with a Personal Access Token (PAT)

### Installation

```bash
# Clone or navigate to the project
cd ado-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .
```

### Configuration

Create a `.env` file in the project root:

```bash
# Copy the example
cp .env.example .env

# Edit with your values
ADO_ORGANIZATION_URL=https://dev.azure.com/YourOrganization
ADO_PAT=your_personal_access_token
ADO_DEFAULT_PROJECT=YourDefaultProject  # Optional
LOG_LEVEL=INFO
```

#### Required PAT Scopes

Your Personal Access Token needs these permissions:
- **Work Items**: Read & Write
- **Code (Repositories)**: Read & Write
- **Wiki**: Read & Write
- **Project and Team**: Read

### Running the Server

```bash
# Run directly
python -m ado_mcp.server

# Or use the CLI command
ado-mcp
```

## 🔧 Integration with AI Assistants

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "azure-devops": {
      "command": "python",
      "args": ["-m", "ado_mcp.server"],
      "cwd": "/path/to/ado-mcp",
      "env": {
        "ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg",
        "ADO_PAT": "your_pat_here",
        "ADO_DEFAULT_PROJECT": "YourProject"
      }
    }
  }
}
```

### VS Code with Copilot

Configure in your VS Code settings or workspace configuration.

## 📖 Usage Examples

Once connected, you can ask the AI assistant:

### Work Items
```
"Get details of work item #1234"
"Show me all active tasks assigned to me"
"Create a new bug: Login button not working on mobile"
"Update work item #1234 to Resolved with comment 'Fixed in PR #567'"
```

### Repositories
```
"List all repositories in the project"
"Analyze the backend-api repository"
"Show me the folder structure of frontend-app"
"Get the content of /src/main.py from backend-api"
```

### Wiki
```
"List all wikis in the project"
"Get the content of the /Home wiki page"
"Create a wiki page for the new authentication feature"
```

### AI Workflows
```
"I want to work on PBI #1234, analyze it and suggest a repository"
"Generate an implementation plan for task #5678"
"Update work item #1234 with 50% progress"
```

## 🛠️ Development

### Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# With coverage
pytest tests/ -v --cov=src/ado_mcp
```

### Code Quality

```bash
# Lint and format
ruff check src/
ruff format src/

# Type checking
mypy src/
```

## 📁 Project Structure

```
ado-mcp/
├── src/ado_mcp/
│   ├── __init__.py
│   ├── server.py           # MCP server entry point
│   ├── config.py           # Configuration management
│   ├── ado_client.py       # Azure DevOps API client
│   ├── tools/              # MCP Tools
│   │   ├── work_items.py   # Work item operations
│   │   ├── repositories.py # Repository operations
│   │   ├── wiki.py         # Wiki operations
│   │   └── analysis.py     # AI workflow analysis
│   ├── resources/          # MCP Resources
│   │   └── projects.py     # Project resources
│   └── prompts/            # MCP Prompts
│       └── workflows.py    # Workflow templates
├── tests/                  # Test files
├── pyproject.toml          # Project configuration
├── .env.example            # Environment template
└── README.md               # This file
```

## 🔒 Security

- **Local Execution**: The server runs locally, keeping your PAT secure
- **No External Calls**: All communication is with your Azure DevOps instance
- **Environment Variables**: Credentials stored in environment, not code

## 📜 License

MIT License - see LICENSE file for details.

## 🤝 Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

---

Built with ❤️ for the Azure DevOps and AI community