aaronsb/ado-mcp

This MCP (Model Context Protocol) server provides tools for interacting with Azure DevOps services through AI assistants.
Architecture
The server follows an entity-based architecture that groups operations by resource type rather than exposing many atomic tools. This approach provides several benefits:
1. **Intuitive organization**: Tools are organized by the entities they operate on (projects, repositories, work items, etc.)
2. **Reduced tool count**: Instead of dozens of individual tools, we have a handful of entity tools with multiple operations
3. **Consistent interface**: All entity tools follow the same pattern for operations and parameters
4. **Better error handling**: Each entity tool can handle errors specific to its domain
5. **Easier discovery**: Users can easily discover available operations for each entity
Architecture Diagram
Component Structure
Key Components
- **Entity Tools**: Each tool represents a major Azure DevOps entity (projects, repositories, work items, etc.) and provides multiple operations (list, get, create, etc.)
- **Tool Registry**: Manages the registration and execution of entity tools
- **API Client**: Handles communication with the Azure DevOps REST API
- **Error Utilities**: Provides standardized error handling with detailed context and user-friendly messages
- **Pagination Utilities**: Implements cursor-based pagination for list operations
- **Configuration Manager**: Loads and validates configuration from environment variables or config file
Recent Improvements
1. Enhanced Error Handling
The server now includes a comprehensive error handling system that provides:
- **Categorized errors**: Errors are categorized by type (authentication, authorization, validation, etc.)
- **Contextual information**: Errors include the source, operation, and other relevant context
- **User-friendly messages**: Error messages are designed to be helpful and actionable
- **Troubleshooting tips**: Where applicable, errors include suggestions for resolving the issue
2. Cursor-based Pagination
All list operations now support cursor-based pagination with:
- **Continuation tokens**: Encoded tokens for resuming pagination
- **Customizable page size**: Control the number of results per page
- **Consistent interface**: Same pagination parameters across all list operations
- **Efficient resource usage**: Only fetch the data you need
3. Improved Documentation
Each tool and operation now includes:
- **Detailed descriptions**: Clear explanations of what each tool and operation does
- **Parameter documentation**: Comprehensive documentation for all parameters
- **Usage examples**: Real-world examples of how to use each operation
- **Type information**: Clear type definitions for all inputs and outputs
Available Entity Tools
Projects Tool
Manages Azure DevOps projects.
Operations:
- list: List all projects in the organization with pagination support
- get: Get detailed information about a specific project
Repositories Tool
Manages Git repositories.
Operations:
- list: List all Git repositories in a project with pagination support