Skip to content

CLAUDE.md

Latest commit

 

History

History
205 lines (159 loc) · 8.87 KB

CLAUDE.md

File metadata and controls

205 lines (159 loc) · 8.87 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an Azure DevOps MCP (Model Context Protocol) server built with .NET 9. It provides comprehensive integration with Azure DevOps through the MCP protocol, enabling tools like Claude Desktop and VS Code to interact with Azure DevOps resources with production-grade reliability and performance.

Architecture

The application follows a modern clean architecture with production-ready features:

MCP Tools Layer (src/AzureDevOps.MCP/Tools/)

  • AzureDevOpsTools.cs - Core read operations (projects, repositories, files, work items)
  • SafeWriteTools.cs - Opt-in write operations with safety measures and audit logging
  • BatchTools.cs - High-performance bulk operations for efficient data retrieval
  • PerformanceTools.cs - System monitoring, metrics collection, and cache management
  • TestPlanTools.cs - Test plan management and test execution operations

Services Layer (src/AzureDevOps.MCP/Services/)

  • Core Services (Services/Core/): Domain-specific business logic
    • ProjectService.cs - Project and team management
    • RepositoryService.cs - Git repository operations
    • WorkItemService.cs - Work item queries and management
    • BuildService.cs - Build and pipeline operations
    • TestService.cs - Test management and results
    • SearchService.cs - Code search capabilities
  • Infrastructure Services (Services/Infrastructure/): Cross-cutting concerns
    • Connection management, caching, performance monitoring, health checks
    • Rate limiting, circuit breakers, and resilient execution patterns
  • Legacy Service: AzureDevOpsService.cs - Backward compatibility wrapper

Configuration & Infrastructure

  • Configuration (Configuration/): Modular configuration classes for production deployment
  • Security (Security/): Secret management with Azure Key Vault integration
  • Authorization (Authorization/): Permission-based access control
  • Error Handling (ErrorHandling/): Resilient error handling patterns

Application Entry Point

  • Program.cs: Application startup with dependency injection and MCP server configuration

Common Commands

Development

Option 1: Development Containers (Recommended)

# VS Code with Dev Containers extension
code .
# Click "Reopen in Container" when prompted

# Or use GitHub Codespaces
# Click "Code" → "Codespaces" → "Create codespace" on GitHub

Option 2: Local Development

# Manual setup (any platform)
dotnet restore
dotnet build
dotnet run --project src/AzureDevOps.MCP

# Build from solution root
dotnet build AzureDevOps.MCP.slnx

Testing & Quality

# Run all tests (153 passing tests, 7 skipped)
dotnet test

# Run tests with detailed output
dotnet test --verbosity normal

# Run specific test categories
dotnet test --filter Category=Unit
dotnet test --filter Category=Integration

# Performance benchmarks (excluded from regular test runs)
# Note: Benchmarks are located in tests/AzureDevOps.MCP.Tests/Benchmarks/
# but are excluded from compilation. They can be run separately for performance analysis.

# Test coverage is automatically generated by CI/CD pipeline
# Coverage reports appear in GitHub Actions summaries and PR comments

Docker

# Build Docker image
docker build -t azuredevops-mcp .

# Run with environment variables
docker run -p 8080:8080 \
  -e AzureDevOps__OrganizationUrl="https://dev.azure.com/your-organization" \
  -e AzureDevOps__PersonalAccessToken="your-pat-goes-here" \
  azuredevops-mcp

Configuration

Required Configuration

The application requires Azure DevOps configuration through environment variables or appsettings.json:

  • AzureDevOps__OrganizationUrl - Azure DevOps organization URL
  • AzureDevOps__PersonalAccessToken - Personal Access Token with appropriate permissions

Production Configuration

The application supports extensive production configuration options:

  • Caching: Memory cache settings, cache duration configuration
  • Performance: Operation thresholds, circuit breaker settings, monitoring options
  • Security: Azure Key Vault integration, secret management, authorization policies
  • Rate Limiting: API rate limiting configuration for Azure DevOps calls
  • Monitoring: Sentry integration, structured logging, performance metrics

Write Operations Configuration

Safe write operations can be enabled by configuring:

  • AzureDevOps__EnabledWriteOperations - Array of enabled write operation types
  • AzureDevOps__RequireConfirmation - Require explicit confirmation for write operations
  • AzureDevOps__EnableAuditLogging - Enable comprehensive audit logging

Available MCP Tools

The server exposes Azure DevOps functionality through five specialized tool categories:

Core Azure DevOps Tools (AzureDevOpsTools)

  • Projects: List all accessible projects and project details
  • Repositories: Git operations including file browsing, content retrieval
  • Work Items: Query and retrieve work item details

Safe Write Tools (SafeWriteTools)

  • Pull Request Operations: Add comments to pull requests, create draft PRs
  • Work Item Management: Update work item tags and metadata

Batch Operations (BatchTools)

  • High-Performance Bulk Operations: Efficiently retrieve multiple work items or repositories in parallel

Test Plan Management (TestPlanTools)

  • Test Plans: Get test plans and detailed test plan information
  • Test Suites: Retrieve test suites for specific test plans
  • Test Runs: Access test runs and test results

Performance & Monitoring (PerformanceTools)

  • System Metrics: Performance monitoring, cache statistics, system management

Key Dependencies

Core Framework & MCP

  • .NET 9: Target framework with modern performance optimizations
  • ModelContextProtocol: MCP server implementation for protocol communication

Azure DevOps Integration

  • Microsoft.TeamFoundationServer.Client: Core Azure DevOps API client
  • Microsoft.VisualStudio.Services.Client: Visual Studio Services web API client

Security & Authentication

  • Azure.Extensions.AspNetCore.Configuration.Secrets: Azure Key Vault integration
  • Azure.Security.KeyVault.Secrets: Key Vault secret management
  • Azure.Identity: Azure authentication and identity management
  • Microsoft.AspNetCore.Authentication.JwtBearer: JWT authentication support

Monitoring & Performance

  • Sentry.AspNetCore: Error tracking and performance monitoring
  • Sentry.Extensions.Logging: Logging integration with Sentry
  • OpenTelemetry.Extensions.Hosting: Telemetry and observability
  • OpenTelemetry.Instrumentation.AspNetCore: ASP.NET Core instrumentation
  • OpenTelemetry.Instrumentation.Http: HTTP client instrumentation

Caching & Performance

  • Microsoft.Extensions.Caching.StackExchangeRedis: Redis distributed caching
  • AspNetCore.HealthChecks.UI: Health check monitoring dashboard

Validation & Development

  • FluentValidation: Input validation framework
  • FluentValidation.AspNetCore: ASP.NET Core integration
  • BenchmarkDotNet: Performance benchmarking (development/testing)

CI/CD Pipeline

The repository includes comprehensive GitHub Actions workflows:

Main Pipeline (ci-cd.yml)

  • Build & Test: .NET 9 build, unit tests, and code coverage
  • Security Analysis: Built-in .NET security analyzers
  • Docker: Multi-platform container builds (linux/amd64, linux/arm64) pushed to GitHub Container Registry
  • Releases: Automated releases with cross-platform binaries (Linux, Windows, macOS)
  • Coverage: GitHub native coverage reporting with PR comments and badges

Security Pipeline (security.yml)

  • CodeQL Analysis: Static code analysis for security vulnerabilities
  • TruffleHog: Secrets scanning for leaked credentials
  • Dependency Review: License compliance and vulnerability checking
  • Container Scanning: Trivy security scanning for Docker images
  • Policy Compliance: Validation of security policies and configurations

Coverage Reporting

  • No external service dependencies (Codecov not required)
  • Coverage summaries in GitHub Actions job summaries
  • Automatic PR comments with coverage changes
  • Visual coverage badges and indicators
  • Configurable thresholds (60% warning, 80% good)

important-instruction-reminders

Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.