ADO Development Assistant MCP

An intelligent MCP server that automates the complete Azure DevOps work item processing workflow, from issue analysis to pull request creation with proper linking and traceability.

🚀 Overview

The ADO Development Assistant MCP provides comprehensive workflow automation for Azure DevOps work item processing. It orchestrates multiple specialized MCP servers to create an end-to-end solution that eliminates manual overhead and ensures consistent development practices.

Key Capabilities

1. 🔍 Intelligent Work Item Analysis: Fetch and parse Azure DevOps work items with context understanding
2. 📊 Advanced Code Analysis: Use Repomix to analyze codebase structure and locate issue-related code
3. 🌿 Smart Branch Management: Automatically create feature branches from latest release branches
4. ⚡ Automated Implementation: Generate and apply code changes based on comprehensive analysis
5. 🔗 Seamless PR Creation: Create pull requests with proper work item linking and formatted descriptions
6. 🎯 Interactive Workflow: User confirmation points ensure quality and control over the automation

8-Step Automated Workflow

1. Parse Work Item - Accept ADO URL or ID and fetch complete work item details
2. Analyze Codebase - Use Repomix to understand the issue in code context
3. Present Understanding - Show analysis and wait for user confirmation
4. Create Feature Branch - Generate feature/workitem-description branch from latest release/*
5. Implement Changes - Apply code modifications based on analysis
6. Update Resolution - Mark work item with implementation details
7. Create Pull Request - Generate PR with proper ADO linking and formatted description
8. Return Results - Provide PR URL and comprehensive workflow summary

🏗️ Architecture

Core Components

• 🔧 ADO Client - Azure DevOps API integration with work item operations
• 🧠 Repomix Integration - Advanced code analysis and pattern recognition
• 📝 Git Operations - Repository management and branch orchestration
• 🎼 Workflow Orchestrator - Main coordination engine with user interaction
• 🔗 PR Manager - Pull request creation with intelligent linking

MCP Server Integration

This server acts as an orchestration layer, delegating to specialized MCP servers:

• @azure-devops/mcp (advantive-devops) - All Azure DevOps operations
• repomix-mcp - Codebase analysis and understanding
• @cyanheads/git-mcp-server - Git repository operations

🛠️ Available MCP Tools

Primary Workflow Tools

process_ado_workflow

Main orchestrator tool - Executes the complete 8-step workflow

{
  work_item_input: string,        // Work item ID or full ADO URL
  repository_path: string,        // Path to git repository
  auto_confirm?: boolean,         // Skip user confirmations (default: false)
  source_branch_pattern?: string, // Pattern for source branch (default: "release/*")
  config?: WorkflowConfig        // Optional configuration overrides
}

process_interactive_ado_workflow

Interactive workflow - Same as above but with explicit user confirmation points

{
  work_item_input: string,
  repository_path: string,
  source_branch_pattern?: string,
  config?: WorkflowConfig
}

continue_interactive_workflow

Continue paused workflow - Resume after user confirmation

{
  workflow_state: object,        // State from previous interactive step
  user_confirmation: boolean,    // User approval (true/false)
  user_feedback?: string,        // Optional user feedback
  repository_path: string
}

Work Item Management Tools

get_work_item

Fetch work item details - Supports both ID and URL input

{
  work_item_input: string,       // "876378" or full ADO URL
  organization?: string,         // Optional org override
  project?: string              // Optional project override
}

analyze_work_item_codebase

Analyze codebase for work item - Uses Repomix for intelligent analysis

{
  work_item_details: object,     // From get_work_item response
  repository_path: string,
  focus_patterns?: string[]      // Optional file patterns to focus on
}

create_feature_branch

Create feature branch - Smart branch naming and source detection

{
  work_item_id: string,
  repository_path: string,
  source_branch: string,
  description?: string           // Optional for branch naming
}

Utility Tools

check_mcp_dependencies

Verify MCP server dependencies - Ensures required servers are available

{
  install_missing?: boolean      // Auto-install if true (default: false)
}

install_mcp_dependencies

Install missing MCP servers - Automated dependency installation

{
  dependencies?: string[]        // Specific deps to install (optional)
}

⚙️ Configuration

Configuration File Structure

Create ado-mcp-config.json in your project root:

{
  "azureDevOps": {
    "organization": "your-org",
    "project": "your-project",
    "resolutionFieldId": "37428292",
    "autoUpdateDescription": true,
    "personalAccessToken": "${ADO_PAT}"
  },
  "git": {
    "sourceBranchPattern": "release/*",
    "branchPrefix": "feature/"
  },
  "workflow": {
    "autoConfirm": false,
    "skipUserInteractions": false
  },
  "repomix": {
    "analysisPatterns": [
      "**/*.js", "**/*.ts", "**/*.py", 
      "**/*.cs", "**/*.java"
    ],
    "excludePatterns": [
      "node_modules/**", "dist/**", 
      "*.test.*", "**/*.spec.*"
    ]
  },
  "env": {
    "ADO_PAT": "your-personal-access-token"
  }
}

Environment Variables

All configuration can be overridden with environment variables:

# Azure DevOps Configuration
export ADO_ORGANIZATION="your-org"
export ADO_PROJECT="your-project"
export ADO_PAT="your-personal-access-token"
export ADO_RESOLUTION_FIELD_ID="37428292"

# Git Configuration
export GIT_SOURCE_BRANCH_PATTERN="release/*"
export GIT_BRANCH_PREFIX="feature/"

# Workflow Configuration
export WORKFLOW_AUTO_CONFIRM="false"

# Config File Location
export ADO_MCP_CONFIG_PATH="/path/to/your/config.json"

Configuration Options Reference

Azure DevOps Settings

• organization - ADO organization name (required)
• project - ADO project name (required)
• resolutionFieldId - Custom field ID for resolution tracking
• autoUpdateDescription - Auto-update work item descriptions
• personalAccessToken - ADO PAT for authentication

Git Settings

• sourceBranchPattern - Pattern to find source branches (default: "release/*")
• branchPrefix - Prefix for created branches (default: "feature/")

Workflow Settings

• autoConfirm - Skip user confirmations (default: false)
• skipUserInteractions - Fully automated mode (default: false)

Repomix Settings

• analysisPatterns - File patterns to include in analysis
• excludePatterns - File patterns to exclude from analysis

📚 Usage Examples

Basic Work Item Processing

# Process a work item by ID
process_ado_workflow({
  "work_item_input": "876378",
  "repository_path": "/path/to/your/repo"
})

# Process using full ADO URL
process_ado_workflow({
  "work_item_input": "https://dev.azure.com/your-org/your-project/_workitems/edit/876378",
  "repository_path": "/path/to/your/repo"
})

Interactive Workflow with User Confirmations

# Start interactive workflow
process_interactive_ado_workflow({
  "work_item_input": "876378",
  "repository_path": "/path/to/your/repo",
  "source_branch_pattern": "release/*"
})

# Continue after user confirmation
continue_interactive_workflow({
  "workflow_state": { /* state from previous step */ },
  "user_confirmation": true,
  "user_feedback": "Looks good, proceed with implementation",
  "repository_path": "/path/to/your/repo"
})

Advanced Configuration Override

process_ado_workflow({
  "work_item_input": "876378",
  "repository_path": "/path/to/your/repo",
  "auto_confirm": false,
  "config": {
    "azureDevOps": {
      "organization": "custom-org",
      "project": "custom-project"
    },
    "git": {
      "sourceBranchPattern": "main",
      "branchPrefix": "bugfix/"
    },
    "workflow": {
      "autoConfirm": false
    }
  }
})

Individual Tool Usage

Analyze Work Item and Codebase

# First, get work item details
get_work_item({
  "work_item_input": "876378"
})

# Then analyze codebase for the work item
analyze_work_item_codebase({
  "work_item_details": { /* response from get_work_item */ },
  "repository_path": "/path/to/your/repo",
  "focus_patterns": ["**/*.js", "**/*.ts", "**/auth/**"]
})

Create Feature Branch

create_feature_branch({
  "work_item_id": "876378",
  "repository_path": "/path/to/your/repo",
  "source_branch": "release/v2.1.0",
  "description": "fix-login-validation"
})

Check Dependencies

# Check if required MCP servers are available
check_mcp_dependencies({
  "install_missing": false
})

# Auto-install missing dependencies
install_mcp_dependencies({
  "dependencies": ["@azure-devops/mcp", "repomix-mcp", "@cyanheads/git-mcp-server"]
})

Expected Response Format

All tools return structured responses with consistent format:

{
  "success": true,
  "data": {
    "pull_request_url": "https://dev.azure.com/org/project/_git/repo/pullrequest/123",
    "feature_branch": "feature/876378-fix-login-validation",
    "work_item_id": "876378",
    "changes_summary": "Updated authentication validation logic",
    "files_modified": ["src/auth/login.js", "src/validators/user.js"]
  },
  "workflow_state": {
    "current_step": 8,
    "completed_steps": [1, 2, 3, 4, 5, 6, 7, 8],
    "interaction_type": "completed"
  },
  "metadata": {
    "execution_time": "45.2s",
    "analysis_files_count": 156,
    "commits_created": 1
  }
}

🚀 Installation & Setup

Prerequisites

• Node.js >= 18.0.0
• Git repository access
• Azure DevOps Personal Access Token
• MCP client environment (Claude Desktop, etc.)

Step 1: Install the MCP Server

# Install from npm (when published)
npm install -g ado-dev-assistant-mcp

# Or build from source
git clone <repository-url>
cd ADO-dev-assistant
npm install
npm run build

Step 2: Install Required MCP Dependencies

# Install required MCP servers
npm install -g @azure-devops/mcp
npm install -g repomix-mcp  
npm install -g @cyanheads/git-mcp-server

Step 3: Configure MCP Client

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "ado-dev-assistant": {
      "command": "node",
      "args": ["/path/to/ado-dev-assistant-mcp/dist/index.js"]
    },
    "azure-devops": {
      "command": "npx",
      "args": ["@azure-devops/mcp"]
    },
    "repomix": {
      "command": "npx", 
      "args": ["repomix-mcp"]
    },
    "git": {
      "command": "npx",
      "args": ["@cyanheads/git-mcp-server"]
    }
  }
}

Step 4: Set Up Authentication

# Set Azure DevOps Personal Access Token
export ADO_PAT="your-personal-access-token"

# Or create config file
echo '{
  "azureDevOps": {
    "organization": "your-org",
    "project": "your-project", 
    "personalAccessToken": "your-pat"
  }
}' > ado-mcp-config.json

Step 5: Verify Installation

# Check dependencies
check_mcp_dependencies()

# Test with a simple work item
process_ado_workflow({
  "work_item_input": "your-work-item-id",
  "repository_path": "/path/to/your/repo"
})

🔧 Troubleshooting

Common Issues

"MCP server not found" errors

• Ensure all required MCP servers are installed globally
• Verify MCP client configuration includes all servers
• Check that server commands are accessible in PATH

"Authentication failed" errors

• Verify ADO_PAT environment variable is set
• Ensure PAT has required permissions (Work Items: Read & Write, Code: Read & Write)
• Check organization and project names in configuration

"Repository not found" errors

• Verify repository path is correct and accessible
• Ensure Git is initialized in the repository
• Check that current user has repository access

"Branch creation failed" errors

• Ensure repository is clean (no uncommitted changes)
• Verify source branch pattern matches existing branches
• Check Git user configuration is set up

Debug Mode

Enable detailed logging:

export DEBUG="ado-dev-assistant:*"
export ADO_MCP_DEBUG="true"

Getting Help

1. Check the troubleshooting guide
2. Review test examples for working configurations
3. Enable debug logging for detailed error information
4. Verify all MCP dependencies are properly installed

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes following the progressive refactoring principles
4. Add tests for new functionality
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• @azure-devops/mcp - Azure DevOps MCP server
• repomix - Repository analysis tool
• @cyanheads/git-mcp-server - Git operations MCP server