@azure-devops/mcp 0.1.0

package/dist/tools/testplans.js

@@ -0,0 +1,212 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { z } from "zod";
+const Test_Plan_Tools = {
+    create_test_plan: "testplan_create_test_plan",
+    create_test_case: "testplan_create_test_case",
+    add_test_cases_to_suite: "testplan_add_test_cases_to_suite",
+    test_results_from_build_id: "testplan_show_test_results_from_build_id",
+    list_test_cases: "testplan_list_test_cases",
+    list_test_plans: "testplan_list_test_plans"
+};
+function configureTestPlanTools(server, tokenProvider, connectionProvider) {
+    /*
+      LIST OF TEST PLANS
+      get list of test plans by project
+    */
+    server.tool(Test_Plan_Tools.list_test_plans, "Retrieve a paginated list of test plans from an Azure DevOps project. Allows filtering for active plans and toggling detailed information.", {
+        project: z.string().describe("The unique identifier (ID or name) of the Azure DevOps project."),
+        filterActivePlans: z.boolean().default(true).describe("Filter to include only active test plans. Defaults to true."),
+        includePlanDetails: z.boolean().default(false).describe("Include detailed information about each test plan."),
+        continuationToken: z.string().optional().describe("Token to continue fetching test plans from a previous request."),
+    }, async ({ project, filterActivePlans, includePlanDetails, continuationToken, }) => {
+        const owner = ""; //making owner an empty string untill we can figure out how to get owner id
+        const connection = await connectionProvider();
+        const testPlanApi = await connection.getTestPlanApi();
+        const testPlans = await testPlanApi.getTestPlans(project, owner, continuationToken, includePlanDetails, filterActivePlans);
+        return {
+            content: [{ type: "text", text: JSON.stringify(testPlans, null, 2) }],
+        };
+    });
+    /*
+      Create Test Plan - CREATE
+    */
+    server.tool(Test_Plan_Tools.create_test_plan, "Creates a new test plan in the project.", {
+        project: z.string().describe("The unique identifier (ID or name) of the Azure DevOps project where the test plan will be created."),
+        name: z.string().describe("The name of the test plan to be created."),
+        iteration: z.string().describe("The iteration path for the test plan"),
+        description: z.string().optional().describe("The description of the test plan"),
+        startDate: z.string().optional().describe("The start date of the test plan"),
+        endDate: z.string().optional().describe("The end date of the test plan"),
+        areaPath: z.string().optional().describe("The area path for the test plan"),
+    }, async ({ project, name, iteration, description, startDate, endDate, areaPath, }) => {
+        const connection = await connectionProvider();
+        const testPlanApi = await connection.getTestPlanApi();
+        const testPlanToCreate = {
+            name,
+            iteration,
+            description,
+            startDate: startDate ? new Date(startDate) : undefined,
+            endDate: endDate ? new Date(endDate) : undefined,
+            areaPath,
+        };
+        const createdTestPlan = await testPlanApi.createTestPlan(testPlanToCreate, project);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(createdTestPlan, null, 2) },
+            ],
+        };
+    });
+    /*
+      Add Test Cases to Suite - ADD
+    */
+    server.tool(Test_Plan_Tools.add_test_cases_to_suite, "Adds existing test cases to a test suite.", {
+        project: z.string().describe("The unique identifier (ID or name) of the Azure DevOps project."),
+        planId: z.number().describe("The ID of the test plan."),
+        suiteId: z.number().describe("The ID of the test suite."),
+        testCaseIds: z.string().or(z.array(z.string())).describe("The ID(s) of the test case(s) to add. "),
+    }, async ({ project, planId, suiteId, testCaseIds }) => {
+        const connection = await connectionProvider();
+        const testApi = await connection.getTestApi();
+        // If testCaseIds is an array, convert it to comma-separated string
+        const testCaseIdsString = Array.isArray(testCaseIds)
+            ? testCaseIds.join(",")
+            : testCaseIds;
+        const addedTestCases = await testApi.addTestCasesToSuite(project, planId, suiteId, testCaseIdsString);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(addedTestCases, null, 2) },
+            ],
+        };
+    });
+    /*
+      Create Test Case - CREATE
+    */
+    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."),
+        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."),
+    }, async ({ project, title, steps, priority, areaPath, iterationPath }) => {
+        const connection = await connectionProvider();
+        const witClient = await connection.getWorkItemTrackingApi();
+        let stepsXml;
+        if (steps) {
+            stepsXml = convertStepsToXml(steps);
+        }
+        // Create JSON patch document for work item
+        const patchDocument = [];
+        patchDocument.push({
+            op: "add",
+            path: "/fields/System.Title",
+            value: title,
+        });
+        if (stepsXml) {
+            patchDocument.push({
+                op: "add",
+                path: "/fields/Microsoft.VSTS.TCM.Steps",
+                value: stepsXml,
+            });
+        }
+        if (priority) {
+            patchDocument.push({
+                op: "add",
+                path: "/fields/Microsoft.VSTS.Common.Priority",
+                value: priority,
+            });
+        }
+        if (areaPath) {
+            patchDocument.push({
+                op: "add",
+                path: "/fields/System.AreaPath",
+                value: areaPath,
+            });
+        }
+        if (iterationPath) {
+            patchDocument.push({
+                op: "add",
+                path: "/fields/System.IterationPath",
+                value: iterationPath,
+            });
+        }
+        const workItem = await witClient.createWorkItem({}, patchDocument, project, "Test Case");
+        return {
+            content: [{ type: "text", text: JSON.stringify(workItem, null, 2) }],
+        };
+    });
+    /*
+      TEST PLANS
+      Gets a list of test cases for a given testplan.
+    */
+    server.tool(Test_Plan_Tools.list_test_cases, "Gets a list of test cases in the test plan.", {
+        project: z.string().describe("The unique identifier (ID or name) of the Azure DevOps project."),
+        planid: z.number().describe("The ID of the test plan."),
+        suiteid: z.number().describe("The ID of the test suite."),
+    }, async ({ project, planid, suiteid }) => {
+        const connection = await connectionProvider();
+        const coreApi = await connection.getTestPlanApi();
+        const testcases = await coreApi.getTestCaseList(project, planid, suiteid);
+        return {
+            content: [{ type: "text", text: JSON.stringify(testcases, null, 2) }],
+        };
+    });
+    /*
+      Gets a list of test results for a given project and build ID
+    */
+    server.tool(Test_Plan_Tools.test_results_from_build_id, "Gets a list of test results for a given project and build ID.", {
+        project: z.string().describe("The unique identifier (ID or name) of the Azure DevOps project."),
+        buildid: z.number().describe("The ID of the build."),
+    }, async ({ project, buildid }) => {
+        const connection = await connectionProvider();
+        const coreApi = await connection.getTestResultsApi();
+        const testResults = await coreApi.getTestResultDetailsForBuild(project, buildid);
+        return {
+            content: [{ type: "text", text: JSON.stringify(testResults, null, 2) }],
+        };
+    });
+}
+/*
+ * Helper function to convert steps text to XML format required
+*/
+function convertStepsToXml(steps) {
+    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;
+            xmlSteps += `
+                <step id="${i + 1}" type="ActionStep">
+                    <parameterizedString isformatted="true">${escapeXml(stepText)}</parameterizedString>
+                    <parameterizedString isformatted="true">Verify step completes successfully</parameterizedString>
+                </step>`;
+        }
+    }
+    xmlSteps += "</steps>";
+    return xmlSteps;
+}
+/*
+ * Helper function to escape XML special characters
+*/
+function escapeXml(unsafe) {
+    return unsafe.replace(/[<>&'"]/g, (c) => {
+        switch (c) {
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case "&":
+                return "&amp;";
+            case "'":
+                return "&apos;";
+            case '"':
+                return "&quot;";
+            default:
+                return c;
+        }
+    });
+}
+export { Test_Plan_Tools, configureTestPlanTools };

package/dist/tools/wiki.js

@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { z } from "zod";
+const WIKI_TOOLS = {
+    list_wikis: "wiki_list_wikis",
+    get_wiki: "wiki_get_wiki",
+    list_wiki_pages: "wiki_list_pages",
+    get_wiki_page_content: "wiki_get_page_content",
+};
+function configureWikiTools(server, tokenProvider, connectionProvider) {
+    server.tool(WIKI_TOOLS.get_wiki, "Get the wiki by wikiIdentifier", {
+        wikiIdentifier: z.string().describe("The unique identifier of the wiki."),
+        project: z.string().optional().describe("The project name or ID where the wiki is located. If not provided, the default project will be used."),
+    }, async ({ wikiIdentifier, project }) => {
+        const connection = await connectionProvider();
+        const wikiApi = await connection.getWikiApi();
+        const wiki = await wikiApi.getWiki(wikiIdentifier, project);
+        return {
+            content: [{ type: "text", text: JSON.stringify(wiki, null, 2) }],
+        };
+    });
+    server.tool(WIKI_TOOLS.list_wikis, "Retrieve a list of wikis for an organization or project.", {
+        project: z.string().optional().describe("The project name or ID to filter wikis. If not provided, all wikis in the organization will be returned."),
+    }, async ({ project }) => {
+        const connection = await connectionProvider();
+        const wikiApi = await connection.getWikiApi();
+        const wikis = await wikiApi.getAllWikis(project);
+        return {
+            content: [{ type: "text", text: JSON.stringify(wikis, null, 2) }],
+        };
+    });
+    server.tool(WIKI_TOOLS.list_wiki_pages, "Retrieve a list of wiki pages for a specific wiki and project.", {
+        wikiIdentifier: z.string().describe("The unique identifier of the wiki."),
+        project: z.string().describe("The project name or ID where the wiki is located."),
+        top: z.number().default(20).describe("The maximum number of pages to return. Defaults to 20."),
+        continuationToken: z.string().optional().describe("Token for pagination to retrieve the next set of pages."),
+        pageViewsForDays: z.number().optional().describe("Number of days to retrieve page views for. If not specified, page views are not included."),
+    }, async ({ wikiIdentifier, project, top = 20, continuationToken, pageViewsForDays, }) => {
+        const connection = await connectionProvider();
+        const wikiApi = await connection.getWikiApi();
+        const pagesBatchRequest = {
+            top,
+            continuationToken,
+            pageViewsForDays,
+        };
+        const pages = await wikiApi.getPagesBatch(pagesBatchRequest, project, wikiIdentifier);
+        return {
+            content: [{ type: "text", text: JSON.stringify(pages, null, 2) }],
+        };
+    });
+    server.tool(WIKI_TOOLS.get_wiki_page_content, "Retrieve wiki page content by wikiIdentifier and path.", {
+        wikiIdentifier: z.string().describe("The unique identifier of the wiki."),
+        project: z.string().describe("The project name or ID where the wiki is located."),
+        path: z.string().describe("The path of the wiki page to retrieve content for."),
+    }, async ({ wikiIdentifier, project, path }) => {
+        const connection = await connectionProvider();
+        const wikiApi = await connection.getWikiApi();
+        const stream = await wikiApi.getPageText(project, wikiIdentifier, path, undefined, undefined, true);
+        const content = await streamToString(stream);
+        return {
+            content: [{ type: "text", text: JSON.stringify(content, null, 2) }],
+        };
+    });
+}
+function streamToString(stream) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => (data += chunk));
+        stream.on("end", () => resolve(data));
+        stream.on("error", reject);
+    });
+}
+export { WIKI_TOOLS, configureWikiTools };

package/dist/tools/work.js

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { z } from "zod";
+import { TreeStructureGroup } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
+const WORK_TOOLS = {
+    list_team_iterations: "work_list_team_iterations",
+    create_iterations: "work_create_iterations",
+    assign_iterations: "work_assign_iterations",
+};
+function configureWorkTools(server, tokenProvider, connectionProvider) {
+    server.tool(WORK_TOOLS.list_team_iterations, "Retrieve a list of iterations for a specific team in a project.", {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        team: z.string().describe("The name or ID of the Azure DevOps team."),
+        timeframe: z.enum(["current"]).optional().describe("The timeframe for which to retrieve iterations. Currently, only 'current' is supported."),
+    }, async ({ project, team, timeframe }) => {
+        const connection = await connectionProvider();
+        const workApi = await connection.getWorkApi();
+        const iterations = await workApi.getTeamIterations({ project, team }, timeframe);
+        return {
+            content: [{ type: "text", text: JSON.stringify(iterations, null, 2) }],
+        };
+    });
+    server.tool(WORK_TOOLS.create_iterations, "Create new iterations in a specified Azure DevOps project.", {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        iterations: z.array(z.object({
+            iterationName: z.string().describe("The name of the iteration to create."),
+            startDate: z.string().optional().describe("The start date of the iteration in ISO format (e.g., '2023-01-01T00:00:00Z'). Optional."),
+            finishDate: z.string().optional().describe("The finish date of the iteration in ISO format (e.g., '2023-01-31T23:59:59Z'). Optional.")
+        })).describe("An array of iterations to create. Each iteration must have a name and can optionally have start and finish dates in ISO format.")
+    }, async ({ project, iterations }) => {
+        const connection = await connectionProvider();
+        const workItemTrackingApi = await connection.getWorkItemTrackingApi();
+        const results = [];
+        for (const { iterationName, startDate, finishDate } of iterations) {
+            // Step 1: Create the iteration
+            const iteration = await workItemTrackingApi.createOrUpdateClassificationNode({
+                name: iterationName,
+                attributes: {
+                    startDate: startDate ? new Date(startDate) : undefined,
+                    finishDate: finishDate ? new Date(finishDate) : undefined,
+                },
+            }, project, TreeStructureGroup.Iterations);
+            results.push(iteration);
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    });
+    server.tool(WORK_TOOLS.assign_iterations, "Assign existing iterations to a specific team in a project.", {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        team: z.string().describe("The name or ID of the Azure DevOps team."),
+        iterations: z.array(z.object({
+            identifier: z.string().describe("The identifier of the iteration to assign."),
+            path: z.string().describe("The path of the iteration to assign, e.g., 'Project/Iteration'.")
+        })).describe("An array of iterations to assign. Each iteration must have an identifier and a path."),
+    }, async ({ project, team, iterations }) => {
+        const connection = await connectionProvider();
+        const workApi = await connection.getWorkApi();
+        const teamContext = { project, team };
+        const results = [];
+        for (const { identifier, path } of iterations) {
+            const assignment = await workApi.postTeamIteration({ path: path, id: identifier }, teamContext);
+            results.push(assignment);
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    });
+}
+export { WORK_TOOLS, configureWorkTools };