list_work_items
Retrieve and filter work items in an Azure DevOps project by type, state, or assigned user to streamline project management and task tracking.
Instructions
List work items in a project
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| assignedTo | No | Filter by assigned user | |
| project | Yes | Name of the Azure DevOps project | |
| states | No | Filter by states | |
| types | No | Filter by work item types |
Input Schema (JSON Schema)
{
"properties": {
"assignedTo": {
"description": "Filter by assigned user",
"type": "string"
},
"project": {
"description": "Name of the Azure DevOps project",
"type": "string"
},
"states": {
"description": "Filter by states",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "Filter by work item types",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"project"
],
"type": "object"
}
Implementation Reference
- src/tools/workItems.ts:17-77 (handler)The handler function that implements the core logic for listing work items using Azure DevOps WIQL query, fetching details, and returning formatted response.export async function listWorkItems(rawParams: any) { // Parse arguments with defaults from environment variables const params = listWorkItemsSchema.parse({ project: rawParams.project || DEFAULT_PROJECT, types: rawParams.types, states: rawParams.states, assignedTo: rawParams.assignedTo, }); console.error("[API] Listing work items:", params); try { // Get the Work Item Tracking API client const witClient = await getWorkItemClient(); // Build WIQL query let wiql = `SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType], [System.AssignedTo] FROM WorkItems WHERE [System.TeamProject] = '${params.project}'`; if (params.types && params.types.length > 0) { wiql += ` AND [System.WorkItemType] IN ('${params.types.join("','")}')`; } if (params.states && params.states.length > 0) { wiql += ` AND [System.State] IN ('${params.states.join("','")}')`; } if (params.assignedTo) { wiql += ` AND [System.AssignedTo] = '${params.assignedTo}'`; } // Execute the query const queryResult = await witClient.queryByWiql({ query: wiql }); if (!queryResult.workItems) { return { content: [{ type: "text", text: JSON.stringify([], null, 2) }], }; } // Get full work item details const workItems = await witClient.getWorkItems( queryResult.workItems.map( (wi: WorkItemInterfaces.WorkItemReference) => wi.id! ), undefined, undefined ); return { content: [ { type: "text", text: JSON.stringify(workItems, null, 2), }, ], }; } catch (error) { logError("Error listing work items", error); throw error; } }
- src/schemas/workItems.ts:6-13 (schema)Zod schema for validating input parameters to listWorkItems function, with project required and others optional.export const listWorkItemsSchema = z.object({ project: z.string(), types: z.array(z.string()).optional(), states: z.array(z.string()).optional(), assignedTo: z.string().optional(), }); export type ListWorkItemsParams = z.infer<typeof listWorkItemsSchema>;
- src/index.ts:69-70 (registration)Registration of the tool handler in the MCP server's CallToolRequestSchema switch statement.case "list_work_items": return await listWorkItems(request.params.arguments || {});
- src/tools/workItems.ts:219-246 (registration)Tool definition object exported in workItemTools array, used for MCP ListTools response defining the tool's name, description, and input schema.{ name: "list_work_items", description: "List work items in a project", inputSchema: { type: "object", properties: { project: { type: "string", description: "Name of the Azure DevOps project", }, types: { type: "array", items: { type: "string" }, description: "Filter by work item types", }, states: { type: "array", items: { type: "string" }, description: "Filter by states", }, assignedTo: { type: "string", description: "Filter by assigned user", }, }, required: ["project"], }, },
- src/index.ts:50-63 (registration)MCP server handler for ListToolsRequestSchema that includes workItemTools in the tools list for registration.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ // Work Items ...workItemTools, // Pull Requests ...pullRequestTools, // Wiki ...wikiTools, // Projects ...projectTools, ], }; });