mcp-ticketer 0.2.0__py3-none-any.whl → 2.2.9__py3-none-any.whl

mcp_ticketer/mcp/__main__.py

@@ -0,0 +1,60 @@
+"""Main entry point for MCP server module invocation.
+
+This module enables running the MCP server via:
+    python -m mcp_ticketer.mcp.server [project_path]
+
+This is the preferred invocation method for MCP configurations as it:
+- Works reliably across installation methods (pipx, pip, uv)
+- Doesn't depend on binary path detection
+- Follows the proven mcp-vector-search pattern
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+from .server import main
+
+
+def run_server() -> None:
+    """Run the MCP server with optional project path argument.
+
+    Usage:
+        python -m mcp_ticketer.mcp.server
+        python -m mcp_ticketer.mcp.server /path/to/project
+
+    Arguments:
+        project_path (optional): Path to project directory for context
+
+    """
+    # Check for project path argument
+    if len(sys.argv) > 1:
+        project_path = Path(sys.argv[1])
+
+        # Validate project path exists
+        if not project_path.exists():
+            sys.stderr.write(f"Error: Project path does not exist: {project_path}\n")
+            sys.exit(1)
+
+        # Change to project directory for context
+        try:
+            import os
+
+            os.chdir(project_path)
+            sys.stderr.write(f"[MCP Server] Working directory: {project_path}\n")
+        except OSError as e:
+            sys.stderr.write(f"Warning: Could not change to project directory: {e}\n")
+
+    # Run the async main function
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        sys.stderr.write("\n[MCP Server] Interrupted by user\n")
+        sys.exit(0)
+    except Exception as e:
+        sys.stderr.write(f"[MCP Server] Fatal error: {e}\n")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run_server()

mcp_ticketer/mcp/server/__init__.py

@@ -0,0 +1,25 @@
+"""MCP Server package for mcp-ticketer.
+
+This package provides the FastMCP server implementation for ticket management
+operations via the Model Context Protocol (MCP).
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .main import MCPTicketServer, main
+
+__all__ = ["main", "MCPTicketServer"]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import to avoid premature module loading."""
+    if name == "main":
+        from .main import main
+
+        return main
+    if name == "MCPTicketServer":
+        from .main import MCPTicketServer
+
+        return MCPTicketServer
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

mcp_ticketer/mcp/server/__main__.py

@@ -0,0 +1,60 @@
+"""Main entry point for MCP server module invocation.
+
+This module enables running the MCP server via:
+    python -m mcp_ticketer.mcp.server [project_path]
+
+This is the preferred invocation method for MCP configurations as it:
+- Works reliably across installation methods (pipx, pip, uv)
+- Doesn't depend on binary path detection
+- Follows the proven mcp-vector-search pattern
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+from .main import main
+
+
+def run_server() -> None:
+    """Run the MCP server with optional project path argument.
+
+    Usage:
+        python -m mcp_ticketer.mcp.server
+        python -m mcp_ticketer.mcp.server /path/to/project
+
+    Arguments:
+        project_path (optional): Path to project directory for context
+
+    """
+    # Check for project path argument
+    if len(sys.argv) > 1:
+        project_path = Path(sys.argv[1])
+
+        # Validate project path exists
+        if not project_path.exists():
+            sys.stderr.write(f"Error: Project path does not exist: {project_path}\n")
+            sys.exit(1)
+
+        # Change to project directory for context
+        try:
+            import os
+
+            os.chdir(project_path)
+            sys.stderr.write(f"[MCP Server] Working directory: {project_path}\n")
+        except OSError as e:
+            sys.stderr.write(f"Warning: Could not change to project directory: {e}\n")
+
+    # Run the async main function
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        sys.stderr.write("\n[MCP Server] Interrupted by user\n")
+        sys.exit(0)
+    except Exception as e:
+        sys.stderr.write(f"[MCP Server] Fatal error: {e}\n")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run_server()

mcp_ticketer/mcp/server/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/server/diagnostic_helper.py

@@ -0,0 +1,175 @@
+"""Diagnostic helper for MCP error handling.
+
+Provides quick diagnostic checks and error classification to help users
+troubleshoot system configuration issues when MCP tools encounter errors.
+"""
+
+import logging
+from enum import Enum
+from typing import Any
+
+from ...core.exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    NetworkError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    StateTransitionError,
+    TimeoutError,
+    ValidationError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorSeverity(Enum):
+    """Classification of error severity for diagnostic suggestions."""
+
+    CRITICAL = "critical"  # Always suggest diagnostics
+    MEDIUM = "medium"  # Suggest if pattern detected
+    LOW = "low"  # Never suggest diagnostics
+
+
+# Map exception types to severity levels
+ERROR_SEVERITY_MAP = {
+    AuthenticationError: ErrorSeverity.CRITICAL,
+    ConfigurationError: ErrorSeverity.CRITICAL,
+    NetworkError: ErrorSeverity.CRITICAL,
+    TimeoutError: ErrorSeverity.CRITICAL,
+    NotFoundError: ErrorSeverity.MEDIUM,
+    PermissionError: ErrorSeverity.MEDIUM,
+    RateLimitError: ErrorSeverity.MEDIUM,
+    ValidationError: ErrorSeverity.LOW,
+    StateTransitionError: ErrorSeverity.LOW,
+}
+
+
+def should_suggest_diagnostics(exception: Exception) -> bool:
+    """Determine if error response should include diagnostic suggestion.
+
+    Args:
+        exception: The exception that was raised
+
+    Returns:
+        True if diagnostics should be suggested
+
+    """
+    severity = get_error_severity(exception)
+    return severity in (ErrorSeverity.CRITICAL, ErrorSeverity.MEDIUM)
+
+
+def get_error_severity(exception: Exception) -> ErrorSeverity:
+    """Get severity level for an exception.
+
+    Args:
+        exception: The exception to classify
+
+    Returns:
+        Error severity level
+
+    """
+    exception_type = type(exception)
+    return ERROR_SEVERITY_MAP.get(exception_type, ErrorSeverity.MEDIUM)
+
+
+async def get_quick_diagnostic_info() -> dict[str, Any]:
+    """Get lightweight diagnostic info without running full test suite.
+
+    Performs fast checks (< 100ms) to provide immediate troubleshooting hints:
+    - Adapter configuration status
+    - Credential presence
+    - Queue system status
+
+    Returns:
+        Dictionary with quick diagnostic results
+
+    """
+    info: dict[str, Any] = {}
+
+    try:
+        # Check adapter configuration (fast file read)
+        from ...cli.utils import CommonPatterns
+
+        config = CommonPatterns.load_config()
+        adapters = config.get("adapters", {})
+
+        info["adapter_configured"] = len(adapters) > 0
+        info["configured_adapters"] = list(adapters.keys())
+        info["default_adapter"] = config.get("default_adapter")
+
+    except Exception as e:
+        logger.debug(f"Quick diagnostic config check failed: {e}")
+        info["adapter_configured"] = False
+        info["config_error"] = str(e)
+
+    try:
+        # Check queue system status (fast status check, no operations)
+        from ...queue.worker import Worker
+
+        worker = Worker()
+        info["queue_running"] = worker.running
+
+    except Exception as e:
+        logger.debug(f"Quick diagnostic queue check failed: {e}")
+        info["queue_running"] = False
+
+    try:
+        # Get version information
+        from ...__version__ import __version__
+
+        info["mcp_ticketer_version"] = __version__
+
+    except Exception as e:
+        logger.debug(f"Quick diagnostic version check failed: {e}")
+        info["mcp_ticketer_version"] = "unknown"
+
+    return info
+
+
+def build_diagnostic_suggestion(
+    exception: Exception, quick_info: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """Build diagnostic suggestion dict for error response.
+
+    Args:
+        exception: The exception that occurred
+        quick_info: Optional quick diagnostic info (from get_quick_diagnostic_info())
+
+    Returns:
+        Diagnostic suggestion dictionary for inclusion in error response
+
+    """
+    severity = get_error_severity(exception)
+
+    suggestion: dict[str, Any] = {
+        "severity": severity.value,
+        "message": _get_severity_message(severity),
+        "recommendation": _get_recommendation(severity),
+        "command": "Use the 'system_diagnostics' MCP tool or CLI: mcp-ticketer doctor",
+    }
+
+    if quick_info:
+        suggestion["quick_checks"] = quick_info
+
+    return suggestion
+
+
+def _get_severity_message(severity: ErrorSeverity) -> str:
+    """Get human-readable message for severity level."""
+    messages = {
+        ErrorSeverity.CRITICAL: "This appears to be a system configuration issue",
+        ErrorSeverity.MEDIUM: "This may indicate a configuration or permission issue",
+        ErrorSeverity.LOW: "This is a validation or input error",
+    }
+    return messages.get(severity, "An error occurred")
+
+
+def _get_recommendation(severity: ErrorSeverity) -> str:
+    """Get recommendation text for severity level."""
+    recommendations = {
+        ErrorSeverity.CRITICAL: "Run system diagnostics to identify the problem",
+        ErrorSeverity.MEDIUM: "Consider running diagnostics if the issue persists",
+        ErrorSeverity.LOW: "Check your input and try again",
+    }
+    return recommendations.get(severity, "Review the error message")

mcp_ticketer/mcp/server/dto.py

@@ -0,0 +1,195 @@
+"""Data Transfer Objects for MCP requests and responses."""
+
+from typing import Any
+
+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: str | None = Field(None, description="Ticket description")
+    priority: str = Field("medium", description="Ticket priority")
+    tags: list[str] = Field(default_factory=list, description="Ticket tags")
+    assignee: str | None = Field(None, description="Ticket assignee")
+
+
+class CreateEpicRequest(BaseModel):
+    """Request to create an epic."""
+
+    title: str = Field(..., min_length=1, description="Epic title")
+    description: str | None = Field(None, description="Epic description")
+    child_issues: list[str] = Field(default_factory=list, description="Child issue IDs")
+    target_date: str | None = Field(None, description="Target completion date")
+    lead_id: str | None = 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: str | None = Field(None, description="Issue description")
+    epic_id: str | None = Field(None, description="Parent epic ID")
+    priority: str = Field("medium", description="Issue priority")
+    assignee: str | None = Field(None, description="Issue assignee")
+    tags: list[str] = Field(default_factory=list, description="Issue tags")
+    estimated_hours: float | None = 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: str | None = Field(None, description="Task description")
+    priority: str = Field("medium", description="Task priority")
+    assignee: str | None = Field(None, description="Task assignee")
+    tags: list[str] = Field(default_factory=list, description="Task tags")
+    estimated_hours: float | None = 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: str | None = Field(None, description="Search query text")
+    state: str | None = Field(None, description="Filter by ticket state")
+    priority: str | None = Field(None, description="Filter by priority")
+    assignee: str | None = Field(None, description="Filter by assignee")
+    tags: list[str] | None = 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: dict[str, Any] | None = 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: str | None = Field(None, description="Comment content (for add)")
+    author: str | None = 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: str | None = Field(None, description="Head branch")
+    title: str | None = Field(None, description="PR title")
+    body: str | None = Field(None, description="PR body")
+    draft: bool = Field(False, description="Create as draft PR")
+    github_owner: str | None = Field(None, description="GitHub owner (for Linear)")
+    github_repo: str | None = 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: str | None = 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: str | None = Field(None, description="Filter by state")
+    priority: str | None = 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: str | None = Field(None, description="File path to attach")
+    file_content: str | None = Field(None, description="File content (base64)")
+    file_name: str | None = Field(None, description="File name")
+
+
+class ListAttachmentsRequest(BaseModel):
+    """Request to list ticket attachments."""
+
+    ticket_id: str = Field(..., description="Ticket ID")