@azure-devops/mcp 2.0.0-nightly.20250826 → 2.0.0-nightly.20250828

package/README.md

@@ -15,10 +15,11 @@ This TypeScript project provides a **local** MCP server for Azure DevOps, enabli
 2. [🏆 Expectations](#-expectations)
 3. [⚙️ Supported Tools](#️-supported-tools)
 4. [🔌 Installation & Getting Started](#-installation--getting-started)
-5. [📝 Troubleshooting](#-troubleshooting)
-6. [🎩 Examples & Best Practices](#-examples--best-practices)
-7. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
-8. [📌 Contributing](#-contributing)
+5. [🌏 Using Domains](#-using-domains)
+6. [📝 Troubleshooting](#-troubleshooting)
+7. [🎩 Examples & Best Practices](#-examples--best-practices)
+8. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
+9. [📌 Contributing](#-contributing)
 
 ## 📺 Overview
 
@@ -110,9 +111,11 @@ Interact with these Azure DevOps services:
 - **build_get_log**: Retrieve the logs for a specific build.
 - **build_get_log_by_id**: Get a specific build log by log ID.
 - **build_get_changes**: Get the changes associated with a specific build.
-- **build_run_build**: Trigger a new build for a specified definition.
 - **build_get_status**: Fetch the status of a specific build.
 - **build_update_build_stage**: Update the stage of a specific build.
+- **pipelines_get_run**: Gets a run for a particular pipeline.
+- **pipelines_list_runs**: Gets top 10000 runs for a particular pipeline.
+- **pipelines_run_pipeline**: Starts a new run of a pipeline.
 
 ### 🚀 Releases
 
@@ -242,6 +245,37 @@ Open GitHub Copilot Chat and try a prompt like `List ADO projects`.
 
 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.
 
+## 🌏 Using Domains
+
+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.
+
+For example, use `"-d", "core", "work", "work-items"` to load only Work Item related tools (see the example below).
+
+```json
+{
+  "inputs": [
+    {
+      "id": "ado_org",
+      "type": "promptString",
+      "description": "Azure DevOps organization name  (e.g. 'contoso')"
+    }
+  ],
+  "servers": {
+    "ado": {
+      "type": "stdio",
+      "command": "mcp-server-azuredevops",
+      "args": ["${input:ado_org}", "-d", "core", "work", "work-items"]
+    }
+  }
+}
+```
+
+Domains that are available are: `core`, `work`, `work-items`, `search`, `test-plans`, `repositories`, `wiki`, `builds`, `releases`, `advanced-security`
+
+We recommend that you always enable `core` tools so that you can fetch project level information.
+
+> By default all domains are loaded
+
 ## 📝 Troubleshooting
 
 See the [Troubleshooting guide](./docs/TROUBLESHOOTING.md) for help with common issues and logging.

package/dist/tools/builds.js

@@ -5,14 +5,16 @@ import { BuildQueryOrder, DefinitionQueryOrder } from "azure-devops-node-api/int
 import { z } from "zod";
 import { StageUpdateType } from "azure-devops-node-api/interfaces/BuildInterfaces.js";
 const BUILD_TOOLS = {
+    get_builds: "build_get_builds",
+    get_changes: "build_get_changes",
     get_definitions: "build_get_definitions",
     get_definition_revisions: "build_get_definition_revisions",
-    get_builds: "build_get_builds",
     get_log: "build_get_log",
     get_log_by_id: "build_get_log_by_id",
-    get_changes: "build_get_changes",
-    run_build: "build_run_build",
     get_status: "build_get_status",
+    pipelines_get_run: "pipelines_get_run",
+    pipelines_list_runs: "pipelines_list_runs",
+    pipelines_run_pipeline: "pipelines_run_pipeline",
     update_build_stage: "build_update_build_stage",
 };
 function configureBuildTools(server, tokenProvider, connectionProvider, userAgentProvider) {
@@ -129,35 +131,96 @@ function configureBuildTools(server, tokenProvider, connectionProvider, userAgen
             content: [{ type: "text", text: JSON.stringify(changes, null, 2) }],
         };
     });
-    server.tool(BUILD_TOOLS.run_build, "Triggers a new build for a specified definition.", {
+    server.tool(BUILD_TOOLS.pipelines_get_run, "Gets a run for a particular pipeline.", {
         project: z.string().describe("Project ID or name to run the build in"),
-        definitionId: z.number().describe("ID of the build definition to run"),
-        sourceBranch: z.string().optional().describe("Source branch to run the build from. If not provided, the default branch will be used."),
-        parameters: z.record(z.string(), z.string()).optional().describe("Custom build parameters as key-value pairs"),
-    }, async ({ project, definitionId, sourceBranch, parameters }) => {
+        pipelineId: z.number().describe("ID of the pipeline to run"),
+        runId: z.number().describe("ID of the run to get"),
+    }, async ({ project, pipelineId, runId }) => {
+        const connection = await connectionProvider();
+        const pipelinesApi = await connection.getPipelinesApi();
+        const pipelineRun = await pipelinesApi.getRun(project, pipelineId, runId);
+        return {
+            content: [{ type: "text", text: JSON.stringify(pipelineRun, null, 2) }],
+        };
+    });
+    server.tool(BUILD_TOOLS.pipelines_list_runs, "Gets top 10000 runs for a particular pipeline.", {
+        project: z.string().describe("Project ID or name to run the build in"),
+        pipelineId: z.number().describe("ID of the pipeline to run"),
+    }, async ({ project, pipelineId }) => {
+        const connection = await connectionProvider();
+        const pipelinesApi = await connection.getPipelinesApi();
+        const pipelineRuns = await pipelinesApi.listRuns(project, pipelineId);
+        return {
+            content: [{ type: "text", text: JSON.stringify(pipelineRuns, null, 2) }],
+        };
+    });
+    const variableSchema = z.object({
+        value: z.string().optional(),
+        isSecret: z.boolean().optional(),
+    });
+    const resourcesSchema = z.object({
+        builds: z
+            .record(z.string().describe("Name of the build resource."), z.object({
+            version: z.string().optional().describe("Version of the build resource."),
+        }))
+            .optional(),
+        containers: z
+            .record(z.string().describe("Name of the container resource."), z.object({
+            version: z.string().optional().describe("Version of the container resource."),
+        }))
+            .optional(),
+        packages: z
+            .record(z.string().describe("Name of the package resource."), z.object({
+            version: z.string().optional().describe("Version of the package resource."),
+        }))
+            .optional(),
+        pipelines: z.record(z.string().describe("Name of the pipeline resource."), z.object({
+            runId: z.number().describe("Id of the source pipeline run that triggered or is referenced by this pipeline run."),
+            version: z.string().optional().describe("Version of the source pipeline run."),
+        })),
+        repositories: z
+            .record(z.string().describe("Name of the repository resource."), z.object({
+            refName: z.string().describe("Reference name, e.g., refs/heads/main."),
+            token: z.string().optional(),
+            tokenType: z.string().optional(),
+            version: z.string().optional().describe("Version of the repository resource, git commit sha."),
+        }))
+            .optional(),
+    });
+    server.tool(BUILD_TOOLS.pipelines_run_pipeline, "Starts a new run of a pipeline.", {
+        project: z.string().describe("Project ID or name to run the build in"),
+        pipelineId: z.number().describe("ID of the pipeline to run"),
+        pipelineVersion: z.number().optional().describe("Version of the pipeline to run. If not provided, the latest version will be used."),
+        previewRun: z.boolean().optional().describe("If true, returns the final YAML document after parsing templates without creating a new run."),
+        resources: resourcesSchema.optional().describe("A dictionary of resources to pass to the pipeline."),
+        stagesToSkip: z.array(z.string()).optional().describe("A list of stages to skip."),
+        templateParameters: z.record(z.string(), z.string()).optional().describe("Custom build parameters as key-value pairs"),
+        variables: z.record(z.string(), variableSchema).optional().describe("A dictionary of variables to pass to the pipeline."),
+        yamlOverride: z.string().optional().describe("YAML override for the pipeline run."),
+    }, async ({ project, pipelineId, pipelineVersion, previewRun, resources, stagesToSkip, templateParameters, variables, yamlOverride }) => {
+        if (!previewRun && yamlOverride) {
+            throw new Error("Parameter 'yamlOverride' can only be specified together with parameter 'previewRun'.");
+        }
         const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
         const pipelinesApi = await connection.getPipelinesApi();
-        const definition = await buildApi.getDefinition(project, definitionId);
         const runRequest = {
+            previewRun: previewRun,
             resources: {
-                repositories: {
-                    self: {
-                        refName: sourceBranch || definition.repository?.defaultBranch || "refs/heads/main",
-                    },
-                },
+                ...resources,
             },
-            templateParameters: parameters,
+            stagesToSkip: stagesToSkip,
+            templateParameters: templateParameters,
+            variables: variables,
+            yamlOverride: yamlOverride,
         };
-        const pipelineRun = await pipelinesApi.runPipeline(runRequest, project, definitionId);
+        const pipelineRun = await pipelinesApi.runPipeline(runRequest, project, pipelineId, pipelineVersion);
         const queuedBuild = { id: pipelineRun.id };
         const buildId = queuedBuild.id;
         if (buildId === undefined) {
             throw new Error("Failed to get build ID from pipeline run");
         }
-        const buildReport = await buildApi.getBuildReport(project, buildId);
         return {
-            content: [{ type: "text", text: JSON.stringify(buildReport, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(pipelineRun, null, 2) }],
         };
     });
     server.tool(BUILD_TOOLS.get_status, "Fetches the status of a specific build.", {

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "2.0.0-nightly.20250826";
+export const packageVersion = "2.0.0-nightly.20250828";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-devops/mcp",
-  "version": "2.0.0-nightly.20250826",
+  "version": "2.0.0-nightly.20250828",
   "description": "MCP server for interacting with Azure DevOps",
   "license": "MIT",
   "author": "Microsoft Corporation",