create_work_item
Generate and manage new work items in Azure DevOps by specifying project ID, type, title, and optional fields like description, priority, and assignee. Streamline task creation and organization.
Instructions
Create a new work item
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| additionalFields | No | Additional fields to set on the work item | |
| areaPath | No | The area path for the work item | |
| assignedTo | No | The email or name of the user to assign the work item to | |
| description | No | The description of the work item | |
| iterationPath | No | The iteration path for the work item | |
| parentId | No | The ID of the parent work item to create a relationship with | |
| priority | No | The priority of the work item | |
| projectId | Yes | The ID or name of the project | |
| title | Yes | The title of the work item | |
| workItemType | Yes | The type of work item to create (e.g., "Task", "Bug", "User Story") |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"additionalFields": {
"additionalProperties": {},
"description": "Additional fields to set on the work item",
"type": "object"
},
"areaPath": {
"description": "The area path for the work item",
"type": "string"
},
"assignedTo": {
"description": "The email or name of the user to assign the work item to",
"type": "string"
},
"description": {
"description": "The description of the work item",
"type": "string"
},
"iterationPath": {
"description": "The iteration path for the work item",
"type": "string"
},
"parentId": {
"description": "The ID of the parent work item to create a relationship with",
"type": "number"
},
"priority": {
"description": "The priority of the work item",
"type": "number"
},
"projectId": {
"description": "The ID or name of the project",
"type": "string"
},
"title": {
"description": "The title of the work item",
"type": "string"
},
"workItemType": {
"description": "The type of work item to create (e.g., \"Task\", \"Bug\", \"User Story\")",
"type": "string"
}
},
"required": [
"projectId",
"workItemType",
"title"
],
"type": "object"
}
Implementation Reference
- Core handler function that constructs and sends the work item creation request to Azure DevOps API.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)}`, ); } }
- Zod schema for input validation of the create_work_item tool parameters.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)Tool definition registration specifying the name, description, and JSON schema for the tool.{ name: 'create_work_item', description: 'Create a new work item', inputSchema: zodToJsonSchema(CreateWorkItemSchema), },
- src/features/work-items/index.ts:90-109 (handler)Feature-level MCP tool request handler that validates input and invokes the core createWorkItem function.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/server.ts:114-124 (registration)Global tool list registration where workItemsTools (including create_work_item) is included in the MCP server's listTools response.const tools = [ ...usersTools, ...organizationsTools, ...projectsTools, ...repositoriesTools, ...workItemsTools, ...searchTools, ...pullRequestsTools, ...pipelinesTools, ...wikisTools, ];