Devops Enhanced MCP

🚀 DevOps Enhanced MCP

A dynamic Azure DevOps MCP (Model Context Protocol) server that automatically switches authentication context based on the current working directory, enabling seamless integration with multiple Azure DevOps organizations and projects from a single MCP server.

🚀 Quick Start

To quickly get started with the DevOps Enhanced MCP, follow these steps:

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

✨ Features

• Local Configuration Files: Each repository contains .azure-devops.json configuration.
• Dynamic Environment Switching: Automatically detects project context based on directory location.
• Multiple Project Support: Supports unlimited projects with separate authentication.
• Comprehensive Azure DevOps Integration: Covers work items, repositories, builds, and more.
• Zero Configuration Switching: Allows seamless switching between projects using local config files.
• Secure Token Storage: PAT tokens are stored locally per repository (excluded from git).
• Error Handling & Fallback: Robust error handling with graceful degradation to environment variables.

📦 Installation

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

💻 Usage Examples

Basic Usage

Get Current Context

{
  "name": "get-current-context",
  "arguments": {
    "directory": "/Users/wangkanai/Sources/riversync"
  }
}

Query Work Items

{
  "name": "get-work-items",
  "arguments": {
    "wiql": "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.State] = 'Active'"
  }
}

Advanced Usage

Create Work Item

{
  "name": "create-work-item",
  "arguments": {
    "type": "Task",
    "title": "Implement new feature",
    "description": "Add authentication system",
    "assignedTo": "user@example.com"
  }
}

Get Repositories

{
  "name": "get-repositories",
  "arguments": {
    "includeLinks": true
  }
}

📚 Documentation

Local Configuration

Each repository should contain a .azure-devops.json configuration file:

Configuration File Structure

{
  "organizationUrl": "https://dev.azure.com/your-org",
  "project": "YourProject",
  "pat": "your-pat-token-here",
  "description": "Azure DevOps configuration for this repository",
  "settings": {
    "timeout": 30000,
    "retries": 3,
    "apiVersion": "7.1"
  },
  "tools": {
    "workItems": true,
    "repositories": true,
    "builds": true,
    "pullRequests": true,
    "pipelines": true
  },
  "meta": {
    "configVersion": "1.0",
    "lastUpdated": "2025-07-21",
    "createdBy": "devops-enhanced-mcp"
  }
}

Security Configuration

⚠️ Important Note

Add .azure-devops.json to your .gitignore file to ensure security:

# Azure DevOps MCP local configuration (contains PAT tokens)
.azure-devops.json

Example Projects

• RiverSync Project:
  • Directory: /Users/wangkanai/Sources/riversync
  • Configuration: .azure-devops.json with RiverSync organization settings
• Mula Project:
  • Directory: /Users/wangkanai/Sources/mula
  • Configuration: .azure-devops.json with Mula organization settings

Authentication

The server uses Personal Access Tokens (PAT) for Azure DevOps authentication. PAT tokens are configured per project in local .azure-devops.json configuration files within each repository.

PAT Token Requirements

PAT tokens should have the following scopes:

• Work Items: Read & Write
• Code: Read
• Build: Read
• Project and Team: Read

Error Handling

The server includes comprehensive error handling:

• Configuration Errors: Graceful fallback when configuration is missing.
• Authentication Errors: Clear error messages for authentication failures.
• API Errors: Detailed error reporting for Azure DevOps API issues.
• Network Errors: Retry logic and timeout handling.

Testing & Validation

Enhanced Validation System (Recommended)

The enhanced validation system includes MCP server startup, connection verification, and readiness checks:

• MCP Server Warmup:

# Prepare MCP servers for validation
./warmup-mcp.sh

# Use custom configuration file
./warmup-mcp.sh custom-config.json

• Enhanced Comprehensive Validation:

# Full validation with MCP server initialization
./validate-enhanced.sh

# Skip interactive Claude tests (faster)
./validate-enhanced.sh --skip-interactive

# Extended warmup for slow systems
./validate-enhanced.sh --warmup 20

# Test only specific repositories
./validate-enhanced.sh --repos "RiverSync,Mula"

# Use custom configuration file
./validate-enhanced.sh --config custom-config.json

# Show all options
./validate-enhanced.sh --help

• Manual Testing:

# Build and test the server manually
npm run build
node test-server.js

Configuration File

The generic validation system uses validation-config.json:

{
  "proxyPath": "/Users/wangkanai/Sources/devops-enhanced-mcp",
  "repositories": [
    {
      "name": "RiverSync",
      "path": "/Users/wangkanai/Sources/riversync",
      "expectedOrganization": "riversync",
      "organizationUrl": "https://dev.azure.com/riversync",
      "project": "RiverSync",
      "enabled": true
    }
  ],
  "testSettings": {
    "timeoutSeconds": 30,
    "skipInteractive": false,
    "mcpServerName": "devops-enhanced-mcp",
    "configFileName": ".azure-devops.json"
  },
  "expectedTools": ["workItems", "repositories", "builds", "pullRequests", "pipelines"]
}

Enhanced Validation Features

• 🚀 MCP Server Management:
  • Startup Verification: Ensures MCP servers are properly configured.
  • Connection Testing: Verifies server connectivity with retry logic.
  • Readiness Checks: Confirms servers respond to basic commands.
  • Warmup Period: Configurable delay for server initialization (default: 10s).
• 🔍 Comprehensive Testing Coverage:
  • ✅ Prerequisites: PowerShell, Claude Code, directory structure, proxy build.
  • ✅ MCP Initialization: Server startup, connectivity, and readiness verification.
  • ✅ Local Configuration: .azure-devops.json file validation with expected values.
  • ✅ Server Configuration: Local scope verification without environment variables.
  • ✅ Claude Integration: MCP command execution and context detection.
  • ✅ Dynamic Switching: Environment switching between multiple repositories.
  • ✅ Error Handling: Comprehensive error detection and reporting with retry logic.

Expected Results

• Full Validation Results:
  • Pass Rate: >90% for successful implementation.
  • All MCP commands functional in both repositories.
  • Automatic context switching based on directory location.

Legacy Environment Configuration (Deprecated)

The server previously supported a global config/environments.json file for environment mapping. This approach has been deprecated in favor of local .azure-devops.json configuration files for better security and project isolation.

If you need to migrate from the old environment-based configuration, convert your settings to local configuration files in each repository.

Architecture

Core Components

• AzureDevOpsMCPProxy: Main server class with MCP protocol handling.
• DirectoryDetector: Smart directory detection and configuration mapping.
• ToolHandlers: Azure DevOps API integration and tool implementations.
• ConfigLoader: Configuration file loading and validation.

Request Flow

1. Tool Call Received: MCP client sends tool call request.
2. Context Detection: Directory detector identifies current project context.
3. Configuration Switch: Server switches to appropriate Azure DevOps configuration.
4. API Request: Tool handler makes authenticated API request to Azure DevOps.
5. Response Processing: Response is formatted and returned to MCP client.

Integration with Claude Code

This MCP server is designed to work seamlessly with Claude Code for Azure DevOps operations:

• Automatic Context Switching: When working in RiverSync or Mula project directories.
• Transparent Authentication: No manual configuration required.
• Rich Tool Set: Comprehensive Azure DevOps functionality.
• Error Recovery: Graceful handling of authentication and network issues.

Security Considerations

• PAT tokens are stored in configuration files (ensure proper file permissions).
• HTTPS is used for all Azure DevOps API communications.
• Authentication is handled per-request with proper token encoding.
• No token caching or persistence beyond configuration file.

Troubleshooting

Common Issues

1. Configuration Not Found: Ensure .azure-devops.json exists in your project directory.
2. Authentication Errors: Verify PAT token permissions and expiration in your local configuration.
3. Directory Detection: Check that your project has a valid .azure-devops.json file.
4. API Errors: Verify Azure DevOps organization and project names in your local configuration.

Debug Mode

Enable debug logging by setting environment variable:

export DEBUG=devops-enhanced-mcp
npm start

🔧 Technical Details

Directory Detection Logic

The server uses intelligent directory detection:

1. Exact Match: Direct match of configured directory paths.
2. Nested Directory Support: Detects parent project directories.
3. Longest Match Priority: Most specific directory match takes precedence.
4. Parent Directory Search: Searches up the directory tree for matches.
5. Fallback Configuration: Uses default configuration when no match found.

📄 License

This project is under the MIT License - see the LICENSE file for details.