Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/work-items/get-work-item/feature.ts:38-110 (handler)

  The core handler function that retrieves a work item by ID from Azure DevOps, fetches additional field definitions to enhance the response with all possible fields set to null if missing, and handles caching and errors.

  export async function getWorkItem(
    connection: WebApi,
    workItemId: number,
    expand: string = 'all',
  ): Promise<WorkItem> {
    try {
      const witApi = await connection.getWorkItemTrackingApi();
  
      const workItem = await witApi.getWorkItem(
        workItemId,
        undefined,
        undefined,
        expandMap[expand.toLowerCase()],
      );
  
      if (!workItem) {
        throw new AzureDevOpsResourceNotFoundError(
          `Work item '${workItemId}' not found`,
        );
      }
  
      // Extract project and work item type to get all possible fields
      const projectName = workItem.fields?.['System.TeamProject'];
      const workItemType = workItem.fields?.['System.WorkItemType'];
  
      if (!projectName || !workItemType) {
        // If we can't determine the project or type, return the original work item
        return workItem;
      }
  
      // Get all possible fields for this work item type
      const allFields =
        workItemTypeFieldsCache[projectName.toString()]?.[
          workItemType.toString()
        ] ??
        (await witApi.getWorkItemTypeFieldsWithReferences(
          projectName.toString(),
          workItemType.toString(),
          WorkItemTypeFieldsExpandLevel.All,
        ));
  
      workItemTypeFieldsCache[projectName.toString()] = {
        ...workItemTypeFieldsCache[projectName.toString()],
        [workItemType.toString()]: allFields,
      };
  
      // Create a new work item object with all fields
      const enhancedWorkItem = { ...workItem };
  
      // Initialize fields object if it doesn't exist
      if (!enhancedWorkItem.fields) {
        enhancedWorkItem.fields = {};
      }
  
      // Set null for all potential fields that don't have values
      for (const field of allFields) {
        if (
          field.referenceName &&
          !(field.referenceName in enhancedWorkItem.fields)
        ) {
          enhancedWorkItem.fields[field.referenceName] = field.defaultValue;
        }
      }
  
      return enhancedWorkItem;
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
      throw new Error(
        `Failed to get work item: ${error instanceof Error ? error.message : String(error)}`,
      );
    }

• src/features/work-items/schemas.ts:7-15 (schema)

  Zod schema for validating input arguments to the get_work_item tool: requires workItemId (number), optional expand (enum for expansion level).

  export const GetWorkItemSchema = z.object({
    workItemId: z.number().describe('The ID of the work item'),
    expand: z
      .enum(['none', 'relations', 'fields', 'links', 'all'])
      .optional()
      .describe(
        'The level of detail to include in the response. Defaults to "all" if not specified.',
      ),
  });

• src/features/work-items/tool-definitions.ts:20-24 (registration)

  Tool registration definition including the tool name 'get_work_item', description, and input schema converted to JSON schema for MCP.

  {
    name: 'get_work_item',
    description: 'Get details of a specific work item',
    inputSchema: zodToJsonSchema(GetWorkItemSchema),
  },

• src/features/work-items/index.ts:65-75 (registration)

  Runtime dispatching/handling of the 'get_work_item' tool request: parses arguments with schema, calls the handler, and formats response.

  case 'get_work_item': {
    const args = GetWorkItemSchema.parse(request.params.arguments);
    const result = await getWorkItem(
      connection,
      args.workItemId,
      args.expand,
    );
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }