Azure DevOps MCP Server with PAT Authentication

Instructions

Implementation Reference

• src/tools/workitems.ts:135-176 (handler)

  The handler function that executes the tool logic: connects to Azure DevOps, fetches work items by IDs in batch, processes identity fields to string format, and returns JSON stringified response.

  async ({ project, ids, fields }) => {
    const connection = await connectionProvider();
    const workItemApi = await connection.getWorkItemTrackingApi();
    const defaultFields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.Parent", "System.Tags", "Microsoft.VSTS.Common.StackRank", "System.AssignedTo"];
  
    // If no fields are provided, use the default set of fields
    const fieldsToUse = !fields || fields.length === 0 ? defaultFields : fields;
  
    const workitems = await workItemApi.getWorkItemsBatch({ ids, fields: fieldsToUse }, project);
  
    // List of identity fields that need to be transformed from objects to formatted strings
    const identityFields = [
      "System.AssignedTo",
      "System.CreatedBy",
      "System.ChangedBy",
      "System.AuthorizedAs",
      "Microsoft.VSTS.Common.ActivatedBy",
      "Microsoft.VSTS.Common.ResolvedBy",
      "Microsoft.VSTS.Common.ClosedBy",
    ];
  
    // Format identity fields 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) {
          identityFields.forEach((fieldName) => {
            if (item.fields && item.fields[fieldName] && typeof item.fields[fieldName] === "object") {
              const identityField = item.fields[fieldName];
              const name = identityField.displayName || "";
              const email = identityField.uniqueName || "";
              item.fields[fieldName] = `${name} <${email}>`.trim();
            }
          });
        }
      });
    }
  
    return {
      content: [{ type: "text", text: JSON.stringify(workitems, null, 2) }],
    };
  }

• src/tools/workitems.ts:130-134 (schema)

  Zod input schema defining parameters: project (string), ids (array of numbers), optional fields (array of strings).

  {
    project: z.string().describe("The name or ID of the Azure DevOps project."),
    ids: z.array(z.number()).describe("The IDs of the work items to retrieve."),
    fields: z.array(z.string()).optional().describe("Optional list of fields to include in the response. If not provided, a hardcoded default set of fields will be used."),
  },

• src/tools/workitems.ts:127-176 (registration)

  Registration of the tool using McpServer.tool() with name from WORKITEM_TOOLS.get_work_items_batch_by_ids ('wit_get_work_items_batch_by_ids'), description, schema, and handler.

  server.tool(
    WORKITEM_TOOLS.get_work_items_batch_by_ids,
    "Retrieve list of work items by IDs in batch.",
    {
      project: z.string().describe("The name or ID of the Azure DevOps project."),
      ids: z.array(z.number()).describe("The IDs of the work items to retrieve."),
      fields: z.array(z.string()).optional().describe("Optional list of fields to include in the response. If not provided, a hardcoded default set of fields will be used."),
    },
    async ({ project, ids, fields }) => {
      const connection = await connectionProvider();
      const workItemApi = await connection.getWorkItemTrackingApi();
      const defaultFields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.Parent", "System.Tags", "Microsoft.VSTS.Common.StackRank", "System.AssignedTo"];
  
      // If no fields are provided, use the default set of fields
      const fieldsToUse = !fields || fields.length === 0 ? defaultFields : fields;
  
      const workitems = await workItemApi.getWorkItemsBatch({ ids, fields: fieldsToUse }, project);
  
      // List of identity fields that need to be transformed from objects to formatted strings
      const identityFields = [
        "System.AssignedTo",
        "System.CreatedBy",
        "System.ChangedBy",
        "System.AuthorizedAs",
        "Microsoft.VSTS.Common.ActivatedBy",
        "Microsoft.VSTS.Common.ResolvedBy",
        "Microsoft.VSTS.Common.ClosedBy",
      ];
  
      // Format identity fields 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) {
            identityFields.forEach((fieldName) => {
              if (item.fields && item.fields[fieldName] && typeof item.fields[fieldName] === "object") {
                const identityField = item.fields[fieldName];
                const name = identityField.displayName || "";
                const email = identityField.uniqueName || "";
                item.fields[fieldName] = `${name} <${email}>`.trim();
              }
            });
          }
        });
      }
  
      return {
        content: [{ type: "text", text: JSON.stringify(workitems, null, 2) }],
      };
    }

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

  Tool name mapping in WORKITEM_TOOLS constant used for registration.

  get_work_items_batch_by_ids: "wit_get_work_items_batch_by_ids",