@azure-devops/mcp 2.9.0 → 2.10.0

package/dist/tools/work-items.js

@@ -8,6 +8,7 @@ import { z } from "zod";
 import { batchApiVersion, markdownCommentsApiVersion, getEnumKeys, safeEnumConvert, encodeFormattedValue } from "../utils.js";
 import { elicitProject, elicitTeam } from "../shared/elicitations.js";
 import { createExternalContentResponse } from "../shared/content-safety.js";
+import { getUserIdentityFromEmail } from "./auth.js";
 const WORKITEM_TOOLS = {
     wit_work_item: "wit_work_item",
     wit_query: "wit_query",
@@ -43,6 +44,8 @@ function getLinkTypeFromName(name) {
             return "Microsoft.VSTS.Common.Affects-Reverse";
         case "artifact":
             return "ArtifactLink";
+        case "hyperlink":
+            return "Hyperlink";
         default:
             throw new Error(`Unknown link type: ${name}`);
     }
@@ -55,6 +58,36 @@ function getArtifactLinkAttributeName(linkType) {
             return linkType;
     }
 }
+function escapeHtml(value) {
+    const entities = {
+        "&": "&",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+    };
+    return value.replace(/[&<>"']/g, (character) => entities[character]);
+}
+async function resolveCommentMentions(text, format, tokenProvider, connectionProvider, userAgentProvider) {
+    const emailMatches = [...text.matchAll(/@<([^<>\s]+@[^<>\s]+)>/g)];
+    if (emailMatches.length === 0)
+        return text;
+    const identities = new Map();
+    for (const email of new Set(emailMatches.map((match) => match[1]))) {
+        try {
+            identities.set(email, await getUserIdentityFromEmail(email, tokenProvider, connectionProvider, userAgentProvider));
+        }
+        catch {
+            // Leave mentions unchanged when their identities cannot be resolved.
+        }
+    }
+    return text.replace(/@<([^<>\s]+@[^<>\s]+)>/g, (mention, email) => {
+        const identity = identities.get(email);
+        if (!identity)
+            return escapeHtml(mention);
+        return format === "Markdown" || format === undefined ? `@<${identity.id}>` : `<a href="#" data-vss-mention="version:2.0,${identity.id}">@${escapeHtml(identity.displayName)}</a>`;
+    });
+}
 function configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider) {
     // --- wit_work_item ----------------------------------------------------------
     server.tool(WORKITEM_TOOLS.wit_work_item, "Retrieve work item data for a project. Use the action parameter to specify the operation.", {
@@ -309,11 +342,24 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
     });
     // --- wit_backlog ------------------------------------------------------------
     server.tool(WORKITEM_TOOLS.wit_backlog, "Retrieve backlog data for a project and team. Use the action parameter to specify the operation.", {
-        action: z.enum(["list", "list_work_items"]).describe("The action to perform. Options: list (list backlog levels for a team), list_work_items (list work items in a specific backlog level)."),
+        action: z
+            .enum(["list", "list_work_items", "reorder"])
+            .describe("The action to perform. Options: list (list backlog levels for a team), list_work_items (list work items in a specific backlog level), reorder (move work items to a new position in a backlog or iteration)."),
         project: z.string().optional().describe("The name or ID of the Azure DevOps project. Reuse from prior context if already known. If not provided, a project selection prompt will be shown."),
         team: z.string().optional().describe("The name or ID of the Azure DevOps team. Reuse from prior context if already known. If not provided, a team selection prompt will be shown."),
         backlogId: z.string().optional().describe("The ID of the backlog category to retrieve work items from. Required for: list_work_items."),
-    }, async ({ action, project, team, backlogId }) => {
+        ids: z.array(z.coerce.number().int().min(1)).min(1).optional().describe("The IDs of the work items to reorder. Required for: reorder."),
+        previousId: z.coerce
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("The ID of the work item that should be before the reordered items. Use 0 to specify the beginning of the list. Optional for: reorder."),
+        nextId: z.coerce.number().int().min(0).optional().describe("The ID of the work item that should be after the reordered items. Use 0 to specify the end of the list. Optional for: reorder."),
+        parentId: z.coerce.number().int().min(0).optional().describe("The parent ID for all work items involved in the operation. Use 0 to indicate the items have no parent. Optional for: reorder."),
+        iterationPath: z.string().optional().describe("The iteration path for the reorder operation. Used when reordering items in an iteration backlog. Optional for: reorder."),
+        iterationId: z.string().optional().describe("The iteration ID. When provided, reorder items in that iteration instead of the team backlog. Used for: reorder."),
+    }, async ({ action, project, team, backlogId, ids, previousId, nextId, parentId, iterationPath, iterationId }) => {
         try {
             const connection = await connectionProvider();
             let resolvedProject = project;
@@ -344,6 +390,13 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                 const workItems = await workApi.getBacklogLevelWorkItems(teamContext, backlogId);
                 return { content: [{ type: "text", text: JSON.stringify(workItems, null, 2) }] };
             }
+            if (action === "reorder") {
+                if (!ids?.length)
+                    return { content: [{ type: "text", text: "ids is required for reorder" }], isError: true };
+                const operation = { ids, previousId, nextId, parentId, iterationPath };
+                const reorderedItems = iterationId ? await workApi.reorderIterationWorkItems(operation, teamContext, iterationId) : await workApi.reorderBacklogWorkItems(operation, teamContext);
+                return { content: [{ type: "text", text: JSON.stringify(reorderedItems, null, 2) }] };
+            }
             return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
         }
         catch (error) {
@@ -351,6 +404,7 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             const msgs = {
                 list: `Error listing backlogs: ${errorMessage}`,
                 list_work_items: `Error listing backlog work items: ${errorMessage}`,
+                reorder: `Error reordering backlog work items: ${errorMessage}`,
             };
             return { content: [{ type: "text", text: msgs[action] ?? `Error: ${errorMessage}` }], isError: true };
         }
@@ -404,9 +458,7 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             }
             const mimeType = getMimeType(fileName);
             if (mimeType.startsWith("text/")) {
-                return {
-                    content: [{ type: "text", text: buffer.toString("utf-8") }],
-                };
+                return createExternalContentResponse(buffer.toString("utf-8"), "work item attachment");
             }
             const base64Data = buffer.toString("base64");
             return {
@@ -451,14 +503,17 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             op: z
                 .string()
                 .transform((val) => val.toLowerCase())
-                .pipe(z.enum(["add", "replace", "remove"]))
+                .pipe(z.enum(["add", "replace", "remove", "test"]))
                 .default("add")
-                .describe("The operation to perform."),
-            path: z.string().describe("The field path, e.g. '/fields/System.Title'."),
-            value: z.string().describe("The new value for the field."),
+                .describe("The operation to perform. Use 'test' with path '/rev' to enforce optimistic concurrency."),
+            path: z.string().describe("The path to operate on, e.g. '/fields/System.Title' or '/rev' for a revision test."),
+            value: z
+                .union([z.string(), z.number(), z.boolean(), z.null()])
+                .optional()
+                .describe("The operation value. Required for add, replace, and test; omit for remove. For a test on '/rev', pass the numeric revision previously read."),
         }))
             .optional()
-            .describe("Field updates for a single work item. Required for: update."),
+            .describe('Field updates for a single work item. Required for: update. For a safe read-modify-write, prepend a test operation on "/rev" with value set to the numeric revision returned by the preceding read; Azure DevOps rejects the entire update if the current revision differs.'),
         batchUpdates: z
             .array(z.object({
             op: z.enum(["Add", "Replace", "Remove"]).default("Add").describe("The operation to perform."),
@@ -521,6 +576,10 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                     return { content: [{ type: "text", text: "id is required for update" }], isError: true };
                 if (!updates || updates.length === 0)
                     return { content: [{ type: "text", text: "updates is required for update" }], isError: true };
+                const updateWithoutValue = updates.find((update) => update.op !== "remove" && update.value === undefined);
+                if (updateWithoutValue) {
+                    return { content: [{ type: "text", text: `value is required for ${updateWithoutValue.op}` }], isError: true };
+                }
                 const workItemApi = await connection.getWorkItemTrackingApi();
                 const apiUpdates = updates.map((update) => ({ ...update, op: update.op }));
                 const updatedWorkItem = await workItemApi.updateWorkItem(null, apiUpdates, id);
@@ -593,8 +652,6 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                     const ops = [
                         { op: "add", path: "/id", value: `-${x + 1}` },
                         { op: "add", path: "/fields/System.Title", value: item.title },
-                        { op: "add", path: "/fields/System.Description", value: encodedDescription },
-                        { op: "add", path: "/fields/Microsoft.VSTS.TCM.ReproSteps", value: encodedDescription },
                         {
                             op: "add",
                             path: "/relations/-",
@@ -610,9 +667,19 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                     if (item.iterationPath && item.iterationPath.trim().length > 0) {
                         ops.push({ op: "add", path: "/fields/System.IterationPath", value: item.iterationPath });
                     }
-                    if (item.format && item.format === "Markdown") {
-                        ops.push({ op: "add", path: "/multilineFieldsFormat/System.Description", value: item.format });
-                        ops.push({ op: "add", path: "/multilineFieldsFormat/Microsoft.VSTS.TCM.ReproSteps", value: item.format });
+                    // check if the work item type is "Bug" to determine which field to use for the description
+                    // ReproSteps is used for Bugs, while Description is used for other work item types
+                    if (workItemType.toLowerCase() === "bug") {
+                        ops.push({ op: "add", path: "/fields/Microsoft.VSTS.TCM.ReproSteps", value: encodedDescription });
+                        if (item.format && item.format === "Markdown") {
+                            ops.push({ op: "add", path: "/multilineFieldsFormat/Microsoft.VSTS.TCM.ReproSteps", value: item.format });
+                        }
+                    }
+                    else {
+                        ops.push({ op: "add", path: "/fields/System.Description", value: encodedDescription });
+                        if (item.format && item.format === "Markdown") {
+                            ops.push({ op: "add", path: "/multilineFieldsFormat/System.Description", value: item.format });
+                        }
                     }
                     return {
                         method: "PATCH",
@@ -641,9 +708,12 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            const statusCode = typeof error === "object" && error !== null && "statusCode" in error && typeof error.statusCode === "number" ? error.statusCode : undefined;
+            const statusText = statusCode === 409 ? " Conflict" : statusCode === 412 ? " Precondition Failed" : "";
+            const updateStatus = statusCode !== undefined ? ` [HTTP ${statusCode}${statusText}]` : "";
             const msgs = {
                 create: `Error creating work item: ${errorMessage}`,
-                update: `Error updating work item: ${errorMessage}`,
+                update: `Error updating work item${updateStatus}: ${errorMessage}`,
                 update_batch: `Error updating work items in batch: ${errorMessage}`,
                 add_child: `Error creating child work items: ${errorMessage}`,
             };
@@ -676,6 +746,7 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             const orgUrl = connection.serverUrl;
             const accessToken = await tokenProvider();
             const formatParameter = (format ?? "Markdown") === "Markdown" ? 0 : 1;
+            const resolvedText = await resolveCommentMentions(text, format, tokenProvider, connectionProvider, userAgentProvider);
             if (action === "add") {
                 const response = await fetch(`${orgUrl}/${encodeURIComponent(resolvedProject)}/_apis/wit/workItems/${workItemId}/comments?format=${formatParameter}&api-version=${markdownCommentsApiVersion}`, {
                     method: "POST",
@@ -684,7 +755,7 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                         "Content-Type": "application/json",
                         "User-Agent": userAgentProvider(),
                     },
-                    body: JSON.stringify({ text }),
+                    body: JSON.stringify({ text: resolvedText }),
                 });
                 if (!response.ok) {
                     throw new Error(`Failed to add a work item comment: ${response.statusText}`);
@@ -701,7 +772,7 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                         "Content-Type": "application/json",
                         "User-Agent": userAgentProvider(),
                     },
-                    body: JSON.stringify({ text }),
+                    body: JSON.stringify({ text: resolvedText }),
                 });
                 if (!response.ok) {
                     throw new Error(`Failed to update work item comment: ${response.statusText}`);
@@ -729,9 +800,10 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         updates: z
             .array(z.object({
             id: z.coerce.number().min(1).describe("The ID of the work item to update."),
-            linkToId: z.coerce.number().min(1).describe("The ID of the work item to link to."),
+            linkToId: z.coerce.number().min(1).optional().describe("The ID of the work item to link to. Required unless type is 'hyperlink'."),
+            url: z.string().optional().describe("The URL for a hyperlink. Required when type is 'hyperlink'."),
             type: z
-                .enum(["parent", "child", "duplicate", "duplicate of", "related", "successor", "predecessor", "tested by", "tests", "affects", "affected by"])
+                .enum(["parent", "child", "duplicate", "duplicate of", "related", "successor", "predecessor", "tested by", "tests", "affects", "affected by", "hyperlink"])
                 .default("related")
                 .describe("Type of link. Defaults to 'related'."),
             comment: z.string().optional().describe("Optional comment for the link."),
@@ -741,7 +813,7 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         // unlink
         id: z.coerce.number().min(1).optional().describe("Work item ID to remove links from. Required for: unlink."),
         type: z
-            .enum(["parent", "child", "duplicate", "duplicate of", "related", "successor", "predecessor", "tested by", "tests", "affects", "affected by", "artifact"])
+            .enum(["parent", "child", "duplicate", "duplicate of", "related", "successor", "predecessor", "tested by", "tests", "affects", "affected by", "artifact", "hyperlink"])
             .optional()
             .describe("Link type to remove. Required for: unlink."),
         url: z.string().optional().describe("URL to match when removing a link. Used for: unlink. If not provided, all links of the specified type are removed."),
@@ -801,15 +873,23 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                     headers: { "Content-Type": "application/json-patch+json" },
                     body: updates
                         .filter((update) => update.id === uid)
-                        .map(({ linkToId, type: linkTypeName, comment: linkComment }) => ({
-                        op: "add",
-                        path: "/relations/-",
-                        value: {
-                            rel: `${getLinkTypeFromName(linkTypeName)}`,
-                            url: `${orgUrl}/${resolvedProject}/_apis/wit/workItems/${linkToId}`,
-                            attributes: { comment: linkComment || "" },
-                        },
-                    })),
+                        .map(({ linkToId, url: linkUrl, type: linkTypeName, comment: linkComment }) => {
+                        if (linkTypeName === "hyperlink" && !linkUrl) {
+                            throw new Error("url is required for hyperlink links");
+                        }
+                        if (linkTypeName !== "hyperlink" && !linkToId) {
+                            throw new Error("linkToId is required for work item links");
+                        }
+                        return {
+                            op: "add",
+                            path: "/relations/-",
+                            value: {
+                                rel: getLinkTypeFromName(linkTypeName),
+                                url: linkTypeName === "hyperlink" ? linkUrl : `${orgUrl}/${resolvedProject}/_apis/wit/workItems/${linkToId}`,
+                                attributes: { comment: linkComment || "" },
+                            },
+                        };
+                    }),
                 }));
                 const response = await fetch(`${orgUrl}/_apis/wit/$batch?api-version=${batchApiVersion}`, {
                     method: "PATCH",

package/dist/tools.js

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
+import { wrapExternalToolResponse } from "./shared/content-safety.js";
 import { Domain } from "./shared/domains.js";
 import { configureAdvSecTools } from "./tools/advanced-security.js";
 import { configureMcpAppsTools } from "./tools/mcp-apps.js";
@@ -14,11 +15,13 @@ import { configureWorkItemTools } from "./tools/work-items.js";
 function configureAllTools(server, tokenProvider, connectionProvider, userAgentProvider, enabledDomains) {
     const configureIfDomainEnabled = (domain, configureFn) => {
         if (enabledDomains.has(domain)) {
-            configureFn();
+            configureToolsWithContentSafety(server, domain, configureFn);
         }
     };
     configureIfDomainEnabled(Domain.CORE, () => configureCoreTools(server, tokenProvider, connectionProvider, userAgentProvider));
-    configureIfDomainEnabled(Domain.MCP_APPS, () => configureMcpAppsTools(server));
+    // This is a local health-check response and contains no Azure DevOps content.
+    if (enabledDomains.has(Domain.MCP_APPS))
+        configureMcpAppsTools(server);
     configureIfDomainEnabled(Domain.WORK, () => configureWorkTools(server, tokenProvider, connectionProvider));
     configureIfDomainEnabled(Domain.PIPELINES, () => configurePipelineTools(server, tokenProvider, connectionProvider, userAgentProvider));
     configureIfDomainEnabled(Domain.REPOSITORIES, () => configureRepoTools(server, tokenProvider, connectionProvider, userAgentProvider));
@@ -28,4 +31,34 @@ function configureAllTools(server, tokenProvider, connectionProvider, userAgentP
     configureIfDomainEnabled(Domain.SEARCH, () => configureSearchTools(server, tokenProvider, connectionProvider, userAgentProvider));
     configureIfDomainEnabled(Domain.ADVANCED_SECURITY, () => configureAdvSecTools(server, tokenProvider, connectionProvider));
 }
+/**
+ * Centralizes the untrusted-content boundary for tool responses. Tool registration
+ * is synchronous, so the original method is restored before this function returns.
+ */
+function configureToolsWithContentSafety(server, domain, configureFn) {
+    const originalTool = server.tool;
+    const originalRegisterTool = server.registerTool;
+    const wrapRegistrationMethod = (registrationMethod) => new Proxy(registrationMethod, {
+        apply(target, thisArg, argumentsList) {
+            const callbackIndex = argumentsList.length - 1;
+            const callback = argumentsList[callbackIndex];
+            if (typeof callback === "function") {
+                argumentsList[callbackIndex] = async (...callbackArgs) => {
+                    const response = (await Reflect.apply(callback, undefined, callbackArgs));
+                    return wrapExternalToolResponse(response, `Azure DevOps ${domain}`);
+                };
+            }
+            return Reflect.apply(target, thisArg, argumentsList);
+        },
+    });
+    server.tool = wrapRegistrationMethod(originalTool);
+    server.registerTool = wrapRegistrationMethod(originalRegisterTool);
+    try {
+        configureFn();
+    }
+    finally {
+        server.tool = originalTool;
+        server.registerTool = originalRegisterTool;
+    }
+}
 export { configureAllTools };

package/dist/utils.js

@@ -3,6 +3,19 @@
 export const apiVersion = "7.2-preview.1";
 export const batchApiVersion = "5.0";
 export const markdownCommentsApiVersion = "7.2-preview.4";
+/**
+ * Returns the user-supplied CLI arguments.
+ *
+ * The server is always started script-style — `[runtime, scriptPath, ...args]` — on Node
+ * and on Electron hosts alike, so the first two entries are always dropped.
+ *
+ * Do not replace this with yargs' `hideBin`: it drops a single entry whenever
+ * `process.versions.electron` is set and `process.defaultApp` is not, so on an Electron
+ * host the script path survives and is parsed as the organization name.
+ */
+export function getCliArgs(argv = process.argv) {
+    return argv.slice(2);
+}
 export function createEnumMapping(enumObject) {
     const mapping = {};
     for (const [key, value] of Object.entries(enumObject)) {

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "2.9.0";
+export const packageVersion = "2.10.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-devops/mcp",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "mcpName": "microsoft.com/azure-devops",
   "description": "MCP server for interacting with Azure DevOps",
   "license": "MIT",
@@ -37,12 +37,15 @@
     "test": "jest"
   },
   "dependencies": {
-    "@azure/identity": "^4.10.0",
-    "@azure/msal-node": "^5.0.6",
+    "@azure/identity": "^4.13.0",
+    "@azure/logger": "^1.3.0",
+    "@azure/msal-node": "^5.5.0",
+    "@azure/msal-node-extensions": "^5.3.5",
     "@modelcontextprotocol/sdk": "1.29.0",
     "azure-devops-extension-api": "^5.272.3",
     "azure-devops-extension-sdk": "^4.0.2",
     "azure-devops-node-api": "^15.1.2",
+    "open": "^10.2.0",
     "winston": "^3.18.3",
     "yargs": "^18.0.0",
     "zod": "^3.25.63",
@@ -69,5 +72,9 @@
     "**/*.(js|ts|jsx|tsx|json|css|md)": [
       "npm run format"
     ]
+  },
+  "allowScripts": {
+    "keytar@7.9.0": true,
+    "@azure/msal-node-extensions@5.3.5": true
   }
 }