@vm3jack/mcp-server-azure-devops 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Micah Rairdon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# Azure DevOps MCP Server
+
+A Model Context Protocol (MCP) server implementation for Azure DevOps, allowing AI assistants to interact with Azure DevOps APIs through a standardized protocol.
+
+## Overview
+
+This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for Azure DevOps, enabling AI assistants like Claude to interact with Azure DevOps resources securely. The server acts as a bridge between AI models and Azure DevOps APIs, providing a standardized way to:
+
+- Access and manage projects, work items, repositories, and more
+- Create and update work items, branches, and pull requests
+- Execute common DevOps workflows through natural language
+- Access repository content via standardized resource URIs
+- Safely authenticate and interact with Azure DevOps resources
+
+## Server Structure
+
+The server is structured around the Model Context Protocol (MCP) for communicating with AI assistants. It provides tools for interacting with Azure DevOps resources including:
+
+- Projects
+- Work Items
+- Repositories
+- Pull Requests
+- Branches
+- Pipelines
+
+### Core Components
+
+- **AzureDevOpsServer**: Main server class that initializes the MCP server and registers tools
+- **Feature Modules**: Organized by feature area (work-items, projects, repositories, etc.)
+- **Request Handlers**: Each feature module provides request identification and handling functions
+- **Tool Handlers**: Modular functions for each Azure DevOps operation
+- **Configuration**: Environment-based configuration for organization URL, PAT, etc.
+
+The server uses a feature-based architecture where each feature area (like work-items, projects, repositories) is encapsulated in its own module. This makes the codebase more maintainable and easier to extend with new features.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js (v16+)
+- npm or yarn
+- Azure DevOps account with appropriate access
+- Authentication credentials (see [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md) for details):
+  - Personal Access Token (PAT), or
+  - Azure Identity credentials, or
+  - Azure CLI login
+
+### Running from npm (npx)
+
+If you just want to run the **published** server package, you **do not** need to clone or build this repository:
+
+```bash
+npx -y @tiberriver256/mcp-server-azure-devops
+```
+
+### Running locally (from source)
+
+From a checkout of this repository:
+
+```bash
+npm ci
+cp .env.example .env   # then edit values
+npm run build
+npm start              # runs: node dist/index.js
+```
+
+For iterative development (auto-reload):
+
+```bash
+npm run dev            # runs src/index.ts via ts-node-dev
+```
+
+### Usage with Claude Desktop/Cursor AI
+
+To integrate with Claude Desktop or Cursor AI, add one of the following configurations to your configuration file.
+
+#### Azure Identity Authentication
+
+Be sure you are logged in to Azure CLI with `az login` then add the following:
+
+```json
+{
+  "mcpServers": {
+    "azureDevOps": {
+      "command": "npx",
+      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
+      "env": {
+        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
+        "AZURE_DEVOPS_AUTH_METHOD": "azure-identity",
+        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
+      }
+    }
+  }
+}
+```
+
+#### Personal Access Token (PAT) Authentication
+
+```json
+{
+  "mcpServers": {
+    "azureDevOps": {
+      "command": "npx",
+      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
+      "env": {
+        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
+        "AZURE_DEVOPS_AUTH_METHOD": "pat",
+        "AZURE_DEVOPS_PAT": "<YOUR_PAT>",
+        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
+      }
+    }
+  }
+}
+```
+
+Azure DevOps Server (on-prem) requires PAT authentication. Example:
+
+```json
+{
+  "mcpServers": {
+    "azureDevOps": {
+      "command": "npx",
+      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
+      "env": {
+        "AZURE_DEVOPS_ORG_URL": "https://server:8080/tfs/DefaultCollection",
+        "AZURE_DEVOPS_AUTH_METHOD": "pat",
+        "AZURE_DEVOPS_PAT": "<YOUR_PAT>",
+        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
+      }
+    }
+  }
+}
+```
+
+For detailed configuration instructions and more authentication options, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md).
+
+## Authentication Methods
+
+This server supports multiple authentication methods for connecting to Azure DevOps APIs. For detailed setup instructions, configuration examples, and troubleshooting tips, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md).
+
+### Supported Authentication Methods
+
+1. **Personal Access Token (PAT)** - Simple token-based authentication
+2. **Azure Identity (DefaultAzureCredential)** - Flexible authentication using the Azure Identity SDK
+3. **Azure CLI** - Authentication using your Azure CLI login
+
+Example configuration files for each authentication method are available in the [examples directory](https://github.com/tiberriver256/mcp-server-azure-devops/tree/main/docs/examples).
+
+Azure DevOps Server (on-prem) supports PAT authentication only. Azure Identity and Azure CLI are supported for Azure DevOps Services.
+
+## Environment Variables
+
+For a complete list of environment variables and their descriptions, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md#configuration-reference).
+
+Key environment variables include:
+
+| Variable                       | Description                                                                        | Required                     | Default          |
+| ------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------- | ---------------- |
+| `AZURE_DEVOPS_AUTH_METHOD`     | Authentication method (`pat`, `azure-identity`, or `azure-cli`) - case-insensitive | No                           | `azure-identity` |
+| `AZURE_DEVOPS_ORG_URL`         | Full URL to your Azure DevOps organization or Server collection (e.g., `https://server:8080/tfs/DefaultCollection`) | Yes                          | -                |
+| `AZURE_DEVOPS_PAT`             | Personal Access Token (for PAT auth)                                               | Only with PAT auth           | -                |
+| `AZURE_DEVOPS_DEFAULT_PROJECT` | Default project if none specified                                                  | No                           | -                |
+| `AZURE_DEVOPS_API_VERSION`     | API version to use                                                                 | No                           | Latest           |
+| `AZURE_TENANT_ID`              | Azure AD tenant ID (for service principals)                                        | Only with service principals | -                |
+| `AZURE_CLIENT_ID`              | Azure AD application ID (for service principals)                                   | Only with service principals | -                |
+| `AZURE_CLIENT_SECRET`          | Azure AD client secret (for service principals)                                    | Only with service principals | -                |
+| `LOG_LEVEL`                    | Logging level (debug, info, warn, error)                                           | No                           | info             |
+
+## Troubleshooting Authentication
+
+For detailed troubleshooting information for each authentication method, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md#troubleshooting-authentication-issues).
+
+Common issues include:
+
+- Invalid or expired credentials
+- Insufficient permissions
+- Network connectivity problems
+- Configuration errors
+
+## Authentication Implementation Details
+
+For technical details about how authentication is implemented in the Azure DevOps MCP server, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md) and the source code in the `src/auth` directory.
+
+## Available Tools
+
+The Azure DevOps MCP server provides a variety of tools for interacting with Azure DevOps resources. For detailed documentation on each tool, please refer to the corresponding documentation.
+
+### User Tools
+
+- `get_me`: Get details of the authenticated user (id, displayName, email) (Azure DevOps Services only)
+
+### Organization Tools
+
+- `list_organizations`: List all accessible organizations (Azure DevOps Services only)
+
+### Project Tools
+
+- `list_projects`: List all projects in an organization
+- `get_project`: Get details of a specific project
+- `get_project_details`: Get comprehensive details of a project including process, work item types, and teams
+
+### Repository Tools
+
+- `list_repositories`: List all repositories in a project
+- `get_repository`: Get details of a specific repository
+- `get_repository_details`: Get detailed information about a repository including statistics and refs
+- `get_file_content`: Get content of a file or directory from a repository
+- `get_repository_tree`: List a repository's file tree from any path and depth
+- `create_branch`: Create a new branch from an existing one
+- `create_commit`: Commit multiple file changes to a branch using unified diffs or search/replace instructions
+
+### Work Item Tools
+
+- `get_work_item`: Retrieve a work item by ID
+- `create_work_item`: Create a new work item
+- `update_work_item`: Update an existing work item
+- `list_work_items`: List work items in a project
+- `manage_work_item_link`: Add, remove, or update links between work items
+
+### Search Tools
+
+- `search_code`: Search for code across repositories in a project
+- `search_wiki`: Search for content across wiki pages in a project
+- `search_work_items`: Search for work items across projects in Azure DevOps
+
+### Pipelines Tools
+
+- `list_pipelines`: List pipelines in a project
+- `get_pipeline`: Get details of a specific pipeline
+- `list_pipeline_runs`: List recent runs for a pipeline with optional filters
+- `get_pipeline_run`: Get detailed run information and artifact summaries
+- `download_pipeline_artifact`: Download a single artifact file as text
+- `pipeline_timeline`: Retrieve the stage and job timeline for a run
+- `get_pipeline_log`: Retrieve raw or JSON-formatted log content
+- `trigger_pipeline`: Trigger a pipeline run with customizable parameters
+
+### Wiki Tools
+
+- `get_wikis`: List all wikis in a project
+- `get_wiki_page`: Get content of a specific wiki page as plain text
+
+### Pull Request Tools
+
+- [`create_pull_request`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#create_pull_request) - Create a new pull request
+- [`get_pull_request`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#get_pull_request) - Get a pull request by ID
+- [`list_pull_requests`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#list_pull_requests) - List pull requests in a repository
+- [`add_pull_request_comment`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#add_pull_request_comment) - Add a comment to a pull request
+- [`get_pull_request_comments`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#get_pull_request_comments) - Get comments from a pull request
+- [`update_pull_request`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#update_pull_request) - Update an existing pull request (title, description, status, draft state, reviewers, work items)
+- [`get_pull_request_changes`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#get_pull_request_changes) - List changes in a pull request and policy evaluation status
+- [`get_pull_request_checks`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#get_pull_request_checks) - Summarize status checks, policy evaluations, and their related pipelines
+
+For comprehensive documentation on all tools, see the [Tools Documentation](https://github.com/tiberriver256/mcp-server-azure-devops/tree/main/docs/tools).
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/CONTRIBUTING.md) for contribution guidelines.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=tiberriver256/mcp-server-azure-devops&type=Date)](https://www.star-history.com/#tiberriver256/mcp-server-azure-devops&Date)
+
+## License
+
+MIT

package/dist/clients/azure-devops.d.ts

@@ -0,0 +1,105 @@
+interface ClientOptions {
+    organizationId?: string;
+    organizationUrl?: string;
+    projectId?: string;
+}
+interface WikiCreateParameters {
+    name: string;
+    projectId: string;
+    type: 'projectWiki' | 'codeWiki';
+    repositoryId?: string;
+    mappedPath?: string;
+    version?: {
+        version: string;
+        versionType?: 'branch' | 'tag' | 'commit';
+    };
+}
+interface WikiPageContent {
+    content: string;
+}
+export interface WikiPageSummary {
+    id: number;
+    path: string;
+    url?: string;
+    order?: number;
+}
+interface PageUpdateOptions {
+    comment?: string;
+    versionDescriptor?: {
+        version?: string;
+    };
+}
+export declare class WikiClient {
+    private baseUrl;
+    constructor(options: {
+        organizationId?: string;
+        organizationUrl?: string;
+        projectId?: string;
+    });
+    /**
+     * Gets a project's ID from its name or verifies a project ID
+     * @param projectNameOrId - Project name or ID
+     * @returns The project ID
+     */
+    private getProjectId;
+    /**
+     * Creates a new wiki in Azure DevOps
+     * @param projectId - Project ID or name
+     * @param params - Parameters for creating the wiki
+     * @returns The created wiki
+     */
+    createWiki(projectId: string, params: WikiCreateParameters): Promise<any>;
+    /**
+     * Gets a wiki page's content
+     * @param projectId - Project ID or name
+     * @param wikiId - Wiki ID or name
+     * @param pagePath - Path of the wiki page
+     * @param options - Additional options like version
+     * @returns The wiki page content and ETag
+     */
+    getPage(projectId: string, wikiId: string, pagePath: string): Promise<{
+        content: any;
+        eTag: any;
+    }>;
+    /**
+     * Creates a new wiki page with the provided content
+     * @param content - Content for the new wiki page
+     * @param projectId - Project ID or name
+     * @param wikiId - Wiki ID or name
+     * @param pagePath - Path of the wiki page to create
+     * @param options - Additional options like comment
+     * @returns The created wiki page
+     */
+    createPage(content: string, projectId: string, wikiId: string, pagePath: string, options?: {
+        comment?: string;
+    }): Promise<any>;
+    /**
+     * Updates a wiki page with the provided content
+     * @param content - Content for the wiki page
+     * @param projectId - Project ID or name
+     * @param wikiId - Wiki ID or name
+     * @param pagePath - Path of the wiki page
+     * @param options - Additional options like comment and version
+     * @returns The updated wiki page
+     */
+    updatePage(content: WikiPageContent, projectId: string, wikiId: string, pagePath: string, options?: PageUpdateOptions): Promise<any>;
+    /**
+     * Lists wiki pages from a wiki using the Pages Batch API
+     * @param projectId - Project ID or name
+     * @param wikiId - Wiki ID or name
+     * @returns Array of wiki page summaries sorted by order then path
+     */
+    listWikiPages(projectId: string, wikiId: string): Promise<WikiPageSummary[]>;
+}
+/**
+ * Creates a Wiki client for Azure DevOps operations
+ * @param options - Options for creating the client
+ * @returns A Wiki client instance
+ */
+export declare function getWikiClient(options: ClientOptions): Promise<WikiClient>;
+/**
+ * Get the authorization header for Azure DevOps API requests
+ * @returns The authorization header
+ */
+export declare function getAuthorizationHeader(): Promise<string>;
+export {};