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

mcp_ticketer/mcp/server/tools/milestone_tools.py

@@ -0,0 +1,338 @@
+"""Unified milestone management tools (v2.0.0).
+
+This module implements milestone management through a single unified `milestone()` interface.
+
+Version 2.0.0 changes:
+- Single `milestone()` function is the exposed MCP tool
+- All operations accessible via milestone(action="create"|"get"|"list"|"update"|"delete"|"get_issues")
+- Follows the pattern from ticket() and hierarchy() unified tools
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Literal
+
+from ....core.adapter import BaseAdapter
+from ..server_sdk import get_adapter, mcp
+
+logger = logging.getLogger(__name__)
+
+# Sentinel value to distinguish between "parameter not provided" and "explicitly None"
+_UNSET = object()
+
+
+def _build_adapter_metadata(
+    adapter: BaseAdapter,
+    milestone_id: str | None = None,
+) -> dict[str, Any]:
+    """Build adapter metadata for MCP responses.
+
+    Args:
+        adapter: The adapter that handled the operation
+        milestone_id: Optional milestone ID to include in metadata
+
+    Returns:
+        Dictionary with adapter metadata fields
+
+    """
+    metadata = {
+        "adapter": adapter.adapter_type,
+        "adapter_name": adapter.adapter_display_name,
+    }
+
+    if milestone_id:
+        metadata["milestone_id"] = milestone_id
+
+    return metadata
+
+
+@mcp.tool()
+async def milestone(
+    action: Literal["create", "get", "list", "update", "delete", "get_issues"],
+    # Entity identification
+    milestone_id: str | None = None,
+    # Creation/Update parameters
+    name: str | None = None,
+    target_date: str | None = None,
+    labels: list[str] | None = None,
+    description: str = "",
+    state: str | None = None,
+    # List/filter parameters
+    project_id: str | None = None,
+) -> dict[str, Any]:
+    """Unified milestone management tool for cross-platform milestone support.
+
+    A milestone is a list of labels with target dates, into which issues can be grouped.
+
+    Consolidates all milestone operations into a single interface with progress tracking.
+
+    Args:
+        action: Operation to perform:
+            - "create": Create new milestone
+            - "get": Get milestone by ID with progress
+            - "list": List milestones (optionally filtered)
+            - "update": Update milestone properties
+            - "delete": Delete milestone
+            - "get_issues": Get issues in milestone
+        milestone_id: Milestone ID (required for get, update, delete, get_issues)
+        name: Milestone name (required for create)
+        target_date: Target completion date (ISO format: YYYY-MM-DD)
+        labels: Labels that define this milestone (user's definition)
+        description: Milestone description
+        state: Milestone state (open, active, completed, closed)
+        project_id: Project/repository filter for list operations
+
+    Returns:
+        Operation results with status, data, and metadata
+
+    Raises:
+        ValueError: If action is invalid or required parameters missing
+
+    Examples:
+        # Create milestone
+        await milestone(
+            action="create",
+            name="v2.1.0 Release",
+            target_date="2025-12-31",
+            labels=["v2.1", "release"]
+        )
+
+        # Get milestone with progress
+        await milestone(action="get", milestone_id="milestone-123")
+
+        # List active milestones
+        await milestone(action="list", state="active")
+
+        # Update milestone
+        await milestone(
+            action="update",
+            milestone_id="milestone-123",
+            state="completed"
+        )
+
+        # Get issues in milestone
+        await milestone(action="get_issues", milestone_id="milestone-123")
+
+        # Delete milestone
+        await milestone(action="delete", milestone_id="milestone-123")
+
+    """
+    try:
+        # Get adapter from registry
+        adapter = get_adapter()
+
+        # Validate action
+        valid_actions = ["create", "get", "list", "update", "delete", "get_issues"]
+        if action not in valid_actions:
+            return {
+                "status": "error",
+                "error": f"Invalid action '{action}'. Must be one of: {', '.join(valid_actions)}",
+            }
+
+        # Route to appropriate handler
+        if action == "create":
+            return await _handle_create(
+                adapter, name, target_date, labels, description, project_id
+            )
+        elif action == "get":
+            return await _handle_get(adapter, milestone_id)
+        elif action == "list":
+            return await _handle_list(adapter, project_id, state)
+        elif action == "update":
+            return await _handle_update(
+                adapter, milestone_id, name, target_date, state, labels, description
+            )
+        elif action == "delete":
+            return await _handle_delete(adapter, milestone_id)
+        elif action == "get_issues":
+            return await _handle_get_issues(adapter, milestone_id, state)
+
+    except Exception as e:
+        logger.exception("Milestone operation failed")
+        return {
+            "status": "error",
+            "error": f"Milestone operation failed: {str(e)}",
+            "action": action,
+            "milestone_id": milestone_id,
+        }
+
+
+async def _handle_create(
+    adapter: BaseAdapter,
+    name: str | None,
+    target_date: str | None,
+    labels: list[str] | None,
+    description: str,
+    project_id: str | None,
+) -> dict[str, Any]:
+    """Handle milestone creation."""
+    if not name:
+        return {
+            "status": "error",
+            "error": "name is required for create action",
+        }
+
+    # Parse target_date if provided (expect date object, not string)
+    parsed_date = None
+    if target_date:
+        try:
+            # Try parsing as ISO date string
+            parsed_date = datetime.fromisoformat(target_date)
+        except ValueError:
+            return {
+                "status": "error",
+                "error": f"Invalid date format '{target_date}'. Use ISO format: YYYY-MM-DD",
+            }
+
+    milestone_obj = await adapter.milestone_create(
+        name=name,
+        target_date=parsed_date,
+        labels=labels or [],
+        description=description,
+        project_id=project_id,
+    )
+
+    return {
+        "status": "completed",
+        "message": f"Milestone '{name}' created successfully",
+        "milestone": milestone_obj.model_dump(),
+        "metadata": _build_adapter_metadata(adapter, milestone_obj.id),
+    }
+
+
+async def _handle_get(adapter: BaseAdapter, milestone_id: str | None) -> dict[str, Any]:
+    """Handle milestone retrieval with progress calculation."""
+    if not milestone_id:
+        return {
+            "status": "error",
+            "error": "milestone_id is required for get action",
+        }
+
+    milestone_obj = await adapter.milestone_get(milestone_id)
+
+    if not milestone_obj:
+        return {
+            "status": "error",
+            "error": f"Milestone '{milestone_id}' not found",
+        }
+
+    return {
+        "status": "completed",
+        "milestone": milestone_obj.model_dump(),
+        "metadata": _build_adapter_metadata(adapter, milestone_id),
+    }
+
+
+async def _handle_list(
+    adapter: BaseAdapter,
+    project_id: str | None,
+    state: str | None,
+) -> dict[str, Any]:
+    """Handle milestone listing with optional filters."""
+    milestones = await adapter.milestone_list(project_id=project_id, state=state)
+
+    return {
+        "status": "completed",
+        "message": f"Found {len(milestones)} milestone(s)",
+        "milestones": [m.model_dump() for m in milestones],
+        "count": len(milestones),
+        "metadata": _build_adapter_metadata(adapter),
+    }
+
+
+async def _handle_update(
+    adapter: BaseAdapter,
+    milestone_id: str | None,
+    name: str | None,
+    target_date: str | None,
+    state: str | None,
+    labels: list[str] | None,
+    description: str | None,
+) -> dict[str, Any]:
+    """Handle milestone update."""
+    if not milestone_id:
+        return {
+            "status": "error",
+            "error": "milestone_id is required for update action",
+        }
+
+    # Parse target_date if provided
+    parsed_date = None
+    if target_date:
+        try:
+            parsed_date = datetime.fromisoformat(target_date)
+        except ValueError:
+            return {
+                "status": "error",
+                "error": f"Invalid date format '{target_date}'. Use ISO format: YYYY-MM-DD",
+            }
+
+    milestone_obj = await adapter.milestone_update(
+        milestone_id=milestone_id,
+        name=name,
+        target_date=parsed_date,
+        state=state,
+        labels=labels,
+        description=description,
+    )
+
+    if not milestone_obj:
+        return {
+            "status": "error",
+            "error": f"Failed to update milestone '{milestone_id}'",
+        }
+
+    return {
+        "status": "completed",
+        "message": f"Milestone '{milestone_id}' updated successfully",
+        "milestone": milestone_obj.model_dump(),
+        "metadata": _build_adapter_metadata(adapter, milestone_id),
+    }
+
+
+async def _handle_delete(
+    adapter: BaseAdapter, milestone_id: str | None
+) -> dict[str, Any]:
+    """Handle milestone deletion."""
+    if not milestone_id:
+        return {
+            "status": "error",
+            "error": "milestone_id is required for delete action",
+        }
+
+    success = await adapter.milestone_delete(milestone_id)
+
+    if success:
+        return {
+            "status": "completed",
+            "message": f"Milestone '{milestone_id}' deleted successfully",
+            "metadata": _build_adapter_metadata(adapter, milestone_id),
+        }
+    else:
+        return {
+            "status": "error",
+            "error": f"Failed to delete milestone '{milestone_id}'",
+        }
+
+
+async def _handle_get_issues(
+    adapter: BaseAdapter,
+    milestone_id: str | None,
+    state: str | None,
+) -> dict[str, Any]:
+    """Handle getting issues in milestone."""
+    if not milestone_id:
+        return {
+            "status": "error",
+            "error": "milestone_id is required for get_issues action",
+        }
+
+    issues = await adapter.milestone_get_issues(milestone_id, state=state)
+
+    return {
+        "status": "completed",
+        "message": f"Found {len(issues)} issue(s) in milestone",
+        "issues": [issue.model_dump() for issue in issues],
+        "count": len(issues),
+        "metadata": _build_adapter_metadata(adapter, milestone_id),
+    }

mcp_ticketer/mcp/server/tools/search_tools.py

@@ -10,6 +10,8 @@ from typing import Any
 from ....core.models import Priority, SearchQuery, TicketState
 from ..server_sdk import get_adapter, mcp
 
+logger = logging.getLogger(__name__)
+
 
 @mcp.tool()
 async def ticket_search(
@@ -19,12 +21,13 @@ async def ticket_search(
     tags: list[str] | None = None,
     assignee: str | None = None,
     project_id: str | None = None,
+    milestone_id: str | None = None,
     limit: int = 10,
     include_hierarchy: bool = False,
     include_children: bool = True,
     max_depth: int = 3,
 ) -> dict[str, Any]:
-    """Search tickets with optional hierarchy information.
+    """Search tickets with optional hierarchy information and milestone filtering.
 
     **Consolidates:**
     - ticket_search() → Default behavior (include_hierarchy=False)
@@ -44,6 +47,7 @@ async def ticket_search(
     - tags: Filter by tags (AND logic)
     - assignee: Filter by assigned user
     - project_id: Scope to specific project
+    - milestone_id: Filter by milestone (NEW in 1M-607)
 
     **Hierarchy Options:**
     - include_hierarchy: Include parent/child relationships (default: False)
@@ -57,6 +61,7 @@ async def ticket_search(
         tags: Filter by tags - tickets must have all specified tags
         assignee: Filter by assigned user ID or email
         project_id: Project/epic ID (required unless default_project configured)
+        milestone_id: Filter by milestone ID (NEW in 1M-607)
         limit: Maximum number of results to return (default: 10, max: 100)
         include_hierarchy: Include parent/child relationships (default: False)
         include_children: Include child tickets in hierarchy (default: True)
@@ -77,6 +82,13 @@ async def ticket_search(
             max_depth=2
         )
 
+        # Search within milestone
+        await ticket_search(
+            milestone_id="milestone-123",
+            state="open",
+            limit=20
+        )
+
     """
     try:
         # Validate project context (NEW: Required for search operations)
@@ -141,6 +153,23 @@ async def ticket_search(
         # Execute search via adapter
         results = await adapter.search(search_query)
 
+        # Filter by milestone if requested (NEW in 1M-607)
+        if milestone_id:
+            try:
+                # Get issues in milestone
+                milestone_issues = await adapter.milestone_get_issues(
+                    milestone_id, state=state
+                )
+                milestone_issue_ids = {issue.id for issue in milestone_issues}
+
+                # Filter search results to only include milestone issues
+                results = [
+                    ticket for ticket in results if ticket.id in milestone_issue_ids
+                ]
+            except Exception as e:
+                logger.warning(f"Failed to filter by milestone {milestone_id}: {e}")
+                # Continue with unfiltered results if milestone filtering fails
+
         # Add hierarchy if requested
         if include_hierarchy:
             # Validate max_depth

mcp_ticketer/mcp/server/tools/ticket_tools.py

@@ -973,7 +973,8 @@ async def ticket_list(
         else:
             ticket_data = [ticket.model_dump() for ticket in tickets]
 
-        return {
+        # Build response
+        response_data = {
             "status": "completed",
             **_build_adapter_metadata(adapter),
             "tickets": ticket_data,
@@ -982,6 +983,41 @@ async def ticket_list(
             "offset": offset,
             "compact": compact,
         }
+
+        # Estimate and validate token count to prevent MCP limit violations
+        # MCP has a 25k token limit per response; we use 20k as safety margin
+        from ....utils.token_utils import estimate_json_tokens
+
+        estimated_tokens = estimate_json_tokens(response_data)
+
+        # If exceeds 20k tokens (safety margin below 25k MCP limit)
+        if estimated_tokens > 20_000:
+            # Calculate recommended limit based on current token-per-ticket ratio
+            if len(tickets) > 0:
+                tokens_per_ticket = estimated_tokens / len(tickets)
+                recommended_limit = int(20_000 / tokens_per_ticket)
+            else:
+                recommended_limit = 20
+
+            return {
+                "status": "error",
+                "error": f"Response would exceed MCP token limit ({estimated_tokens:,} tokens)",
+                "recommendation": (
+                    f"Use smaller limit (try limit={recommended_limit}), "
+                    "add filters (state=open, project_id=...), or enable compact mode"
+                ),
+                "current_settings": {
+                    "limit": limit,
+                    "compact": compact,
+                    "estimated_tokens": estimated_tokens,
+                    "max_allowed": 25_000,
+                },
+            }
+
+        # Add token estimate to successful response for monitoring
+        response_data["estimated_tokens"] = estimated_tokens
+
+        return response_data
     except Exception as e:
         error_response = {
             "status": "error",

mcp_ticketer/queue/queue.py

@@ -535,3 +535,71 @@ class Queue:
                 stats[status] = count
 
             return stats
+
+    def poll_until_complete(
+        self,
+        queue_id: str,
+        timeout: float = 30.0,
+        poll_interval: float = 0.5,
+    ) -> QueueItem:
+        """Poll queue item until completion or timeout.
+
+        This enables synchronous waiting for queue operations, useful for:
+        - CLI commands that need immediate results
+        - Testing that requires actual ticket IDs
+        - GitHub adapter operations requiring ticket numbers
+
+        Args:
+            queue_id: Queue ID to poll (e.g., "Q-9E7B5050")
+            timeout: Maximum seconds to wait (default: 30.0)
+            poll_interval: Seconds between polls (default: 0.5)
+
+        Returns:
+            Completed QueueItem with result data
+
+        Raises:
+            TimeoutError: If operation doesn't complete within timeout
+            RuntimeError: If operation fails or queue item not found
+
+        Example:
+            >>> queue = Queue()
+            >>> queue_id = queue.add(ticket_data={...}, adapter="github", operation="create")
+            >>> # Start worker to process the queue
+            >>> completed_item = queue.poll_until_complete(queue_id, timeout=30)
+            >>> ticket_id = completed_item.result["id"]
+
+        """
+        import time
+
+        start_time = time.time()
+        elapsed = 0.0
+
+        while elapsed < timeout:
+            item = self.get_item(queue_id)
+
+            if item is None:
+                raise RuntimeError(f"Queue item not found: {queue_id}")
+
+            if item.status == QueueStatus.COMPLETED:
+                if item.result is None:
+                    raise RuntimeError(
+                        f"Queue operation completed but has no result data: {queue_id}"
+                    )
+                return item
+
+            elif item.status == QueueStatus.FAILED:
+                error_msg = item.error_message or "Unknown error"
+                raise RuntimeError(
+                    f"Queue operation failed: {error_msg} (queue_id: {queue_id})"
+                )
+
+            # Still pending or processing - wait and retry
+            time.sleep(poll_interval)
+            elapsed = time.time() - start_time
+
+        # Timeout reached
+        final_item = self.get_item(queue_id)
+        final_status = final_item.status.value if final_item else "UNKNOWN"
+        raise TimeoutError(
+            f"Queue operation timed out after {timeout}s (status: {final_status}, queue_id: {queue_id})"
+        )

{mcp_ticketer-2.0.1.dist-info → mcp_ticketer-2.2.13.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: mcp-ticketer
-Version: 2.0.1
+Version: 2.2.13
 Summary: Universal ticket management interface for AI agents with MCP support
 Author-email: MCP Ticketer Team <support@mcp-ticketer.io>
 Maintainer-email: MCP Ticketer Team <support@mcp-ticketer.io>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/mcp-ticketer/mcp-ticketer
 Project-URL: Documentation, https://mcp-ticketer.readthedocs.io
 Project-URL: Repository, https://github.com/mcp-ticketer/mcp-ticketer
@@ -14,7 +14,6 @@ Keywords: mcp,tickets,jira,linear,github,issue-tracking,project-management,ai,au
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
@@ -56,9 +55,12 @@ Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
 Requires-Dist: tox>=4.11.0; extra == "dev"
 Requires-Dist: pre-commit>=3.5.0; extra == "dev"
 Requires-Dist: bump2version>=1.0.1; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.2.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
@@ -160,6 +162,34 @@ pip install -e .
 - Python 3.9+
 - Virtual environment (recommended)
 
+### PATH Configuration (Optional but Recommended)
+
+For optimal Claude Desktop MCP integration, ensure `mcp-ticketer` is in your PATH:
+
+**pipx users**:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# Add to ~/.bashrc or ~/.zshrc to make permanent
+```
+
+**uv users**:
+```bash
+export PATH="$HOME/.local/bin:$PATH"  # Linux/macOS
+# Add to ~/.bashrc or ~/.zshrc to make permanent
+```
+
+**Why configure PATH?**
+- ✅ **With PATH**: Native Claude CLI integration for better UX
+- ⚠️ **Without PATH**: mcp-ticketer still works using full paths (legacy mode)
+
+**Verify PATH configuration**:
+```bash
+which mcp-ticketer
+# Should show: /Users/username/.local/bin/mcp-ticketer (or similar)
+```
+
+**Note (v2.0.2+)**: The installer automatically detects if `mcp-ticketer` is in PATH and configures Claude Desktop appropriately. See [1M-579](https://linear.app/1m-hyperdev/issue/1M-579) for technical details.
+
 ## 🤖 Supported AI Clients
 
 MCP Ticketer integrates with multiple AI clients via the Model Context Protocol (MCP):