@azure-devops/mcp 1.1.0 → 1.2.0

package/dist/tools/workitems.js

@@ -1,7 +1,16 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
+import { QueryExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { z } from "zod";
-import { batchApiVersion } from "../utils.js";
+import { batchApiVersion, markdownCommentsApiVersion, getEnumKeys, safeEnumConvert } from "../utils.js";
+/**
+ * Converts Operation enum key to lowercase string for API usage
+ * @param operation The Operation enum key (e.g., "Add", "Replace", "Remove")
+ * @returns Lowercase string for API usage (e.g., "add", "replace", "remove")
+ */
+function operationToApiString(operation) {
+    return operation.toLowerCase();
+}
 const WORKITEM_TOOLS = {
     my_work_items: "wit_my_work_items",
     list_backlogs: "wit_list_backlogs",
@@ -42,6 +51,10 @@ function getLinkTypeFromName(name) {
             return "Microsoft.VSTS.Common.TestedBy-Forward";
         case "tests":
             return "Microsoft.VSTS.Common.TestedBy-Reverse";
+        case "affects":
+            return "Microsoft.VSTS.Common.Affects-Forward";
+        case "affected by":
+            return "Microsoft.VSTS.Common.Affects-Reverse";
         default:
             throw new Error(`Unknown link type: ${name}`);
     }
@@ -131,13 +144,30 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         project: z.string().describe("The name or ID of the Azure DevOps project."),
         workItemId: z.number().describe("The ID of the work item to add a comment to."),
         comment: z.string().describe("The text of the comment to add to the work item."),
-    }, async ({ project, workItemId, comment }) => {
+        format: z.enum(["markdown", "html"]).optional().default("html"),
+    }, async ({ project, workItemId, comment, format }) => {
         const connection = await connectionProvider();
-        const workItemApi = await connection.getWorkItemTrackingApi();
-        const commentCreate = { text: comment };
-        const commentResponse = await workItemApi.addComment(commentCreate, project, workItemId);
+        const orgUrl = connection.serverUrl;
+        const accessToken = await tokenProvider();
+        const body = {
+            text: comment,
+        };
+        const formatParameter = format === "markdown" ? 0 : 1;
+        const response = await fetch(`${orgUrl}/${project}/_apis/wit/workItems/${workItemId}/comments?format=${formatParameter}&api-version=${markdownCommentsApiVersion}`, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${accessToken.token}`,
+                "Content-Type": "application/json",
+                "User-Agent": userAgentProvider(),
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to add a work item comment: ${response.statusText}}`);
+        }
+        const comments = await response.text();
         return {
-            content: [{ type: "text", text: JSON.stringify(commentResponse, null, 2) }],
+            content: [{ type: "text", text: comments }],
         };
     });
     server.tool(WORKITEM_TOOLS.add_child_work_items, "Create one or many child work items from a parent by work item type and parent id.", {
@@ -200,6 +230,13 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                         value: item.areaPath,
                     });
                 }
+                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",
@@ -212,13 +249,6 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                         value: item.format,
                     });
                 }
-                if (item.iterationPath && item.iterationPath.trim().length > 0) {
-                    ops.push({
-                        op: "add",
-                        path: "/fields/System.IterationPath",
-                        value: item.iterationPath,
-                    });
-                }
                 return {
                     method: "PATCH",
                     uri: `/${project}/_apis/wit/workitems/$${workItemType}?api-version=${batchApiVersion}`,
@@ -254,17 +284,17 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         }
     });
     server.tool(WORKITEM_TOOLS.link_work_item_to_pull_request, "Link a single work item to an existing pull request.", {
-        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        projectId: z.string().describe("The project ID of the Azure DevOps project (note: project name is not valid)."),
         repositoryId: z.string().describe("The ID of the repository containing the pull request. Do not use the repository name here, use the ID instead."),
         pullRequestId: z.number().describe("The ID of the pull request to link to."),
         workItemId: z.number().describe("The ID of the work item to link to the pull request."),
-    }, async ({ project, repositoryId, pullRequestId, workItemId }) => {
+    }, async ({ projectId, repositoryId, pullRequestId, workItemId }) => {
         try {
             const connection = await connectionProvider();
             const workItemTrackingApi = await connection.getWorkItemTrackingApi();
             // Create artifact link relation using vstfs format
             // Format: vstfs:///Git/PullRequestId/{project}/{repositoryId}/{pullRequestId}
-            const artifactPathValue = `${project}/${repositoryId}/${pullRequestId}`;
+            const artifactPathValue = `${projectId}/${repositoryId}/${pullRequestId}`;
             const vstfsUrl = `vstfs:///Git/PullRequestId/${encodeURIComponent(artifactPathValue)}`;
             // Use the PATCH document format for adding a relation
             const patchDocument = [
@@ -281,7 +311,7 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                 },
             ];
             // Use the WorkItem API to update the work item with the new relation
-            const workItem = await workItemTrackingApi.updateWorkItem({}, patchDocument, workItemId, project);
+            const workItem = await workItemTrackingApi.updateWorkItem({}, patchDocument, workItemId, projectId);
             if (!workItem) {
                 return { content: [{ type: "text", text: "Work item update failed" }], isError: true };
             }
@@ -323,15 +353,20 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         id: z.number().describe("The ID of the work item to update."),
         updates: z
             .array(z.object({
-            op: z.enum(["add", "replace", "remove"]).default("add").describe("The operation to perform on the field."),
+            op: z.enum(["Add", "Replace", "Remove"]).default("Add").describe("The operation to perform on the field."),
             path: z.string().describe("The path of the field to update, e.g., '/fields/System.Title'."),
-            value: z.string().describe("The new value for the field. This is required for 'add' and 'replace' operations, and should be omitted for 'remove' operations."),
+            value: z.string().describe("The new value for the field. This is required for 'Add' and 'Replace' operations, and should be omitted for 'Remove' operations."),
         }))
             .describe("An array of field updates to apply to the work item."),
     }, async ({ id, updates }) => {
         const connection = await connectionProvider();
         const workItemApi = await connection.getWorkItemTrackingApi();
-        const updatedWorkItem = await workItemApi.updateWorkItem(null, updates, id);
+        // Convert operation names to lowercase for API
+        const apiUpdates = updates.map((update) => ({
+            ...update,
+            op: operationToApiString(update.op),
+        }));
+        const updatedWorkItem = await workItemApi.updateWorkItem(null, apiUpdates, id);
         return {
             content: [{ type: "text", text: JSON.stringify(updatedWorkItem, null, 2) }],
         };
@@ -351,17 +386,33 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         project: z.string().describe("The name or ID of the Azure DevOps project."),
         workItemType: z.string().describe("The type of work item to create, e.g., 'Task', 'Bug', etc."),
         fields: z
-            .record(z.string(), z.string())
-            .describe("A record of field names and values to set on the new work item. Each key is a field name, and each value is the corresponding value to set for that field."),
+            .array(z.object({
+            name: z.string().describe("The name of the field, e.g., 'System.Title'."),
+            value: z.string().describe("The value of the field."),
+            format: z.enum(["Html", "Markdown"]).optional().describe("the format of the field value, e.g., 'Html', 'Markdown'. Optional, defaults to 'Html'."),
+        }))
+            .describe("A record of field names and values to set on the new work item. Each fild is the field name and each value is the corresponding value to set for that field."),
     }, async ({ project, workItemType, fields }) => {
         try {
             const connection = await connectionProvider();
             const workItemApi = await connection.getWorkItemTrackingApi();
-            const document = Object.entries(fields).map(([key, value]) => ({
+            const document = fields.map(({ name, value }) => ({
                 op: "add",
-                path: `/fields/${key}`,
-                value,
+                path: `/fields/${name}`,
+                value: value,
             }));
+            // Check if any field has format === "Markdown" and add the multilineFieldsFormat operation
+            // this should only happen for large text fields, but since we dont't know by field name, lets assume if the users
+            // passes a value longer than 50 characters, then we can set the format to Markdown
+            fields.forEach(({ name, value, format }) => {
+                if (value.length > 50 && format === "Markdown") {
+                    document.push({
+                        op: "add",
+                        path: `/multilineFieldsFormat/${name}`,
+                        value: "Markdown",
+                    });
+                }
+            });
             const newWorkItem = await workItemApi.createWorkItem(null, document, project, workItemType);
             if (!newWorkItem) {
                 return { content: [{ type: "text", text: "Work item was not created" }], isError: true };
@@ -381,14 +432,17 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
     server.tool(WORKITEM_TOOLS.get_query, "Get a query by its ID or path.", {
         project: z.string().describe("The name or ID of the Azure DevOps project."),
         query: z.string().describe("The ID or path of the query to retrieve."),
-        expand: z.enum(["all", "clauses", "minimal", "none", "wiql"]).optional().describe("Optional expand parameter to include additional details in the response. Defaults to 'none'."),
+        expand: z
+            .enum(getEnumKeys(QueryExpand))
+            .optional()
+            .describe("Optional expand parameter to include additional details in the response. Defaults to 'None'."),
         depth: z.number().default(0).describe("Optional depth parameter to specify how deep to expand the query. Defaults to 0."),
         includeDeleted: z.boolean().default(false).describe("Whether to include deleted items in the query results. Defaults to false."),
         useIsoDateFormat: z.boolean().default(false).describe("Whether to use ISO date format in the response. Defaults to false."),
     }, async ({ project, query, expand, depth, includeDeleted, useIsoDateFormat }) => {
         const connection = await connectionProvider();
         const workItemApi = await connection.getWorkItemTrackingApi();
-        const queryDetails = await workItemApi.getQuery(project, query, expand, depth, includeDeleted, useIsoDateFormat);
+        const queryDetails = await workItemApi.getQuery(project, query, safeEnumConvert(QueryExpand, expand), depth, includeDeleted, useIsoDateFormat);
         return {
             content: [{ type: "text", text: JSON.stringify(queryDetails, null, 2) }],
         };
@@ -411,10 +465,11 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
     server.tool(WORKITEM_TOOLS.update_work_items_batch, "Update work items in batch", {
         updates: z
             .array(z.object({
-            op: z.enum(["add", "replace", "remove"]).default("add").describe("The operation to perform on the field."),
+            op: z.enum(["Add", "Replace", "Remove"]).default("Add").describe("The operation to perform on the field."),
             id: z.number().describe("The ID of the work item to update."),
             path: z.string().describe("The path of the field to update, e.g., '/fields/System.Title'."),
             value: z.string().describe("The new value for the field. This is required for 'add' and 'replace' operations, and should be omitted for 'remove' operations."),
+            format: z.enum(["Html", "Markdown"]).optional().describe("The format of the field value. Only to be used for large text fields. e.g., 'Html', 'Markdown'. Optional, defaults to 'Html'."),
         }))
             .describe("An array of updates to apply to work items. Each update should include the operation (op), work item ID (id), field path (path), and new value (value)."),
     }, async ({ updates }) => {
@@ -423,20 +478,32 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         const accessToken = await tokenProvider();
         // Extract unique IDs from the updates array
         const uniqueIds = Array.from(new Set(updates.map((update) => update.id)));
-        const body = uniqueIds.map((id) => ({
-            method: "PATCH",
-            uri: `/_apis/wit/workitems/${id}?api-version=${batchApiVersion}`,
-            headers: {
-                "Content-Type": "application/json-patch+json",
-            },
-            body: updates
-                .filter((update) => update.id === id)
-                .map(({ op, path, value }) => ({
+        const body = uniqueIds.map((id) => {
+            const workItemUpdates = updates.filter((update) => update.id === id);
+            const operations = workItemUpdates.map(({ op, path, value }) => ({
                 op: op,
                 path: path,
                 value: value,
-            })),
-        }));
+            }));
+            // Add format operations for Markdown fields
+            workItemUpdates.forEach(({ path, value, format }) => {
+                if (format === "Markdown" && value && value.length > 50) {
+                    operations.push({
+                        op: "Add",
+                        path: `/multilineFieldsFormat${path.replace("/fields", "")}`,
+                        value: "Markdown",
+                    });
+                }
+            });
+            return {
+                method: "PATCH",
+                uri: `/_apis/wit/workitems/${id}?api-version=${batchApiVersion}`,
+                headers: {
+                    "Content-Type": "application/json-patch+json",
+                },
+                body: operations,
+            };
+        });
         const response = await fetch(`${orgUrl}/_apis/wit/$batch?api-version=${batchApiVersion}`, {
             method: "PATCH",
             headers: {
@@ -461,9 +528,9 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             id: z.number().describe("The ID of the work item to update."),
             linkToId: z.number().describe("The ID of the work item to link to."),
             type: z
-                .enum(["parent", "child", "duplicate", "duplicate of", "related", "successor", "predecessor", "tested by", "tests"])
+                .enum(["parent", "child", "duplicate", "duplicate of", "related", "successor", "predecessor", "tested by", "tests", "affects", "affected by"])
                 .default("related")
-                .describe("Type of link to create between the work items. Options include 'parent', 'child', 'duplicate', 'duplicate of', 'related', 'successor', 'predecessor', 'tested by', 'tests', 'referenced by', and 'references'. Defaults to 'related'."),
+                .describe("Type of link to create between the work items. Options include 'parent', 'child', 'duplicate', 'duplicate of', 'related', 'successor', 'predecessor', 'tested by', 'tests', 'affects', and 'affected by'. Defaults to 'related'."),
             comment: z.string().optional().describe("Optional comment to include with the link. This can be used to provide additional context for the link being created."),
         }))
             .describe(""),

package/dist/useragent.js

@@ -1,3 +1,5 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
 class UserAgentComposer {
     _userAgent;
     _mcpClientInfoAppended;

package/dist/utils.js

@@ -2,3 +2,29 @@
 // Licensed under the MIT License.
 export const apiVersion = "7.2-preview.1";
 export const batchApiVersion = "5.0";
+export const markdownCommentsApiVersion = "7.2-preview.4";
+/**
+ * Converts a TypeScript numeric enum to an array of string keys for use with z.enum().
+ * This ensures that enum schemas generate string values rather than numeric values.
+ * @param enumObject The TypeScript enum object
+ * @returns Array of string keys from the enum
+ */
+export function getEnumKeys(enumObject) {
+    return Object.keys(enumObject).filter((key) => isNaN(Number(key)));
+}
+/**
+ * Safely converts a string enum key to its corresponding enum value.
+ * Validates that the key exists in the enum before conversion.
+ * @param enumObject The TypeScript enum object
+ * @param key The string key to convert
+ * @returns The enum value if key is valid, undefined otherwise
+ */
+export function safeEnumConvert(enumObject, key) {
+    if (!key)
+        return undefined;
+    const validKeys = getEnumKeys(enumObject);
+    if (!validKeys.includes(key)) {
+        return undefined;
+    }
+    return enumObject[key];
+}

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "1.1.0";
+export const packageVersion = "1.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-devops/mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server for interacting with Azure DevOps",
   "license": "MIT",
   "author": "Microsoft Corporation",
@@ -26,7 +26,7 @@
     "build": "tsc && shx chmod +x dist/*.js",
     "prepare": "npm run build",
     "watch": "tsc --watch",
-    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "inspect": "ALLOWED_ORIGINS=http://127.0.0.1:6274 npx @modelcontextprotocol/inspector node dist/index.js",
     "start": "node -r tsconfig-paths/register dist/index.js",
     "eslint": "eslint",
     "eslint-fix": "eslint --fix",
@@ -37,18 +37,19 @@
   },
   "dependencies": {
     "@azure/identity": "^4.10.0",
-    "@modelcontextprotocol/sdk": "1.13.2",
+    "@modelcontextprotocol/sdk": "1.16.0",
     "azure-devops-extension-api": "^4.252.0",
     "azure-devops-extension-sdk": "^4.0.2",
     "azure-devops-node-api": "^15.1.0",
+    "yargs": "^18.0.0",
     "zod": "^3.25.63",
     "zod-to-json-schema": "^3.24.5"
   },
   "devDependencies": {
-    "@modelcontextprotocol/inspector": "^0.15.0",
+    "@modelcontextprotocol/inspector": "^0.16.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^22",
-    "eslint-config-prettier": "10.1.5",
+    "eslint-config-prettier": "10.1.8",
     "eslint-plugin-header": "^3.1.1",
     "jest": "^30.0.2",
     "jest-extended": "^6.0.0",