Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/work-items/update-work-item/feature.ts:18-129 (handler)

  Core handler function that executes the update_work_item tool logic by constructing a JSON patch document and calling the Azure DevOps WorkItemTrackingApi.updateWorkItem method.

  export async function updateWorkItem(
    connection: WebApi,
    workItemId: number,
    options: UpdateWorkItemOptions,
  ): Promise<WorkItem> {
    try {
      const witApi = await connection.getWorkItemTrackingApi();
  
      // Create the JSON patch document
      const document = [];
  
      // Add optional fields if provided
      if (options.title) {
        document.push({
          op: 'add',
          path: '/fields/System.Title',
          value: options.title,
        });
      }
  
      if (options.description) {
        document.push({
          op: 'add',
          path: '/fields/System.Description',
          value: options.description,
        });
      }
  
      if (options.assignedTo) {
        document.push({
          op: 'add',
          path: '/fields/System.AssignedTo',
          value: options.assignedTo,
        });
      }
  
      if (options.areaPath) {
        document.push({
          op: 'add',
          path: '/fields/System.AreaPath',
          value: options.areaPath,
        });
      }
  
      if (options.iterationPath) {
        document.push({
          op: 'add',
          path: '/fields/System.IterationPath',
          value: options.iterationPath,
        });
      }
  
      if (options.priority) {
        document.push({
          op: 'add',
          path: '/fields/Microsoft.VSTS.Common.Priority',
          value: options.priority,
        });
      }
  
      if (options.state) {
        document.push({
          op: 'add',
          path: '/fields/System.State',
          value: options.state,
        });
      }
  
      // Add any additional fields
      if (options.additionalFields) {
        for (const [key, value] of Object.entries(options.additionalFields)) {
          document.push({
            op: 'add',
            path: `/fields/${key}`,
            value: value,
          });
        }
      }
  
      // If no fields to update, throw an error
      if (document.length === 0) {
        throw new Error('At least one field must be provided for update');
      }
  
      // Update the work item
      const updatedWorkItem = await witApi.updateWorkItem(
        {}, // customHeaders
        document,
        workItemId,
        undefined, // project
        false, // validateOnly
        false, // bypassRules
        false, // suppressNotifications
        WorkItemExpand.All, // expand
      );
  
      if (!updatedWorkItem) {
        throw new AzureDevOpsResourceNotFoundError(
          `Work item '${workItemId}' not found`,
        );
      }
  
      return updatedWorkItem;
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
      throw new Error(
        `Failed to update work item: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/work-items/schemas.ts:85-117 (schema)

  Zod schema defining the input parameters and validation for the update_work_item tool.

  export const UpdateWorkItemSchema = z.object({
    workItemId: z.number().describe('The ID of the work item to update'),
    title: z.string().optional().describe('The updated title of the work item'),
    description: z
      .string()
      .optional()
      .describe(
        'Work item description in HTML format. Multi-line text fields (i.e., System.History, AcceptanceCriteria, etc.) must use HTML format. Do not use CDATA tags.',
      ),
    assignedTo: z
      .string()
      .optional()
      .describe('The email or name of the user to assign the work item to'),
    areaPath: z
      .string()
      .optional()
      .describe('The updated area path for the work item'),
    iterationPath: z
      .string()
      .optional()
      .describe('The updated iteration path for the work item'),
    priority: z
      .number()
      .optional()
      .describe('The updated priority of the work item'),
    state: z.string().optional().describe('The updated state of the work item'),
    additionalFields: z
      .record(z.string(), z.any())
      .optional()
      .describe(
        'Additional fields to update on the work item. Multi-line text fields (i.e., System.History, AcceptanceCriteria, etc.) must use HTML format. Do not use CDATA tags.',
      ),
  });

• src/features/work-items/tool-definitions.ts:30-34 (registration)

  ToolDefinition object registering the update_work_item tool with name, description, and input schema.

  {
    name: 'update_work_item',
    description: 'Update an existing work item',
    inputSchema: zodToJsonSchema(UpdateWorkItemSchema),
  },

• src/features/work-items/index.ts:111-126 (handler)

  Dispatch handler in the work items request router that parses arguments with the schema and calls the core updateWorkItem function.

  case 'update_work_item': {
    const args = UpdateWorkItemSchema.parse(request.params.arguments);
    const result = await updateWorkItem(connection, args.workItemId, {
      title: args.title,
      description: args.description,
      assignedTo: args.assignedTo,
      areaPath: args.areaPath,
      iterationPath: args.iterationPath,
      priority: args.priority,
      state: args.state,
      additionalFields: args.additionalFields,
    });
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }