@azure-devops/mcp 2.7.0 → 2.8.0-nightly.20260624

package/README.md

@@ -3,22 +3,23 @@
 > [!IMPORTANT]
 > The Azure DevOps Remote MCP Server is now available in public preview for all organizations. We recommend migrating to the [Remote MCP Server](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server) going forward.
 >
-> [Learn more](#-remote-mcp-server)
+> [Learn more](#-remote-mcp-server-recommended)
 
-This TypeScript project provides a **local** MCP server for Azure DevOps, enabling you to perform a wide range of Azure DevOps tasks directly from your code editor.
+This project provides Azure DevOps MCP tooling for AI agents, with a **remote-first** onboarding experience and a local server option when you need it.
 
 ## 📄 Table of Contents
 
 1. [📺 Overview](#-overview)
 2. [🏆 Expectations](#-expectations)
-3. [🚀 Remote MCP Server](#-remote-mcp-server)
+3. [🚀 Remote MCP Server (Recommended)](#-remote-mcp-server-recommended)
 4. [⚙️ Supported Tools](#️-supported-tools)
-5. [🔌 Installation & Getting Started](#-installation--getting-started)
-6. [🌏 Using Domains](#-using-domains)
-7. [📝 Troubleshooting](#-troubleshooting)
-8. [🎩 Examples & Best Practices](#-examples--best-practices)
-9. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
-10. [📌 Contributing](#-contributing)
+5. [🔌 Local MCP Server Installation (Optional)](#-local-mcp-server-installation-optional)
+6. [🌏 Using Domains (local)](#-using-domains-local)
+7. [🐥 Project and Team Defaults (local)](#-project-and-team-defaults-local)
+8. [📝 Troubleshooting](#-troubleshooting)
+9. [🎩 Examples & Best Practices](#-examples--best-practices)
+10. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
+11. [📌 Contributing](#-contributing)
 
 ## 📺 Overview
 
@@ -39,9 +40,9 @@ The Azure DevOps MCP Server brings Azure DevOps context to your agents. Try prom
 
 ## 🏆 Expectations
 
-The Azure DevOps MCP Server is built from tools that are concise, simple, focused, and easy to use—each designed for a specific scenario. We intentionally avoid complex tools that try to do too much. The goal is to provide a thin abstraction layer over the REST APIs, making data access straightforward and letting the language model handle complex reasoning.
+The Azure DevOps MCP Server is built around tools that are concise, simple, focused, and easy to use, with each one designed for a specific scenario. We intentionally avoid creating complex tools that try to do too much. The goal is to provide a thin abstraction layer over the REST APIs that makes data access straightforward while allowing the language model to handle the more complex reasoning.
 
-## 🚀 Remote MCP Server
+## 🚀 Remote MCP Server (Recommended)
 
 The Azure DevOps **Remote MCP Server** is now available in [public preview](https://devblogs.microsoft.com/devops/azure-devops-remote-mcp-server-public-preview).
 
@@ -54,15 +55,42 @@ If you encounter issues with tools, need support, or have a feature request, you
 > [!WARNING]
 > Internal Microsoft users of the Remote MCP Server should **not** create issues in this repository. Please use the dedicated Teams channel instead.
 
-For instructions on how to get started with the Remote MCP Server, see the [onboarding documentation](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server).
+For complete instructions, see the [Remote MCP Server onboarding documentation](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server?view=azure-devops).
+
+### Quick start with `.vscode/mcp.json`
+
+Use this configuration to connect directly to the Azure DevOps-hosted endpoint using streamable HTTP transport:
+
+```json
+{
+  "servers": {
+    "ado-remote-mcp": {
+      "url": "https://mcp.dev.azure.com/{organization}",
+      "type": "http"
+    }
+  },
+  "inputs": []
+}
+```
+
+See [documentation](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server?view=azure-devops#mcpjson-configuration) for additional configuration options.
+
+After saving `.vscode/mcp.json`, start the server from the MCP view in VS Code, then run a prompt like `List ADO projects`.
 
 ## ⚙️ Supported Tools
 
-See [TOOLSET.md](./docs/TOOLSET.md) for a comprehensive list.
+See the [Available Tools](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server?view=azure-devops#available-tools) documentation for the complete list of available remote tools.
+
+For a comprehensive list of local tools, see [TOOLSET.md](./docs/TOOLSET.md).
+
+## 🔌 Local MCP Server Installation (Optional)
+
+> [!IMPORTANT]
+> Start with the Remote MCP Server first. Use the local MCP Server only if your scenario specifically requires a local `stdio` setup.
 
-## 🔌 Installation & Getting Started
+Use this section if you specifically need the local `stdio` server experience. For most users, start with the [Remote MCP Server](#-remote-mcp-server-recommended) section above.
 
-For the best experience, use Visual Studio Code and GitHub Copilot. See the [getting started documentation](./docs/GETTINGSTARTED.md) to use our MCP Server with other tools such as Visual Studio 2022, Claude Code, Cursor, Opencode, and Kilocode.
+For the best experience, use Visual Studio Code and GitHub Copilot. See the [getting started documentation](./docs/GETTINGSTARTED.md) to use our MCP Server with other tools such as Visual Studio 2022, Codex, Claude Code, Cursor, Opencode, and Kilocode.
 
 ### Prerequisites
 
@@ -72,7 +100,7 @@ For the best experience, use Visual Studio Code and GitHub Copilot. See the [get
 
 ### Installation
 
-#### 🧨 Install from Public Feed (Recommended)
+#### 🧨 Install from Public Feed
 
 This installation method is the easiest for all users of Visual Studio Code.
 
@@ -137,9 +165,9 @@ Open GitHub Copilot Chat and try a prompt like `List ADO projects`. The first ti
 > 💥 We strongly recommend creating a `.github\copilot-instructions.md` in your project. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
 > To start, just include "`This project uses Azure DevOps. Always check to see if the Azure DevOps MCP server has a tool relevant to the user's request`" in your copilot instructions file.
 
-See the [getting started documentation](./docs/GETTINGSTARTED.md) to use our MCP Server with other tools such as Visual Studio 2022, Claude Code, and Cursor.
+See the [getting started documentation](./docs/GETTINGSTARTED.md) to use our MCP Server with other tools such as Visual Studio 2022, Codex, Claude Code, and Cursor.
 
-## 🌏 Using Domains
+## 🌏 Using Domains (local)
 
 Azure DevOps exposes a large surface area. As a result, our Azure DevOps MCP Server includes many tools. To keep the toolset manageable, avoid confusing the model, and respect client limits on loaded tools, use Domains to load only the areas you need. Domains are named groups of related tools (for example: core, work, work-items, repositories, wiki). Add the `-d` argument and the domain names to the server args in your `mcp.json` to list the domains to enable.
 
@@ -170,6 +198,28 @@ We recommend that you always enable `core` tools so that you can fetch project l
 
 > By default all domains are loaded
 
+## 🐥 Project and Team Defaults (local)
+
+You can also configure default Azure DevOps project and team values from `.vscode/mcp.json` using `project` and `team`, so tools can skip selection prompts.
+
+### Example `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "ado": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@azure-devops/mcp", "myorg", "--authentication", "azcli"],
+      "env": {
+        "ado_mcp_project": "Contoso",
+        "ado_mcp_team": "Fabrikam Team"
+      }
+    }
+  }
+}
+```
+
 ## 📝 Troubleshooting
 
 See the [Troubleshooting guide](./docs/TROUBLESHOOTING.md) for help with common issues and logging.

package/dist/index.js

@@ -111,7 +111,7 @@ async function main() {
         };
         logger.debug("PAT mode: global fetch interceptor installed to rewrite Bearer -> Basic auth headers");
     }
-    // removing prompts untill further notice
+    // removing prompts until further notice
     // configurePrompts(server);
     configureAllTools(server, authenticator, getAzureDevOpsClient(authenticator, userAgentComposer, argv.authentication), () => userAgentComposer.userAgent, enabledDomains);
     const transport = new StdioServerTransport();

package/dist/shared/elicitations.js

@@ -1,6 +1,11 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 export async function elicitProject(server, connection, message) {
+    // Check for default project from environment variable
+    const defaultProject = process.env.ado_mcp_project;
+    if (defaultProject) {
+        return { resolved: defaultProject };
+    }
     const coreApi = await connection.getCoreApi();
     const projects = await coreApi.getProjects("wellFormed", 100, 0, undefined, false);
     if (!projects || projects.length === 0) {
@@ -31,6 +36,11 @@ export async function elicitProject(server, connection, message) {
     return { resolved: String(result.content.project) };
 }
 export async function elicitTeam(server, connection, project, message) {
+    // Check for default team from environment variable
+    const defaultTeam = process.env.ado_mcp_team;
+    if (defaultTeam) {
+        return { resolved: defaultTeam };
+    }
     const coreApi = await connection.getCoreApi();
     const teams = await coreApi.getTeams(project, undefined, undefined, undefined, false);
     if (!teams || teams.length === 0) {

package/dist/tools/pipelines.js

@@ -27,7 +27,10 @@ const PIPELINE_TOOLS = {
 function configurePipelineTools(server, tokenProvider, connectionProvider, userAgentProvider) {
     server.tool(PIPELINE_TOOLS.pipelines_get_build_definitions, "Retrieves a list of build definitions for a given project.", {
         project: z.string().describe("Project ID or name to get build definitions for"),
-        repositoryId: z.string().optional().describe("Repository ID to filter build definitions"),
+        repositoryId: z
+            .string()
+            .optional()
+            .describe("Repository ID to filter build definitions. Can be a GUID or a repository name; when a name is provided, it is auto-resolved to the repository GUID using the project parameter (Azure Repos / TfsGit only)."),
         repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter build definitions"),
         name: z.string().optional().describe("Name of the build definition to filter"),
         path: z.string().optional().describe("Path of the build definition to filter"),
@@ -49,7 +52,24 @@ function configurePipelineTools(server, tokenProvider, connectionProvider, userA
     }, async ({ project, repositoryId, repositoryType, name, path, queryOrder, top, continuationToken, minMetricsTime, definitionIds, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename, }) => {
         const connection = await connectionProvider();
         const buildApi = await connection.getBuildApi();
-        const buildDefinitions = await buildApi.getDefinitions(project, name, repositoryId, repositoryType, safeEnumConvert(DefinitionQueryOrder, queryOrder), top, continuationToken, minMetricsTime, definitionIds, path, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename);
+        // Auto-resolve repositoryId from name to GUID for Azure Repos
+        let resolvedRepositoryId = repositoryId;
+        if (repositoryId) {
+            const isGuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(repositoryId);
+            if (!isGuid && (!repositoryType || repositoryType === "TfsGit")) {
+                const gitApi = await connection.getGitApi();
+                const repositories = await gitApi.getRepositories(project);
+                const repo = repositories?.find((r) => r.name === repositoryId);
+                if (!repo?.id) {
+                    return {
+                        content: [{ type: "text", text: `Error: Repository '${repositoryId}' not found in project '${project}'.` }],
+                        isError: true,
+                    };
+                }
+                resolvedRepositoryId = repo.id;
+            }
+        }
+        const buildDefinitions = await buildApi.getDefinitions(project, name, resolvedRepositoryId, repositoryType, safeEnumConvert(DefinitionQueryOrder, queryOrder), top, continuationToken, minMetricsTime, definitionIds, path, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename);
         return {
             content: [{ type: "text", text: JSON.stringify(buildDefinitions, null, 2) }],
         };
@@ -329,19 +349,21 @@ function configurePipelineTools(server, tokenProvider, connectionProvider, userA
             content: [{ type: "text", text: JSON.stringify(artifacts, null, 2) }],
         };
     });
-    server.tool(PIPELINE_TOOLS.pipelines_download_artifact, "Downloads a pipeline artifact.", {
+    server.tool(PIPELINE_TOOLS.pipelines_download_artifact, "Downloads a pipeline artifact. When destinationPath is provided, it must be a relative local path; absolute paths and path traversal are not allowed.", {
         project: z.string().describe("The name or ID of the project."),
         buildId: z.coerce.number().min(1).describe("The ID of the build."),
         artifactName: z.string().describe("The name of the artifact to download."),
-        destinationPath: z.string().optional().describe("The local path to download the artifact to. If not provided, returns binary content as base64."),
+        destinationPath: z.string().optional().describe("The relative local path to download the artifact to. If not provided, returns binary content as base64."),
     }, async ({ project, buildId, artifactName, destinationPath }) => {
-        const isAbsolutePath = (value) => posix.isAbsolute(value) || win32.isAbsolute(value);
+        const hasUnsafePathSegment = (value) => value.split(/[\\/]+/).some((segment) => segment === "." || segment === "..");
+        const hasPathSeparators = (value) => /[\\/]/.test(value);
         const hasDriveLetter = (value) => /^[a-zA-Z]:/.test(value);
-        if (artifactName.includes("..")) {
-            throw new Error("Invalid artifactName: path traversal is not allowed.");
+        const isAbsolutePath = (value) => posix.isAbsolute(value) || win32.isAbsolute(value);
+        if (hasUnsafePathSegment(artifactName) || hasPathSeparators(artifactName) || hasDriveLetter(artifactName) || isAbsolutePath(artifactName)) {
+            throw new Error("Invalid artifactName: artifactName must be a file name, not a path.");
         }
-        if (destinationPath && (destinationPath.includes("..") || isAbsolutePath(destinationPath) || hasDriveLetter(destinationPath))) {
-            throw new Error("Invalid destinationPath: absolute paths and path traversals are not allowed.");
+        if (destinationPath && (hasUnsafePathSegment(destinationPath) || isAbsolutePath(destinationPath) || hasDriveLetter(destinationPath))) {
+            throw new Error("Invalid destinationPath: use a relative path without path traversal.");
         }
         const connection = await connectionProvider();
         const buildApi = await connection.getBuildApi();