add_parent_child_link
Establish hierarchical relationships between work items to organize epics, features, user stories, and tasks for structured work breakdown and progress tracking.
Instructions
Adds a parent-child relationship between two work items.
Use this tool when you need to:
- Establish hierarchy between work items
- Organize epics, features, user stories, and tasks
- Create a structured breakdown of work
- Enable rollup of effort and progress tracking
IMPORTANT: The child work item will immediately appear under the parent
in hierarchical views. This relationship affects how the items are
displayed in backlogs and boards. In Azure DevOps, a work item can have
only one parent but multiple children.
Args:
parent_id: ID of the parent work item
child_id: ID of the child work item
project: Optional project name or ID
Returns:
Formatted string containing the updated child work item details
showing the new parent relationship, formatted as markdown
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| parent_id | Yes | ||
| child_id | Yes | ||
| project | No |
Implementation Reference
- The handler and registration for the 'add_parent_child_link' MCP tool. It takes parent_id and child_id, retrieves the work item client, and calls the helper _add_link_to_work_item_impl to add a 'System.LinkTypes.Hierarchy-Reverse' relation from child to parent on the child work item.
@mcp.tool() def add_parent_child_link( parent_id: int, child_id: int, project: Optional[str] = None, ) -> str: """ Adds a parent-child relationship between two work items. Use this tool when you need to: - Establish hierarchy between work items - Organize epics, features, user stories, and tasks - Create a structured breakdown of work - Enable rollup of effort and progress tracking IMPORTANT: The child work item will immediately appear under the parent in hierarchical views. This relationship affects how the items are displayed in backlogs and boards. In Azure DevOps, a work item can have only one parent but multiple children. Args: parent_id: ID of the parent work item child_id: ID of the child work item project: Optional project name or ID Returns: Formatted string containing the updated child work item details showing the new parent relationship, formatted as markdown """ try: wit_client = get_work_item_client() return _add_link_to_work_item_impl( source_id=child_id, target_id=parent_id, link_type="System.LinkTypes.Hierarchy-Reverse", wit_client=wit_client, project=project ) except AzureDevOpsClientError as e: return f"Error: {str(e)}" except Exception as e: return f"Error creating parent-child link: {str(e)}" - Core helper function that implements adding a link to a work item by building a JsonPatchOperation to add a relation and updating the work item via the Azure DevOps client.
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) - Helper function that constructs the JsonPatchOperation document specifically for adding a relation link to a work item.
def _build_link_document(target_id: int, link_type: str, org_url: str) -> list: """ Build a document for creating a link between work items. Args: target_id: ID of the target work item to link to link_type: Type of link to create org_url: Base organization URL Returns: List of JsonPatchOperation objects """ return [ JsonPatchOperation( op="add", path="/relations/-", value={ "rel": link_type, "url": f"{org_url}/_apis/wit/workItems/{target_id}" } ) ]