@pepperi-addons/ado-dev-assistant-mcp

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

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

8-Step Automated Workflow

• Parse Work Item - Accept ADO URL or ID and fetch complete work item details
• Analyze Codebase - Use Repomix to understand the issue in code context
• Present Understanding - Show analysis and wait for user confirmation
• Create Feature Branch - Generate feature/workitem-description branch from latest release/*
• Implement Changes - Apply code modifications based on analysis
• Update Resolution - Mark work item with implementation details
• Create Pull Request - Generate PR with proper ADO linking and formatted description
• 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

• Check the troubleshooting guide
• Review test examples for working configurations
• Enable debug logging for detailed error information
• Verify all MCP dependencies are properly installed

🤝 Contributing

• Fork the repository
• Create a feature branch
• Make your changes following the progressive refactoring principles
• Add tests for new functionality
• 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