mcp-ticketer 0.4.11__py3-none-any.whl → 2.0.1__py3-none-any.whl

mcp_ticketer/mcp/server/tools/attachment_tools.py

@@ -5,13 +5,14 @@ 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
-from ..server_sdk import get_adapter, mcp
+from ....core.models import Comment, TicketType
+from ..server_sdk import get_adapter
 
 
-@mcp.tool()
 async def ticket_attach(
     ticket_id: str,
     file_path: str,
@@ -34,7 +35,7 @@ async def ticket_attach(
     try:
         adapter = get_adapter()
 
-        # Read ticket to validate it exists
+        # Read ticket to validate it exists and determine type
         ticket = await adapter.read(ticket_id)
         if ticket is None:
             return {
@@ -42,27 +43,72 @@ async def ticket_attach(
                 "error": f"Ticket {ticket_id} not found",
             }
 
-        # Check if adapter supports attachments
-        if not hasattr(adapter, "add_attachment"):
+        # Check if file exists
+        file_path_obj = Path(file_path)
+        if not file_path_obj.exists():
             return {
                 "status": "error",
-                "error": f"File attachments not supported by {type(adapter).__name__} adapter",
+                "error": f"File not found: {file_path}",
                 "ticket_id": ticket_id,
-                "note": "Consider using ticket_comment to add a reference to the file location",
             }
 
-        # Add attachment via adapter
-        attachment = await adapter.add_attachment(  # type: ignore
-            ticket_id=ticket_id, file_path=file_path, description=description
-        )
+        # 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)
+
+                # 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(
+                        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(
+                        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(
+                ticket_id=ticket_id, file_path=file_path, description=description
+            )
 
-        return {
-            "status": "completed",
-            "ticket_id": ticket_id,
-            "attachment": attachment,
-        }
+            return {
+                "status": "completed",
+                "ticket_id": ticket_id,
+                "method": "adapter_native",
+                "attachment": attachment,
+            }
 
-    except AttributeError:
         # Fallback: Add file reference as comment
         comment_text = f"Attachment: {file_path}"
         if description:
@@ -98,7 +144,6 @@ async def ticket_attach(
         }
 
 
-@mcp.tool()
 async def ticket_attachments(
     ticket_id: str,
 ) -> dict[str, Any]:  # Keep as dict for MCP compatibility
@@ -135,7 +180,7 @@ async def ticket_attachments(
             }
 
         # Get attachments via adapter
-        attachments = await adapter.get_attachments(ticket_id)  # type: ignore
+        attachments = await adapter.get_attachments(ticket_id)
 
         return {
             "status": "completed",

mcp_ticketer/mcp/server/tools/bulk_tools.py

@@ -2,6 +2,16 @@
 
 This module implements tools for batch operations on tickets to improve
 efficiency when working with multiple items.
+
+Features:
+- ticket_bulk: Unified interface for all bulk operations (create, update)
+
+All tools follow the MCP response pattern:
+    {
+        "status": "completed" | "error",
+        "summary": {"total": N, "created": N, "updated": N, "failed": N},
+        "results": {...}
+    }
 """
 
 from typing import Any
@@ -11,263 +21,310 @@ from ..server_sdk import get_adapter, mcp
 
 
 @mcp.tool()
-async def ticket_bulk_create(
-    tickets: list[dict[str, Any]],
+async def ticket_bulk(
+    action: str,
+    tickets: list[dict[str, Any]] | None = None,
+    updates: list[dict[str, Any]] | None = None,
 ) -> dict[str, Any]:
-    """Create multiple tickets in a single operation.
+    """Unified bulk ticket operations tool.
 
-    Each ticket dict should contain at minimum a 'title' field, with optional
-    fields: description, priority, tags, assignee, ticket_type, parent_epic, parent_issue.
+    Performs bulk create or update operations on tickets through a single
+    interface.
 
     Args:
-        tickets: List of ticket dictionaries to create
+        action: Operation to perform. Valid values:
+            - "create": Create multiple new tickets
+            - "update": Update multiple existing tickets
+        tickets: List of ticket dicts for bulk create (required if action="create")
+                Each dict should contain at minimum 'title', with optional fields:
+                description, priority, tags, assignee, ticket_type, parent_epic, parent_issue
+        updates: List of update dicts for bulk update (required if action="update")
+                Each dict must contain 'ticket_id' and at least one field to update.
+                Valid update fields: title, description, priority, state, assignee, tags
 
     Returns:
-        Results of bulk creation including successes and failures
-
+        Results dictionary containing:
+        - status: "completed" or "error"
+        - summary: Statistics (total, created/updated, failed)
+        - results: Detailed results for each operation
+
+    Raises:
+        ValueError: If action is invalid or required parameters missing
+
+    Examples:
+        # Bulk create
+        result = await ticket_bulk(
+            action="create",
+            tickets=[
+                {"title": "Bug 1", "priority": "high", "description": "Fix login"},
+                {"title": "Bug 2", "priority": "medium", "tags": ["backend"]}
+            ]
+        )
+
+        # Bulk update
+        result = await ticket_bulk(
+            action="update",
+            updates=[
+                {"ticket_id": "PROJ-123", "state": "done", "priority": "low"},
+                {"ticket_id": "PROJ-456", "assignee": "user@example.com"}
+            ]
+        )
+
+    See: docs/mcp-api-reference.md for detailed response formats
     """
-    try:
-        adapter = get_adapter()
+    action_lower = action.lower()
 
-        if not tickets:
+    # Route to appropriate handler based on action
+    if action_lower == "create":
+        if tickets is None:
             return {
                 "status": "error",
-                "error": "No tickets provided for bulk creation",
+                "error": "tickets parameter required for action='create'",
+                "hint": "Use ticket_bulk(action='create', tickets=[...])",
+            }
+        # Inline implementation of bulk create
+        try:
+            adapter = get_adapter()
+
+            if not tickets:
+                return {
+                    "status": "error",
+                    "error": "No tickets provided for bulk creation",
+                }
+
+            results: dict[str, list[Any]] = {
+                "created": [],
+                "failed": [],
             }
 
-        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:
+            for i, ticket_data in enumerate(tickets):
+                try:
+                    # Validate required fields
+                    if "title" not in ticket_data:
                         results["failed"].append(
                             {
                                 "index": i,
-                                "error": f"Invalid ticket_type: {ticket_data['ticket_type']}",
+                                "error": "Missing required field: title",
                                 "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.
+                    # 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"),
+                    )
 
-    Args:
-        updates: List of update operation dictionaries
+                    # Create via adapter
+                    created = await adapter.create(task)
+                    results["created"].append(
+                        {
+                            "index": i,
+                            "ticket": created.model_dump(),
+                        }
+                    )
 
-    Returns:
-        Results of bulk update including successes and failures
+                except Exception as e:
+                    results["failed"].append(
+                        {
+                            "index": i,
+                            "error": str(e),
+                            "data": ticket_data,
+                        }
+                    )
 
-    """
-    try:
-        adapter = get_adapter()
+            return {
+                "status": "completed",
+                "summary": {
+                    "total": len(tickets),
+                    "created": len(results["created"]),
+                    "failed": len(results["failed"]),
+                },
+                "results": results,
+            }
 
-        if not updates:
+        except Exception as e:
             return {
                 "status": "error",
-                "error": "No updates provided for bulk operation",
+                "error": f"Bulk creation failed: {str(e)}",
             }
 
-        results = {
-            "updated": [],
-            "failed": [],
-        }
+    elif action_lower == "update":
+        if updates is None:
+            return {
+                "status": "error",
+                "error": "updates parameter required for action='update'",
+                "hint": "Use ticket_bulk(action='update', updates=[...])",
+            }
+        # Inline implementation of bulk update
+        try:
+            adapter = get_adapter()
+
+            if not updates:
+                return {
+                    "status": "error",
+                    "error": "No updates provided for bulk operation",
+                }
+
+            results: dict[str, list[Any]] = {
+                "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:
+            for i, update_data in enumerate(updates):
+                try:
+                    # Validate required fields
+                    if "ticket_id" not in update_data:
                         results["failed"].append(
                             {
                                 "index": i,
-                                "error": f"Invalid priority: {update_data['priority']}",
+                                "error": "Missing required field: ticket_id",
                                 "data": update_data,
                             }
                         )
                         continue
 
-                # Parse state if provided
-                if "state" in update_data:
-                    try:
-                        update_fields["state"] = TicketState(
-                            update_data["state"].lower()
-                        )
-                    except ValueError:
+                    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": f"Invalid state: {update_data['state']}",
+                                "error": "No valid update fields provided",
                                 "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(),
+                            }
+                        )
 
-                # Update via adapter
-                updated = await adapter.update(ticket_id, update_fields)
-                if updated is None:
+                except Exception as e:
                     results["failed"].append(
                         {
                             "index": i,
-                            "error": f"Ticket {ticket_id} not found or update failed",
+                            "error": str(e),
                             "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,
+            }
 
-        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)}",
+            }
 
-    except Exception as e:
+    else:
+        valid_actions = ["create", "update"]
         return {
             "status": "error",
-            "error": f"Bulk update failed: {str(e)}",
+            "error": f"Invalid action '{action}'. Must be one of: {', '.join(valid_actions)}",
+            "valid_actions": valid_actions,
+            "hint": "Use ticket_bulk(action='create'|'update', ...)",
         }