{"id":27928572,"url":"https://github.com/aaronsb/ado-mcp","last_synced_at":"2025-09-06T00:59:14.946Z","repository":{"id":281946123,"uuid":"946945816","full_name":"aaronsb/ado-mcp","owner":"aaronsb","description":"Azure DevOps MCP Server","archived":false,"fork":false,"pushed_at":"2025-03-24T12:08:40.000Z","size":982,"stargazers_count":10,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-07T02:44:42.561Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronsb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-11T23:25:22.000Z","updated_at":"2025-05-05T00:12:52.000Z","dependencies_parsed_at":"2025-03-12T01:30:02.797Z","dependency_job_id":"c8fe3e94-8191-43c1-b3f7-fbee74e4c36c","html_url":"https://github.com/aaronsb/ado-mcp","commit_stats":null,"previous_names":["aaronsb/ado-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/ado-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fado-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fado-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fado-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fado-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/ado-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fado-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273842816,"owners_count":25177921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-07T02:40:44.338Z","updated_at":"2025-09-06T00:59:14.918Z","avatar_url":"https://github.com/aaronsb.png","language":"TypeScript","funding_links":[],"categories":["Cloud Infrastructure","🌐 Web Development"],"sub_categories":["☁️ Cloud Providers"],"readme":"# Azure DevOps MCP Server\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/ado-mcp-400x400.png\" alt=\"ADO MCP Logo\" width=\"400\" height=\"400\"\u003e\n\u003c/p\u003e\n\nThis MCP (Model Context Protocol) server provides tools for interacting with Azure DevOps services through AI assistants.\n\n## Architecture\n\nThe server follows an entity-based architecture that groups operations by resource type rather than exposing many atomic tools. This approach provides several benefits:\n\n1. **Intuitive organization**: Tools are organized by the entities they operate on (projects, repositories, work items, etc.)\n2. **Reduced tool count**: Instead of dozens of individual tools, we have a handful of entity tools with multiple operations\n3. **Consistent interface**: All entity tools follow the same pattern for operations and parameters\n4. **Better error handling**: Each entity tool can handle errors specific to its domain\n5. **Easier discovery**: Users can easily discover available operations for each entity\n\n### Architecture Diagram\n\n```mermaid\nflowchart TB\n    Client[AI Assistant] --\u003e|MCP Request| Server[MCP Server]\n    Server --\u003e|MCP Response| Client\n    \n    subgraph \"Azure DevOps MCP Server\"\n        Server --\u003e RequestHandler[Request Handler]\n        RequestHandler --\u003e ToolRegistry[Tool Registry]\n        ToolRegistry --\u003e EntityTools[Entity Tools]\n        EntityTools --\u003e ApiClient[API Client]\n        ApiClient --\u003e ErrorUtils[Error Utilities]\n        ApiClient --\u003e PaginationUtils[Pagination Utilities]\n        ApiClient --\u003e|HTTP Request| AzureDevOps[Azure DevOps API]\n        AzureDevOps --\u003e|HTTP Response| ApiClient\n        ConfigManager[Configuration Manager] --\u003e ApiClient\n    end\n    \n    classDef primary fill:#4285F4,stroke:#0D47A1,color:white\n    classDef secondary fill:#34A853,stroke:#0D652D,color:white\n    classDef utility fill:#FBBC05,stroke:#866A00,color:white\n    classDef external fill:#EA4335,stroke:#980905,color:white\n    \n    class Server,RequestHandler primary\n    class ToolRegistry,EntityTools,ApiClient secondary\n    class ErrorUtils,PaginationUtils,ConfigManager utility\n    class Client,AzureDevOps external\n```\n\n### Component Structure\n\n```mermaid\nclassDiagram\n    class EntityTool {\n        +name: string\n        +description: string\n        +operations: Record~string, Function~\n        +schemas: Record~string, ZodSchema~\n        +getDefinition(): ToolDefinition\n        +execute(args: unknown): Promise~any~\n        #registerOperation(operation, handler, schema, description)\n    }\n    \n    class ADOApiClient {\n        +config: ADOApiConfig\n        +connection: WebApi\n        +getCoreApi()\n        +getWorkItemTrackingApi()\n        +getGitApi()\n        +getPipelineApi()\n        +handleError(error, context)\n    }\n    \n    class ToolRegistry {\n        +registerTool(tool: Tool)\n        +getTool(name: string): Tool\n        +getToolDefinitions(): ToolDefinition[]\n    }\n    \n    class ErrorUtils {\n        +createError(code, message, context)\n        +handleApiError(error, source, operation)\n    }\n    \n    class PaginationUtils {\n        +normalizePaginationParams(params)\n        +createPaginationResult(items, totalCount, continuationToken)\n        +encodeContinuationToken(data)\n        +decodeContinuationToken(token)\n    }\n    \n    EntityTool --\u003e ADOApiClient : uses\n    EntityTool --\u003e ErrorUtils : uses\n    EntityTool --\u003e PaginationUtils : uses\n    ToolRegistry --\u003e EntityTool : registers\n```\n\n### Key Components\n\n- **Entity Tools**: Each tool represents a major Azure DevOps entity (projects, repositories, work items, etc.) and provides multiple operations (list, get, create, etc.)\n- **Tool Registry**: Manages the registration and execution of entity tools\n- **API Client**: Handles communication with the Azure DevOps REST API\n- **Error Utilities**: Provides standardized error handling with detailed context and user-friendly messages\n- **Pagination Utilities**: Implements cursor-based pagination for list operations\n- **Configuration Manager**: Loads and validates configuration from environment variables or config file\n\n## Recent Improvements\n\n### 1. Enhanced Error Handling\n\nThe server now includes a comprehensive error handling system that provides:\n\n- **Categorized errors**: Errors are categorized by type (authentication, authorization, validation, etc.)\n- **Contextual information**: Errors include the source, operation, and other relevant context\n- **User-friendly messages**: Error messages are designed to be helpful and actionable\n- **Troubleshooting tips**: Where applicable, errors include suggestions for resolving the issue\n\n```mermaid\nflowchart LR\n    Error[API Error] --\u003e Handler[Error Handler]\n    Handler --\u003e Category{Categorize}\n    Category --\u003e|Authentication| AuthError[Authentication Error]\n    Category --\u003e|Authorization| AuthzError[Authorization Error]\n    Category --\u003e|Not Found| NotFoundError[Not Found Error]\n    Category --\u003e|Validation| ValidationError[Validation Error]\n    Category --\u003e|Rate Limit| RateLimitError[Rate Limit Error]\n    Category --\u003e|Service| ServiceError[Service Error]\n    Category --\u003e|Unknown| UnknownError[Unknown Error]\n    \n    AuthError \u0026 AuthzError \u0026 NotFoundError \u0026 ValidationError \u0026 RateLimitError \u0026 ServiceError \u0026 UnknownError --\u003e Format[Format User Message]\n    Format --\u003e McpError[MCP Error Response]\n    \n    classDef error fill:#EA4335,stroke:#980905,color:white\n    classDef process fill:#4285F4,stroke:#0D47A1,color:white\n    classDef result fill:#34A853,stroke:#0D652D,color:white\n    \n    class Error,AuthError,AuthzError,NotFoundError,ValidationError,RateLimitError,ServiceError,UnknownError error\n    class Handler,Category,Format process\n    class McpError result\n```\n\n### 2. Cursor-based Pagination\n\nAll list operations now support cursor-based pagination with:\n\n- **Continuation tokens**: Encoded tokens for resuming pagination\n- **Customizable page size**: Control the number of results per page\n- **Consistent interface**: Same pagination parameters across all list operations\n- **Efficient resource usage**: Only fetch the data you need\n\n```mermaid\nsequenceDiagram\n    participant Client as AI Assistant\n    participant Server as MCP Server\n    participant API as Azure DevOps API\n    \n    Client-\u003e\u003eServer: List request (maxResults=10)\n    Server-\u003e\u003eAPI: API request (top=10, skip=0)\n    API-\u003e\u003eServer: Response with items\n    \n    Note over Server: Create continuation token\n    \n    Server-\u003e\u003eClient: Response with items and token\n    \n    Client-\u003e\u003eServer: List request with token\n    \n    Note over Server: Decode token to get position\n    \n    Server-\u003e\u003eAPI: API request (top=10, skip=10)\n    API-\u003e\u003eServer: Response with more items\n    Server-\u003e\u003eClient: Response with items and new token\n```\n\n### 3. Improved Documentation\n\nEach tool and operation now includes:\n\n- **Detailed descriptions**: Clear explanations of what each tool and operation does\n- **Parameter documentation**: Comprehensive documentation for all parameters\n- **Usage examples**: Real-world examples of how to use each operation\n- **Type information**: Clear type definitions for all inputs and outputs\n\n## Available Entity Tools\n\n### Projects Tool\n\nManages Azure DevOps projects.\n\nOperations:\n- `list`: List all projects in the organization with pagination support\n- `get`: Get detailed information about a specific project\n\n### Repositories Tool\n\nManages Git repositories.\n\nOperations:\n- `list`: List all Git repositories in a project with pagination support\n- `get`: Get detailed information about a specific Git repository\n- `listBranches`: List all branches in a Git repository with pagination support\n\n### Work Items Tool\n\nManages work items (bugs, tasks, user stories, etc.).\n\nOperations:\n- `get`: Get detailed information about a specific work item\n- `create`: Create a new work item in a project\n\n### Pull Requests Tool\n\nManages pull requests in repositories.\n\nOperations:\n- `list`: List pull requests in a repository with filtering and pagination support\n- `get`: Get detailed information about a specific pull request\n\n### Pipelines Tool\n\nManages CI/CD pipelines.\n\nOperations:\n- `list`: List all pipelines in a project with pagination support\n- `get`: Get detailed information about a specific pipeline\n\n## Usage Examples\n\n### List Projects with Pagination\n\n```json\n{\n  \"operation\": \"list\",\n  \"listParams\": {\n    \"maxResults\": 10,\n    \"continuationToken\": \"optional-token-from-previous-request\"\n  }\n}\n```\n\n### Get Project Details\n\n```json\n{\n  \"operation\": \"get\",\n  \"getParams\": {\n    \"projectId\": \"my-project\",\n    \"includeCapabilities\": true\n  }\n}\n```\n\n### List Repositories in a Project\n\n```json\n{\n  \"operation\": \"list\",\n  \"listParams\": {\n    \"projectId\": \"my-project\",\n    \"maxResults\": 20\n  }\n}\n```\n\n### List Branches in a Repository\n\n```json\n{\n  \"operation\": \"listBranches\",\n  \"listBranchesParams\": {\n    \"projectId\": \"my-project\",\n    \"repositoryId\": \"my-repo\",\n    \"maxResults\": 15\n  }\n}\n```\n\n### Get Work Item Details\n\n```json\n{\n  \"operation\": \"get\",\n  \"getParams\": {\n    \"id\": 123,\n    \"expand\": \"Relations\"\n  }\n}\n```\n\n### Create a Work Item\n\n```json\n{\n  \"operation\": \"create\",\n  \"createParams\": {\n    \"projectId\": \"my-project\",\n    \"type\": \"Task\",\n    \"title\": \"Implement new feature\",\n    \"description\": \"This task involves implementing the new feature XYZ\",\n    \"assignedTo\": \"user@example.com\"\n  }\n}\n```\n\n### List Pull Requests with Filtering\n\n```json\n{\n  \"operation\": \"list\",\n  \"listParams\": {\n    \"projectId\": \"my-project\",\n    \"repositoryId\": \"my-repo\",\n    \"status\": \"Active\",\n    \"maxResults\": 10\n  }\n}\n```\n\n## Configuration\n\nThe server can be configured using environment variables or a configuration file.\n\n### Environment Variables\n\n- `ADO_ORGANIZATION`: Azure DevOps organization name (required)\n- `ADO_PROJECT`: Default project name (optional)\n- `ADO_PAT`: Personal Access Token for authentication (required)\n- `ADO_API_URL`: Base URL for the API (optional, defaults to https://dev.azure.com)\n- `ADO_API_VERSION`: API version (optional, defaults to 7.0)\n- `ADO_API_MAX_RETRIES`: Maximum number of retries for API calls (optional, defaults to 3)\n- `ADO_API_DELAY_MS`: Delay between retries in milliseconds (optional, defaults to 1000)\n- `ADO_API_BACKOFF_FACTOR`: Backoff factor for retries (optional, defaults to 2)\n\n### Configuration File\n\nAlternatively, you can create a `config/azuredevops.json` file with the following structure:\n\n```json\n{\n  \"organization\": \"your-organization\",\n  \"project\": \"your-project\",\n  \"credentials\": {\n    \"pat\": \"your-personal-access-token\"\n  },\n  \"api\": {\n    \"baseUrl\": \"https://dev.azure.com\",\n    \"version\": \"7.0\",\n    \"retry\": {\n      \"maxRetries\": 3,\n      \"delayMs\": 1000,\n      \"backoffFactor\": 2\n    }\n  }\n}\n```\n\n## Development\n\n### Building the Server\n\n```bash\nnpm run build\n```\n\n### Running the Server\n\n```bash\nnode build/index.js\n```\n\n### Docker\n\n```bash\ndocker build -t azure-devops-mcp:local .\ndocker run -i --rm -e ADO_ORGANIZATION=your-org -e ADO_PAT=your-pat azure-devops-mcp:local\n\n## License\n\nMIT License © 2025 Aaron Bockelie \u003caaronsb@gmail.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fado-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Fado-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fado-mcp/lists"}