search_workitem
Search and filter Azure DevOps work items by text, project, area path, type, state, or assigned users using PAT authentication. Supports pagination and optional facet inclusion for detailed results.
Instructions
Get Azure DevOps Work Item search results for a given search text
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| areaPath | No | Filter by area paths | |
| assignedTo | No | Filter by assigned to users | |
| includeFacets | No | Include facets in the search results | |
| project | No | Filter by projects | |
| searchText | Yes | Search text to find in work items | |
| skip | No | Number of results to skip for pagination | |
| state | No | Filter by work item states | |
| top | No | Number of results to return | |
| workItemType | No | Filter by work item types |
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",