Glama
Azure DevOps MCP Server

### Key Points
- Research suggests the `azure-devops-node-api` library is a suitable choice for interacting with Azure DevOps APIs in a Typescript MCP server, offering convenient wrappers for most operations.
- It seems likely that the library supports core functionalities like listing projects and creating work items, but may require manual HTTP requests for listing organizations and search operations.
- The evidence leans toward the library using Promises for asynchronous operations, requiring error handling and potentially manual pagination for large datasets.

---

### Direct Answer

#### Overview
The `azure-devops-node-api` library is a Node.js tool that helps you interact with Azure DevOps services using Typescript, making it ideal for building your MCP server. It simplifies API calls by providing ready-made methods for tasks like managing repositories, work items, and pipelines.

#### How It Works
To use it, first install it via npm and create a `WebApi` object with your Azure DevOps organization and a Personal Access Token (PAT) for authentication. Then, you can access different APIs, like `getCoreApi()` for projects or `getGitApi()` for repository operations. For example, to list projects, you’d use `coreApi.getProjects()`, and to create a work item, you’d call `witApi.createWorkItem()` with the right details.

#### Limitations and Considerations
An interesting detail is that some operations, like listing all organizations or using the Search API, aren’t directly supported, so you’ll need to make raw HTTP requests for those using a library like Axios. Also, the library uses Promises, so you’ll need to handle asynchronous calls and errors, and manage pagination for large datasets manually if needed.

For more details, check the [Azure DevOps Node API GitHub Repository](https://github.com/Microsoft/azure-devops-node-API) or the [Azure DevOps REST API Documentation](https://learn.microsoft.com/en-us/rest/api/azure/devops/?view=azure-devops-rest-7.1).

---

### Comprehensive Analysis of the `azure-devops-node-api` Library for MCP Server Development

This note provides an in-depth exploration of the `azure-devops-node-api` library, focusing on its suitability for building an Azure DevOps reference server for the Model Context Protocol (MCP) as of 01:01 AM EST on Thursday, February 27, 2025. The analysis covers installation, authentication, API interactions, error handling, pagination, and limitations, ensuring a thorough understanding for implementing the server’s tools.

#### Introduction
The `azure-devops-node-api` library, hosted at [Azure Devops Node API GitHub Repository](https://github.com/Microsoft/azure-devops-node-API), is a Node.js library designed to interact with the Azure DevOps Services REST API. It provides a Typescript-friendly wrapper for making API calls, making it a suitable choice for building an MCP server that integrates with Azure DevOps for tasks like repository management, work item tracking, and pipeline automation. This research aims to understand its capabilities and identify any gaps for the server’s implementation.

#### Installation and Initialization
To use the library, it must be installed via npm with the command `npm install azure-devops-node-api`. The library is compatible with Node.js environments, and its Typescript support aligns with the MCP server’s tech stack requirement. Initialization involves creating a `WebApi` object, typically using a Personal Access Token (PAT) for authentication, as shown below:

```ts
import { WebApi } from 'azure-devops-node-api';

const pat = process.env.AZURE_DEVOPS_PAT;
const organization = process.env.AZURE_DEVOPS_ORG;

const api = new WebApi(`https://dev.azure.com/${organization}`, pat);
```

This approach ensures secure handling of sensitive credentials via environment variables, aligning with MCP server configuration practices.

#### Authentication Support
The library supports PAT-based authentication, which is straightforward and mirrors the GitHub MCP server’s approach. The PAT is passed to the `WebApi` constructor, enabling access to Azure DevOps APIs. For other methods like OAuth or Azure Identity, the library can be extended, but PAT is sufficient for initial implementation. The documentation at [Azure Devops Node API Documentation](https://github.com/Microsoft/azure-devops-node-API/blob/master/README.md) provides examples, ensuring secure authentication setup.

#### API Interactions
The library offers various API objects for different Azure DevOps services, accessed via methods like `getCoreApi()`, `getGitApi()`, `getWorkItemTrackingApi()`, and `getBuildApi()`. Each API object provides methods that wrap the corresponding REST API endpoints, simplifying interactions. Below is a table of common operations and their corresponding library methods:

| **Operation**               | **API Object**              | **Method Example**                          | **Corresponding REST Endpoint**                     |
|-----------------------------|-----------------------------|---------------------------------------------|-----------------------------------------------------|
| List Projects               | CoreApi                    | `getProjects()`                             | `GET https://dev.azure.com/{org}/_apis/Projects`    |
| List Repositories           | GitApi                     | `getRepositories()`                         | `GET https://dev.azure.com/{org}/{proj}/_apis/Git/Repositories` |
| Create Work Item            | WorkItemTrackingApi        | `createWorkItem()`                          | `POST https://dev.azure.com/{org}/{proj}/_apis/Wit/WorkItems` |
| Trigger Build               | BuildApi                   | `queueBuild()`                              | `POST https://dev.azure.com/{org}/{proj}/_apis/Build/Builds` |
| Get File Contents           | GitApi                     | `getItemContent()`                          | `GET https://dev.azure.com/{org}/{proj}/_apis/Git/Repositories/{repoId}/Files/{path}` |
| Create Commit (File Update) | GitApi                     | `createCommit()`                            | `POST https://dev.azure.com/{org}/{proj}/_apis/Git/Repositories/{repoId}/Commits` |

For example, to list projects, the implementation would be:

```ts
const coreApi = await api.getCoreApi();
const projects = await coreApi.getProjects();
```

Similarly, to create a work item:

```ts
const witApi = await api.getWorkItemTrackingApi();
const workItem = await witApi.createWorkItem({}, { fields: { System_Title: 'New Task' } }, 'your_project', 'Task');
```

These methods handle the underlying HTTP requests, reducing the need for raw REST calls and ensuring consistency with Azure DevOps API versions.

#### Asynchronous Operations and Error Handling
All library methods return Promises, requiring asynchronous handling with `await` or `.then()`. This aligns with MCP tool definitions, which expect async functions. Error handling is crucial, as API calls may fail due to authentication issues, rate limits, or invalid inputs. The library throws exceptions that must be caught, for example:

```ts
try {
  const projects = await coreApi.getProjects();
} catch (error) {
  console.error('Failed to list projects:', error.message);
  // Return error to MCP client
}
```

This ensures the server can gracefully handle failures, maintaining reliability for AI-driven workflows.

#### Pagination and Performance
Many API calls return paginated results, with the library supporting pagination via methods that return `WebApiTeamServicesResult`, which includes a `count`, `value` (array of results), and potentially a `nextLink` for fetching additional pages. For instance, listing work items might return:

```ts
const workItems = await witApi.getWorkItems('your_project', { top: 100, skip: 0 });
```

To fetch all pages, you’d need to implement a loop checking for `nextLink`, which the library does not handle automatically. For the MCP server, you might decide to return the first page with a note on pagination, balancing performance and completeness. This is particularly important for operations like `list_work_items`, where large datasets could impact response times.

#### Limitations and Gaps
An interesting detail is that the library does not support all Azure DevOps APIs directly. Specifically:
- **Listing Organizations**: The endpoint `GET https://app.vssps.visualstudio.com/_apis/accounts` is not covered, as the `WebApi` object is tied to a specific organization. This requires raw HTTP requests using a library like Axios, impacting implementation for the `list_organizations` tool.
- **Search API**: The [Search REST API](https://learn.microsoft.com/en-us/rest/api/azure/devops/search/?view=azure-devops-rest-7.1) (e.g., `POST https://almsearch.dev.azure.com/{org}/{proj}/_apis/search/codesearchresults`) is not supported, necessitating manual HTTP requests for tools like `search_code`, `search_work_items`, and `search_wiki`. This is manageable but adds complexity.

These gaps are minor compared to the library’s coverage of core operations, and they can be addressed by combining the library with raw requests for unsupported endpoints.

#### Community and Maintenance
The library, maintained by Microsoft, is actively updated, with the latest version (as of February 27, 2025) ensuring compatibility with Azure DevOps API version 7.1. Checking the GitHub repository’s issues and discussions reveals no major blockers, with community examples providing additional guidance for common use cases.

#### Conclusion
The `azure-devops-node-api` library is a robust choice for building the Azure DevOps MCP server, offering convenient wrappers for most required operations like listing projects, creating work items, and managing repositories. It uses Promises for asynchronous calls, requires manual error handling, and supports pagination with some manual effort. However, it lacks support for listing organizations and the Search API, requiring raw HTTP requests for those tools. This research equips you to proceed with prototyping, ensuring alignment with your goal of an AI-driven workflow from user story to pull request.

#### Key Citations
- [Azure Devops Node API GitHub Repository](https://github.com/Microsoft/azure-devops-node-API)
- [Azure Devops Node API Documentation](https://github.com/Microsoft/azure-devops-node-API/blob/master/README.md)
- [Azure Devops REST API Documentation](https://learn.microsoft.com/en-us/rest/api/azure/devops/?view=azure-devops-rest-7.1)
- [Search REST API](https://learn.microsoft.com/en-us/rest/api/azure/devops/search/?view=azure-devops-rest-7.1)