article email support - fixes #205

docker-compose.yml

@@ -0,0 +1,16 @@
+version: '3.8'
+
+services:
+  zammad-mcp:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      - ZAMMAD_URL=${ZAMMAD_URL}
+      - ZAMMAD_HTTP_TOKEN=${ZAMMAD_HTTP_TOKEN}
+      - MCP_TRANSPORT=http
+      - MCP_HOST=0.0.0.0
+      - MCP_PORT=8000
+    ports:
+      - "9146:8000"
+    restart: unless-stopped

mcp_zammad/__main__.py

@@ -1,7 +1,7 @@
 """Entry point for the Zammad MCP server."""
 
 from .config import TransportConfig, TransportType
-from .server import mcp
+from .server import _configure_logging, mcp
 
 
 def main() -> None:
@@ -12,6 +12,9 @@ def main() -> None:
     - MCP_HOST: Host for HTTP transport (default: 127.0.0.1)
     - MCP_PORT: Port for HTTP transport (required if transport=http)
     """
+    # Configure logging first to prevent output leakage
+    _configure_logging()
+
     # Load transport configuration from environment
     config = TransportConfig.from_env()
     config.validate()

mcp_zammad/client.py

@@ -240,6 +240,10 @@ def add_article(
         article_type: str = "note",
         internal: bool = False,
         sender: str = "Agent",
+        subject: str | None = None,
+        to: str | None = None,
+        cc: str | None = None,
+        content_type: str | None = None,
         attachments: list[dict[str, str]] | None = None,
     ) -> dict[str, Any]:
         """Add an article (comment/note) to a ticket with optional attachments.
@@ -250,6 +254,10 @@ def add_article(
             article_type: Article type (note, email, phone)
             internal: Whether the article is internal
             sender: Sender type (Agent, Customer, System)
+            subject: Optional article subject (for emails)
+            to: Optional email recipient (for email type)
+            cc: Optional email CC recipients
+            content_type: Optional content type (text/plain or text/html)
             attachments: Optional list of attachments with keys:
                 - filename: str
                 - data: str (base64-encoded content)
@@ -266,6 +274,14 @@ def add_article(
             "sender": sender,
         }
 
+        if subject:
+            article_data["subject"] = subject
+        if to:
+            article_data["to"] = to
+        if cc:
+            article_data["cc"] = cc
+        if content_type:
+            article_data["content_type"] = content_type
         if attachments:
             article_data["attachments"] = attachments
 

mcp_zammad/models.py

@@ -322,6 +322,10 @@ class ArticleCreate(StrictBaseModel):
     article_type: ArticleType = Field(default=ArticleType.NOTE, alias="type", description="Article type")
     internal: bool = Field(default=False, description="Whether the article is internal")
     sender: ArticleSender = Field(default=ArticleSender.AGENT, description="Sender type")
+    subject: str | None = Field(default=None, description="Article subject (for emails)")
+    to: str | None = Field(default=None, description="Email recipient (for email type)")
+    cc: str | None = Field(default=None, description="Email CC recipients")
+    content_type: str | None = Field(default=None, description="Content type (text/plain or text/html)")
     attachments: list[AttachmentUpload] | None = Field(
         default=None, description="Optional attachments to include", max_length=10
     )

mcp_zammad/server.py

@@ -5,6 +5,7 @@
 import json
 import logging
 import os
+import sys
 import time
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
@@ -819,7 +820,9 @@ async def lifespan(_app: FastMCP) -> AsyncIterator[None]:
     def get_client(self) -> ZammadClient:
         """Get the Zammad client, ensuring it's initialized."""
         if not self.client:
-            raise RuntimeError("Zammad client not initialized")
+            logger.debug("Zammad client not initialized, performing lazy initialization")
+            # Lazy initialization for cases where lifespan initialization hasn't finished
+            self.client = ZammadClient()
         return self.client
 
     async def initialize(self) -> None:
@@ -2548,7 +2551,7 @@ def _configure_logging() -> None:
 
     # Add handler if none exists
     if not root_logger.handlers:
-        handler = logging.StreamHandler()
+        handler = logging.StreamHandler(sys.stderr)
         handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
         root_logger.addHandler(handler)
 

tests/test_server.py

@@ -12,6 +12,7 @@
 import pytest
 import requests
 from pydantic import ValidationError
+from zammad_py.exceptions import ConfigException
 
 from mcp_zammad.models import (
     Article,
@@ -249,8 +250,8 @@ def test_tool_without_client():
     server_inst = ZammadMCPServer()
     server_inst.client = None
 
-    # Should raise RuntimeError when client is not initialized
-    with pytest.raises(RuntimeError, match="Zammad client not initialized"):
+    # Should raise ConfigException when client is not initialized and env vars are missing
+    with pytest.raises(ConfigException, match="Zammad URL is required"):
         server_inst.get_client()
 
 
@@ -517,7 +518,16 @@ def test_add_article_tool(mock_zammad_client, sample_article_data, decorator_cap
 
     # Verify the client was called with correct params (including attachments=None for backward compat)
     mock_instance.add_article.assert_called_once_with(
-        ticket_id=1, article_type="note", attachments=None, body="New comment", internal=False, sender="Agent"
+        ticket_id=1,
+        article_type="note",
+        attachments=None,
+        body="New comment",
+        internal=False,
+        sender="Agent",
+        subject=None,
+        to=None,
+        cc=None,
+        content_type=None,
     )
 
 
@@ -598,9 +608,71 @@ def test_add_article_with_attachments_tool(mock_zammad_client, decorator_capture
     assert "attachments" in call_kwargs
     assert call_kwargs["attachments"] is not None
     assert len(call_kwargs["attachments"]) == 1
-    assert call_kwargs["attachments"][0]["filename"] == "doc.pdf"
-    assert call_kwargs["attachments"][0]["data"] == "dGVzdA=="
-    assert call_kwargs["attachments"][0]["mime-type"] == "application/pdf"
+
+
+def test_add_article_with_email_fields(mock_zammad_client, decorator_capturer):
+    """Test zammad_add_article tool with email-specific fields."""
+    mock_instance, _ = mock_zammad_client
+
+    # Mock client response
+    mock_instance.add_article.return_value = {
+        "id": 456,
+        "ticket_id": 123,
+        "body": "Email body",
+        "type": "email",
+        "internal": False,
+        "sender": "Agent",
+        "subject": "Re: Help",
+        "to": "customer@example.com",
+        "cc": "boss@example.com",
+        "content_type": "text/plain",
+        "created_at": "2024-01-15T16:30:00Z",
+        "updated_at": "2024-01-15T16:30:00Z",
+        "created_by_id": 1,
+        "updated_by_id": 1,
+    }
+
+    server_inst = ZammadMCPServer()
+    server_inst.client = mock_instance
+
+    # Capture tools using shared fixture
+    test_tools, capture_tool = decorator_capturer(server_inst.mcp.tool)
+    server_inst.mcp.tool = capture_tool  # type: ignore[method-assign, assignment]
+    server_inst.get_client = lambda: server_inst.client  # type: ignore[method-assign, assignment, return-value]
+    server_inst._setup_tools()
+
+    # Create params with email fields
+    params = ArticleCreate(
+        ticket_id=123,
+        body="Email body",
+        article_type=ArticleType.EMAIL,
+        subject="Re: Help",
+        to="customer@example.com",
+        cc="boss@example.com",
+        content_type="text/plain",
+    )
+
+    # Call tool
+    result = test_tools["zammad_add_article"](params)
+
+    # Verify result
+    assert result.id == 456
+    assert result.subject == "Re: Help"
+    assert result.to == "customer@example.com"
+
+    # Verify client.add_article was called with all email fields
+    mock_instance.add_article.assert_called_once_with(
+        ticket_id=123,
+        article_type="email",
+        body="Email body",
+        internal=False,
+        sender="Agent",
+        subject="Re: Help",
+        to="customer@example.com",
+        cc="boss@example.com",
+        content_type="text/plain",
+        attachments=None,
+    )
 
 
 def test_add_article_without_attachments_backward_compat_tool(mock_zammad_client, decorator_capturer):
@@ -1277,7 +1349,7 @@ def test_get_client_error():
     server = ZammadMCPServer()
     server.client = None
 
-    with pytest.raises(RuntimeError, match="Zammad client not initialized"):
+    with pytest.raises(ConfigException, match="Zammad URL is required"):
         server.get_client()