create_work_item
Create and manage work items in Azure DevOps projects. Specify field values, assignees, hierarchies, and metadata to track tasks, bugs, or user stories efficiently. Outputs formatted work item details for clarity.
Instructions
Creates a new work item in Azure DevOps.
Use this tool when you need to:
- Add a new task, user story, bug, or other work item to a project
- Create work items with specific field values and metadata
- Establish work hierarchies by setting parent relationships
- Track new requirements, features, or issues in your project
IMPORTANT: The work item will be created immediately and visible to all
users with access to the specified project. It will also trigger any
configured notifications or automation rules.
Args:
title: The title of the work item
project: The project name or ID where the work item will be created
work_item_type: Type of work item (e.g., "User Story", "Bug",
"Task")
fields: Optional dictionary of additional field name/value pairs
to set
description: Optional description of the work item
state: Optional initial state for the work item
assigned_to: Optional user email to assign the work item to
parent_id: Optional ID of parent work item for hierarchy
iteration_path: Optional iteration path for the work item
area_path: Optional area path for the work item
story_points: Optional story points value
priority: Optional priority value
tags: Optional tags as comma-separated string
Returns:
Formatted string containing the created work item details including
ID, title, type, state, and all other specified fields, formatted
as markdown
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| area_path | No | ||
| assigned_to | No | ||
| description | No | ||
| fields | No | ||
| iteration_path | No | ||
| parent_id | No | ||
| priority | No | ||
| project | Yes | ||
| state | No | ||
| story_points | No | ||
| tags | No | ||
| title | Yes | ||
| work_item_type | Yes |
Implementation Reference
- Main handler function for the 'create_work_item' MCP tool. Processes input parameters, validates title, prepares standard and custom fields, gets the Azure DevOps work item client, and calls the core implementation helper.def create_work_item( title: str, project: str, work_item_type: str, fields: Optional[Dict[str, Any]] = None, description: Optional[str] = None, state: Optional[str] = None, assigned_to: Optional[str] = None, parent_id: Optional[int] = None, iteration_path: Optional[str] = None, area_path: Optional[str] = None, story_points: Optional[float] = None, priority: Optional[int] = None, tags: Optional[str] = None, ) -> str: """ Creates a new work item in Azure DevOps. Use this tool when you need to: - Add a new task, user story, bug, or other work item to a project - Create work items with specific field values and metadata - Establish work hierarchies by setting parent relationships - Track new requirements, features, or issues in your project IMPORTANT: The work item will be created immediately and visible to all users with access to the specified project. It will also trigger any configured notifications or automation rules. Args: title: The title of the work item project: The project name or ID where the work item will be created work_item_type: Type of work item (e.g., "User Story", "Bug", "Task") fields: Optional dictionary of additional field name/value pairs to set description: Optional description of the work item state: Optional initial state for the work item assigned_to: Optional user email to assign the work item to parent_id: Optional ID of parent work item for hierarchy iteration_path: Optional iteration path for the work item area_path: Optional area path for the work item story_points: Optional story points value priority: Optional priority value tags: Optional tags as comma-separated string Returns: Formatted string containing the created work item details including ID, title, type, state, and all other specified fields, formatted as markdown """ try: wit_client = get_work_item_client() # Start with standard fields all_fields = _prepare_standard_fields( title, description, state, assigned_to, iteration_path, area_path, story_points, priority, tags ) # Add custom fields if provided if fields: for field_name, field_value in fields.items(): field_name = _ensure_system_prefix(field_name) all_fields[field_name] = field_value if not all_fields.get("System.Title"): return "Error: Title is required for work item creation" return _create_work_item_impl( fields=all_fields, project=project, work_item_type=work_item_type, wit_client=wit_client, parent_id=parent_id ) except AzureDevOpsClientError as e: return f"Error: {str(e)}" except Exception as e: return f"Error creating work item: {str(e)}"
- Core helper implementing the work item creation logic: builds JSON patch document from fields, creates the work item using Azure DevOps client, optionally adds parent-child link by updating with relation, and formats the result.def _create_work_item_impl( fields: Dict[str, Any], project: str, work_item_type: str, wit_client: WorkItemTrackingClient, parent_id: Optional[int] = None, ) -> str: """ Implementation of creating a work item. Args: fields: Dictionary of field name/value pairs to set project: The project name or ID work_item_type: Type of work item (e.g., "User Story", "Bug", "Task") wit_client: Work item tracking client parent_id: Optional ID of parent work item for hierarchy Returns: Formatted string containing the created work item details """ document = _build_field_document(fields) # Create the work item new_work_item = wit_client.create_work_item( document=document, project=project, type=work_item_type ) # If parent_id is provided, establish parent-child relationship if parent_id: try: # Get organization URL from environment org_url = _get_organization_url() # Create parent-child relationship link_document = _build_link_document( target_id=parent_id, link_type="System.LinkTypes.Hierarchy-Reverse", org_url=org_url ) # Update the work item to add the parent link new_work_item = wit_client.update_work_item( document=link_document, id=new_work_item.id, project=project ) except Exception as e: return (f"Work item created successfully, but failed to establish " f"parent-child relationship: {str(e)}\n\n" f"{format_work_item(new_work_item)}") # Format and return the created work item return format_work_item(new_work_item)
- Helper to build the JsonPatchOperation document required by Azure DevOps API from a dictionary of field updates.def _build_field_document(fields: Dict[str, Any], operation: str = "add") -> list: """ Build a document of JsonPatchOperations from a dictionary of fields. Args: fields: Dictionary of field name/value pairs operation: The operation to perform (add or replace) Returns: List of JsonPatchOperation objects """ document = [] for field_name, field_value in fields.items(): # Ensure field names are prefixed with /fields/ path = (field_name if field_name.startswith("/fields/") else f"/fields/{field_name}") document.append( JsonPatchOperation( op=operation, path=path, value=field_value ) ) return document
- Helper that maps common parameter names to standard Azure DevOps work item field names (e.g., 'title' to 'System.Title') and prepares the fields dictionary for creation.def _update_work_item_impl( id: int, fields: Dict[str, Any], wit_client: WorkItemTrackingClient, project: Optional[str] = None, ) -> str: """ Implementation of updating a work item. Args: id: The ID of the work item to update fields: Dictionary of field name/value pairs to update wit_client: Work item tracking client project: Optional project name or ID Returns: Formatted string containing the updated work item details """ document = _build_field_document(fields, "replace") # Update the work item updated_work_item = wit_client.update_work_item( document=document, id=id, project=project ) return format_work_item(updated_work_item) def _add_link_to_work_item_impl( source_id: int, target_id: int, link_type: str, wit_client: WorkItemTrackingClient, project: Optional[str] = None, ) -> str: """ Implementation of adding a link between work items. Args: source_id: ID of the source work item target_id: ID of the target work item link_type: Type of link to create wit_client: Work item tracking client project: Optional project name or ID Returns: Formatted string containing the updated work item details """ # Get organization URL from environment org_url = _get_organization_url() # Build link document with the full URL link_document = _build_link_document(target_id, link_type, org_url) # Update the work item to add the link updated_work_item = wit_client.update_work_item( document=link_document, id=source_id, project=project ) return format_work_item(updated_work_item) def _prepare_standard_fields(
- Registration call that invokes the register_tools function from create.py, which defines and registers the create_work_item tool using @mcp.tool() decorator.create.register_tools(mcp)