add_work_item_comment
Add comments to Azure DevOps work items to provide feedback, document decisions, or communicate with team members. Comments become permanent history and support markdown formatting.
Instructions
Adds a new comment to a work item.
Use this tool when you need to:
- Provide feedback or clarification on a work item
- Document decisions made about the work
- Add context without changing the work item's fields
- Communicate with team members about specific tasks
IMPORTANT: Comments in Azure DevOps become part of the permanent work
item history and cannot be edited or deleted after they are added. The
comment will be attributed to the user associated with the Personal
Access Token used for authentication.
Args:
id: The work item ID
text: The text of the comment (supports markdown formatting)
project: Optional project name. If not provided, will be
determined from the work item.
Returns:
Formatted string containing confirmation and the added comment with
author information and timestamp
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| text | Yes | ||
| project | No |
Implementation Reference
- Core implementation function that handles adding a comment to a work item. Resolves project name if not provided, creates CommentCreate object, calls the Azure DevOps WIT client to add the comment, and returns formatted confirmation.
def _add_work_item_comment_impl( item_id: int, text: str, wit_client: WorkItemTrackingClient, project: Optional[str] = None ) -> str: """ Implementation of work item comment addition. Args: item_id: The work item ID text: Comment text to add wit_client: Work item tracking client project: Optional project name Returns: Formatted string containing the added comment """ # If project is not provided, try to get it from the work item if not project: project = _get_project_for_work_item(item_id, wit_client) if not project: return f"Error retrieving work item {item_id} to determine project" # Create comment request comment_request = CommentCreate(text=text) # Add the comment new_comment = wit_client.add_comment( request=comment_request, project=project, work_item_id=item_id ) return f"Comment added successfully.\n\n{_format_comment(new_comment)}" - MCP tool registration for 'add_work_item_comment'. Uses @mcp.tool() decorator to register the tool with input schema (id: int, text: str, project: Optional[str]), detailed usage instructions in docstring, obtains client, calls core impl, handles errors.
@mcp.tool() def add_work_item_comment( id: int, text: str, project: Optional[str] = None ) -> str: """ Adds a new comment to a work item. Use this tool when you need to: - Provide feedback or clarification on a work item - Document decisions made about the work - Add context without changing the work item's fields - Communicate with team members about specific tasks IMPORTANT: Comments in Azure DevOps become part of the permanent work item history and cannot be edited or deleted after they are added. The comment will be attributed to the user associated with the Personal Access Token used for authentication. Args: id: The work item ID text: The text of the comment (supports markdown formatting) project: Optional project name. If not provided, will be determined from the work item. Returns: Formatted string containing confirmation and the added comment with author information and timestamp """ try: wit_client = get_work_item_client() return _add_work_item_comment_impl(id, text, wit_client, project) except AzureDevOpsClientError as e: return f"Error: {str(e)}" - Helper function to retrieve the project name from a work item by fetching the work item and extracting 'System.TeamProject' field. Used when project parameter is not provided.
def _get_project_for_work_item( item_id: int, wit_client: WorkItemTrackingClient ) -> Optional[str]: """ Get the project name for a work item. Args: item_id: The work item ID wit_client: Work item tracking client Returns: Project name or None if not found """ try: work_item = wit_client.get_work_item(item_id) if work_item and work_item.fields: return work_item.fields.get("System.TeamProject") except Exception: pass return None - Helper function to format a comment object into a readable markdown string including author, date, and text.
def _format_comment(comment) -> str: """ Format a work item comment for display. Args: comment: Comment object to format Returns: Formatted string representation of the comment """ # Format the date if available created_date = "" if hasattr(comment, 'created_date') and comment.created_date: created_date = f" on {comment.created_date}" # Format the author if available author = "Unknown" if hasattr(comment, 'created_by') and comment.created_by: if (hasattr(comment.created_by, 'display_name') and comment.created_by.display_name): author = comment.created_by.display_name # Format the comment text text = "No text" if hasattr(comment, 'text') and comment.text: text = comment.text return f"## Comment by {author}{created_date}:\n{text}" - Aggregates registration of all work items tools, including comments.register_tools(mcp) which registers the add_work_item_comment 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)