DevOps Enhanced MCP

# CLAUDE.md - DevOps MCP for Claude Code Integration Comprehensive context for Claude Code to work effectively with the Azure DevOps MCP server for seamless project management and development workflows. --- ## 📋 **Project Overview** ### **devops-mcp** - Azure DevOps MCP Server for Claude **Technology**: Node.js, TypeScript, MCP Protocol **Purpose**: Dynamic Azure DevOps integration with intelligent directory-based authentication switching **Status**: ✅ **PRODUCTION READY** - Active deployment with >95% test coverage **GitHub**: <https://github.com/wangkanai/devops-mcp> **NPM Package**: [@wangkanai/devops-mcp](https://www.npmjs.com/package/@wangkanai/devops-mcp) **Features**: Local `.azure-devops.json` configuration, secure PAT tokens, comprehensive testing, full Azure DevOps API integration --- ## 🚀 **Quick Start for Claude Users** ### **Immediate Setup (2 minutes)** ```bash # 1. Install via Claude Code (Recommended) claude mcp add devops-mcp -- -y @wangkanai/devops-mcp # 2. Create configuration in your project directory cat > .azure-devops.json << EOF { "organizationUrl": "https://dev.azure.com/your-org", "project": "YourProject", "pat": "your-pat-token-here", "description": "Azure DevOps configuration for this repository" } EOF # 3. Secure your configuration echo ".azure-devops.json" >> .gitignore # 4. Verify installation mcp__devops-mcp__get-current-context ``` ### **Claude Desktop Users** Add to your MCP settings file: ```json { "mcpServers": { "devops-mcp": { "command": "npx", "args": ["-y", "@wangkanai/devops-mcp"] } } } ``` **Settings Location**: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` --- ## 🎯 **Core Capabilities for Claude** ### **Smart Context Switching** Claude automatically detects project context based on your current directory: - **RiverSync projects**: Auto-switches to `https://dev.azure.com/riversync` - **Mula projects**: Auto-switches to `https://dev.azure.com/mula-x` - **Any project**: Uses local `.azure-devops.json` configuration ### **Complete Azure DevOps Integration** - ✅ **Work Item Management**: Create, update, query work items with full hierarchy support - ✅ **Repository Operations**: Access repositories, pull requests, branch information - ✅ **Build & Pipeline**: Trigger pipelines, monitor builds, check deployment status - ✅ **Project Context**: Get current configuration, validate authentication --- ## 🛠️ **Available MCP Commands** ### **Work Item Commands** | Command | Purpose | Key Parameters | |---------|---------|----------------| | `mcp__devops-mcp__get-work-items` | Query work items | `--wiql`, `--ids`, `--fields` | | `mcp__devops-mcp__create-work-item` | Create new work items | `--type`, `--title`, `--parent`, `--assignedTo` | | `mcp__devops-mcp__update-work-item` | Update existing items | `--id`, `--state`, `--assignedTo`, `--parent` | | `mcp__devops-mcp__add-work-item-comment` | Add comments | `--id`, `--comment` | ### **Repository Commands** | Command | Purpose | Key Parameters | |---------|---------|----------------| | `mcp__devops-mcp__get-repositories` | List repositories | `--includeLinks` | | `mcp__devops-mcp__get-pull-requests` | Get PR information | `--status`, `--repositoryId`, `--createdBy` | ### **Build & Pipeline Commands** | Command | Purpose | Key Parameters | |---------|---------|----------------| | `mcp__devops-mcp__get-builds` | Get build history | `--definitionIds`, `--top` | | `mcp__devops-mcp__trigger-pipeline` | Start builds | `--definitionId`, `--definitionName`, `--sourceBranch` | | `mcp__devops-mcp__get-pipeline-status` | Check build status | `--buildId`, `--definitionId`, `--includeTimeline` | ### **Context Commands** | Command | Purpose | Key Parameters | |---------|---------|----------------| | `mcp__devops-mcp__get-current-context` | Show configuration | `--directory` | --- ## 💡 **Claude-Optimized Workflows** ### **🆕 Feature Development Workflow** ```bash # Create complete feature hierarchy # 1. Epic for major initiative mcp__devops-mcp__create-work-item \ --type "Epic" \ --title "User Authentication System" \ --description "Implement comprehensive user authentication and authorization" # 2. Feature under Epic (assuming Epic ID = 1100) mcp__devops-mcp__create-work-item \ --type "Feature" \ --title "OAuth 2.0 Integration" \ --parent 1100 \ --iterationPath "MyProject\\Sprint 1" # 3. User Stories under Feature (assuming Feature ID = 1101) mcp__devops-mcp__create-work-item \ --type "User Story" \ --title "As a user, I want to login with Google OAuth" \ --parent 1101 \ --assignedTo "frontend@company.com" # 4. Implementation Tasks (assuming User Story ID = 1102) mcp__devops-mcp__create-work-item \ --type "Task" \ --title "Design OAuth login UI components" \ --parent 1102 \ --assignedTo "frontend@company.com" mcp__devops-mcp__create-work-item \ --type "Task" \ --title "Implement OAuth backend service" \ --parent 1102 \ --assignedTo "backend@company.com" ``` ### **🐛 Bug Triage and Resolution** ```bash # Create bug report with comprehensive details mcp__devops-mcp__create-work-item \ --type "Bug" \ --title "Login page crashes on Safari iOS" \ --description "Steps: 1. Open Safari on iOS, 2. Navigate to /login, 3. Enter credentials, 4. Page becomes unresponsive" \ --tags "browser-compatibility;ios;critical" \ --assignedTo "qa@company.com" # Add investigation findings mcp__devops-mcp__add-work-item-comment \ --id 1234 \ --comment "Reproduced on Safari 16.5+ on iOS. Issue appears related to form validation polyfill. Testing alternative approaches." # Assign to developer and activate mcp__devops-mcp__update-work-item \ --id 1234 \ --assignedTo "developer@company.com" \ --state "Active" \ --iterationPath "MyProject\\Current Sprint" ``` ### **📈 Sprint Management** ```bash # Get all work items in current sprint mcp__devops-mcp__get-work-items \ --wiql "SELECT [System.Id], [System.Title], [System.State], [System.AssignedTo] FROM WorkItems WHERE [System.IterationPath] UNDER 'MyProject\\Current Sprint'" # Move incomplete items to next sprint mcp__devops-mcp__update-work-item \ --id 1234 \ --iterationPath "MyProject\\Sprint 2" # Close completed items mcp__devops-mcp__update-work-item --id 1235 --state "Closed" mcp__devops-mcp__add-work-item-comment \ --id 1235 \ --comment "Feature complete and deployed to production. All acceptance criteria met." ``` ### **🚀 CI/CD Integration** ```bash # Trigger deployment pipeline mcp__devops-mcp__trigger-pipeline \ --definitionName "Production Deployment" \ --sourceBranch "main" \ --parameters '{"environment": "production", "runTests": true, "requireApproval": true}' # Monitor deployment progress mcp__devops-mcp__get-pipeline-status \ --buildId 5678 \ --includeTimeline true # Update work items post-deployment mcp__devops-mcp__add-work-item-comment \ --id 1234 \ --comment "Deployed to production in build #5678. Feature available to all users." ``` --- ## 🔍 **Advanced Query Patterns** ### **WIQL Query Examples for Claude** ```bash # Get my assigned active work items mcp__devops-mcp__get-work-items \ --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.AssignedTo] = @me AND [System.State] = 'Active'" # Find high-priority bugs mcp__devops-mcp__get-work-items \ --wiql "SELECT [System.Id], [System.Title], [Microsoft.VSTS.Common.Priority] FROM WorkItems WHERE [System.WorkItemType] = 'Bug' AND [Microsoft.VSTS.Common.Priority] <= 2" # Get work items by parent hierarchy mcp__devops-mcp__get-work-items \ --wiql "SELECT [System.Id], [System.Title], [System.Parent] FROM WorkItems WHERE [System.Parent] = 1100" # Find recently modified work items mcp__devops-mcp__get-work-items \ --wiql "SELECT [System.Id], [System.Title], [System.ChangedDate] FROM WorkItems WHERE [System.ChangedDate] >= @today-7" # Get work items by tags mcp__devops-mcp__get-work-items \ --wiql "SELECT [System.Id], [System.Title], [System.Tags] FROM WorkItems WHERE [System.Tags] CONTAINS 'authentication'" ``` ### **Repository and PR Analysis** ```bash # Get all active pull requests with details mcp__devops-mcp__get-pull-requests --status "active" # Find PRs by specific developer mcp__devops-mcp__get-pull-requests --createdBy "developer@company.com" # Get repository information for project planning mcp__devops-mcp__get-repositories --includeLinks true ``` --- ## 🏗️ **Architecture for Claude Integration** ### **Directory-Based Authentication** The MCP server automatically detects and switches Azure DevOps contexts based on your current directory: ``` ~/Projects/ ├── riversync/ # Auto-uses riversync organization │ ├── .azure-devops.json # https://dev.azure.com/riversync │ └── src/ ├── mula/ # Auto-uses mula-x organization │ ├── .azure-devops.json # https://dev.azure.com/mula-x │ └── src/ └── client-project/ # Uses client-specific configuration ├── .azure-devops.json # https://dev.azure.com/client-org └── src/ ``` ### **Configuration Template** ```json { "organizationUrl": "https://dev.azure.com/your-organization", "project": "YourProjectName", "pat": "your-personal-access-token-here", "description": "Azure DevOps configuration for [Project Name]" } ``` ### **Required PAT Permissions** ``` ✅ Work Items: Read & Write ✅ Code: Read ✅ Build: Read & Execute ✅ Project and Team: Read ❌ Full Access (not required) ``` --- ## 🔧 **Core Implementation Details** ### **Recently Resolved Issues** All major issues have been resolved in the current version: #### **GitHub Issue #53** - Microsoft.VSTS Field Resolution ✅ **FIXED** - **Problem**: Work item creation failing with Microsoft.VSTS field mapping - **Solution**: Implemented proper field name resolution system - **Commit**: [`48ed08c595ab5f7360650a225f4c683ebd294d63`](https://github.com/wangkanai/devops-mcp/commit/48ed08c595ab5f7360650a225f4c683ebd294d63) #### **GitHub Issue #8** - Work Item Creation 404 Error ✅ **FIXED** - **Problem**: Incorrect endpoint format causing 404 errors - **Solution**: Fixed endpoint URL format, HTTP method, and Content-Type headers - **Impact**: Work item creation now functions correctly across all Azure DevOps configurations ### **Azure DevOps API Best Practices** ```typescript // Correct work item creation format const endpoint = `${baseUrl}/_apis/wit/workitems/$${workItemType}?api-version=7.1`; const method = 'PATCH'; const headers = { 'Content-Type': 'application/json-patch+json', 'Authorization': `Basic ${Buffer.from(`:${pat}`).toString('base64')}` }; ``` --- ## 📊 **Quality Metrics & Validation** ### **Production-Ready Status** - ✅ **Test Coverage**: >95% (Jest framework) - ✅ **Code Quality**: ESLint + Prettier enforcement - ✅ **Type Safety**: Full TypeScript coverage - ✅ **Security**: Secure PAT token handling, credential isolation - ✅ **Performance**: <200ms response time for typical operations - ✅ **Reliability**: <1% error rate for well-formed requests ### **Comprehensive Testing** - **Unit Tests**: 15 tests covering core functionality - **Integration Tests**: 25 tests for Azure DevOps API integration - **End-to-End Tests**: 10 tests for complete workflow validation - **Security Tests**: 11 tests for credential protection and isolation --- ## 🚀 **Advanced Usage Patterns** ### **Batch Operations** ```bash # Create multiple related work items efficiently # Use parent IDs from previous commands to build hierarchy # Update multiple work items for sprint planning for id in 1234 1235 1236; do mcp__devops-mcp__update-work-item \ --id $id \ --iterationPath "MyProject\\Sprint 2" done ``` ### **Pipeline Integration** ```bash # Automated deployment workflow build_id=$(mcp__devops-mcp__trigger-pipeline \ --definitionName "Staging Deploy" \ --sourceBranch "develop") # Wait and check status sleep 30 mcp__devops-mcp__get-pipeline-status \ --buildId $build_id \ --includeTimeline true # Update related work items on successful deployment mcp__devops-mcp__update-work-item \ --id 1234 \ --state "Resolved" ``` ### **Cross-Project Coordination** ```bash # Switch between project contexts seamlessly cd /path/to/riversync/project mcp__devops-mcp__get-current-context # Shows RiverSync configuration cd /path/to/mula/project mcp__devops-mcp__get-current-context # Shows Mula configuration cd /path/to/client/project mcp__devops-mcp__get-current-context # Shows client configuration ``` --- ## 🔍 **Troubleshooting for Claude** ### **Common Issues & Solutions** #### ❌ "No Azure DevOps configuration found" ```bash # Check current context mcp__devops-mcp__get-current-context # Verify configuration file exists ls -la .azure-devops.json # Validate JSON format cat .azure-devops.json | jq . ``` #### ❌ "Authentication failed" ```bash # Verify PAT token permissions and expiration # Check organization URL format: https://dev.azure.com/orgname # Ensure project name matches exactly ``` #### ❌ "Work item type not found" ```bash # Use process-specific work item types: # Agile: Epic, Feature, User Story, Task, Bug # Scrum: Epic, Feature, Product Backlog Item, Task, Bug # CMMI: Epic, Feature, Requirement, Task, Bug ``` ### **Debug Commands** ```bash # Test basic connectivity mcp__devops-mcp__get-work-items --wiql "SELECT TOP 1 [System.Id] FROM WorkItems" # Verify repository access mcp__devops-mcp__get-repositories # Check current configuration details mcp__devops-mcp__get-current-context ``` --- ## 📚 **Additional Resources for Claude Users** ### **Quick Reference** - **Command Reference**: See `MCP-COMMANDS.md` for complete parameter documentation - **Workflow Examples**: See `CLAUDE-MCP-USAGE.md` for practical usage patterns - **Issue Resolution**: See `RESOLVED.md` for historical issue fixes ### **External Documentation** - **Azure DevOps REST API**: [Microsoft Documentation](https://docs.microsoft.com/en-us/rest/api/azure/devops/) - **WIQL Query Language**: [Query Syntax Reference](https://docs.microsoft.com/en-us/azure/devops/boards/queries/wiql-syntax) - **Work Item Types**: [Process Template Guide](https://docs.microsoft.com/en-us/azure/devops/boards/work-items/guidance/choose-process) - **PAT Token Security**: [Authentication Guide](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) --- ## 🎯 **Success Patterns for Claude** ### **Efficient Work Item Management** 1. **Start with Epics** for major initiatives 2. **Break down into Features** for deliverable functionality 3. **Create User Stories** that provide user value 4. **Add Tasks** for implementation work 5. **Use descriptive titles** and comprehensive descriptions 6. **Tag appropriately** for filtering and organization ### **Optimal Query Strategies** 1. **Use specific WIQL queries** for targeted results 2. **Filter by iteration paths** for sprint-focused views 3. **Query by assignment** for personal task management 4. **Search by tags** for cross-cutting concerns 5. **Include parent relationships** for hierarchy understanding ### **Pipeline Integration Best Practices** 1. **Monitor build status** before marking work items complete 2. **Update work items** post-deployment with build numbers 3. **Use parameterized triggers** for environment-specific deployments 4. **Include timeline data** for detailed troubleshooting --- **Documentation Version**: 2.0 **Created**: 2025-07-27 **Last Updated**: 2025-07-27 **Project Status**: Production Ready (Active Deployment) **Primary Technologies**: Node.js, TypeScript, MCP Protocol, Azure DevOps REST API v7.1+ **Test Coverage**: >95% **GitHub**: <https://github.com/wangkanai/devops-mcp> **NPM**: [@wangkanai/devops-mcp](https://www.npmjs.com/package/@wangkanai/devops-mcp)