Azure DevOps MCP Server with PAT Authentication

Instructions

Implementation Reference

• src/tools/workitems.ts:281-393 (handler)

  The handler function that creates one or more child work items under a specified parent work item using the Azure DevOps WIT batch API. It constructs PATCH operations to set title, description, repro steps, link to parent, and optional area/iteration paths and markdown formatting.

  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,
        };
      }
  
      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.iterationPath && item.iterationPath.trim().length > 0) {
          ops.push({
            op: "add",
            path: "/fields/System.IterationPath",
            value: item.iterationPath,
          });
        }
  
        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,
          });
        }
  
        return {
          method: "PATCH",
          uri: `/${project}/_apis/wit/workitems/$${workItemType}?api-version=${batchApiVersion}`,
          headers: {
            "Content-Type": "application/json-patch+json",
          },
          body: ops,
        };
      });
  
      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),
      });
  
      if (!response.ok) {
        throw new Error(`Failed to update work items in batch: ${response.statusText}`);
      }
  
      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,
      };
    }
  }

• src/tools/workitems.ts:268-280 (schema)

  Zod schema defining the input parameters for the tool: parentId, project, workItemType, and an array of child item details (title, description, format, optional areaPath and iterationPath).

    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."),
    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."),
      })
    ),
  },

• src/tools/workitems.ts:264-394 (registration)

  Registers the 'wit_add_child_work_items' tool with the MCP server using server.tool(), referencing WORKITEM_TOOLS.add_child_work_items, providing description, input schema, and handler function.

  server.tool(
    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."),
      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, 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,
          };
        }
  
        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.iterationPath && item.iterationPath.trim().length > 0) {
            ops.push({
              op: "add",
              path: "/fields/System.IterationPath",
              value: item.iterationPath,
            });
          }
  
          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,
            });
          }
  
          return {
            method: "PATCH",
            uri: `/${project}/_apis/wit/workitems/$${workItemType}?api-version=${batchApiVersion}`,
            headers: {
              "Content-Type": "application/json-patch+json",
            },
            body: ops,
          };
        });
  
        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),
        });
  
        if (!response.ok) {
          throw new Error(`Failed to update work items in batch: ${response.statusText}`);
        }
  
        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,
        };
      }
    }
  );

• src/tools/workitems.ts:12-32 (registration)

  Constant object mapping internal tool identifiers to MCP tool names, including add_child_work_items: 'wit_add_child_work_items'.

  const WORKITEM_TOOLS = {
    my_work_items: "wit_my_work_items",
    list_backlogs: "wit_list_backlogs",
    list_backlog_work_items: "wit_list_backlog_work_items",
    get_work_item: "wit_get_work_item",
    get_work_items_batch_by_ids: "wit_get_work_items_batch_by_ids",
    update_work_item: "wit_update_work_item",
    create_work_item: "wit_create_work_item",
    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_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",
    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",
    add_artifact_link: "wit_add_artifact_link",
  };