Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/work-items/create-work-item/feature.ts:14-122 (handler)

  Core handler function that implements the logic to create a work item in Azure DevOps using the WorkItemTrackingApi.

  export async function createWorkItem(
    connection: WebApi,
    projectId: string,
    workItemType: string,
    options: CreateWorkItemOptions,
  ): Promise<WorkItem> {
    try {
      if (!options.title) {
        throw new Error('Title is required');
      }
  
      const witApi = await connection.getWorkItemTrackingApi();
  
      // Create the JSON patch document
      const document = [];
  
      // Add required fields
      document.push({
        op: 'add',
        path: '/fields/System.Title',
        value: options.title,
      });
  
      // Add optional fields if provided
      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 !== undefined) {
        document.push({
          op: 'add',
          path: '/fields/Microsoft.VSTS.Common.Priority',
          value: options.priority,
        });
      }
  
      // Add parent relationship if parentId is provided
      if (options.parentId) {
        document.push({
          op: 'add',
          path: '/relations/-',
          value: {
            rel: 'System.LinkTypes.Hierarchy-Reverse',
            url: `${connection.serverUrl}/_apis/wit/workItems/${options.parentId}`,
          },
        });
      }
  
      // 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,
          });
        }
      }
  
      // Create the work item
      const workItem = await witApi.createWorkItem(
        null,
        document,
        projectId,
        workItemType,
      );
  
      if (!workItem) {
        throw new Error('Failed to create work item');
      }
  
      return workItem;
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
      throw new Error(
        `Failed to create work item: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/work-items/index.ts:90-109 (handler)

  MCP tool request handler that validates input with schema, maps arguments, calls the core createWorkItem function, and formats the response.

  case 'create_work_item': {
    const args = CreateWorkItemSchema.parse(request.params.arguments);
    const result = await createWorkItem(
      connection,
      args.projectId ?? defaultProject,
      args.workItemType,
      {
        title: args.title,
        description: args.description,
        assignedTo: args.assignedTo,
        areaPath: args.areaPath,
        iterationPath: args.iterationPath,
        priority: args.priority,
        parentId: args.parentId,
        additionalFields: args.additionalFields,
      },
    );
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };

• src/features/work-items/schemas.ts:39-80 (schema)

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

  export const CreateWorkItemSchema = 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})`),
    workItemType: z
      .string()
      .describe(
        'The type of work item to create (e.g., "Task", "Bug", "User Story")',
      ),
    title: z.string().describe('The 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 area path for the work item'),
    iterationPath: z
      .string()
      .optional()
      .describe('The iteration path for the work item'),
    priority: z.number().optional().describe('The priority of the work item'),
    parentId: z
      .number()
      .optional()
      .describe('The ID of the parent work item to create a relationship with'),
    additionalFields: z
      .record(z.string(), z.any())
      .optional()
      .describe(
        'Additional fields to set 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:25-29 (registration)

  Registration of the create_work_item tool in the workItemsTools array, including name, description, and input schema.

  {
    name: 'create_work_item',
    description: 'Create a new work item',
    inputSchema: zodToJsonSchema(CreateWorkItemSchema),
  },

• src/features/work-items/types.ts:21-30 (schema)

  TypeScript interface matching the options used by the createWorkItem handler function.

  export interface CreateWorkItemOptions {
    title: string;
    description?: string;
    assignedTo?: string;
    areaPath?: string;
    iterationPath?: string;
    priority?: number;
    parentId?: number;
    additionalFields?: Record<string, string | number | boolean | null>;
  }