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", };