@azure-devops/mcp 1.2.1 → 1.3.0

package/dist/tools/testplan.test.js

@@ -0,0 +1,125 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { describe, expect, it } from '@jest/globals';
+import { configureTestPlanTools } from '../../../src/tools/testplans';
+describe("configureTestPlanTools", () => {
+    let server;
+    let tokenProvider;
+    let connectionProvider;
+    let mockConnection;
+    let mockTestPlanApi;
+    let mockTestResultsApi;
+    beforeEach(() => {
+        server = { tool: jest.fn() };
+        tokenProvider = jest.fn();
+        mockTestPlanApi = {
+            getTestPlans: jest.fn(),
+            createTestPlan: jest.fn(),
+            addTestCasesToSuite: jest.fn(),
+            getTestCaseList: jest.fn(),
+        };
+        mockTestResultsApi = {
+            getTestResultDetailsForBuild: jest.fn(),
+        };
+        mockConnection = {
+            getTestPlanApi: jest.fn().mockResolvedValue(mockTestPlanApi),
+            getTestResultsApi: jest.fn().mockResolvedValue(mockTestResultsApi),
+        };
+        connectionProvider = jest.fn().mockResolvedValue(mockConnection);
+    });
+    describe("tool registration", () => {
+        it("registers test plan tools on the server", () => {
+            configureTestPlanTools(server, tokenProvider, connectionProvider);
+            expect(server.tool.mock.calls.map(call => call[0])).toEqual(expect.arrayContaining([
+                "ado_list_test_plans",
+                "ado_create_test_plan",
+                "ado_add_test_cases_to_suite",
+                "ado_list_test_cases",
+                "ado_show_test_results_from_build_id",
+            ]));
+        });
+    });
+    describe("list_test_plans tool", () => {
+        it("should call getTestPlans with the correct parameters and return the expected result", async () => {
+            configureTestPlanTools(server, tokenProvider, connectionProvider);
+            const call = server.tool.mock.calls.find(([toolName]) => toolName === "ado_list_test_plans");
+            if (!call)
+                throw new Error("ado_list_test_plans tool not registered");
+            const [, , , handler] = call;
+            mockTestPlanApi.getTestPlans.mockResolvedValue([{ id: 1, name: "Test Plan 1" }]);
+            const params = {
+                project: "proj1",
+                filterActivePlans: true,
+                includePlanDetails: false,
+                continuationToken: undefined,
+            };
+            const result = await handler(params);
+            expect(mockTestPlanApi.getTestPlans).toHaveBeenCalledWith("proj1", "", undefined, false, true);
+            expect(result.content[0].text).toBe(JSON.stringify([{ id: 1, name: "Test Plan 1" }], null, 2));
+        });
+    });
+    describe("create_test_plan tool", () => {
+        it("should call createTestPlan with the correct parameters and return the expected result", async () => {
+            configureTestPlanTools(server, tokenProvider, connectionProvider);
+            const call = server.tool.mock.calls.find(([toolName]) => toolName === "ado_create_test_plan");
+            if (!call)
+                throw new Error("ado_create_test_plan tool not registered");
+            const [, , , handler] = call;
+            mockTestPlanApi.createTestPlan.mockResolvedValue({ id: 1, name: "New Test Plan" });
+            const params = {
+                project: "proj1",
+                name: "New Test Plan",
+                iteration: "Iteration 1",
+                description: "Description",
+                startDate: "2025-05-01",
+                endDate: "2025-05-31",
+                areaPath: "Area 1",
+            };
+            const result = await handler(params);
+            expect(mockTestPlanApi.createTestPlan).toHaveBeenCalledWith({
+                name: "New Test Plan",
+                iteration: "Iteration 1",
+                description: "Description",
+                startDate: new Date("2025-05-01"),
+                endDate: new Date("2025-05-31"),
+                areaPath: "Area 1",
+            }, "proj1");
+            expect(result.content[0].text).toBe(JSON.stringify({ id: 1, name: "New Test Plan" }, null, 2));
+        });
+    });
+    describe("list_test_cases tool", () => {
+        it("should call getTestCaseList with the correct parameters and return the expected result", async () => {
+            configureTestPlanTools(server, tokenProvider, connectionProvider);
+            const call = server.tool.mock.calls.find(([toolName]) => toolName === "ado_list_test_cases");
+            if (!call)
+                throw new Error("ado_list_test_cases tool not registered");
+            const [, , , handler] = call;
+            mockTestPlanApi.getTestCaseList.mockResolvedValue([{ id: 1, name: "Test Case 1" }]);
+            const params = {
+                project: "proj1",
+                planid: 1,
+                suiteid: 2,
+            };
+            const result = await handler(params);
+            expect(mockTestPlanApi.getTestCaseList).toHaveBeenCalledWith("proj1", 1, 2);
+            expect(result.content[0].text).toBe(JSON.stringify([{ id: 1, name: "Test Case 1" }], null, 2));
+        });
+    });
+    describe("test_results_from_build_id tool", () => {
+        it("should call getTestResultDetailsForBuild with the correct parameters and return the expected result", async () => {
+            configureTestPlanTools(server, tokenProvider, connectionProvider);
+            const call = server.tool.mock.calls.find(([toolName]) => toolName === "ado_show_test_results_from_build_id");
+            if (!call)
+                throw new Error("ado_show_test_results_from_build_id tool not registered");
+            const [, , , handler] = call;
+            mockTestResultsApi.getTestResultDetailsForBuild.mockResolvedValue({ results: ["Result 1"] });
+            const params = {
+                project: "proj1",
+                buildid: 123,
+            };
+            const result = await handler(params);
+            expect(mockTestResultsApi.getTestResultDetailsForBuild).toHaveBeenCalledWith("proj1", 123);
+            expect(result.content[0].text).toBe(JSON.stringify({ results: ["Result 1"] }, null, 2));
+        });
+    });
+});

package/dist/tools/testplans.js

@@ -79,7 +79,7 @@ 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\\n2. Step two' etc."),
+        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"),
         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."),
@@ -165,17 +165,21 @@ function configureTestPlanTools(server, tokenProvider, connectionProvider) {
  * Helper function to convert steps text to XML format required
  */
 function convertStepsToXml(steps) {
+    // Accepts steps in the format: '1. Step one|Expected result one\n2. Step two|Expected result two'
     const stepsLines = steps.split("\n").filter((line) => line.trim() !== "");
     let xmlSteps = `<steps id="0" last="${stepsLines.length}">`;
     for (let i = 0; i < stepsLines.length; i++) {
         const stepLine = stepsLines[i].trim();
         if (stepLine) {
-            const stepMatch = stepLine.match(/^(\d+)\.\s*(.+)$/);
-            const stepText = stepMatch ? stepMatch[2] : stepLine;
+            // Split step and expected result by '|', fallback to default if not provided
+            const [stepPart, expectedPart] = stepLine.split("|").map((s) => s.trim());
+            const stepMatch = stepPart.match(/^(\d+)\.\s*(.+)$/);
+            const stepText = stepMatch ? stepMatch[2] : stepPart;
+            const expectedText = expectedPart || "Verify step completes successfully";
             xmlSteps += `
                 <step id="${i + 1}" type="ActionStep">
                     <parameterizedString isformatted="true">${escapeXml(stepText)}</parameterizedString>
-                    <parameterizedString isformatted="true">Verify step completes successfully</parameterizedString>
+                    <parameterizedString isformatted="true">${escapeXml(expectedText)}</parameterizedString>
                 </step>`;
         }
     }

package/dist/tools/utils.js

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { packageVersion } from "./version.js";
+export const apiVersion = "7.2-preview.1";
+export const batchApiVersion = "5.0";
+export const userAgent = `AzureDevOps.MCP/${packageVersion} (local)`;

package/dist/tools/wiki.test.js

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { describe, expect, it } from '@jest/globals';
+import { configureWikiTools } from '../../../src/tools/wiki';
+describe("configureWikiTools", () => {
+    let server;
+    let tokenProvider;
+    let connectionProvider;
+    let mockConnection;
+    let mockWikiApi;
+    beforeEach(() => {
+        server = { tool: jest.fn() };
+        tokenProvider = jest.fn();
+        mockWikiApi = {
+            getWiki: jest.fn(),
+            getAllWikis: jest.fn(),
+            getPagesBatch: jest.fn(),
+            getPageText: jest.fn(),
+        };
+        mockConnection = {
+            getWikiApi: jest.fn().mockResolvedValue(mockWikiApi),
+        };
+        connectionProvider = jest.fn().mockResolvedValue(mockConnection);
+    });
+    describe("tool registration", () => {
+        it("registers wiki tools on the server", () => {
+            configureWikiTools(server, tokenProvider, connectionProvider);
+            expect(server.tool).toHaveBeenCalled();
+        });
+    });
+    describe("get_wiki_page_content tool", () => {
+        it("should call getPageText with the correct parameters and return the expected result", async () => {
+            configureWikiTools(server, tokenProvider, connectionProvider);
+            const call = server.tool.mock.calls.find(([toolName]) => toolName === "ado_get_wiki_page_content");
+            if (!call)
+                throw new Error("ado_get_wiki_page_content tool not registered");
+            const [, , , handler] = call;
+            // Mock a stream-like object for getPageText
+            const mockStream = {
+                setEncoding: jest.fn(),
+                on: function (event, cb) {
+                    if (event === "data") {
+                        setImmediate(() => cb("mock page text"));
+                    }
+                    if (event === "end") {
+                        setImmediate(() => cb());
+                    }
+                    return this;
+                }
+            };
+            mockWikiApi.getPageText.mockResolvedValue(mockStream);
+            const params = {
+                wikiIdentifier: "wiki1",
+                project: "proj1",
+                path: "/page1"
+            };
+            const result = await handler(params);
+            expect(mockWikiApi.getPageText).toHaveBeenCalledWith("proj1", "wiki1", "/page1", undefined, undefined, true);
+            expect(result.content[0].text).toBe("\"mock page text\"");
+        });
+    });
+    describe("list_wiki_pages tool", () => {
+        it("should call getPagesBatch with the correct parameters and return the expected result", async () => {
+            configureWikiTools(server, tokenProvider, connectionProvider);
+            const call = server.tool.mock.calls.find(([toolName]) => toolName === "ado_list_wiki_pages");
+            if (!call)
+                throw new Error("ado_list_wiki_pages tool not registered");
+            const [, , , handler] = call;
+            mockWikiApi.getPagesBatch.mockResolvedValue({ value: ["page1", "page2"] });
+            const params = {
+                wikiIdentifier: "wiki2",
+                project: "proj2",
+                top: 10,
+                continuationToken: "token123",
+                pageViewsForDays: 7
+            };
+            const result = await handler(params);
+            const parsedResult = JSON.parse(result.content[0].text);
+            expect(mockWikiApi.getPagesBatch).toHaveBeenCalledWith({
+                top: 10,
+                continuationToken: "token123",
+                pageViewsForDays: 7
+            }, "proj2", "wiki2");
+            expect(parsedResult.value).toEqual(["page1", "page2"]);
+        });
+    });
+});

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,5 +1,6 @@
 // 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";
@@ -21,6 +22,7 @@ const WORKITEM_TOOLS = {
     get_query_results_by_id: "wit_get_query_results_by_id",
     update_work_items_batch: "wit_update_work_items_batch",
     work_items_link: "wit_work_items_link",
+    work_item_unlink: "wit_work_item_unlink",
 };
 function getLinkTypeFromName(name) {
     switch (name.toLowerCase()) {
@@ -46,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}`);
     }
@@ -95,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) }],
         };
@@ -279,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 = [
@@ -573,5 +591,69 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
+    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."),
+        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),
+                    },
+                ],
+                isError: false,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error unlinking work item: ${error instanceof Error ? error.message : "Unknown error occurred"}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
 }
 export { WORKITEM_TOOLS, configureWorkItemTools };