# Azure DevOps MCP Server

This is a Model Context Protocol (MCP) server that provides access to Azure DevOps resources and tools through a standardized interface.

## Features

The server provides the following Azure DevOps tools:

- **get_workitems** - Retrieve work items using WIQL queries
- **get_repositories** - List Git repositories
- **get_pullrequests** - Get pull requests from repositories
- **get_builds** - Retrieve build pipeline information
- **get_commits** - Get Git commits from repositories
- **create_workitem** - Create new work items (bugs, features, tasks, etc.)

## Prerequisites

1. **Azure DevOps Account**: You need access to an Azure DevOps organization
2. **Personal Access Token**: Generate a PAT with the following scopes:
   - Work Items (Read & Write)
   - Code (Read)
   - Build (Read)
   - Release (Read)

## Setup Instructions

### 1. Configure Environment Variables

Edit the `.env` file in the project root and replace the placeholder values:

```bash
# Your Azure DevOps organization name (e.g., "mycompany" for dev.azure.com/mycompany)
AZURE_DEVOPS_ORG=your-actual-organization

# Your Azure DevOps project name
AZURE_DEVOPS_PROJECT=your-actual-project

# Your Azure DevOps Personal Access Token
AZURE_DEVOPS_TOKEN=your-actual-personal-access-token
```

### 2. Generate Personal Access Token

1. Go to your Azure DevOps organization: `https://dev.azure.com/{your-org}/_usersSettings/tokens`
2. Click "New Token"
3. Set the following scopes:
   - **Work Items**: Read & Write
   - **Code**: Read
   - **Build**: Read
   - **Release**: Read
4. Copy the generated token and add it to your `.env` file

### 3. Test the Server

Run the server to test your configuration:

```bash
# Activate virtual environment
source azure-mcp-venv/bin/activate

# Run the server
python main.py
```

If successful, you should see: `🚀 Azure DevOps MCP Server running...`

## Running the MCP Server

### Option 1: Terminal Interactive Client (Recommended for VPN environments)

If you're behind a VPN or can't connect through VS Code, you can use the interactive MCP client directly from the terminal:

```bash
# Navigate to the project directory
cd /Users/kshitijijari/Desktop/MySpace/MCP/azure-devops-mcp-server

# Activate the virtual environment
source azure-mcp-venv/bin/activate

# Run the interactive MCP client
python mcp_client.py
```

This will start an interactive menu with the following options:

1. **List available tools** - See all Azure DevOps tools available
2. **Get work items** - Run custom WIQL queries
3. **Get repositories** - List Git repositories
4. **Get builds** - View build pipeline information
5. **Get pull requests** - View PRs from repositories
6. **Get commits** - View Git commits
7. **Create work item** - Create new work items
8. **Exit**

### Option 2: Direct MCP Server

Run the MCP server directly (for use with MCP clients):

```bash
# Navigate to the project directory
cd /Users/kshitijijari/Desktop/MySpace/MCP/azure-devops-mcp-server

# Activate the virtual environment
source azure-mcp-venv/bin/activate

# Run the MCP server
python main.py
```

### Option 3: Using the startup script

```bash
# Make the script executable
chmod +x start_mcp_server.sh

# Run the startup script
./start_mcp_server.sh
```

## Adding to MCP Client (VS Code/Cursor)

### Option 1: Using the provided configuration

Copy the `mcp_config.json` file to your MCP client configuration directory and update the environment variables:

```json
{
  "mcpServers": {
    "azure-devops": {
      "command": "python",
      "args": [
        "/Users/kshitijijari/Desktop/MySpace/MCP/azure-devops-mcp-server/main.py"
      ],
      "env": {
        "AZURE_DEVOPS_ORG": "your-actual-organization",
        "AZURE_DEVOPS_PROJECT": "your-actual-project",
        "AZURE_DEVOPS_TOKEN": "your-actual-personal-access-token"
      }
    }
  }
}
```

### Option 2: Manual configuration

Add this to your MCP client configuration:

```json
{
  "mcpServers": {
    "azure-devops": {
      "command": "python",
      "args": ["/absolute/path/to/your/azure-devops-mcp-server/main.py"],
      "env": {
        "AZURE_DEVOPS_ORG": "your-organization",
        "AZURE_DEVOPS_PROJECT": "your-project",
        "AZURE_DEVOPS_TOKEN": "your-personal-access-token"
      }
    }
  }
}
```

### Option 3: Using the startup script

You can also use the provided startup script:

```json
{
  "mcpServers": {
    "azure-devops": {
      "command": "/Users/kshitijijari/Desktop/MySpace/MCP/azure-devops-mcp-server/start_mcp_server.sh",
      "env": {
        "AZURE_DEVOPS_ORG": "your-organization",
        "AZURE_DEVOPS_PROJECT": "your-project",
        "AZURE_DEVOPS_TOKEN": "your-personal-access-token"
      }
    }
  }
}
```

## Usage Examples

### Terminal Interactive Client Examples

When using the interactive MCP client (`python mcp_client.py`), you can:

**Get work items with custom queries:**

- Enter a WIQL query like: `SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.AssignedTo] = 'John Doe'`
- Or use the default query for recent work items

**Get repositories:**

- Optionally filter by repository name
- View all available Git repositories

**Get builds:**

- Filter by build definition ID
- Filter by status (inProgress, completed, all)
- Set custom limits

**Create work items:**

- Choose work item type (Bug, Feature, Task, User Story, Epic)
- Set title, description, assignee, area path, and iteration path

### MCP Client Integration Examples

Once configured, you can use the Azure DevOps tools in your MCP client:

### Get Work Items

```json
{
  "name": "get_workitems",
  "arguments": {
    "query": "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.TeamProject] = @project",
    "limit": 10
  }
}
```

### Get Repositories

```json
{
  "name": "get_repositories",
  "arguments": {}
}
```

### Create Work Item

```json
{
  "name": "create_workitem",
  "arguments": {
    "work_item_type": "Bug",
    "title": "New bug report",
    "description": "Description of the bug",
    "assigned_to": "user@example.com"
  }
}
```

## Troubleshooting

### Common Issues

1. **Authentication Error**: Verify your Personal Access Token is correct and has the required scopes
2. **Organization/Project Not Found**: Check that your organization and project names are spelled correctly
3. **Permission Denied**: Ensure your PAT has the necessary permissions for the operations you're trying to perform

### Debug Mode

To enable debug logging, modify the logging level in `main.py`:

```python
logging.basicConfig(level=logging.DEBUG)
```

## Security Notes

- Never commit your `.env` file or Personal Access Token to version control
- Use environment variables or secure configuration management in production
- Regularly rotate your Personal Access Tokens
- Use the principle of least privilege when setting token scopes

## Support

For issues or questions:

1. Check the Azure DevOps API documentation
2. Verify your token permissions
3. Test your connection using the Azure DevOps REST API directly