create_work_item
Create new tasks, user stories, bugs, or other work items in Azure DevOps projects with custom fields, hierarchies, and metadata for tracking requirements and issues.
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 |
|---|---|---|---|
| title | Yes | ||
| project | Yes | ||
| work_item_type | Yes | ||
| fields | No | ||
| description | No | ||
| state | No | ||
| assigned_to | No | ||
| parent_id | No | ||
| iteration_path | No | ||
| area_path | No | ||
| story_points | No | ||
| priority | No | ||
| tags | No |
Implementation Reference
- The primary handler for the 'create_work_item' MCP tool. Decorated with @mcp.tool(), it processes input parameters, prepares standard and custom fields, retrieves the WorkItemTrackingClient, and delegates to the core implementation function. Includes comprehensive error handling and input validation.
@mcp.tool() 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 function implementing the actual work item creation logic. Builds JSON patch document from fields, creates the work item via Azure DevOps client, optionally adds parent-child link, 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 utility to convert field dictionary into Azure DevOps JsonPatchOperation list required for work item creation/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 - Aggregates and calls register_tools from all work item tool modules, including create.register_tools(mcp) which registers the create_work_item tool.
def register_tools(mcp) -> None: """ Register all work item tools with the MCP server. Args: mcp: The FastMCP server instance """ query.register_tools(mcp) read.register_tools(mcp) comments.register_tools(mcp) create.register_tools(mcp) types.register_tools(mcp) templates.register_tools(mcp) process.register_tools(mcp) - src/mcp_azure_devops/features/work_items/__init__.py:5-13 (registration)Top-level registration entry point for work items feature, calling tools.register_tools(mcp).
def register(mcp): """ Register all work items components with the MCP server. Args: mcp: The FastMCP server instance """ tools.register_tools(mcp)