mcp-ticketer 0.3.5__py3-none-any.whl → 0.12.0__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/{dto.py → server/dto.py}

@@ -1,6 +1,6 @@
 """Data Transfer Objects for MCP requests and responses."""
 
-from typing import Any, Optional
+from typing import Any
 
 from pydantic import BaseModel, Field
 
@@ -10,32 +10,32 @@ 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")
+    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: Optional[str] = Field(None, description="Ticket assignee")
+    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: Optional[str] = Field(None, description="Epic description")
+    description: str | None = 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")
+    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: Optional[str] = Field(None, description="Issue description")
-    epic_id: Optional[str] = Field(None, description="Parent epic ID")
+    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: Optional[str] = Field(None, description="Issue assignee")
+    assignee: str | None = Field(None, description="Issue assignee")
     tags: list[str] = Field(default_factory=list, description="Issue tags")
-    estimated_hours: Optional[float] = Field(
+    estimated_hours: float | None = Field(
         None, description="Estimated hours to complete"
     )
 
@@ -45,11 +45,11 @@ class CreateTaskRequest(BaseModel):
 
     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")
+    description: str | None = Field(None, description="Task description")
     priority: str = Field("medium", description="Task priority")
-    assignee: Optional[str] = Field(None, description="Task assignee")
+    assignee: str | None = Field(None, description="Task assignee")
     tags: list[str] = Field(default_factory=list, description="Task tags")
-    estimated_hours: Optional[float] = Field(
+    estimated_hours: float | None = Field(
         None, description="Estimated hours to complete"
     )
 
@@ -77,11 +77,11 @@ class TransitionRequest(BaseModel):
 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")
+    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")
 
 
@@ -90,7 +90,7 @@ class ListRequest(BaseModel):
 
     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")
+    filters: dict[str, Any] | None = Field(None, description="Additional filters")
 
 
 class DeleteTicketRequest(BaseModel):
@@ -104,8 +104,8 @@ class CommentRequest(BaseModel):
 
     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)")
+    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)")
 
@@ -115,12 +115,12 @@ class CreatePRRequest(BaseModel):
 
     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")
+    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: Optional[str] = Field(None, description="GitHub owner (for Linear)")
-    github_repo: Optional[str] = Field(None, description="GitHub repo (for Linear)")
+    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):
@@ -152,7 +152,7 @@ class IssueTasksRequest(BaseModel):
 class HierarchyTreeRequest(BaseModel):
     """Request to get hierarchy tree."""
 
-    epic_id: Optional[str] = Field(None, description="Specific epic ID (optional)")
+    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)")
 
@@ -173,8 +173,8 @@ 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")
+    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")
@@ -184,9 +184,9 @@ 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")
+    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):

mcp_ticketer/mcp/{server.py → server/main.py}

@@ -4,15 +4,15 @@ import asyncio
 import json
 import sys
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from dotenv import load_dotenv
 
 # Import adapters module to trigger registration
 import mcp_ticketer.adapters  # noqa: F401
 
-from ..core import AdapterRegistry
-from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
+from ...core import AdapterRegistry
+from ...core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
 from .constants import (
     DEFAULT_BASE_PATH,
     DEFAULT_LIMIT,
@@ -48,29 +48,12 @@ from .dto import (
 )
 from .response_builder import ResponseBuilder
 
-# Load environment variables early (prioritize .env.local)
-# Check for .env.local first (takes precedence)
-env_local_file = Path.cwd() / ".env.local"
-if env_local_file.exists():
-    load_dotenv(env_local_file, override=True)
-    sys.stderr.write(f"[MCP Server] Loaded environment from: {env_local_file}\n")
-else:
-    # Fall back to .env
-    env_file = Path.cwd() / ".env"
-    if env_file.exists():
-        load_dotenv(env_file, override=True)
-        sys.stderr.write(f"[MCP Server] Loaded environment from: {env_file}\n")
-    else:
-        # Try default dotenv loading (searches upward)
-        load_dotenv(override=True)
-        sys.stderr.write("[MCP Server] Loaded environment from default search path\n")
-
 
 class MCPTicketServer:
     """MCP server for ticket operations over stdio - synchronous implementation."""
 
     def __init__(
-        self, adapter_type: str = "aitrackdown", config: Optional[dict[str, Any]] = None
+        self, adapter_type: str = "aitrackdown", config: dict[str, Any] | None = None
     ):
         """Initialize MCP server.
 
@@ -861,6 +844,44 @@ class MCPTicketServer:
                         "required": ["title"],
                     },
                 },
+                {
+                    "name": "ticket_comment",
+                    "description": "Add or list comments on a ticket",
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "operation": {
+                                "type": "string",
+                                "enum": ["add", "list"],
+                                "description": "Operation to perform: 'add' to create a comment, 'list' to retrieve comments",
+                                "default": "add",
+                            },
+                            "ticket_id": {
+                                "type": "string",
+                                "description": "Ticket ID to comment on",
+                            },
+                            "content": {
+                                "type": "string",
+                                "description": "Comment content (required for 'add' operation)",
+                            },
+                            "author": {
+                                "type": "string",
+                                "description": "Comment author (optional for 'add' operation)",
+                            },
+                            "limit": {
+                                "type": "integer",
+                                "default": 10,
+                                "description": "Maximum number of comments to return (for 'list' operation)",
+                            },
+                            "offset": {
+                                "type": "integer",
+                                "default": 0,
+                                "description": "Number of comments to skip (for 'list' operation)",
+                            },
+                        },
+                        "required": ["ticket_id"],
+                    },
+                },
             ]
         }
 
@@ -913,6 +934,8 @@ class MCPTicketServer:
                 result = await self._handle_transition(arguments)
             elif tool_name == "ticket_search":
                 result = await self._handle_search(arguments)
+            elif tool_name == "ticket_comment":
+                result = await self._handle_comment(arguments)
             # PR integration
             elif tool_name == "ticket_create_pr":
                 result = await self._handle_create_pr(arguments)
@@ -1010,8 +1033,8 @@ class MCPTicketServer:
         await self.adapter.close()
 
 
-async def main():
-    """Main entry point for MCP server - kept for backward compatibility.
+async def main() -> None:
+    """Run main entry point for MCP server - kept for backward compatibility.
 
     This function is maintained in case it's being called directly,
     but the preferred way is now through the CLI: `mcp-ticketer mcp`
@@ -1023,62 +1046,94 @@ async def main():
     # Load configuration
     import json
     import logging
-    from pathlib import Path
 
     logger = logging.getLogger(__name__)
 
+    # Load environment variables AFTER working directory has been set by __main__.py
+    # This ensures we load .env files from the target project directory, not from where the command is executed
+    env_local_file = Path.cwd() / ".env.local"
+    if env_local_file.exists():
+        load_dotenv(env_local_file, override=True)
+        sys.stderr.write(f"[MCP Server] Loaded environment from: {env_local_file}\n")
+        logger.debug(f"Loaded environment from: {env_local_file}")
+    else:
+        # Fall back to .env
+        env_file = Path.cwd() / ".env"
+        if env_file.exists():
+            load_dotenv(env_file, override=True)
+            sys.stderr.write(f"[MCP Server] Loaded environment from: {env_file}\n")
+            logger.debug(f"Loaded environment from: {env_file}")
+        else:
+            # Try default dotenv loading (searches upward)
+            load_dotenv(override=True)
+            sys.stderr.write(
+                "[MCP Server] Loaded environment from default search path\n"
+            )
+            logger.debug("Loaded environment from default search path")
+
     # Initialize defaults
     adapter_type = "aitrackdown"
     adapter_config = {"base_path": DEFAULT_BASE_PATH}
 
-    # Priority 1: Check .env files (highest priority for MCP)
-    env_config = _load_env_configuration()
-    if env_config and env_config.get("adapter_type"):
-        adapter_type = env_config["adapter_type"]
-        adapter_config = env_config["adapter_config"]
-        logger.info(f"Using adapter from .env files: {adapter_type}")
-        logger.info(f"Built adapter config from .env: {list(adapter_config.keys())}")
-    else:
-        # Priority 2: Check project-local config file
-        config_file = Path.cwd() / ".mcp-ticketer" / "config.json"
-        if config_file.exists():
-            # Validate config is within project
-            try:
-                if not config_file.resolve().is_relative_to(Path.cwd().resolve()):
-                    logger.error(
-                        f"Security violation: Config file {config_file} "
-                        "is not within project directory"
-                    )
-                    raise ValueError(
-                        f"Security violation: Config file {config_file} "
-                        "is not within project directory"
-                    )
-            except (ValueError, RuntimeError):
-                # is_relative_to may raise ValueError in some cases
-                pass
+    # Priority 1: Check project-local config file (highest priority)
+    config_file = Path.cwd() / ".mcp-ticketer" / "config.json"
+    config_loaded = False
 
-            try:
-                with open(config_file) as f:
-                    config = json.load(f)
-                    adapter_type = config.get("default_adapter", "aitrackdown")
-                    # Get adapter-specific config
-                    adapters_config = config.get("adapters", {})
-                    adapter_config = adapters_config.get(adapter_type, {})
-                    # Fallback to legacy config format
-                    if not adapter_config and "config" in config:
-                        adapter_config = config["config"]
-                    logger.info(
-                        f"Loaded MCP configuration from project-local: {config_file}"
-                    )
-            except (OSError, json.JSONDecodeError) as e:
-                logger.warning(f"Could not load project config: {e}, using defaults")
-                adapter_type = "aitrackdown"
-                adapter_config = {"base_path": DEFAULT_BASE_PATH}
-        else:
-            # Priority 3: Default to aitrackdown
-            logger.info("No configuration found, defaulting to aitrackdown adapter")
-            adapter_type = "aitrackdown"
-            adapter_config = {"base_path": DEFAULT_BASE_PATH}
+    if config_file.exists():
+        # Validate config is within project
+        try:
+            if not config_file.resolve().is_relative_to(Path.cwd().resolve()):
+                logger.error(
+                    f"Security violation: Config file {config_file} "
+                    "is not within project directory"
+                )
+                raise ValueError(
+                    f"Security violation: Config file {config_file} "
+                    "is not within project directory"
+                )
+        except (ValueError, RuntimeError):
+            # is_relative_to may raise ValueError in some cases
+            pass
+
+        try:
+            with open(config_file) as f:
+                config = json.load(f)
+                adapter_type = config.get("default_adapter", "aitrackdown")
+                # Get adapter-specific config
+                adapters_config = config.get("adapters", {})
+                adapter_config = adapters_config.get(adapter_type, {})
+                # Fallback to legacy config format
+                if not adapter_config and "config" in config:
+                    adapter_config = config["config"]
+                config_loaded = True
+                logger.info(
+                    f"Loaded MCP configuration from project-local: {config_file}"
+                )
+                sys.stderr.write(
+                    f"[MCP Server] Using adapter from config: {adapter_type}\n"
+                )
+        except (OSError, json.JSONDecodeError) as e:
+            logger.warning(f"Could not load project config: {e}, will try .env files")
+
+    # Priority 2: Check .env files (only if no config file found)
+    if not config_loaded:
+        env_config = _load_env_configuration()
+        if env_config and env_config.get("adapter_type"):
+            adapter_type = env_config["adapter_type"]
+            adapter_config = env_config["adapter_config"]
+            config_loaded = True
+            logger.info(f"Using adapter from .env files: {adapter_type}")
+            logger.info(
+                f"Built adapter config from .env: {list(adapter_config.keys())}"
+            )
+            sys.stderr.write(f"[MCP Server] Using adapter from .env: {adapter_type}\n")
+
+    # Priority 3: Default to aitrackdown
+    if not config_loaded:
+        logger.info("No configuration found, defaulting to aitrackdown adapter")
+        sys.stderr.write("[MCP Server] No config found, using default: aitrackdown\n")
+        adapter_type = "aitrackdown"
+        adapter_config = {"base_path": DEFAULT_BASE_PATH}
 
     # Log final configuration for debugging
     logger.info(f"Starting MCP server with adapter: {adapter_type}")
@@ -1089,7 +1144,7 @@ async def main():
     await server.run()
 
 
-def _load_env_configuration() -> Optional[dict[str, Any]]:
+def _load_env_configuration() -> dict[str, Any] | None:
     """Load adapter configuration from .env files.
 
     Checks .env.local first (highest priority), then .env.
@@ -1098,8 +1153,6 @@ def _load_env_configuration() -> Optional[dict[str, Any]]:
         Dictionary with 'adapter_type' and 'adapter_config' keys, or None if no config found
 
     """
-    from pathlib import Path
-
     # Check for .env files in order of preference
     env_files = [".env.local", ".env"]
     env_vars = {}

mcp_ticketer/mcp/{response_builder.py → server/response_builder.py}

@@ -1,6 +1,6 @@
 """Response builder utility for consistent MCP responses."""
 
-from typing import Any, Optional
+from typing import Any
 
 from .constants import JSONRPC_VERSION, STATUS_COMPLETED
 
@@ -36,7 +36,7 @@ class ResponseBuilder:
         request_id: Any,
         code: int,
         message: str,
-        data: Optional[dict[str, Any]] = None,
+        data: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Build error response.