list_work_items
Retrieve work items in an Azure DevOps project using project ID, query ID, or WIQL. Supports filtering, pagination, and team-specific results for efficient project management.
Instructions
List work items in a project
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | The ID or name of the project | |
| queryId | No | ID of a saved work item query | |
| skip | No | Number of work items to skip | |
| teamId | No | The ID of the team | |
| top | No | Maximum number of work items to return | |
| wiql | No | Work Item Query Language (WIQL) query |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"projectId": {
"description": "The ID or name of the project",
"type": "string"
},
"queryId": {
"description": "ID of a saved work item query",
"type": "string"
},
"skip": {
"description": "Number of work items to skip",
"type": "number"
},
"teamId": {
"description": "The ID of the team",
"type": "string"
},
"top": {
"description": "Maximum number of work items to return",
"type": "number"
},
"wiql": {
"description": "Work Item Query Language (WIQL) query",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
}
Implementation Reference
- Core handler function that executes the list_work_items tool logic, querying Azure DevOps Work Item Tracking API with WIQL or query ID, applying pagination, and fetching work item details.export async function listWorkItems( connection: WebApi, options: ListWorkItemsOptions, ): Promise<WorkItemType[]> { try { const witApi = await connection.getWorkItemTrackingApi(); const { projectId, teamId, queryId, wiql } = options; let workItemRefs: WorkItemReference[] = []; if (queryId) { const teamContext: TeamContext = { project: projectId, team: teamId, }; const queryResult = await witApi.queryById(queryId, teamContext); workItemRefs = queryResult.workItems || []; } else { const query = wiql || constructDefaultWiql(projectId, teamId); const teamContext: TeamContext = { project: projectId, team: teamId, }; const queryResult = await witApi.queryByWiql({ query }, teamContext); workItemRefs = queryResult.workItems || []; } // Apply pagination in memory const { top = 200, skip } = options; if (skip !== undefined) { workItemRefs = workItemRefs.slice(skip); } if (top !== undefined) { workItemRefs = workItemRefs.slice(0, top); } const workItemIds = workItemRefs .map((ref) => ref.id) .filter((id): id is number => id !== undefined); if (workItemIds.length === 0) { return []; } const fields = [ 'System.Id', 'System.Title', 'System.State', 'System.AssignedTo', ]; const workItems = await witApi.getWorkItems( workItemIds, fields, undefined, undefined, ); if (!workItems) { return []; } return workItems.filter((wi): wi is WorkItem => wi !== undefined); } catch (error) { if (error instanceof AzureDevOpsError) { throw error; } // Check for specific error types and convert to appropriate Azure DevOps errors if (error instanceof Error) { if ( error.message.includes('Authentication') || error.message.includes('Unauthorized') ) { throw new AzureDevOpsAuthenticationError( `Failed to authenticate: ${error.message}`, ); } if ( error.message.includes('not found') || error.message.includes('does not exist') ) { throw new AzureDevOpsResourceNotFoundError( `Resource not found: ${error.message}`, ); } } throw new AzureDevOpsError( `Failed to list work items: ${error instanceof Error ? error.message : String(error)}`, ); } }
- Zod schema defining the input parameters and validation for the list_work_items tool.export const ListWorkItemsSchema = z.object({ projectId: z .string() .optional() .describe(`The ID or name of the project (Default: ${defaultProject})`), organizationId: z .string() .optional() .describe(`The ID or name of the organization (Default: ${defaultOrg})`), teamId: z.string().optional().describe('The ID of the team'), queryId: z.string().optional().describe('ID of a saved work item query'), wiql: z.string().optional().describe('Work Item Query Language (WIQL) query'), top: z.number().optional().describe('Maximum number of work items to return'), skip: z.number().optional().describe('Number of work items to skip'), });
- src/features/work-items/tool-definitions.ts:15-19 (registration)MCP ToolDefinition registration for the list_work_items tool, specifying name, description, and input schema.{ name: 'list_work_items', description: 'List work items in a project', inputSchema: zodToJsonSchema(ListWorkItemsSchema), },
- src/features/work-items/index.ts:76-88 (handler)Dispatch handler case within work-items request handler that parses arguments and invokes the listWorkItems function.case 'list_work_items': { const args = ListWorkItemsSchema.parse(request.params.arguments); const result = await listWorkItems(connection, { projectId: args.projectId ?? defaultProject, teamId: args.teamId, queryId: args.queryId, wiql: args.wiql, top: args.top, skip: args.skip, }); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], };
- TypeScript interface defining options for the listWorkItems handler function.export interface ListWorkItemsOptions { projectId: string; teamId?: string; queryId?: string; wiql?: string; top?: number; skip?: number; }