@vm3jack/mcp-server-azure-devops 1.0.0

package/docs/tools/README.md

@@ -0,0 +1,73 @@
+# Azure DevOps MCP Server Tools Documentation
+
+This directory contains documentation for all tools available in the Azure DevOps MCP server. Each tool is documented with examples, parameters, response formats, and error handling information.
+
+## Navigation
+
+- [Core Navigation Tools](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/core-navigation.md) - Overview of tools for navigating Azure DevOps resources
+  - [Organizations](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/organizations.md) - Tools for working with organizations
+  - [Projects](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/projects.md) - Tools for working with projects
+  - [Repositories](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/repositories.md) - Tools for working with Git repositories
+  - [Pull Requests](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md) - Tools for working with pull requests
+  - [Work Items](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/work-items.md) - Tools for working with work items
+  - [Pipelines](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pipelines.md) - Tools for working with pipelines
+- [Resource URIs](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/resources.md) - Documentation for accessing repository content via resource URIs
+
+## Tools by Category
+
+### Organization Tools
+
+- [`list_organizations`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/organizations.md#list_organizations) - List all Azure DevOps organizations accessible to the user
+
+### Project Tools
+
+- [`list_projects`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/projects.md#list_projects) - List all projects in the organization
+- [`get_project`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/projects.md#get_project) - Get details of a specific project
+
+### Repository Tools
+
+- [`list_repositories`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/repositories.md#list_repositories) - List all repositories in a project
+- [`get_repository`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/repositories.md#get_repository) - Get details of a specific repository
+- [`get_repository_details`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/repositories.md#get_repository_details) - Get detailed information about a repository
+- [`get_file_content`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/repositories.md#get_file_content) - Get content of a file or directory from a repository
+
+### 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)
+
+### Work Item Tools
+
+- [`get_work_item`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/work-items.md#get_work_item) - Retrieve a work item by ID
+- [`create_work_item`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/work-items.md#create_work_item) - Create a new work item
+- [`list_work_items`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/work-items.md#list_work_items) - List work items in a project
+
+### Pipeline Tools
+
+- [`list_pipelines`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pipelines.md#list_pipelines) - List all pipelines in a project
+- [`get_pipeline`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pipelines.md#get_pipeline) - Get details of a specific pipeline
+- [`list_pipeline_runs`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pipelines.md#list_pipeline_runs) - List recent runs for a pipeline with filters
+- [`get_pipeline_run`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pipelines.md#get_pipeline_run) - Get detailed information about a specific run
+- [`download_pipeline_artifact`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pipelines.md#download_pipeline_artifact) - Download a file from pipeline artifacts as text
+- [`pipeline_timeline`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pipelines.md#pipeline_timeline) - Retrieve the stage/job timeline for a run
+- [`get_pipeline_log`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pipelines.md#get_pipeline_log) - Retrieve log contents in plain or JSON formats
+- [`trigger_pipeline`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pipelines.md#trigger_pipeline) - Trigger a pipeline run with customizable parameters
+
+## Tool Structure
+
+Each tool documentation follows a consistent structure:
+
+1. **Description**: Brief explanation of what the tool does
+2. **Parameters**: Required and optional parameters with explanations
+3. **Response**: Expected response format with examples
+4. **Error Handling**: Potential errors and how they're handled
+5. **Example Usage**: Code examples showing how to use the tool
+6. **Implementation Details**: Technical details about how the tool works
+
+## Examples
+
+Examples of using multiple tools together can be found in the [Core Navigation Tools](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/core-navigation.md#common-use-cases) documentation.

package/docs/tools/core-navigation.md

@@ -0,0 +1,114 @@
+# Core Navigation Tools for Azure DevOps
+
+This document provides an overview of the core navigation tools available in the Azure DevOps MCP server. These tools help you discover and navigate the organizational structure of Azure DevOps, from organizations down to repositories.
+
+## Navigation Hierarchy
+
+Azure DevOps resources are organized in a hierarchical structure:
+
+```
+Organizations
+└── Projects
+    ├── Repositories
+    │   └── Branches, Files, etc.
+    │   └── Pull Requests
+    └── Work Items
+```
+
+The core navigation tools allow you to explore this hierarchy from top to bottom.
+
+## Available Tools
+
+| Tool Name                                                     | Description                                                 | Required Parameters | Optional Parameters                       |
+| ------------------------------------------------------------- | ----------------------------------------------------------- | ------------------- | ----------------------------------------- |
+| [`list_organizations`](./organizations.md#list_organizations) | Lists all Azure DevOps organizations accessible to the user | None                | None                                      |
+| [`list_projects`](./projects.md#list_projects)                | Lists all projects in the organization                      | None                | stateFilter, top, skip, continuationToken |
+| [`list_repositories`](./repositories.md#list_repositories)    | Lists all repositories in a project                         | projectId           | includeLinks                              |
+| [`list_pull_requests`](./pull-requests.md#list_pull_requests) | Lists pull requests in a repository                         | projectId, repositoryId | status, creatorId, reviewerId, etc.    |
+| [`get_pull_request`](./pull-requests.md#get_pull_request)     | Gets a pull request by ID                                   | projectId, pullRequestId | None                                 |
+
+## Common Use Cases
+
+### Discovering Resource Structure
+
+A common workflow is to navigate the hierarchy to discover resources:
+
+1. Use `list_organizations` to find available organizations
+2. Use `list_projects` to find projects in a selected organization
+3. Use `list_repositories` to find repositories in a selected project
+4. Use `list_pull_requests` to find pull requests in a selected repository
+5. Use `get_pull_request` when you know a PR ID but not its repository
+
+Example:
+
+```typescript
+// Step 1: Get all organizations
+const organizations = await mcpClient.callTool('list_organizations', {});
+const myOrg = organizations[0]; // Use the first organization for this example
+
+// Step 2: Get all projects in the organization
+const projects = await mcpClient.callTool('list_projects', {});
+const myProject = projects[0]; // Use the first project for this example
+
+// Step 3: Get all repositories in the project
+const repositories = await mcpClient.callTool('list_repositories', {
+  projectId: myProject.name,
+});
+const myRepo = repositories[0]; // Use the first repository for this example
+
+// Step 4: Get all active pull requests in the repository
+const pullRequests = await mcpClient.callTool('list_pull_requests', {
+  projectId: myProject.name,
+  repositoryId: myRepo.name,
+  status: 'active'
+});
+
+// Step 5: Fetch a PR directly by ID (no repository needed)
+const pullRequest = await mcpClient.callTool('get_pull_request', {
+  projectId: myProject.name,
+  pullRequestId: 42,
+});
+```
+
+### Filtering Projects
+
+You can filter projects based on their state:
+
+```typescript
+// Get only well-formed projects (state = 1)
+const wellFormedProjects = await mcpClient.callTool('list_projects', {
+  stateFilter: 1,
+});
+```
+
+### Pagination
+
+For organizations with many projects or repositories, you can use pagination:
+
+```typescript
+// Get projects with pagination (first 10 projects)
+const firstPage = await mcpClient.callTool('list_projects', {
+  top: 10,
+  skip: 0,
+});
+
+// Get the next 10 projects
+const secondPage = await mcpClient.callTool('list_projects', {
+  top: 10,
+  skip: 10,
+});
+```
+
+## Detailed Documentation
+
+For detailed information about each tool, including parameters, response format, and error handling, please refer to the individual tool documentation:
+
+- [list_organizations](./organizations.md#list_organizations)
+- [list_projects](./projects.md#list_projects)
+- [list_repositories](./repositories.md#list_repositories)
+- [list_pull_requests](./pull-requests.md#list_pull_requests)
+- [create_pull_request](./pull-requests.md#create_pull_request)
+
+## Error Handling
+
+Each of these tools may throw various errors, such as authentication errors or permission errors. Be sure to implement proper error handling when using these tools. Refer to the individual tool documentation for specific error types that each tool might throw.

package/docs/tools/organizations.md

@@ -0,0 +1,73 @@
+# Azure DevOps Organizations Tools
+
+This document describes the tools available for working with Azure DevOps organizations.
+
+## list_organizations
+
+Lists all Azure DevOps organizations accessible to the authenticated user.
+
+### Description
+
+The `list_organizations` tool retrieves all Azure DevOps organizations that the authenticated user has access to. This is useful for discovering which organizations are available before performing operations on specific projects or repositories.
+
+Unlike most other tools in this server, this tool uses Axios for direct API calls rather than the Azure DevOps Node API client, as the WebApi client doesn't support the organizations endpoint.
+
+### Parameters
+
+This tool doesn't require any parameters.
+
+```json
+{
+  // No parameters required
+}
+```
+
+### Response
+
+The tool returns an array of organization objects, each containing:
+
+- `id`: The unique identifier of the organization
+- `name`: The name of the organization
+- `url`: The URL of the organization
+
+Example response:
+
+```json
+[
+  {
+    "id": "org1-id",
+    "name": "org1-name",
+    "url": "https://dev.azure.com/org1-name"
+  },
+  {
+    "id": "org2-id",
+    "name": "org2-name",
+    "url": "https://dev.azure.com/org2-name"
+  }
+]
+```
+
+### Error Handling
+
+The tool may throw the following errors:
+
+- `AzureDevOpsAuthenticationError`: If authentication fails or the user profile cannot be retrieved
+- General errors: If the accounts API call fails or other unexpected errors occur
+
+### Example Usage
+
+```typescript
+// Example MCP client call
+const result = await mcpClient.callTool('list_organizations', {});
+console.log(result);
+```
+
+### Implementation Details
+
+This tool uses a two-step process to retrieve organizations:
+
+1. First, it gets the user profile from `https://app.vssps.visualstudio.com/_apis/profile/profiles/me`
+2. Then it extracts the `publicAlias` from the profile response
+3. Finally, it uses the `publicAlias` to get organizations from `https://app.vssps.visualstudio.com/_apis/accounts?memberId={publicAlias}`
+
+Authentication is handled using Basic Auth with the Personal Access Token.