feat: add zammad_merge_tickets tool via legacy ticket_merge REST endpoint

Wraps PUT /api/v1/ticket_merge/{source_id}/{target_number} (zammad_py does
not expose merge; the newer PUT /tickets/{id}/merge route 404s on some
instances). Target can be given by display number or internal ID (number
is looked up). Failed merges (HTTP 200 + result='failed') raise ValueError
instead of being reported as success.

Tests: 6 client + 6 model cases; suite 236 passed.

Author: iisat

README.md

@@ -19,6 +19,7 @@ An MCP server that connects AI assistants to Zammad, providing tools for managin
   - `zammad_update_ticket` - Update ticket properties
   - `zammad_add_article` - Add comments/notes to tickets
   - `zammad_add_ticket_tag` / `zammad_remove_ticket_tag` - Manage ticket tags
+  - `zammad_merge_tickets` - Merge a source ticket into a target ticket (moves all articles; irreversible)
   - `zammad_get_ticket_tags` - Get tags assigned to a specific ticket
   - `zammad_list_tags` - List all tags defined in the system (requires admin.tag permission)
 

mcp_zammad/client.py

@@ -269,6 +269,63 @@ def update_ticket(
 
         return dict(self.api.ticket.update(ticket_id, update_data))
 
+    def merge_tickets(
+        self,
+        source_ticket_id: int,
+        target_ticket_number: str | None = None,
+        target_ticket_id: int | None = None,
+    ) -> dict[str, Any]:
+        """
+        Merge a duplicate ticket into a target ticket.
+
+        The source ticket's articles are moved into the target ticket and the
+        source ticket receives the state 'merged'. This operation cannot be undone.
+
+        Uses the legacy REST endpoint PUT /api/v1/ticket_merge/{source_id}/{target_number}
+        via zammad_py's internal session, since the library does not expose ticket
+        merge and the newer PUT /tickets/{id}/merge route returns 404 on some instances.
+
+        Exactly one of target_ticket_number / target_ticket_id must be provided.
+        When only the target's internal ID is known, its display number is looked up first.
+
+        Parameters
+        ----------
+        source_ticket_id : int
+            Internal database ID of the duplicate ticket
+        target_ticket_number : str | None
+            Display number of the ticket to merge into
+        target_ticket_id : int | None
+            Internal database ID of the ticket to merge into
+
+        Returns
+        -------
+        dict
+            Merge result payload with 'result', 'target_ticket' and 'source_ticket'
+
+        Raises
+        ------
+        ValueError
+            If both or neither target identifier is provided, or if the
+            API reports the merge as failed (the ticket_merge endpoint answers
+            failures with HTTP 200 and {"result": "failed", "message": ...}).
+        requests.HTTPError
+            If the API request itself fails.
+
+        """
+        if (target_ticket_number is None) == (target_ticket_id is None):
+            raise ValueError("Provide exactly one of target_ticket_number or target_ticket_id")
+
+        if target_ticket_number is None:
+            target = self.api.ticket.find(target_ticket_id)
+            target_ticket_number = str(target["number"])
+
+        response = self.api.session.put(f"{self.url}/ticket_merge/{source_ticket_id}/{target_ticket_number}")
+        response.raise_for_status()
+        payload = response.json()
+        if payload.get("result") != "success":
+            raise ValueError(f"Ticket merge failed: {payload.get('message', payload)}")
+        return dict(payload)
+
     def add_article(
         self,
         ticket_id: int,

mcp_zammad/models.py

@@ -384,6 +384,45 @@ def sanitize_title(cls, v: str | None) -> str | None:
         return html.escape(v) if v else v
 
 
+class TicketMergeParams(StrictBaseModel):
+    """
+    Merge ticket request parameters.
+
+    Exactly one of target_ticket_number / target_ticket_id must be provided.
+    """
+
+    source_ticket_id: int = Field(
+        gt=0,
+        description="Internal database ID of the duplicate ticket (it is merged away and gets state 'merged')",
+    )
+    target_ticket_number: str | None = Field(
+        None,
+        min_length=1,
+        max_length=50,
+        description="Display number of the ticket to merge into (e.g. '65003')",
+    )
+    target_ticket_id: int | None = Field(
+        None,
+        gt=0,
+        description="Internal database ID of the ticket to merge into (its number is looked up automatically)",
+    )
+
+    @model_validator(mode="after")
+    def exactly_one_target(self) -> "TicketMergeParams":
+        """Ensure exactly one target identifier is provided."""
+        if (self.target_ticket_number is None) == (self.target_ticket_id is None):
+            raise ValueError("Provide exactly one of target_ticket_number or target_ticket_id")
+        return self
+
+
+class TicketMergeResult(BaseModel):
+    """Result of a ticket merge operation."""
+
+    result: str = Field(description="Merge status ('success' on success)")
+    target_ticket: Ticket = Field(description="The surviving ticket after the merge")
+    source_ticket: Ticket | None = Field(None, description="The merged (duplicate) ticket, if returned by the API")
+
+
 class GetArticleAttachmentsParams(StrictBaseModel):
     """Get article attachments request parameters."""
 

mcp_zammad/server.py

@@ -48,6 +48,8 @@
     Ticket,
     TicketCreate,
     TicketIdGuidanceError,
+    TicketMergeParams,
+    TicketMergeResult,
     TicketPriority,
     TicketSearchParams,
     TicketState,
@@ -1173,6 +1175,62 @@ def zammad_update_ticket(params: TicketUpdateParams) -> Ticket:
             except Exception as e:
                 _handle_ticket_not_found_error(params.ticket_id, e)
 
+        @self.mcp.tool(annotations=_write_annotations("Merge Tickets"))
+        def zammad_merge_tickets(params: TicketMergeParams) -> TicketMergeResult:
+            """Merge a duplicate ticket into another ticket (irreversible).
+
+            The source ticket's articles are moved into the target ticket and the
+            source ticket receives the state 'merged'. The target ticket keeps its
+            owner, state, and conversation.
+
+            Args:
+                params (TicketMergeParams): Validated merge parameters containing:
+                    - source_ticket_id (int): Internal database ID of the DUPLICATE ticket
+                      (required, NOT display number - it is merged away)
+                    - target_ticket_number (str | None): Display number of the surviving
+                      ticket (e.g. "65003")
+                    - target_ticket_id (int | None): Internal database ID of the surviving
+                      ticket (its number is looked up automatically)
+
+                Exactly one of target_ticket_number / target_ticket_id must be provided.
+
+            Returns:
+                TicketMergeResult: The merge result with schema:
+
+                ```json
+                {
+                    "result": "success",
+                    "target_ticket": {"id": 124, "number": "65004", "state_id": 2, "...": "..."},
+                    "source_ticket": {"id": 123, "number": "65003", "state_id": 5, "...": "..."}
+                }
+                ```
+
+            Examples:
+                - Use when: "Merge duplicate 123 into ticket 65004" -> source_ticket_id=123, target_ticket_number="65004"
+                - Use when: "Merge ticket 123 into ticket 124" -> source_ticket_id=123, target_ticket_id=124
+                - Don't use when: Only linking related tickets (merge is irreversible)
+                - Don't use when: Adding a comment (use zammad_add_article)
+
+            Error Handling:
+                - Returns TicketIdGuidanceError if source ticket not found (suggests using search)
+                - Returns "Error: Validation failed" if both or neither target identifier is given
+                - Returns "Ticket merge failed: ..." if Zammad rejects the merge (the API
+                  answers failures with HTTP 200 and result='failed'; surfaced as an error)
+                - Returns "Error: Permission denied" if no update permissions
+
+            Note:
+                source_ticket_id / target_ticket_id are internal database IDs, NOT display
+                numbers. Use the 'id' field from search results, not the 'number' field.
+                Both customers may see the merged conversation - merge only tickets that
+                truly belong together (same organization/issue).
+            """
+            client = self.get_client()
+            try:
+                result = client.merge_tickets(**params.model_dump(exclude_none=True))
+                return TicketMergeResult(**result)
+            except Exception as e:
+                _handle_ticket_not_found_error(params.source_ticket_id, e)
+
         @self.mcp.tool(annotations=_write_annotations("Add Ticket Article"))
         def zammad_add_article(params: ArticleCreate) -> Article:
             """Add an article (comment/note/email) to an existing ticket with optional attachments.

tests/test_client_methods.py

@@ -652,3 +652,93 @@ def test_list_tags_permission_denied(self, mock_zammad_api: Mock) -> None:
 
         with pytest.raises(requests.HTTPError, match="403"):
             client.list_tags()
+
+
+class TestMergeTickets:
+    """Test ZammadClient.merge_tickets."""
+
+    @pytest.fixture
+    def mock_zammad_api(self) -> Generator[Mock, None, None]:
+        """Mock the underlying zammad_py.ZammadAPI."""
+        with patch("mcp_zammad.client.ZammadAPI") as mock_api:
+            yield mock_api
+
+    def _make_client(self, mock_zammad_api: Mock) -> tuple[ZammadClient, Mock]:
+        """Build a client with a mocked API and return (client, mock_instance)."""
+        mock_instance = Mock()
+        mock_zammad_api.return_value = mock_instance
+        client = ZammadClient(url="https://test.zammad.com/api/v1", http_token="test-token")
+        return client, mock_instance
+
+    def test_merge_with_target_number(self, mock_zammad_api: Mock) -> None:
+        """Merge uses legacy ticket_merge route with the target number."""
+        client, mock_instance = self._make_client(mock_zammad_api)
+        mock_response = Mock()
+        mock_response.json.return_value = {
+            "result": "success",
+            "target_ticket": {"id": 124, "number": "65004"},
+            "source_ticket": {"id": 123, "number": "65003", "state_id": 5},
+        }
+        mock_response.raise_for_status = Mock()
+        mock_instance.session.put.return_value = mock_response
+
+        result = client.merge_tickets(source_ticket_id=123, target_ticket_number="65004")
+
+        assert result["result"] == "success"
+        assert result["target_ticket"]["id"] == 124
+        mock_instance.session.put.assert_called_once_with("https://test.zammad.com/api/v1/ticket_merge/123/65004")
+        mock_instance.ticket.find.assert_not_called()
+
+    def test_merge_with_target_id_looks_up_number(self, mock_zammad_api: Mock) -> None:
+        """When only the target ID is given, its number is resolved first."""
+        client, mock_instance = self._make_client(mock_zammad_api)
+        mock_instance.ticket.find.return_value = {"id": 124, "number": "65004"}
+        mock_response = Mock()
+        mock_response.json.return_value = {"result": "success", "target_ticket": {"id": 124, "number": "65004"}}
+        mock_response.raise_for_status = Mock()
+        mock_instance.session.put.return_value = mock_response
+
+        result = client.merge_tickets(source_ticket_id=123, target_ticket_id=124)
+
+        mock_instance.ticket.find.assert_called_once_with(124)
+        mock_instance.session.put.assert_called_once_with("https://test.zammad.com/api/v1/ticket_merge/123/65004")
+        assert result["result"] == "success"
+
+    def test_merge_rejects_both_targets(self, mock_zammad_api: Mock) -> None:
+        """Providing both target identifiers raises ValueError."""
+        client, mock_instance = self._make_client(mock_zammad_api)
+
+        with pytest.raises(ValueError, match="exactly one"):
+            client.merge_tickets(source_ticket_id=123, target_ticket_number="65004", target_ticket_id=124)
+
+        mock_instance.session.put.assert_not_called()
+
+    def test_merge_rejects_no_target(self, mock_zammad_api: Mock) -> None:
+        """Providing no target identifier raises ValueError."""
+        client, mock_instance = self._make_client(mock_zammad_api)
+
+        with pytest.raises(ValueError, match="exactly one"):
+            client.merge_tickets(source_ticket_id=123)
+
+        mock_instance.session.put.assert_not_called()
+
+    def test_merge_http_error_propagates(self, mock_zammad_api: Mock) -> None:
+        """HTTP errors from the merge endpoint propagate."""
+        client, mock_instance = self._make_client(mock_zammad_api)
+        mock_response = Mock()
+        mock_response.raise_for_status.side_effect = requests.HTTPError("404 Not Found")
+        mock_instance.session.put.return_value = mock_response
+
+        with pytest.raises(requests.HTTPError, match="404"):
+            client.merge_tickets(source_ticket_id=123, target_ticket_number="99999")
+
+    def test_merge_failed_result_raises(self, mock_zammad_api: Mock) -> None:
+        """Zammad reports merge failures as HTTP 200 with result='failed' - must raise."""
+        client, mock_instance = self._make_client(mock_zammad_api)
+        mock_response = Mock()
+        mock_response.json.return_value = {"result": "failed", "message": "The source ticket could not be found."}
+        mock_response.raise_for_status = Mock()
+        mock_instance.session.put.return_value = mock_response
+
+        with pytest.raises(ValueError, match="source ticket could not be found"):
+            client.merge_tickets(source_ticket_id=99999999, target_ticket_number="65004")

tests/test_models.py

@@ -11,6 +11,7 @@
     GetTicketParams,
     ResponseFormat,
     TicketCreate,
+    TicketMergeParams,
     TicketUpdate,
 )
 
@@ -58,6 +59,43 @@ def test_html_sanitization_in_title(self):
         update = TicketUpdate(title="<i>Important</i> Update")  # type: ignore[call-arg]
         assert update.title == "&lt;i&gt;Important&lt;/i&gt; Update"
 
+
+class TestTicketMergeParams:
+    """Test TicketMergeParams model validation."""
+
+    def test_valid_with_target_number(self):
+        """Target by display number is accepted."""
+        params = TicketMergeParams(source_ticket_id=123, target_ticket_number="65004")  # type: ignore[call-arg]
+        assert params.source_ticket_id == 123
+        assert params.target_ticket_number == "65004"
+        assert params.target_ticket_id is None
+
+    def test_valid_with_target_id(self):
+        """Target by internal ID is accepted."""
+        params = TicketMergeParams(source_ticket_id=123, target_ticket_id=124)  # type: ignore[call-arg]
+        assert params.target_ticket_id == 124
+        assert params.target_ticket_number is None
+
+    def test_rejects_both_targets(self):
+        """Providing both target identifiers fails validation."""
+        with pytest.raises(ValidationError, match="exactly one"):
+            TicketMergeParams(source_ticket_id=123, target_ticket_number="65004", target_ticket_id=124)  # type: ignore[call-arg]
+
+    def test_rejects_no_target(self):
+        """Providing no target identifier fails validation."""
+        with pytest.raises(ValidationError, match="exactly one"):
+            TicketMergeParams(source_ticket_id=123)  # type: ignore[call-arg]
+
+    def test_rejects_invalid_source_id(self):
+        """Source ticket ID must be positive."""
+        with pytest.raises(ValidationError):
+            TicketMergeParams(source_ticket_id=0, target_ticket_number="65004")  # type: ignore[call-arg]
+
+    def test_rejects_empty_target_number(self):
+        """Target number must not be empty or whitespace-only."""
+        with pytest.raises(ValidationError):
+            TicketMergeParams(source_ticket_id=123, target_ticket_number="  ")  # type: ignore[call-arg]
+
     def test_none_title_not_sanitized(self):
         """Test that None title is not processed."""
         update = TicketUpdate(state="closed")  # type: ignore[call-arg]