@azure-devops/mcp 1.3.1-nightly.20250811 → 1.3.1-nightly.20250813

package/README.md

@@ -16,7 +16,7 @@ This TypeScript project provides a **local** MCP server for Azure DevOps, enabli
 3. [⚙️ Supported Tools](#️-supported-tools)
 4. [🔌 Installation & Getting Started](#-installation--getting-started)
 5. [📝 Troubleshooting](#-troubleshooting)
-6. [🎩 Examples & Best Practices](#-samples--best-practices)
+6. [🎩 Examples & Best Practices](#-examples--best-practices)
 7. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
 8. [📌 Contributing](#-contributing)
 
@@ -198,13 +198,13 @@ In your project, add a `.vscode\mcp.json` file with the following content:
 
 Save the file, then click 'Start'.
 
-<img src="./docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
+![start mcp server](./docs/media/start-mcp-server.gif)
 
 In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
 
 Click "Select Tools" and choose the available tools.
 
-<img src="./docs/media/configure-mcp-server-tools.gif" alt="configure mcp server tools" width="300"/>
+![configure mcp server tools](./docs/media/configure-mcp-server-tools.gif)
 
 Open GitHub Copilot Chat and try a prompt like `List ADO projects`.
 

package/dist/tools/testplans.js

@@ -79,7 +79,10 @@ function configureTestPlanTools(server, tokenProvider, connectionProvider) {
     server.tool(Test_Plan_Tools.create_test_case, "Creates a new test case work item.", {
         project: z.string().describe("The unique identifier (ID or name) of the Azure DevOps project."),
         title: z.string().describe("The title of the test case."),
-        steps: z.string().optional().describe("The steps to reproduce the test case. Make sure to format each step as '1. Step one|Expected result one\n2. Step two|Expected result two"),
+        steps: z
+            .string()
+            .optional()
+            .describe("The steps to reproduce the test case. Make sure to format each step as '1. Step one|Expected result one\n2. Step two|Expected result two. USE '|' as the delimiter between step and expected result. DO NOT use '|' in the description of the step or expected result."),
         priority: z.number().optional().describe("The priority of the test case."),
         areaPath: z.string().optional().describe("The area path for the test case."),
         iterationPath: z.string().optional().describe("The iteration path for the test case."),

package/dist/tools/workitems.js

@@ -23,6 +23,7 @@ const WORKITEM_TOOLS = {
     update_work_items_batch: "wit_update_work_items_batch",
     work_items_link: "wit_work_items_link",
     work_item_unlink: "wit_work_item_unlink",
+    add_artifact_link: "wit_add_artifact_link",
 };
 function getLinkTypeFromName(name) {
     switch (name.toLowerCase()) {
@@ -104,15 +105,29 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         // If no fields are provided, use the default set of fields
         const fieldsToUse = !fields || fields.length === 0 ? defaultFields : fields;
         const workitems = await workItemApi.getWorkItemsBatch({ ids, fields: fieldsToUse }, project);
-        // Format the assignedTo field to include displayName and uniqueName
+        // List of identity fields that need to be transformed from objects to formatted strings
+        const identityFields = [
+            "System.AssignedTo",
+            "System.CreatedBy",
+            "System.ChangedBy",
+            "System.AuthorizedAs",
+            "Microsoft.VSTS.Common.ActivatedBy",
+            "Microsoft.VSTS.Common.ResolvedBy",
+            "Microsoft.VSTS.Common.ClosedBy",
+        ];
+        // Format identity fields to include displayName and uniqueName
         // Removing the identity object as the response. It's too much and not needed
         if (workitems && Array.isArray(workitems)) {
             workitems.forEach((item) => {
-                if (item.fields && item.fields["System.AssignedTo"] && typeof item.fields["System.AssignedTo"] === "object") {
-                    const assignedTo = item.fields["System.AssignedTo"];
-                    const name = assignedTo.displayName || "";
-                    const email = assignedTo.uniqueName || "";
-                    item.fields["System.AssignedTo"] = `${name} <${email}>`.trim();
+                if (item.fields) {
+                    identityFields.forEach((fieldName) => {
+                        if (item.fields && item.fields[fieldName] && typeof item.fields[fieldName] === "object") {
+                            const identityField = item.fields[fieldName];
+                            const name = identityField.displayName || "";
+                            const email = identityField.uniqueName || "";
+                            item.fields[fieldName] = `${name} <${email}>`.trim();
+                        }
+                    });
                 }
             });
         }
@@ -658,5 +673,137 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             };
         }
     });
+    server.tool(WORKITEM_TOOLS.add_artifact_link, "Add artifact links (repository, branch, commit, builds) to work items. You can either provide the full vstfs URI or the individual components to build it automatically.", {
+        workItemId: z.number().describe("The ID of the work item to add the artifact link to."),
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        // Option 1: Provide full URI directly
+        artifactUri: z.string().optional().describe("The complete VSTFS URI of the artifact to link. If provided, individual component parameters are ignored."),
+        // Option 2: Provide individual components to build URI automatically based on linkType
+        projectId: z.string().optional().describe("The project ID (GUID) containing the artifact. Required for Git artifacts when artifactUri is not provided."),
+        repositoryId: z.string().optional().describe("The repository ID (GUID) containing the artifact. Required for Git artifacts when artifactUri is not provided."),
+        branchName: z.string().optional().describe("The branch name (e.g., 'main'). Required when linkType is 'Branch'."),
+        commitId: z.string().optional().describe("The commit SHA hash. Required when linkType is 'Fixed in Commit'."),
+        pullRequestId: z.number().optional().describe("The pull request ID. Required when linkType is 'Pull Request'."),
+        buildId: z.number().optional().describe("The build ID. Required when linkType is 'Build', 'Found in build', or 'Integrated in build'."),
+        linkType: z
+            .enum([
+            "Branch",
+            "Build",
+            "Fixed in Changeset",
+            "Fixed in Commit",
+            "Found in build",
+            "Integrated in build",
+            "Model Link",
+            "Pull Request",
+            "Related Workitem",
+            "Result Attachment",
+            "Source Code File",
+            "Tag",
+            "Test Result",
+            "Wiki",
+        ])
+            .default("Branch")
+            .describe("Type of artifact link, defaults to 'Branch'. This determines both the link type and how to build the VSTFS URI from individual components."),
+        comment: z.string().optional().describe("Comment to include with the artifact link."),
+    }, async ({ workItemId, project, artifactUri, projectId, repositoryId, branchName, commitId, pullRequestId, buildId, linkType, comment }) => {
+        try {
+            const connection = await connectionProvider();
+            const workItemTrackingApi = await connection.getWorkItemTrackingApi();
+            let finalArtifactUri;
+            if (artifactUri) {
+                // Use the provided full URI
+                finalArtifactUri = artifactUri;
+            }
+            else {
+                // Build the URI from individual components based on linkType
+                switch (linkType) {
+                    case "Branch":
+                        if (!projectId || !repositoryId || !branchName) {
+                            return {
+                                content: [{ type: "text", text: "For 'Branch' links, 'projectId', 'repositoryId', and 'branchName' are required." }],
+                                isError: true,
+                            };
+                        }
+                        finalArtifactUri = `vstfs:///Git/Ref/${encodeURIComponent(projectId)}%2F${encodeURIComponent(repositoryId)}%2FGB${encodeURIComponent(branchName)}`;
+                        break;
+                    case "Fixed in Commit":
+                        if (!projectId || !repositoryId || !commitId) {
+                            return {
+                                content: [{ type: "text", text: "For 'Fixed in Commit' links, 'projectId', 'repositoryId', and 'commitId' are required." }],
+                                isError: true,
+                            };
+                        }
+                        finalArtifactUri = `vstfs:///Git/Commit/${encodeURIComponent(projectId)}%2F${encodeURIComponent(repositoryId)}%2F${encodeURIComponent(commitId)}`;
+                        break;
+                    case "Pull Request":
+                        if (!projectId || !repositoryId || pullRequestId === undefined) {
+                            return {
+                                content: [{ type: "text", text: "For 'Pull Request' links, 'projectId', 'repositoryId', and 'pullRequestId' are required." }],
+                                isError: true,
+                            };
+                        }
+                        finalArtifactUri = `vstfs:///Git/PullRequestId/${encodeURIComponent(projectId)}%2F${encodeURIComponent(repositoryId)}%2F${encodeURIComponent(pullRequestId.toString())}`;
+                        break;
+                    case "Build":
+                    case "Found in build":
+                    case "Integrated in build":
+                        if (buildId === undefined) {
+                            return {
+                                content: [{ type: "text", text: `For '${linkType}' links, 'buildId' is required.` }],
+                                isError: true,
+                            };
+                        }
+                        finalArtifactUri = `vstfs:///Build/Build/${encodeURIComponent(buildId.toString())}`;
+                        break;
+                    default:
+                        return {
+                            content: [{ type: "text", text: `URI building from components is not supported for link type '${linkType}'. Please provide the full 'artifactUri' instead.` }],
+                            isError: true,
+                        };
+                }
+            }
+            // Create the patch document for adding an artifact link relation
+            const patchDocument = [
+                {
+                    op: "add",
+                    path: "/relations/-",
+                    value: {
+                        rel: "ArtifactLink",
+                        url: finalArtifactUri,
+                        attributes: {
+                            name: linkType,
+                            ...(comment && { comment }),
+                        },
+                    },
+                },
+            ];
+            // Use the WorkItem API to update the work item with the new relation
+            const workItem = await workItemTrackingApi.updateWorkItem({}, patchDocument, workItemId, project);
+            if (!workItem) {
+                return { content: [{ type: "text", text: "Work item update failed" }], isError: true };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            workItemId,
+                            artifactUri: finalArtifactUri,
+                            linkType,
+                            comment: comment || null,
+                            success: true,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [{ type: "text", text: `Error adding artifact link to work item: ${errorMessage}` }],
+                isError: true,
+            };
+        }
+    });
 }
 export { WORKITEM_TOOLS, configureWorkItemTools };

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "1.3.1-nightly.20250811";
+export const packageVersion = "1.3.1-nightly.20250813";

package/package.json

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