changed tool to allow for bulk create child items instead of one (#241)

Added new tool that allows multiple child work items to be added in a
single call. Removed old tool that only allows one at a time. included
adding format for Markdown in comments.

## GitHub issue number #227 

## **Associated Risks**

No risks

## ✅ **PR Checklist**

- [x] **I have read the [contribution
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CONTRIBUTING.md)**
- [x] **I have read the [code of conduct
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CODE_OF_CONDUCT.md)**
- [x] Title of the pull request is clear and informative.
- [x] 👌 Code hygiene
- [x] 🔭 Telemetry added, updated, or N/A
- [x] 📄 Documentation added, updated, or N/A
- [x] 🛡️ Automated tests added, or N/A

## 🧪 **How did you test it?**

Removed old tests and still need to add tests for new method. But tested
this out a lot manually.

---------

Co-authored-by: Anton Audzei <antonaudzei@microsoft.com>

Author: danhellem

README.md

@@ -66,7 +66,7 @@ Interact with these Azure DevOps services:
 - **wit_list_work_item_comments**: Retrieves a list of comments for a work item by ID.
 - **wit_get_work_items_for_iteration**: Retrieves a list of work items for a specified iteration.
 - **wit_add_work_item_comment**: Add comment to a work item by ID.
-- **wit_add_child_work_item**: Create a child work item from a parent by ID.
+- **wit_add_child_work_items**: Create one or many child work items of a specific work item type for the given parent Id
 - **wit_link_work_item_to_pull_request**: Link a single work item to an existing pull request.
 - **wit_get_work_item_type**: Get a specific work item type.
 - **wit_get_query**: Get a query by its ID or path.
@@ -75,6 +75,10 @@ Interact with these Azure DevOps services:
 - **wit_close_and_link_workitem_duplicates**: Close duplicate work items by id.
 - **wit_work_items_link**: Link work items together in batch.
 
+#### Deprecated tools
+
+- **wit_add_child_work_item**: Replaced by `wit_add_child_work_items` so that you can create one or many child items per call.
+
 ### 📁 Repositories
 
 - **repo_list_repos_by_project**: Retrieve a list of repositories for a given project.

src/tools/workitems.ts

@@ -20,7 +20,7 @@ const WORKITEM_TOOLS = {
   list_work_item_comments: "wit_list_work_item_comments",
   get_work_items_for_iteration: "wit_get_work_items_for_iteration",
   add_work_item_comment: "wit_add_work_item_comment",
-  add_child_work_item: "wit_add_child_work_item",
+  add_child_work_items: "wit_add_child_work_items",
   link_work_item_to_pull_request: "wit_link_work_item_to_pull_request",
   get_work_item_type: "wit_get_work_item_type",
   get_query: "wit_get_query",
@@ -200,63 +200,134 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
   );
 
   server.tool(
-    WORKITEM_TOOLS.add_child_work_item,
-    "Create a child work item from a parent by ID.",
+    WORKITEM_TOOLS.add_child_work_items,
+    "Create one or many child work items from a parent by work item type and parent id.",
     {
       parentId: z.number().describe("The ID of the parent work item to create a child work item under."),
       project: z.string().describe("The name or ID of the Azure DevOps project."),
       workItemType: z.string().describe("The type of the child work item to create."),
-      title: z.string().describe("The title of the child work item."),
-      description: z.string().describe("The description of the child work item."),
-      areaPath: z.string().optional().describe("Optional area path for the child work item."),
-      iterationPath: z.string().optional().describe("Optional iteration path for the child work item."),
+      items: z.array(
+        z.object({
+          title: z.string().describe("The title of the child work item."),
+          description: z.string().describe("The description of the child work item."),
+          format: z.enum(["Markdown", "Html"]).default("Html").describe("Format for the description on the child work item, e.g., 'Markdown', 'Html'. Defaults to 'Html'."),
+          areaPath: z.string().optional().describe("Optional area path for the child work item."),
+          iterationPath: z.string().optional().describe("Optional iteration path for the child work item."),
+        })
+      ),
     },
-    async ({ parentId, project, workItemType, title, description, areaPath, iterationPath }) => {
-      const connection = await connectionProvider();
-      const workItemApi = await connection.getWorkItemTrackingApi();
-
-      const document = [
-        {
-          op: "add",
-          path: "/fields/System.Title",
-          value: title,
-        },
-        {
-          op: "add",
-          path: "/fields/System.Description",
-          value: description,
-        },
-        {
-          op: "add",
-          path: "/relations/-",
-          value: {
-            rel: "System.LinkTypes.Hierarchy-Reverse",
-            url: `${connection.serverUrl}/${project}/_apis/wit/workItems/${parentId}`,
-          },
-        },
-      ];
+    async ({ parentId, project, workItemType, items }) => {
+      try {
+        const connection = await connectionProvider();
+        const orgUrl = connection.serverUrl;
+        const accessToken = await tokenProvider();
+
+        if (items.length > 50) {
+          return {
+            content: [{ type: "text", text: `A maximum of 50 child work items can be created in a single call.` }],
+            isError: true,
+          };
+        }
 
-      if (areaPath && areaPath.trim().length > 0) {
-        document.push({
-          op: "add",
-          path: "/fields/System.AreaPath",
-          value: areaPath,
+        const body = items.map((item, x) => {
+          const ops = [
+            {
+              op: "add",
+              path: "/id",
+              value: `-${x + 1}`,
+            },
+            {
+              op: "add",
+              path: "/fields/System.Title",
+              value: item.title,
+            },
+            {
+              op: "add",
+              path: "/fields/System.Description",
+              value: item.description,
+            },
+            {
+              op: "add",
+              path: "/fields/Microsoft.VSTS.TCM.ReproSteps",
+              value: item.description,
+            },
+            {
+              op: "add",
+              path: "/relations/-",
+              value: {
+                rel: "System.LinkTypes.Hierarchy-Reverse",
+                url: `${connection.serverUrl}/${project}/_apis/wit/workItems/${parentId}`,
+              },
+            },
+          ];
+
+          if (item.areaPath && item.areaPath.trim().length > 0) {
+            ops.push({
+              op: "add",
+              path: "/fields/System.AreaPath",
+              value: item.areaPath,
+            });
+          }
+
+          if (item.format && item.format === "Markdown") {
+            ops.push({
+              op: "add",
+              path: "/multilineFieldsFormat/System.Description",
+              value: item.format,
+            });
+
+            ops.push({
+              op: "add",
+              path: "/multilineFieldsFormat/Microsoft.VSTS.TCM.ReproSteps",
+              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}`,
+            headers: {
+              "Content-Type": "application/json-patch+json",
+            },
+            body: ops,
+          };
         });
-      }
 
-      if (iterationPath && iterationPath.trim().length > 0) {
-        document.push({
-          op: "add",
-          path: "/fields/System.IterationPath",
-          value: iterationPath,
+        const response = await fetch(`${orgUrl}/_apis/wit/$batch?api-version=${batchApiVersion}`, {
+          method: "PATCH",
+          headers: {
+            "Authorization": `Bearer ${accessToken.token}`,
+            "Content-Type": "application/json",
+            "User-Agent": userAgentProvider(),
+          },
+          body: JSON.stringify(body),
         });
-      }
 
-      const childWorkItem = await workItemApi.createWorkItem(null, document, project, workItemType);
+        if (!response.ok) {
+          throw new Error(`Failed to update work items in batch: ${response.statusText}`);
+        }
 
-      return {
-        content: [{ type: "text", text: JSON.stringify(childWorkItem, null, 2) }],
-      };
+        const result = await response.json();
+
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+
+        return {
+          content: [{ type: "text", text: `Error creating child work items: ${errorMessage}` }],
+          isError: true,
+        };
+      }
     }
   );
 

test/src/tools/workitems.test.ts

@@ -367,66 +367,6 @@ describe("configureWorkItemTools", () => {
     });
   });
 
-  describe("add_child_work_item tool", () => {
-    it("should call workItemApi.add_child_work_item API with the correct parameters and return the expected result", async () => {
-      configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);
-
-      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "wit_add_child_work_item");
-
-      if (!call) throw new Error("wit_add_child_work_item tool not registered");
-      const [, , , handler] = call;
-
-      (mockWorkItemTrackingApi.createWorkItem as jest.Mock).mockResolvedValue([_mockWorkItem]);
-
-      const params = {
-        parentId: 299,
-        project: "Contoso",
-        workItemType: "Task",
-        title: "Sample task",
-        description: "This is a sample task",
-        areaPath: "Contoso\\Development",
-        iterationPath: "Contoso\\Sprint 1",
-      };
-
-      const document = [
-        {
-          op: "add",
-          path: "/fields/System.Title",
-          value: params.title,
-        },
-        {
-          op: "add",
-          path: "/fields/System.Description",
-          value: params.description,
-        },
-        {
-          op: "add",
-          path: "/relations/-",
-          value: {
-            rel: "System.LinkTypes.Hierarchy-Reverse",
-            url: `undefined/${params.project}/_apis/wit/workItems/${params.parentId}`,
-          },
-        },
-        {
-          op: "add",
-          path: "/fields/System.AreaPath",
-          value: params.areaPath,
-        },
-        {
-          op: "add",
-          path: "/fields/System.IterationPath",
-          value: params.iterationPath,
-        },
-      ];
-
-      const result = await handler(params);
-
-      expect(mockWorkItemTrackingApi.createWorkItem).toHaveBeenCalledWith(null, document, params.project, params.workItemType);
-
-      expect(result.content[0].text).toBe(JSON.stringify([_mockWorkItem], null, 2));
-    });
-  });
-
   describe("link_work_item_to_pull_request tool", () => {
     it("should call workItemApi.updateWorkItem API with the correct parameters and return the expected result", async () => {
       configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);