@azure-devops/mcp 1.0.0 → 1.1.0

package/dist/index.js

@@ -7,7 +7,7 @@ import * as azdev from "azure-devops-node-api";
 import { DefaultAzureCredential } from "@azure/identity";
 import { configurePrompts } from "./prompts.js";
 import { configureAllTools } from "./tools.js";
-import { userAgent } from "./utils.js";
+import { UserAgentComposer } from "./useragent.js";
 import { packageVersion } from "./version.js";
 const args = process.argv.slice(2);
 if (args.length === 0) {
@@ -22,25 +22,30 @@ async function getAzureDevOpsToken() {
     const token = await credential.getToken("499b84ac-1321-427f-aa17-267ca6975798/.default");
     return token;
 }
-async function getAzureDevOpsClient() {
-    const token = await getAzureDevOpsToken();
-    const authHandler = azdev.getBearerHandler(token.token);
-    const connection = new azdev.WebApi(orgUrl, authHandler, undefined, {
-        productName: "AzureDevOps.MCP",
-        productVersion: packageVersion,
-        userAgent: userAgent
-    });
-    return connection;
+function getAzureDevOpsClient(userAgentComposer) {
+    return async () => {
+        const token = await getAzureDevOpsToken();
+        const authHandler = azdev.getBearerHandler(token.token);
+        const connection = new azdev.WebApi(orgUrl, authHandler, undefined, {
+            productName: "AzureDevOps.MCP",
+            productVersion: packageVersion,
+            userAgent: userAgentComposer.userAgent,
+        });
+        return connection;
+    };
 }
 async function main() {
     const server = new McpServer({
         name: "Azure DevOps MCP Server",
         version: packageVersion,
     });
+    const userAgentComposer = new UserAgentComposer(packageVersion);
+    server.server.oninitialized = () => {
+        userAgentComposer.appendMcpClientInfo(server.server.getClientVersion());
+    };
     configurePrompts(server);
-    configureAllTools(server, getAzureDevOpsToken, getAzureDevOpsClient);
+    configureAllTools(server, getAzureDevOpsToken, getAzureDevOpsClient(userAgentComposer), () => userAgentComposer.userAgent);
     const transport = new StdioServerTransport();
-    console.log("Azure DevOps MCP Server version : " + packageVersion);
     await server.connect(transport);
 }
 main().catch((error) => {

package/dist/prompts.js

@@ -1,22 +1,47 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 import { z } from "zod";
-import { REPO_TOOLS } from "./tools/repos.js";
+import { CORE_TOOLS } from "./tools/core.js";
+import { WORKITEM_TOOLS } from "./tools/workitems.js";
 function configurePrompts(server) {
-    server.prompt("relevant_pull_requests", "Presents the list of relevant pull requests for a given repository.", { repositoryId: z.string() }, ({ repositoryId }) => ({
+    server.prompt("listProjects", "Lists all projects in the Azure DevOps organization.", {}, () => ({
         messages: [
             {
                 role: "user",
                 content: {
                     type: "text",
-                    text: String.raw `
-# Prerequisites
-1. Unless already provided, ask user for the project name
-2. Unless already provided, use '${REPO_TOOLS.list_repos_by_project}' tool to get a summarized response of the repositories in this project and ask user to select one
-
-# Task
-Find all pull requests for repository ${repositoryId} using '${REPO_TOOLS.list_pull_requests_by_repo}' tool and summarize them in a table.
-Include the following columns: ID, Title, Status, Created Date, Author and Reviewers.`,
+                    text: String.raw `
+# Task
+Use the '${CORE_TOOLS.list_projects}' tool to retrieve all projects in the current Azure DevOps organization.
+Present the results in a table with the following columns: Project ID, Name, and Description.`,
+                },
+            },
+        ],
+    }));
+    server.prompt("listTeams", "Retrieves all teams for a given Azure DevOps project.", { project: z.string() }, ({ project }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: String.raw `
+  # Task
+  Use the '${CORE_TOOLS.list_project_teams}' tool to retrieve all teams for the project '${project}'.
+  Present the results in a table with the following columns: Team ID, and Name`,
+                },
+            },
+        ],
+    }));
+    server.prompt("getWorkItem", "Retrieves details for a specific Azure DevOps work item by ID.", { id: z.string().describe("The ID of the work item to retrieve."), project: z.string().describe("The name or ID of the Azure DevOps project.") }, ({ id, project }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: String.raw `
+  # Task
+  Use the '${WORKITEM_TOOLS.get_work_item}' tool to retrieve details for the work item with ID '${id}' in project '${project}'.
+  Present the following fields: ID, Title, State, Assigned To, Work Item Type, Description or Repro Steps, and Created Date.`,
                 },
             },
         ],

package/dist/tools/auth.js

@@ -7,7 +7,7 @@ async function getCurrentUserDetails(tokenProvider, connectionProvider) {
     const response = await fetch(url, {
         method: "GET",
         headers: {
-            Authorization: `Bearer ${token}`,
+            "Authorization": `Bearer ${token}`,
             "Content-Type": "application/json",
         },
     });

package/dist/tools/builds.js

@@ -1,7 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
+import { apiVersion } from "../utils.js";
 import { BuildQueryOrder, DefinitionQueryOrder } from "azure-devops-node-api/interfaces/BuildInterfaces.js";
 import { z } from "zod";
+import { StageUpdateType } from "azure-devops-node-api/interfaces/BuildInterfaces.js";
 const BUILD_TOOLS = {
     get_definitions: "build_get_definitions",
     get_definition_revisions: "build_get_definition_revisions",
@@ -10,7 +12,8 @@ const BUILD_TOOLS = {
     get_log_by_id: "build_get_log_by_id",
     get_changes: "build_get_changes",
     run_build: "build_run_build",
-    get_status: "build_get_status"
+    get_status: "build_get_status",
+    update_build_stage: "build_update_build_stage",
 };
 function configureBuildTools(server, tokenProvider, connectionProvider) {
     server.tool(BUILD_TOOLS.get_definitions, "Retrieves a list of build definitions for a given project.", {
@@ -22,10 +25,10 @@ function configureBuildTools(server, tokenProvider, connectionProvider) {
         queryOrder: z.nativeEnum(DefinitionQueryOrder).optional().describe("Order in which build definitions are returned"),
         top: z.number().optional().describe("Maximum number of build definitions to return"),
         continuationToken: z.string().optional().describe("Token for continuing paged results"),
-        minMetricsTime: z.date().optional().describe("Minimum metrics time to filter build definitions"),
+        minMetricsTime: z.coerce.date().optional().describe("Minimum metrics time to filter build definitions"),
         definitionIds: z.array(z.number()).optional().describe("Array of build definition IDs to filter"),
-        builtAfter: z.date().optional().describe("Return definitions that have builds after this date"),
-        notBuiltAfter: z.date().optional().describe("Return definitions that do not have builds after this date"),
+        builtAfter: z.coerce.date().optional().describe("Return definitions that have builds after this date"),
+        notBuiltAfter: z.coerce.date().optional().describe("Return definitions that do not have builds after this date"),
         includeAllProperties: z.boolean().optional().describe("Whether to include all properties in the results"),
         includeLatestBuilds: z.boolean().optional().describe("Whether to include the latest builds for each definition"),
         taskIdFilter: z.string().optional().describe("Task ID to filter build definitions"),
@@ -55,8 +58,8 @@ function configureBuildTools(server, tokenProvider, connectionProvider) {
         definitions: z.array(z.number()).optional().describe("Array of build definition IDs to filter builds"),
         queues: z.array(z.number()).optional().describe("Array of queue IDs to filter builds"),
         buildNumber: z.string().optional().describe("Build number to filter builds"),
-        minTime: z.date().optional().describe("Minimum finish time to filter builds"),
-        maxTime: z.date().optional().describe("Maximum finish time to filter builds"),
+        minTime: z.coerce.date().optional().describe("Minimum finish time to filter builds"),
+        maxTime: z.coerce.date().optional().describe("Maximum finish time to filter builds"),
         requestedFor: z.string().optional().describe("User ID or name who requested the build"),
         reasonFilter: z.number().optional().describe("Reason filter for the build (see BuildReason enum)"),
         statusFilter: z.number().optional().describe("Status filter for the build (see BuildStatus enum)"),
@@ -123,12 +126,31 @@ function configureBuildTools(server, tokenProvider, connectionProvider) {
         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."),
-    }, async ({ project, definitionId, sourceBranch }) => {
+        parameters: z.record(z.string(), z.string()).optional().describe("Custom build parameters as key-value pairs"),
+    }, async ({ project, definitionId, sourceBranch, parameters }) => {
         const connection = await connectionProvider();
         const buildApi = await connection.getBuildApi();
-        const build = await buildApi.queueBuild({ definition: { id: definitionId }, sourceBranch }, project);
+        const pipelinesApi = await connection.getPipelinesApi();
+        const definition = await buildApi.getDefinition(project, definitionId);
+        const runRequest = {
+            resources: {
+                repositories: {
+                    self: {
+                        refName: sourceBranch || definition.repository?.defaultBranch || "refs/heads/main",
+                    },
+                },
+            },
+            templateParameters: parameters,
+        };
+        const pipelineRun = await pipelinesApi.runPipeline(runRequest, project, definitionId);
+        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(build, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(buildReport, null, 2) }],
         };
     });
     server.tool(BUILD_TOOLS.get_status, "Fetches the status of a specific build.", {
@@ -142,5 +164,37 @@ function configureBuildTools(server, tokenProvider, connectionProvider) {
             content: [{ type: "text", text: JSON.stringify(build, null, 2) }],
         };
     });
+    server.tool(BUILD_TOOLS.update_build_stage, "Updates the stage of a specific build.", {
+        project: z.string().describe("Project ID or name to update the build stage for"),
+        buildId: z.number().describe("ID of the build to update"),
+        stageName: z.string().describe("Name of the stage to update"),
+        status: z.nativeEnum(StageUpdateType).describe("New status for the stage"),
+        forceRetryAllJobs: z.boolean().default(false).describe("Whether to force retry all jobs in the stage."),
+    }, async ({ project, buildId, stageName, status, forceRetryAllJobs }) => {
+        const connection = await connectionProvider();
+        const orgUrl = connection.serverUrl;
+        const endpoint = `${orgUrl}/${project}/_apis/build/builds/${buildId}/stages/${stageName}?api-version=${apiVersion}`;
+        const token = await tokenProvider();
+        const body = {
+            forceRetryAllJobs: forceRetryAllJobs,
+            state: status.valueOf(),
+        };
+        const response = await fetch(endpoint, {
+            method: "PATCH",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${token.token}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Failed to update build stage: ${response.status} ${errorText}`);
+        }
+        const updatedBuild = await response.text();
+        return {
+            content: [{ type: "text", text: JSON.stringify(updatedBuild, null, 2) }],
+        };
+    });
 }
 export { BUILD_TOOLS, configureBuildTools };

package/dist/tools/core.js

@@ -5,6 +5,10 @@ const CORE_TOOLS = {
     list_project_teams: "core_list_project_teams",
     list_projects: "core_list_projects",
 };
+function filterProjectsByName(projects, projectNameFilter) {
+    const lowerCaseFilter = projectNameFilter.toLowerCase();
+    return projects.filter((project) => project.name?.toLowerCase().includes(lowerCaseFilter));
+}
 function configureCoreTools(server, tokenProvider, connectionProvider) {
     server.tool(CORE_TOOLS.list_project_teams, "Retrieve a list of teams for the specified Azure DevOps project.", {
         project: z.string().describe("The name or ID of the Azure DevOps project."),
@@ -24,10 +28,10 @@ function configureCoreTools(server, tokenProvider, connectionProvider) {
             };
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
             return {
                 content: [{ type: "text", text: `Error fetching project teams: ${errorMessage}` }],
-                isError: true
+                isError: true,
             };
         }
     });
@@ -36,7 +40,8 @@ function configureCoreTools(server, tokenProvider, connectionProvider) {
         top: z.number().optional().describe("The maximum number of projects to return. Defaults to 100."),
         skip: z.number().optional().describe("The number of projects to skip for pagination. Defaults to 0."),
         continuationToken: z.number().optional().describe("Continuation token for pagination. Used to fetch the next set of results if available."),
-    }, async ({ stateFilter, top, skip, continuationToken }) => {
+        projectNameFilter: z.string().optional().describe("Filter projects by name. Supports partial matches."),
+    }, async ({ stateFilter, top, skip, continuationToken, projectNameFilter }) => {
         try {
             const connection = await connectionProvider();
             const coreApi = await connection.getCoreApi();
@@ -44,15 +49,16 @@ function configureCoreTools(server, tokenProvider, connectionProvider) {
             if (!projects) {
                 return { content: [{ type: "text", text: "No projects found" }], isError: true };
             }
+            const filteredProject = projectNameFilter ? filterProjectsByName(projects, projectNameFilter) : projects;
             return {
-                content: [{ type: "text", text: JSON.stringify(projects, null, 2) }],
+                content: [{ type: "text", text: JSON.stringify(filteredProject, null, 2) }],
             };
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
             return {
                 content: [{ type: "text", text: `Error fetching projects: ${errorMessage}` }],
-                isError: true
+                isError: true,
             };
         }
     });

package/dist/tools/releases.js

@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
-import { ReleaseDefinitionExpands, ReleaseDefinitionQueryOrder, ReleaseExpands, ReleaseStatus, ReleaseQueryOrder, } from "azure-devops-node-api/interfaces/ReleaseInterfaces.js";
+import { ReleaseDefinitionExpands, ReleaseDefinitionQueryOrder, ReleaseExpands, ReleaseStatus, ReleaseQueryOrder } from "azure-devops-node-api/interfaces/ReleaseInterfaces.js";
 import { z } from "zod";
 const RELEASE_TOOLS = {
     get_release_definitions: "release_get_definitions",
@@ -28,9 +28,7 @@ function configureReleaseTools(server, tokenProvider, connectionProvider) {
         const releaseApi = await connection.getReleaseApi();
         const releaseDefinitions = await releaseApi.getReleaseDefinitions(project, searchText, expand, artifactType, artifactSourceId, top, continuationToken, queryOrder, path, isExactNameMatch, tagFilter, propertyFilters, definitionIdFilter, isDeleted, searchTextContainsFolderName);
         return {
-            content: [
-                { type: "text", text: JSON.stringify(releaseDefinitions, null, 2) },
-            ],
+            content: [{ type: "text", text: JSON.stringify(releaseDefinitions, null, 2) }],
         };
     });
     server.tool(RELEASE_TOOLS.get_releases, "Retrieves a list of releases for a given project.", {
@@ -41,12 +39,20 @@ function configureReleaseTools(server, tokenProvider, connectionProvider) {
         createdBy: z.string().optional().describe("User ID or name who created the release"),
         statusFilter: z.nativeEnum(ReleaseStatus).optional().default(ReleaseStatus.Active).describe("Status of the releases to filter (default: Active)"),
         environmentStatusFilter: z.number().optional().describe("Environment status to filter releases"),
-        minCreatedTime: z.date().optional().default(() => {
+        minCreatedTime: z.coerce
+            .date()
+            .optional()
+            .default(() => {
             const sevenDaysAgo = new Date();
             sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
             return sevenDaysAgo;
-        }).describe("Minimum created time for releases (default: 7 days ago)"),
-        maxCreatedTime: z.date().optional().default(() => new Date()).describe("Maximum created time for releases (default: now)"),
+        })
+            .describe("Minimum created time for releases (default: 7 days ago)"),
+        maxCreatedTime: z.coerce
+            .date()
+            .optional()
+            .default(() => new Date())
+            .describe("Maximum created time for releases (default: now)"),
         queryOrder: z.nativeEnum(ReleaseQueryOrder).optional().default(ReleaseQueryOrder.Ascending).describe("Order in which to return releases (default: Ascending)"),
         top: z.number().optional().describe("Number of releases to return"),
         continuationToken: z.number().optional().describe("Continuation token for pagination"),