mcp-ticketer 0.3.5__py3-none-any.whl → 0.12.0__py3-none-any.whl

mcp_ticketer/mcp/server/server_sdk.py

@@ -0,0 +1,93 @@
+"""FastMCP-based MCP server implementation.
+
+This module implements the MCP server using the official FastMCP SDK,
+replacing the custom JSON-RPC implementation. It provides a cleaner,
+more maintainable approach with automatic schema generation and
+better error handling.
+
+The server manages a global adapter instance that is configured at
+startup and used by all tool implementations.
+"""
+
+import logging
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from ...core.adapter import BaseAdapter
+from ...core.registry import AdapterRegistry
+
+# Initialize FastMCP server
+mcp = FastMCP("mcp-ticketer")
+
+# Global adapter instance
+_adapter: BaseAdapter | None = None
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+def configure_adapter(adapter_type: str, config: dict[str, Any]) -> None:
+    """Configure the global adapter instance.
+
+    This must be called before starting the server to initialize the
+    adapter that will handle all ticket operations.
+
+    Args:
+        adapter_type: Type of adapter to create (e.g., "linear", "jira", "github")
+        config: Configuration dictionary for the adapter
+
+    Raises:
+        ValueError: If adapter type is not registered
+        RuntimeError: If adapter configuration fails
+
+    """
+    global _adapter
+
+    try:
+        # Get adapter from registry
+        _adapter = AdapterRegistry.get_adapter(adapter_type, config)
+        logger.info(f"Configured {adapter_type} adapter for MCP server")
+    except Exception as e:
+        logger.error(f"Failed to configure adapter: {e}")
+        raise RuntimeError(f"Adapter configuration failed: {e}") from e
+
+
+def get_adapter() -> BaseAdapter:
+    """Get the configured adapter instance.
+
+    Returns:
+        The global adapter instance
+
+    Raises:
+        RuntimeError: If adapter has not been configured
+
+    """
+    if _adapter is None:
+        raise RuntimeError(
+            "Adapter not configured. Call configure_adapter() before starting server."
+        )
+    return _adapter
+
+
+# Import all tool modules to register them with FastMCP
+# These imports must come after mcp is initialized but before main()
+from . import tools  # noqa: E402, F401
+
+
+def main() -> None:
+    """Run the FastMCP server.
+
+    This function starts the server using stdio transport for
+    JSON-RPC communication with Claude Desktop/Code.
+
+    The adapter must be configured via configure_adapter() before
+    calling this function.
+
+    """
+    # Run the server with stdio transport
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

mcp_ticketer/mcp/server/tools/__init__.py

@@ -0,0 +1,47 @@
+"""MCP tool modules for ticket operations.
+
+This package contains all FastMCP tool implementations organized by
+functional area. Tools are automatically registered with the FastMCP
+server when imported.
+
+Modules:
+    ticket_tools: Basic CRUD operations for tickets
+    hierarchy_tools: Epic/Issue/Task hierarchy management
+    search_tools: Search and query operations
+    bulk_tools: Bulk create and update operations
+    comment_tools: Comment management
+    pr_tools: Pull request integration
+    attachment_tools: File attachment handling
+    instruction_tools: Ticket instructions management
+    config_tools: Configuration management (adapter, project, user settings)
+    user_ticket_tools: User-specific ticket operations (my tickets, transitions)
+
+"""
+
+# Import all tool modules to register them with FastMCP
+# Order matters - import core functionality first
+from . import (
+    attachment_tools,  # noqa: F401
+    bulk_tools,  # noqa: F401
+    comment_tools,  # noqa: F401
+    config_tools,  # noqa: F401
+    hierarchy_tools,  # noqa: F401
+    instruction_tools,  # noqa: F401
+    pr_tools,  # noqa: F401
+    search_tools,  # noqa: F401
+    ticket_tools,  # noqa: F401
+    user_ticket_tools,  # noqa: F401
+)
+
+__all__ = [
+    "ticket_tools",
+    "hierarchy_tools",
+    "search_tools",
+    "bulk_tools",
+    "comment_tools",
+    "pr_tools",
+    "attachment_tools",
+    "instruction_tools",
+    "config_tools",
+    "user_ticket_tools",
+]

mcp_ticketer/mcp/server/tools/attachment_tools.py

@@ -0,0 +1,226 @@
+"""Attachment management tools for tickets.
+
+This module implements tools for attaching files to tickets and retrieving
+attachment information. Note that file attachment functionality may not be
+available in all adapters.
+"""
+
+import mimetypes
+from pathlib import Path
+from typing import Any
+
+from ....core.models import Comment, TicketType
+from ..server_sdk import get_adapter, mcp
+
+
+@mcp.tool()
+async def ticket_attach(
+    ticket_id: str,
+    file_path: str,
+    description: str = "",
+) -> dict[str, Any]:  # Keep as dict for MCP compatibility
+    """Attach a file to a ticket.
+
+    Uploads a file and associates it with the specified ticket. This
+    functionality may not be available in all adapters.
+
+    Args:
+        ticket_id: Unique identifier of the ticket
+        file_path: Path to the file to attach
+        description: Optional description of the attachment
+
+    Returns:
+        Attachment details including URL or ID, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Read ticket to validate it exists and determine type
+        ticket = await adapter.read(ticket_id)
+        if ticket is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found",
+            }
+
+        # Check if file exists
+        file_path_obj = Path(file_path)
+        if not file_path_obj.exists():
+            return {
+                "status": "error",
+                "error": f"File not found: {file_path}",
+                "ticket_id": ticket_id,
+            }
+
+        # Try Linear-specific upload methods first (most advanced)
+        if hasattr(adapter, "upload_file") and hasattr(adapter, "attach_file_to_issue"):
+            try:
+                # Determine MIME type
+                mime_type = mimetypes.guess_type(file_path)[0]
+
+                # Upload file to Linear's storage
+                file_url = await adapter.upload_file(file_path, mime_type)  # type: ignore
+
+                # Determine ticket type and attach accordingly
+                ticket_type = getattr(ticket, "ticket_type", None)
+                filename = file_path_obj.name
+
+                if ticket_type == TicketType.EPIC and hasattr(
+                    adapter, "attach_file_to_epic"
+                ):
+                    # Attach to epic (project)
+                    result = await adapter.attach_file_to_epic(  # type: ignore
+                        epic_id=ticket_id,
+                        file_url=file_url,
+                        title=description or filename,
+                        subtitle=f"Uploaded file: {filename}",
+                    )
+                else:
+                    # Attach to issue/task
+                    result = await adapter.attach_file_to_issue(  # type: ignore
+                        issue_id=ticket_id,
+                        file_url=file_url,
+                        title=description or filename,
+                        subtitle=f"Uploaded file: {filename}",
+                        comment_body=description if description else None,
+                    )
+
+                return {
+                    "status": "completed",
+                    "ticket_id": ticket_id,
+                    "method": "linear_native_upload",
+                    "file_url": file_url,
+                    "attachment": result,
+                }
+            except Exception:
+                # Fall through to legacy method if Linear-specific upload fails
+                pass
+
+        # Try legacy add_attachment method
+        if hasattr(adapter, "add_attachment"):
+            attachment = await adapter.add_attachment(  # type: ignore
+                ticket_id=ticket_id, file_path=file_path, description=description
+            )
+
+            return {
+                "status": "completed",
+                "ticket_id": ticket_id,
+                "method": "adapter_native",
+                "attachment": attachment,
+            }
+
+        # Fallback: Add file reference as comment
+        comment_text = f"Attachment: {file_path}"
+        if description:
+            comment_text += f"\nDescription: {description}"
+
+        comment = Comment(
+            ticket_id=ticket_id,
+            content=comment_text,
+        )
+
+        created_comment = await adapter.add_comment(comment)
+
+        return {
+            "status": "completed",
+            "ticket_id": ticket_id,
+            "method": "comment_reference",
+            "file_path": file_path,
+            "comment": created_comment.model_dump(),
+            "note": "Adapter does not support direct file uploads. File reference added as comment.",
+        }
+
+    except FileNotFoundError:
+        return {
+            "status": "error",
+            "error": f"File not found: {file_path}",
+            "ticket_id": ticket_id,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to attach file: {str(e)}",
+            "ticket_id": ticket_id,
+        }
+
+
+@mcp.tool()
+async def ticket_attachments(
+    ticket_id: str,
+) -> dict[str, Any]:  # Keep as dict for MCP compatibility
+    """Get all attachments for a ticket.
+
+    Retrieves a list of all files attached to the specified ticket.
+    This functionality may not be available in all adapters.
+
+    Args:
+        ticket_id: Unique identifier of the ticket
+
+    Returns:
+        List of attachments with metadata, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Read ticket to validate it exists
+        ticket = await adapter.read(ticket_id)
+        if ticket is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found",
+            }
+
+        # Check if adapter supports attachments
+        if not hasattr(adapter, "get_attachments"):
+            return {
+                "status": "error",
+                "error": f"Attachment retrieval not supported by {type(adapter).__name__} adapter",
+                "ticket_id": ticket_id,
+                "note": "Check ticket comments for file references",
+            }
+
+        # Get attachments via adapter
+        attachments = await adapter.get_attachments(ticket_id)  # type: ignore
+
+        return {
+            "status": "completed",
+            "ticket_id": ticket_id,
+            "attachments": attachments,
+            "count": len(attachments) if isinstance(attachments, list) else 0,
+        }
+
+    except AttributeError:
+        # Fallback: Check comments for attachment references
+        comments = await adapter.get_comments(ticket_id=ticket_id, limit=100)
+
+        # Look for comments that reference files
+        attachment_refs = []
+        for comment in comments:
+            content = comment.content or ""
+            if content.startswith("Attachment:") or "file://" in content:
+                attachment_refs.append(
+                    {
+                        "type": "comment_reference",
+                        "comment_id": comment.id,
+                        "content": content,
+                        "created_at": comment.created_at,
+                    }
+                )
+
+        return {
+            "status": "completed",
+            "ticket_id": ticket_id,
+            "method": "comment_references",
+            "attachments": attachment_refs,
+            "count": len(attachment_refs),
+            "note": "Adapter does not support direct attachments. Showing file references from comments.",
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to get attachments: {str(e)}",
+            "ticket_id": ticket_id,
+        }

mcp_ticketer/mcp/server/tools/bulk_tools.py

@@ -0,0 +1,273 @@
+"""Bulk operations for creating and updating multiple tickets.
+
+This module implements tools for batch operations on tickets to improve
+efficiency when working with multiple items.
+"""
+
+from typing import Any
+
+from ....core.models import Priority, Task, TicketState, TicketType
+from ..server_sdk import get_adapter, mcp
+
+
+@mcp.tool()
+async def ticket_bulk_create(
+    tickets: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Create multiple tickets in a single operation.
+
+    Each ticket dict should contain at minimum a 'title' field, with optional
+    fields: description, priority, tags, assignee, ticket_type, parent_epic, parent_issue.
+
+    Args:
+        tickets: List of ticket dictionaries to create
+
+    Returns:
+        Results of bulk creation including successes and failures
+
+    """
+    try:
+        adapter = get_adapter()
+
+        if not tickets:
+            return {
+                "status": "error",
+                "error": "No tickets provided for bulk creation",
+            }
+
+        results = {
+            "created": [],
+            "failed": [],
+        }
+
+        for i, ticket_data in enumerate(tickets):
+            try:
+                # Validate required fields
+                if "title" not in ticket_data:
+                    results["failed"].append(
+                        {
+                            "index": i,
+                            "error": "Missing required field: title",
+                            "data": ticket_data,
+                        }
+                    )
+                    continue
+
+                # Parse priority if provided
+                priority = Priority.MEDIUM  # Default
+                if "priority" in ticket_data:
+                    try:
+                        priority = Priority(ticket_data["priority"].lower())
+                    except ValueError:
+                        results["failed"].append(
+                            {
+                                "index": i,
+                                "error": f"Invalid priority: {ticket_data['priority']}",
+                                "data": ticket_data,
+                            }
+                        )
+                        continue
+
+                # Parse ticket type if provided
+                ticket_type = TicketType.ISSUE  # Default
+                if "ticket_type" in ticket_data:
+                    try:
+                        ticket_type = TicketType(ticket_data["ticket_type"].lower())
+                    except ValueError:
+                        results["failed"].append(
+                            {
+                                "index": i,
+                                "error": f"Invalid ticket_type: {ticket_data['ticket_type']}",
+                                "data": ticket_data,
+                            }
+                        )
+                        continue
+
+                # Create task object
+                task = Task(
+                    title=ticket_data["title"],
+                    description=ticket_data.get("description", ""),
+                    priority=priority,
+                    ticket_type=ticket_type,
+                    tags=ticket_data.get("tags", []),
+                    assignee=ticket_data.get("assignee"),
+                    parent_epic=ticket_data.get("parent_epic"),
+                    parent_issue=ticket_data.get("parent_issue"),
+                )
+
+                # Create via adapter
+                created = await adapter.create(task)
+                results["created"].append(
+                    {
+                        "index": i,
+                        "ticket": created.model_dump(),
+                    }
+                )
+
+            except Exception as e:
+                results["failed"].append(
+                    {
+                        "index": i,
+                        "error": str(e),
+                        "data": ticket_data,
+                    }
+                )
+
+        return {
+            "status": "completed",
+            "summary": {
+                "total": len(tickets),
+                "created": len(results["created"]),
+                "failed": len(results["failed"]),
+            },
+            "results": results,
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Bulk creation failed: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def ticket_bulk_update(
+    updates: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Update multiple tickets in a single operation.
+
+    Each update dict must contain 'ticket_id' and at least one field to update.
+    Valid update fields: title, description, priority, state, assignee, tags.
+
+    Args:
+        updates: List of update operation dictionaries
+
+    Returns:
+        Results of bulk update including successes and failures
+
+    """
+    try:
+        adapter = get_adapter()
+
+        if not updates:
+            return {
+                "status": "error",
+                "error": "No updates provided for bulk operation",
+            }
+
+        results = {
+            "updated": [],
+            "failed": [],
+        }
+
+        for i, update_data in enumerate(updates):
+            try:
+                # Validate required fields
+                if "ticket_id" not in update_data:
+                    results["failed"].append(
+                        {
+                            "index": i,
+                            "error": "Missing required field: ticket_id",
+                            "data": update_data,
+                        }
+                    )
+                    continue
+
+                ticket_id = update_data["ticket_id"]
+
+                # Build update dict
+                update_fields: dict[str, Any] = {}
+
+                if "title" in update_data:
+                    update_fields["title"] = update_data["title"]
+                if "description" in update_data:
+                    update_fields["description"] = update_data["description"]
+                if "assignee" in update_data:
+                    update_fields["assignee"] = update_data["assignee"]
+                if "tags" in update_data:
+                    update_fields["tags"] = update_data["tags"]
+
+                # Parse priority if provided
+                if "priority" in update_data:
+                    try:
+                        update_fields["priority"] = Priority(
+                            update_data["priority"].lower()
+                        )
+                    except ValueError:
+                        results["failed"].append(
+                            {
+                                "index": i,
+                                "error": f"Invalid priority: {update_data['priority']}",
+                                "data": update_data,
+                            }
+                        )
+                        continue
+
+                # Parse state if provided
+                if "state" in update_data:
+                    try:
+                        update_fields["state"] = TicketState(
+                            update_data["state"].lower()
+                        )
+                    except ValueError:
+                        results["failed"].append(
+                            {
+                                "index": i,
+                                "error": f"Invalid state: {update_data['state']}",
+                                "data": update_data,
+                            }
+                        )
+                        continue
+
+                if not update_fields:
+                    results["failed"].append(
+                        {
+                            "index": i,
+                            "error": "No valid update fields provided",
+                            "data": update_data,
+                        }
+                    )
+                    continue
+
+                # Update via adapter
+                updated = await adapter.update(ticket_id, update_fields)
+                if updated is None:
+                    results["failed"].append(
+                        {
+                            "index": i,
+                            "error": f"Ticket {ticket_id} not found or update failed",
+                            "data": update_data,
+                        }
+                    )
+                else:
+                    results["updated"].append(
+                        {
+                            "index": i,
+                            "ticket": updated.model_dump(),
+                        }
+                    )
+
+            except Exception as e:
+                results["failed"].append(
+                    {
+                        "index": i,
+                        "error": str(e),
+                        "data": update_data,
+                    }
+                )
+
+        return {
+            "status": "completed",
+            "summary": {
+                "total": len(updates),
+                "updated": len(results["updated"]),
+                "failed": len(results["failed"]),
+            },
+            "results": results,
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Bulk update failed: {str(e)}",
+        }