@azure-devops/mcp 1.2.0 → 1.3.0

package/dist/tools/workitem.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "@jest/globals";
+import { configureWorkItemTools } from "../../../src/tools/workitems";
+describe("configureWorkItemTools", () => {
+    let server;
+    let tokenProvider;
+    let connectionProvider;
+    let mockConnection;
+    let mockWorkApi;
+    let mockWorkItemTrackingApi;
+    beforeEach(() => {
+        server = { tool: jest.fn() };
+        tokenProvider = jest.fn();
+        mockWorkApi = {
+            getBacklogs: jest.fn(),
+            getPredefinedQueryResults: jest.fn(),
+            getTeamIterations: jest.fn(),
+            getIterationWorkItems: jest.fn(),
+        };
+        mockWorkItemTrackingApi = {
+            getWorkItemsBatch: jest.fn(),
+            getWorkItem: jest.fn(),
+            getComments: jest.fn(),
+            addComment: jest.fn(),
+            updateWorkItem: jest.fn(),
+            createWorkItem: jest.fn(),
+            getWorkItemType: jest.fn(),
+            getQuery: jest.fn(),
+            queryById: jest.fn(),
+        };
+        mockConnection = {
+            getWorkApi: jest.fn().mockResolvedValue(mockWorkApi),
+            getWorkItemTrackingApi: jest.fn().mockResolvedValue(mockWorkItemTrackingApi),
+        };
+        connectionProvider = jest.fn().mockResolvedValue(mockConnection);
+    });
+    describe("tool registration", () => {
+        it("registers core tools on the server", () => {
+            configureWorkItemTools(server, tokenProvider, connectionProvider);
+            expect(server.tool).toHaveBeenCalled();
+        });
+    });
+    describe("list_backlogs tool", () => {
+        it("should call getBacklogs API with the correct parameters and return the expected result", async () => {
+            configureWorkItemTools(server, tokenProvider, connectionProvider);
+            const call = server.tool.mock.calls.find(([toolName]) => toolName === "ado_list_backlogs");
+            if (!call)
+                throw new Error("ado_list_backlogs tool not registered");
+            const [, , , handler] = call;
+            mockWorkApi.getBacklogs.mockResolvedValue([
+                {
+                    id: "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
+                    name: "Fabrikam-Fiber-TFVC",
+                    description: "Team Foundation Version Control projects.",
+                    url: "https://dev.azure.com/fabrikam/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
+                    state: "wellFormed",
+                },
+                {
+                    id: "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
+                    name: "Fabrikam-Fiber-Git",
+                    description: "Git projects",
+                    url: "https://dev.azure.com/fabrikam/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
+                    state: "wellFormed",
+                },
+                {
+                    id: "281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
+                    name: "TestGit",
+                    url: "https://dev.azure.com/fabrikam/_apis/projects/281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
+                    state: "wellFormed",
+                },
+            ]);
+            const params = {
+                project: "Contoso",
+                team: "Fabrikam",
+            };
+            const result = await handler(params);
+            expect(mockWorkApi.getBacklogs).toHaveBeenCalledWith({ project: "Contoso", team: "Fabrikam" });
+            expect(result.content[0].text).toBe(JSON.stringify([
+                {
+                    id: "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
+                    name: "Fabrikam-Fiber-TFVC",
+                    description: "Team Foundation Version Control projects.",
+                    url: "https://dev.azure.com/fabrikam/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
+                    state: "wellFormed",
+                },
+                {
+                    id: "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
+                    name: "Fabrikam-Fiber-Git",
+                    description: "Git projects",
+                    url: "https://dev.azure.com/fabrikam/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
+                    state: "wellFormed",
+                },
+                {
+                    id: "281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
+                    name: "TestGit",
+                    url: "https://dev.azure.com/fabrikam/_apis/projects/281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
+                    state: "wellFormed",
+                },
+            ], null, 2));
+        });
+    });
+});

package/dist/tools/workitems.js

@@ -1,16 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
+import { WorkItemExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { QueryExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { z } from "zod";
 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",
@@ -28,8 +21,8 @@ const WORKITEM_TOOLS = {
     get_query: "wit_get_query",
     get_query_results_by_id: "wit_get_query_results_by_id",
     update_work_items_batch: "wit_update_work_items_batch",
-    close_and_link_workitem_duplicates: "wit_close_and_link_workitem_duplicates",
     work_items_link: "wit_work_items_link",
+    work_item_unlink: "wit_work_item_unlink",
 };
 function getLinkTypeFromName(name) {
     switch (name.toLowerCase()) {
@@ -55,6 +48,8 @@ function getLinkTypeFromName(name) {
             return "Microsoft.VSTS.Common.Affects-Forward";
         case "affected by":
             return "Microsoft.VSTS.Common.Affects-Reverse";
+        case "artifact":
+            return "ArtifactLink";
         default:
             throw new Error(`Unknown link type: ${name}`);
     }
@@ -104,8 +99,20 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
     }, async ({ project, ids }) => {
         const connection = await connectionProvider();
         const workItemApi = await connection.getWorkItemTrackingApi();
-        const fields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.Parent", "System.Tags"];
+        const fields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.Parent", "System.Tags", "Microsoft.VSTS.Common.StackRank", "System.AssignedTo"];
         const workitems = await workItemApi.getWorkItemsBatch({ ids, fields }, project);
+        // Format the assignedTo field 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();
+                }
+            });
+        }
         return {
             content: [{ type: "text", text: JSON.stringify(workitems, null, 2) }],
         };
@@ -288,13 +295,15 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         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 ({ projectId, repositoryId, pullRequestId, workItemId }) => {
+        pullRequestProjectId: z.string().optional().describe("The project ID containing the pull request. If not provided, defaults to the work item's project ID (for same-project linking)."),
+    }, async ({ projectId, repositoryId, pullRequestId, workItemId, pullRequestProjectId }) => {
         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 = `${projectId}/${repositoryId}/${pullRequestId}`;
+            const artifactProjectId = pullRequestProjectId && pullRequestProjectId.trim() !== "" ? pullRequestProjectId : projectId;
+            const artifactPathValue = `${artifactProjectId}/${repositoryId}/${pullRequestId}`;
             const vstfsUrl = `vstfs:///Git/PullRequestId/${encodeURIComponent(artifactPathValue)}`;
             // Use the PATCH document format for adding a relation
             const patchDocument = [
@@ -353,7 +362,12 @@ 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
+                .string()
+                .transform((val) => val.toLowerCase())
+                .pipe(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."),
         }))
@@ -364,7 +378,7 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         // Convert operation names to lowercase for API
         const apiUpdates = updates.map((update) => ({
             ...update,
-            op: operationToApiString(update.op),
+            op: update.op,
         }));
         const updatedWorkItem = await workItemApi.updateWorkItem(null, apiUpdates, id);
         return {
@@ -577,52 +591,69 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    server.tool(WORKITEM_TOOLS.close_and_link_workitem_duplicates, "Close duplicate work items by id.", {
-        id: z.number().describe("The ID of the work item to close and link duplicates to."),
-        duplicateIds: z.array(z.number()).describe("An array of IDs of the duplicate work items to close and link to the specified work item."),
+    server.tool(WORKITEM_TOOLS.work_item_unlink, "Remove one or many links from a single work item", {
         project: z.string().describe("The name or ID of the Azure DevOps project."),
-        state: z.string().default("Removed").describe("The state to set for the duplicate work items. Defaults to 'Removed'."),
-    }, async ({ id, duplicateIds, project, state }) => {
-        const connection = await connectionProvider();
-        const body = duplicateIds.map((duplicateId) => ({
-            method: "PATCH",
-            uri: `/_apis/wit/workitems/${duplicateId}?api-version=${batchApiVersion}`,
-            headers: {
-                "Content-Type": "application/json-patch+json",
-            },
-            body: [
-                {
-                    op: "add",
-                    path: "/fields/System.State",
-                    value: `${state}`,
-                },
-                {
-                    op: "add",
-                    path: "/relations/-",
-                    value: {
-                        rel: "System.LinkTypes.Duplicate-Reverse",
-                        url: `${connection.serverUrl}/${project}/_apis/wit/workItems/${id}`,
+        id: z.number().describe("The ID of the work item to remove the links from."),
+        type: z
+            .enum(["parent", "child", "duplicate", "duplicate of", "related", "successor", "predecessor", "tested by", "tests", "affects", "affected by", "artifact"])
+            .default("related")
+            .describe("Type of link to remove. Options include 'parent', 'child', 'duplicate', 'duplicate of', 'related', 'successor', 'predecessor', 'tested by', 'tests', 'affects', 'affected by', and 'artifact'. Defaults to 'related'."),
+        url: z.string().optional().describe("Optional URL to match for the link to remove. If not provided, all links of the specified type will be removed."),
+    }, async ({ project, id, type, url }) => {
+        try {
+            const connection = await connectionProvider();
+            const workItemApi = await connection.getWorkItemTrackingApi();
+            const workItem = await workItemApi.getWorkItem(id, undefined, undefined, WorkItemExpand.Relations, project);
+            const relations = workItem.relations ?? [];
+            const linkType = getLinkTypeFromName(type);
+            let relationIndexes = [];
+            if (url && url.trim().length > 0) {
+                // If url is provided, find relations matching both rel type and url
+                relationIndexes = relations.map((relation, idx) => (relation.url === url ? idx : -1)).filter((idx) => idx !== -1);
+            }
+            else {
+                // If url is not provided, find all relations matching rel type
+                relationIndexes = relations.map((relation, idx) => (relation.rel === linkType ? idx : -1)).filter((idx) => idx !== -1);
+            }
+            if (relationIndexes.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No matching relations found for link type '${type}'${url ? ` and URL '${url}'` : ""}.\n${JSON.stringify(relations, null, 2)}` }],
+                    isError: true,
+                };
+            }
+            // Get the relations that will be removed for logging
+            const removedRelations = relationIndexes.map((idx) => relations[idx]);
+            // Sort indexes in descending order to avoid index shifting when removing
+            relationIndexes.sort((a, b) => b - a);
+            const apiUpdates = relationIndexes.map((idx) => ({
+                op: "remove",
+                path: `/relations/${idx}`,
+            }));
+            const updatedWorkItem = await workItemApi.updateWorkItem(null, apiUpdates, id, project);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Removed ${removedRelations.length} link(s) of type '${type}':\n` +
+                            JSON.stringify(removedRelations, null, 2) +
+                            `\n\nUpdated work item result:\n` +
+                            JSON.stringify(updatedWorkItem, null, 2),
                     },
-                },
-            ],
-        }));
-        const accessToken = await tokenProvider();
-        const response = await fetch(`${connection.serverUrl}/_apis/wit/$batch?api-version=${batchApiVersion}`, {
-            method: "PATCH",
-            headers: {
-                "Authorization": `Bearer ${accessToken.token}`,
-                "Content-Type": "application/json",
-                "User-Agent": userAgentProvider(),
-            },
-            body: JSON.stringify(body),
-        });
-        if (!response.ok) {
-            throw new Error(`Failed to update work items in batch: ${response.statusText}`);
+                ],
+                isError: false,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error unlinking work item: ${error instanceof Error ? error.message : "Unknown error occurred"}`,
+                    },
+                ],
+                isError: true,
+            };
         }
-        const result = await response.json();
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
     });
 }
 export { WORKITEM_TOOLS, configureWorkItemTools };