create_work_item

Instructions

Implementation Reference

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

  The core handler function that creates a work item via Azure DevOps API. Builds a JSON patch document with title (required), plus optional fields (description, assignedTo, areaPath, iterationPath, priority, parentId, additionalFields), then calls witApi.createWorkItem().

  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/schemas.ts:39-80 (schema)

  Zod schema definition for the create_work_item tool input. Defines projectId, organizationId, workItemType (required), title (required), and optional fields: description, assignedTo, areaPath, iterationPath, priority, parentId, additionalFields.

  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-40 (registration)

  Tool registration entry in tool-definitions.ts defining the tool name 'create_work_item' with description and inputSchema derived from CreateWorkItemSchema.

    {
      name: 'create_work_item',
      description: 'Create a new work item',
      inputSchema: zodToJsonSchema(CreateWorkItemSchema),
    },
    {
      name: 'update_work_item',
      description: 'Update an existing work item',
      inputSchema: zodToJsonSchema(UpdateWorkItemSchema),
    },
    {
      name: 'manage_work_item_link',
      description: 'Add or remove links between work items',
      inputSchema: zodToJsonSchema(ManageWorkItemLinkSchema),
    },
  ];

• src/features/work-items/index.ts:90-148 (registration)

  Request handler routing in the work-items feature index. The 'create_work_item' case parses arguments via CreateWorkItemSchema, then invokes the createWorkItem handler function with the connection, projectId, workItemType, and options.

      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) }],
        };
      }
      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) }],
        };
      }
      case 'manage_work_item_link': {
        const args = ManageWorkItemLinkSchema.parse(request.params.arguments);
        const result = await manageWorkItemLink(
          connection,
          args.projectId ?? defaultProject,
          {
            sourceWorkItemId: args.sourceWorkItemId,
            targetWorkItemId: args.targetWorkItemId,
            operation: args.operation,
            relationType: args.relationType,
            newRelationType: args.newRelationType,
            comment: args.comment,
          },
        );
        return {
          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        };
      }
      default:
        throw new Error(`Unknown work items tool: ${request.params.name}`);
    }
  };

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

  TypeScript interface 'CreateWorkItemOptions' defining the typed options object for creating work items (title, description, assignedTo, areaPath, iterationPath, priority, parentId, additionalFields).

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