mcp-ticketer 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

mcp_ticketer/mcp/constants.py

@@ -0,0 +1,58 @@
+"""MCP server constants and configuration."""
+
+# JSON-RPC Protocol
+JSONRPC_VERSION = "2.0"
+MCP_PROTOCOL_VERSION = "2024-11-05"
+
+# Server Info
+SERVER_NAME = "mcp-ticketer"
+SERVER_VERSION = "0.3.2"
+
+# Status Values
+STATUS_COMPLETED = "completed"
+STATUS_ERROR = "error"
+STATUS_NOT_IMPLEMENTED = "not_implemented"
+
+# Error Codes
+ERROR_PARSE = -32700
+ERROR_INVALID_REQUEST = -32600
+ERROR_METHOD_NOT_FOUND = -32601
+ERROR_INVALID_PARAMS = -32602
+ERROR_INTERNAL = -32603
+
+# Default Values
+DEFAULT_LIMIT = 10
+DEFAULT_OFFSET = 0
+DEFAULT_PRIORITY = "medium"
+DEFAULT_MAX_DEPTH = 3
+DEFAULT_BASE_PATH = ".aitrackdown"
+
+# Response Messages
+MSG_TICKET_NOT_FOUND = "Ticket {ticket_id} not found"
+MSG_UPDATE_FAILED = "Ticket {ticket_id} not found or update failed"
+MSG_TRANSITION_FAILED = "Ticket {ticket_id} not found or transition failed"
+MSG_EPIC_NOT_FOUND = "Epic {epic_id} not found"
+MSG_MISSING_PARENT_ID = "Tasks must have a parent_id (issue identifier)"
+MSG_UNKNOWN_OPERATION = "Unknown comment operation: {operation}"
+MSG_UNKNOWN_METHOD = "Method not found: {method}"
+MSG_INTERNAL_ERROR = "Internal error: {error}"
+MSG_NO_TICKETS_PROVIDED = "No tickets provided for bulk creation"
+MSG_NO_UPDATES_PROVIDED = "No updates provided for bulk operation"
+MSG_MISSING_TITLE = "Ticket {index} missing required 'title' field"
+MSG_MISSING_TICKET_ID = "Update {index} missing required 'ticket_id' field"
+MSG_TICKET_ID_REQUIRED = "ticket_id is required"
+MSG_PR_URL_REQUIRED = "pr_url is required"
+MSG_ATTACHMENT_NOT_IMPLEMENTED = "Attachment functionality not yet implemented"
+MSG_PR_NOT_SUPPORTED = "PR creation not supported for adapter: {adapter}"
+MSG_PR_LINK_NOT_SUPPORTED = "PR linking not supported for adapter: {adapter}"
+MSG_UNKNOWN_TOOL = "Unknown tool: {tool}"
+MSG_GITHUB_CONFIG_REQUIRED = "GitHub owner and repo are required for Linear PR creation"
+
+# Attachment Alternative Messages
+ATTACHMENT_ALTERNATIVES = [
+    "Add file URLs in comments",
+    "Use external file storage",
+]
+ATTACHMENT_NOT_IMPLEMENTED_REASON = (
+    "File attachments require adapter-specific implementation"
+)

mcp_ticketer/mcp/dto.py

@@ -0,0 +1,195 @@
+"""Data Transfer Objects for MCP requests and responses."""
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+# Request DTOs
+class CreateTicketRequest(BaseModel):
+    """Request to create a ticket."""
+
+    title: str = Field(..., min_length=1, description="Ticket title")
+    description: Optional[str] = Field(None, description="Ticket description")
+    priority: str = Field("medium", description="Ticket priority")
+    tags: list[str] = Field(default_factory=list, description="Ticket tags")
+    assignee: Optional[str] = Field(None, description="Ticket assignee")
+
+
+class CreateEpicRequest(BaseModel):
+    """Request to create an epic."""
+
+    title: str = Field(..., min_length=1, description="Epic title")
+    description: Optional[str] = Field(None, description="Epic description")
+    child_issues: list[str] = Field(default_factory=list, description="Child issue IDs")
+    target_date: Optional[str] = Field(None, description="Target completion date")
+    lead_id: Optional[str] = Field(None, description="Epic lead/owner ID")
+
+
+class CreateIssueRequest(BaseModel):
+    """Request to create an issue."""
+
+    title: str = Field(..., min_length=1, description="Issue title")
+    description: Optional[str] = Field(None, description="Issue description")
+    epic_id: Optional[str] = Field(None, description="Parent epic ID")
+    priority: str = Field("medium", description="Issue priority")
+    assignee: Optional[str] = Field(None, description="Issue assignee")
+    tags: list[str] = Field(default_factory=list, description="Issue tags")
+    estimated_hours: Optional[float] = Field(
+        None, description="Estimated hours to complete"
+    )
+
+
+class CreateTaskRequest(BaseModel):
+    """Request to create a task."""
+
+    title: str = Field(..., min_length=1, description="Task title")
+    parent_id: str = Field(..., description="Parent issue ID")
+    description: Optional[str] = Field(None, description="Task description")
+    priority: str = Field("medium", description="Task priority")
+    assignee: Optional[str] = Field(None, description="Task assignee")
+    tags: list[str] = Field(default_factory=list, description="Task tags")
+    estimated_hours: Optional[float] = Field(
+        None, description="Estimated hours to complete"
+    )
+
+
+class ReadTicketRequest(BaseModel):
+    """Request to read a ticket."""
+
+    ticket_id: str = Field(..., description="Ticket ID to read")
+
+
+class UpdateTicketRequest(BaseModel):
+    """Request to update a ticket."""
+
+    ticket_id: str = Field(..., description="Ticket ID to update")
+    updates: dict[str, Any] = Field(..., description="Fields to update")
+
+
+class TransitionRequest(BaseModel):
+    """Request to transition ticket state."""
+
+    ticket_id: str = Field(..., description="Ticket ID")
+    target_state: str = Field(..., description="Target state")
+
+
+class SearchRequest(BaseModel):
+    """Request to search tickets."""
+
+    query: Optional[str] = Field(None, description="Search query text")
+    state: Optional[str] = Field(None, description="Filter by ticket state")
+    priority: Optional[str] = Field(None, description="Filter by priority")
+    assignee: Optional[str] = Field(None, description="Filter by assignee")
+    tags: Optional[list[str]] = Field(None, description="Filter by tags")
+    limit: int = Field(10, description="Maximum number of results")
+
+
+class ListRequest(BaseModel):
+    """Request to list tickets."""
+
+    limit: int = Field(10, description="Maximum number of tickets to return")
+    offset: int = Field(0, description="Number of tickets to skip")
+    filters: Optional[dict[str, Any]] = Field(None, description="Additional filters")
+
+
+class DeleteTicketRequest(BaseModel):
+    """Request to delete a ticket."""
+
+    ticket_id: str = Field(..., description="Ticket ID to delete")
+
+
+class CommentRequest(BaseModel):
+    """Request for comment operations."""
+
+    operation: str = Field("add", description="Operation: 'add' or 'list'")
+    ticket_id: str = Field(..., description="Ticket ID")
+    content: Optional[str] = Field(None, description="Comment content (for add)")
+    author: Optional[str] = Field(None, description="Comment author (for add)")
+    limit: int = Field(10, description="Max comments to return (for list)")
+    offset: int = Field(0, description="Number of comments to skip (for list)")
+
+
+class CreatePRRequest(BaseModel):
+    """Request to create a pull request."""
+
+    ticket_id: str = Field(..., description="Ticket ID")
+    base_branch: str = Field("main", description="Base branch")
+    head_branch: Optional[str] = Field(None, description="Head branch")
+    title: Optional[str] = Field(None, description="PR title")
+    body: Optional[str] = Field(None, description="PR body")
+    draft: bool = Field(False, description="Create as draft PR")
+    github_owner: Optional[str] = Field(None, description="GitHub owner (for Linear)")
+    github_repo: Optional[str] = Field(None, description="GitHub repo (for Linear)")
+
+
+class LinkPRRequest(BaseModel):
+    """Request to link an existing PR to a ticket."""
+
+    ticket_id: str = Field(..., description="Ticket ID")
+    pr_url: str = Field(..., description="Pull request URL")
+
+
+class EpicListRequest(BaseModel):
+    """Request to list epics."""
+
+    limit: int = Field(10, description="Maximum number of epics to return")
+    offset: int = Field(0, description="Number of epics to skip")
+
+
+class EpicIssuesRequest(BaseModel):
+    """Request to list issues in an epic."""
+
+    epic_id: str = Field(..., description="Epic ID")
+
+
+class IssueTasksRequest(BaseModel):
+    """Request to list tasks in an issue."""
+
+    issue_id: str = Field(..., description="Issue ID")
+
+
+class HierarchyTreeRequest(BaseModel):
+    """Request to get hierarchy tree."""
+
+    epic_id: Optional[str] = Field(None, description="Specific epic ID (optional)")
+    max_depth: int = Field(3, description="Maximum depth of tree")
+    limit: int = Field(10, description="Max epics to return (if no epic_id)")
+
+
+class BulkCreateRequest(BaseModel):
+    """Request to bulk create tickets."""
+
+    tickets: list[dict[str, Any]] = Field(..., description="List of ticket data")
+
+
+class BulkUpdateRequest(BaseModel):
+    """Request to bulk update tickets."""
+
+    updates: list[dict[str, Any]] = Field(..., description="List of update data")
+
+
+class SearchHierarchyRequest(BaseModel):
+    """Request to search with hierarchy context."""
+
+    query: str = Field("", description="Search query")
+    state: Optional[str] = Field(None, description="Filter by state")
+    priority: Optional[str] = Field(None, description="Filter by priority")
+    include_children: bool = Field(True, description="Include child tickets")
+    include_parents: bool = Field(True, description="Include parent tickets")
+    limit: int = Field(50, description="Maximum number of results")
+
+
+class AttachRequest(BaseModel):
+    """Request to attach file to ticket."""
+
+    ticket_id: str = Field(..., description="Ticket ID")
+    file_path: Optional[str] = Field(None, description="File path to attach")
+    file_content: Optional[str] = Field(None, description="File content (base64)")
+    file_name: Optional[str] = Field(None, description="File name")
+
+
+class ListAttachmentsRequest(BaseModel):
+    """Request to list ticket attachments."""
+
+    ticket_id: str = Field(..., description="Ticket ID")

mcp_ticketer/mcp/response_builder.py

@@ -0,0 +1,206 @@
+"""Response builder utility for consistent MCP responses."""
+
+from typing import Any, Optional
+
+from .constants import JSONRPC_VERSION, STATUS_COMPLETED
+
+
+class ResponseBuilder:
+    """Build consistent JSON-RPC and MCP responses."""
+
+    @staticmethod
+    def success(
+        request_id: Any,
+        result: dict[str, Any],
+        status: str = STATUS_COMPLETED,
+    ) -> dict[str, Any]:
+        """Build successful response.
+
+        Args:
+            request_id: Request ID
+            result: Result data
+            status: Status value
+
+        Returns:
+            JSON-RPC response
+
+        """
+        return {
+            "jsonrpc": JSONRPC_VERSION,
+            "result": {"status": status, **result},
+            "id": request_id,
+        }
+
+    @staticmethod
+    def error(
+        request_id: Any,
+        code: int,
+        message: str,
+        data: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Build error response.
+
+        Args:
+            request_id: Request ID
+            code: Error code
+            message: Error message
+            data: Additional error data
+
+        Returns:
+            JSON-RPC error response
+
+        """
+        error_obj = {"code": code, "message": message}
+        if data:
+            error_obj["data"] = data
+
+        return {
+            "jsonrpc": JSONRPC_VERSION,
+            "error": error_obj,
+            "id": request_id,
+        }
+
+    @staticmethod
+    def status_result(status: str, **kwargs: Any) -> dict[str, Any]:
+        """Build status result with additional fields.
+
+        Args:
+            status: Status value
+            **kwargs: Additional fields
+
+        Returns:
+            Result dictionary
+
+        """
+        return {"status": status, **kwargs}
+
+    @staticmethod
+    def ticket_result(ticket: Any) -> dict[str, Any]:
+        """Build ticket result.
+
+        Args:
+            ticket: Ticket object
+
+        Returns:
+            Result dictionary with ticket data
+
+        """
+        return {"ticket": ticket.model_dump()}
+
+    @staticmethod
+    def tickets_result(tickets: list[Any]) -> dict[str, Any]:
+        """Build tickets list result.
+
+        Args:
+            tickets: List of ticket objects
+
+        Returns:
+            Result dictionary with tickets data
+
+        """
+        return {"tickets": [t.model_dump() for t in tickets]}
+
+    @staticmethod
+    def comment_result(comment: Any) -> dict[str, Any]:
+        """Build comment result.
+
+        Args:
+            comment: Comment object
+
+        Returns:
+            Result dictionary with comment data
+
+        """
+        return {"comment": comment.model_dump()}
+
+    @staticmethod
+    def comments_result(comments: list[Any]) -> dict[str, Any]:
+        """Build comments list result.
+
+        Args:
+            comments: List of comment objects
+
+        Returns:
+            Result dictionary with comments data
+
+        """
+        return {"comments": [c.model_dump() for c in comments]}
+
+    @staticmethod
+    def deletion_result(ticket_id: str, success: bool) -> dict[str, Any]:
+        """Build deletion result.
+
+        Args:
+            ticket_id: ID of deleted ticket
+            success: Whether deletion was successful
+
+        Returns:
+            Result dictionary with deletion status
+
+        """
+        return {"success": success, "ticket_id": ticket_id}
+
+    @staticmethod
+    def bulk_result(results: list[dict[str, Any]]) -> dict[str, Any]:
+        """Build bulk operation result.
+
+        Args:
+            results: List of operation results
+
+        Returns:
+            Result dictionary with bulk operation data
+
+        """
+        return {"results": results, "count": len(results)}
+
+    @staticmethod
+    def epics_result(epics: list[Any]) -> dict[str, Any]:
+        """Build epics list result.
+
+        Args:
+            epics: List of epic objects
+
+        Returns:
+            Result dictionary with epics data
+
+        """
+        return {"epics": [epic.model_dump() for epic in epics]}
+
+    @staticmethod
+    def issues_result(issues: list[Any]) -> dict[str, Any]:
+        """Build issues list result.
+
+        Args:
+            issues: List of issue objects
+
+        Returns:
+            Result dictionary with issues data
+
+        """
+        return {"issues": [issue.model_dump() for issue in issues]}
+
+    @staticmethod
+    def tasks_result(tasks: list[Any]) -> dict[str, Any]:
+        """Build tasks list result.
+
+        Args:
+            tasks: List of task objects
+
+        Returns:
+            Result dictionary with tasks data
+
+        """
+        return {"tasks": [task.model_dump() for task in tasks]}
+
+    @staticmethod
+    def attachments_result(attachments: list[Any]) -> dict[str, Any]:
+        """Build attachments list result.
+
+        Args:
+            attachments: List of attachment objects
+
+        Returns:
+            Result dictionary with attachments data
+
+        """
+        return {"attachments": attachments}