Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/work-items/list-work-items/feature.ts:33-125 (handler)

  The core handler function implementing the list_work_items tool. It queries Azure DevOps work items using WIQL or a saved query ID, applies pagination, retrieves details for specified fields, and handles errors.

  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)}`,
      );
    }
  }

• src/features/work-items/schemas.ts:20-34 (schema)

  Zod schema defining the input validation for list_work_items tool parameters.

  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)

  Tool definition object registering the list_work_items tool with name, description, and JSON schema.

  {
    name: 'list_work_items',
    description: 'List work items in a project',
    inputSchema: zodToJsonSchema(ListWorkItemsSchema),
  },

• src/features/work-items/index.ts:76-88 (registration)

  Dispatch handler case for list_work_items that validates input with schema and invokes the handler 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) }],
    };

• src/features/work-items/types.ts:9-16 (helper)

  TypeScript interface defining options for the listWorkItems handler function, matching the schema.

  export interface ListWorkItemsOptions {
    projectId: string;
    teamId?: string;
    queryId?: string;
    wiql?: string;
    top?: number;
    skip?: number;
  }