DevOps

Frequently asked questions

What does the DevOps MCP server do?

Azure DevOps MCP A dynamic Azure DevOps MCP (Model Context Protocol) server that automatically switches authentication context based on the current working directory. This enables seamless integration with multiple Azure DevOps organizations and projects from a single MCP server. > /> > 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 : Work items, repositories, builds, and more Zero Configuration Switching : Seamless switching between projects with local config files Secure Token Storage : PAT tokens stored locally per repository (excluded from git) Error Handling & Fallback : Robust error handling with graceful degradation to environment variables Local Configuration Each repository should contain a .azure-devops.json configuration file: Configuration File Structure Security Configuration Important : Add .azure-devops.json to your .gitignore file: 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 Installation Claude Code Installation (Recommended) > Note : The -y flag automatically accepts the package installation prompt, ensuring smooth non-interactive execution for MCP servers. Claude Desktop Installation For Claude Desktop users, add this configuration to your MCP settings: Claude Desktop MCP Settings Location: macOS : /Library/Application Support/Claude/claude desktop config.json Windows : %APPDATA%\Claude\claude desktop config.json Available Tools > 📋 For comprehensive command documentation with detailed examples, see MCP-COMMANDS.md Work Items get-work-items : Retrieve work items using WIQL queries or specific IDs with field selection create-work-item : Create new work items with full hierarchy support (Epic → Feature → User Story → Task) update-work-item : Update existing work items including state, assignments, parent relationships, and iteration paths add-work-item-comment : Add comments to existing work items for progress tracking Repositories & Pull Requests get-repositories : List all repositories in the current project context get-pull-requests : Get pull requests with filtering options (status, creator, repository) Builds & Pipelines get-builds : Get build definitions and recent build history with filtering trigger-pipeline : Trigger build pipelines with parameters and branch selection get-pipeline-status : Get detailed build status and timeline information Context Management get-current-context : Get current Azure DevOps context based on directory 🎯 Key Features ✅ Hierarchical Work Items : Full Epic → Feature → User Story → Task hierarchy support ✅ Parent Relationships : Establish parent-child relationships during work item creation ✅ WIQL Queries : Powerful Work Item Query Language support for complex searches ✅ Sprint Management : Iteration path assignment and management ✅ Pipeline Integration : Trigger builds and monitor deployment status ✅ Multi-Project Support : Seamless switching between Azure DevOps organizations Usage Examples Get Current Context Query Work Items Create Work Item Get Repositories Directory Detection Logic The server uses intelligent directory detection: Exact Match : Direct match of configured directory paths Nested Directory Support : Detects parent project directories Longest Match Priority : Most specific directory match takes precedence Parent Directory Search : Searches up the directory tree for matches Fallback Configuration : Uses default configuration when no match found Local Configuration Each repository should contain a .azure-devops.json configuration file: Configuration File Structure Security Configuration Important : Add .azure-devops.json to your .gitignore file: 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 Enhanced Comprehensive Validation Manual Testing Configuration File The generic validation system uses validation-config.json : Enhanced Validation Features The enhanced validation system includes: 🚀 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 Tool Call Received : MCP client sends tool call request Context Detection : Directory detector identifies current project context Configuration Switch : Server switches to appropriate Azure DevOps configuration API Request : Tool handler makes authenticated API request to Azure DevOps 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 Installation Command Issues (Issue 14 Resolution) Problem : Incorrect installation commands that fail to start the server Root Cause : Outdated documentation showing incorrect command syntax Solution : Use the correct installation command: Alternative working commands : Configuration Issues Configuration Not Found : Ensure .azure-devops.json exists in your project directory Authentication Errors : Verify PAT token permissions and expiration in your local configuration Directory Detection : Check that your project has a valid .azure-devops.json file API Errors : Verify Azure DevOps organization and project names in your local configuration Installation Verification Test your installation with these commands: Debug Mode Enable debug logging by setting environment variable: NPM Package Technical Details Package Name : @wangkanai/devops-mcp Binary Name : devops-mcp (auto-generated by NPM) Latest Version : Check with npm view @wangkanai/devops-mcp version Installation Verification : npm list -g @wangkanai/devops-mcp License MIT License - see LICENSE file for details.

How do I install DevOps?

Run the install command shown above, then paste the config for your client (Claude Desktop, Claude Code, Cursor, VS Code or Windsurf) into its MCP settings and restart the client.

Is DevOps free to use?

The MCP server itself is free to install. The source is public on https://github.com/wangkanai/devops-mcp. Any third-party service it calls may require its own API key and account.

Which clients support DevOps?

Any MCP-compatible client can use it, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and custom agents.