Azure DevOps MCP Server with PAT Authentication

Instructions

Implementation Reference

• src/tools/search.ts:147-187 (handler)

  The handler function for the 'search_workitem' tool. It constructs a search request to the Azure DevOps Work Item Search API, applies filters, fetches results, and returns them as text content.

  async ({ searchText, project, areaPath, workItemType, state, assignedTo, includeFacets, skip, top }) => {
    const accessToken = await tokenProvider();
    const url = `https://almsearch.dev.azure.com/${orgName}/_apis/search/workitemsearchresults?api-version=${apiVersion}`;
  
    const requestBody: Record<string, unknown> = {
      searchText,
      includeFacets,
      $skip: skip,
      $top: top,
    };
  
    const filters: Record<string, unknown> = {};
    if (project && project.length > 0) filters["System.TeamProject"] = project;
    if (areaPath && areaPath.length > 0) filters["System.AreaPath"] = areaPath;
    if (workItemType && workItemType.length > 0) filters["System.WorkItemType"] = workItemType;
    if (state && state.length > 0) filters["System.State"] = state;
    if (assignedTo && assignedTo.length > 0) filters["System.AssignedTo"] = assignedTo;
  
    if (Object.keys(filters).length > 0) {
      requestBody.filters = filters;
    }
  
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${accessToken.token}`,
        "User-Agent": userAgentProvider(),
      },
      body: JSON.stringify(requestBody),
    });
  
    if (!response.ok) {
      throw new Error(`Azure DevOps Work Item Search API error: ${response.status} ${response.statusText}`);
    }
  
    const result = await response.text();
    return {
      content: [{ type: "text", text: result }],
    };
  }

• src/tools/search.ts:136-146 (schema)

  Zod schema defining the input parameters for the 'search_workitem' tool.

  {
    searchText: z.string().describe("Search text to find in work items"),
    project: z.array(z.string()).optional().describe("Filter by projects"),
    areaPath: z.array(z.string()).optional().describe("Filter by area paths"),
    workItemType: z.array(z.string()).optional().describe("Filter by work item types"),
    state: z.array(z.string()).optional().describe("Filter by work item states"),
    assignedTo: z.array(z.string()).optional().describe("Filter by assigned to users"),
    includeFacets: z.boolean().default(false).describe("Include facets in the search results"),
    skip: z.number().default(0).describe("Number of results to skip for pagination"),
    top: z.number().default(10).describe("Number of results to return"),
  },

• src/tools/search.ts:133-188 (registration)

  Registers the 'search_workitem' tool on the MCP server using server.tool(), referencing SEARCH_TOOLS.search_workitem, providing description, input schema, and handler function.

  server.tool(
    SEARCH_TOOLS.search_workitem,
    "Get Azure DevOps Work Item search results for a given search text",
    {
      searchText: z.string().describe("Search text to find in work items"),
      project: z.array(z.string()).optional().describe("Filter by projects"),
      areaPath: z.array(z.string()).optional().describe("Filter by area paths"),
      workItemType: z.array(z.string()).optional().describe("Filter by work item types"),
      state: z.array(z.string()).optional().describe("Filter by work item states"),
      assignedTo: z.array(z.string()).optional().describe("Filter by assigned to users"),
      includeFacets: z.boolean().default(false).describe("Include facets in the search results"),
      skip: z.number().default(0).describe("Number of results to skip for pagination"),
      top: z.number().default(10).describe("Number of results to return"),
    },
    async ({ searchText, project, areaPath, workItemType, state, assignedTo, includeFacets, skip, top }) => {
      const accessToken = await tokenProvider();
      const url = `https://almsearch.dev.azure.com/${orgName}/_apis/search/workitemsearchresults?api-version=${apiVersion}`;
  
      const requestBody: Record<string, unknown> = {
        searchText,
        includeFacets,
        $skip: skip,
        $top: top,
      };
  
      const filters: Record<string, unknown> = {};
      if (project && project.length > 0) filters["System.TeamProject"] = project;
      if (areaPath && areaPath.length > 0) filters["System.AreaPath"] = areaPath;
      if (workItemType && workItemType.length > 0) filters["System.WorkItemType"] = workItemType;
      if (state && state.length > 0) filters["System.State"] = state;
      if (assignedTo && assignedTo.length > 0) filters["System.AssignedTo"] = assignedTo;
  
      if (Object.keys(filters).length > 0) {
        requestBody.filters = filters;
      }
  
      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": `Bearer ${accessToken.token}`,
          "User-Agent": userAgentProvider(),
        },
        body: JSON.stringify(requestBody),
      });
  
      if (!response.ok) {
        throw new Error(`Azure DevOps Work Item Search API error: ${response.status} ${response.statusText}`);
      }
  
      const result = await response.text();
      return {
        content: [{ type: "text", text: result }],
      };
    }
  );

• src/tools/search.ts:17-17 (helper)

  Constant string identifier for the 'search_workitem' tool used in registration.

  search_workitem: "search_workitem",