npm package: @pepperi-addons/ado-dev-assistant-mcp
Description: MCP server for Azure DevOps work item processing workflow automation
Author: Advantive DevOps
Latest version: 1.0.3

# ADO Development Assistant MCP

[![Version](https://img.shields.io/badge/version-1.0.2-blue.svg)](package.json)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](package.json)

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
```typescript
{
  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
```typescript
{
  work_item_input: string,
  repository_path: string,
  source_branch_pattern?: string,
  config?: WorkflowConfig
}
```

#### `continue_interactive_workflow`
**Continue paused workflow** - Resume after user confirmation
```typescript
{
  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
```typescript
{
  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
```typescript
{
  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
```typescript
{
  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
```typescript
{
  install_missing?: boolean      // Auto-install if true (default: false)
}
```

#### `install_mcp_dependencies`
**Install missing MCP servers** - Automated dependency installation
```typescript
{
  dependencies?: string[]        // Specific deps to install (optional)
}
```

## ⚙️ Configuration

### Configuration File Structure

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

```json
{
  "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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
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

```bash
# 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:

```json
{
  "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

```bash
# 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

```bash
# 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):

```json
{
  "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

```bash
# 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

```bash
# 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:

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

### Getting Help

1. Check the [troubleshooting guide](TROUBLESHOOTING.md)
2. Review [test examples](test/) 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](LICENSE) file for details.

## 🔗 Related Projects

- [@azure-devops/mcp](https://github.com/advantive-devops/azure-devops-mcp) - Azure DevOps MCP server
- [repomix](https://github.com/yamadashy/repomix) - Repository analysis tool
- [@cyanheads/git-mcp-server](https://github.com/cyanheads/git-mcp-server) - Git operations MCP server