mcp-ticketer 0.3.5__py3-none-any.whl → 0.12.0__py3-none-any.whl

mcp_ticketer/mcp/server/tools/instruction_tools.py

@@ -0,0 +1,293 @@
+"""Ticket instructions management tools.
+
+This module implements MCP tools for managing ticket writing instructions,
+allowing AI agents to query and customize the guidelines that help create
+well-structured, consistent tickets.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from ....core.instructions import (
+    InstructionsError,
+    InstructionsValidationError,
+    TicketInstructionsManager,
+)
+from ..server_sdk import mcp
+
+
+@mcp.tool()
+async def instructions_get() -> dict[str, Any]:
+    """Get current ticket writing instructions.
+
+    Retrieves the active instructions for the current project, which may be
+    custom project-specific instructions or the default embedded instructions.
+
+    Returns:
+        A dictionary containing:
+        - status: "completed" or "error"
+        - instructions: The full instruction text (if successful)
+        - source: "custom" or "default" indicating which instructions are active
+        - path: Path to custom instructions file (if exists)
+        - error: Error message (if failed)
+
+    Example response:
+        {
+            "status": "completed",
+            "instructions": "# Ticket Writing Guidelines...",
+            "source": "custom",
+            "path": "/path/to/project/.mcp-ticketer/instructions.md"
+        }
+
+    """
+    try:
+        # Use current working directory as project directory
+        manager = TicketInstructionsManager(project_dir=Path.cwd())
+
+        # Get instructions
+        instructions = manager.get_instructions()
+
+        # Determine source
+        source = "custom" if manager.has_custom_instructions() else "default"
+
+        # Build response
+        response: dict[str, Any] = {
+            "status": "completed",
+            "instructions": instructions,
+            "source": source,
+        }
+
+        # Add path if custom instructions exist
+        if source == "custom":
+            response["path"] = str(manager.get_instructions_path())
+
+        return response
+
+    except InstructionsError as e:
+        return {
+            "status": "error",
+            "error": f"Failed to get instructions: {str(e)}",
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Unexpected error: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def instructions_set(content: str, source: str = "inline") -> dict[str, Any]:
+    r"""Set custom ticket writing instructions for the project.
+
+    Creates or overwrites custom instructions with the provided content.
+    The content is validated before saving.
+
+    Args:
+        content: The custom instructions content (markdown text)
+        source: Source type - "inline" for direct content or "file" for file path
+            (currently only "inline" is supported by MCP tools)
+
+    Returns:
+        A dictionary containing:
+        - status: "completed" or "error"
+        - message: Success or error message
+        - path: Path where instructions were saved (if successful)
+        - error: Detailed error message (if failed)
+
+    Example:
+        To set custom instructions:
+        instructions_set(
+            content="# Our Team's Ticket Guidelines\\n\\n...",
+            source="inline"
+        )
+
+    """
+    try:
+        # Validate source parameter
+        if source not in ["inline", "file"]:
+            return {
+                "status": "error",
+                "error": f"Invalid source '{source}'. Must be 'inline' or 'file'",
+            }
+
+        # Use current working directory as project directory
+        manager = TicketInstructionsManager(project_dir=Path.cwd())
+
+        # Set instructions
+        manager.set_instructions(content)
+
+        # Get path where instructions were saved
+        inst_path = manager.get_instructions_path()
+
+        return {
+            "status": "completed",
+            "message": "Custom instructions saved successfully",
+            "path": str(inst_path),
+        }
+
+    except InstructionsValidationError as e:
+        return {
+            "status": "error",
+            "error": f"Validation failed: {str(e)}",
+            "message": "Instructions content did not pass validation checks",
+        }
+    except InstructionsError as e:
+        return {
+            "status": "error",
+            "error": f"Failed to set instructions: {str(e)}",
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Unexpected error: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def instructions_reset() -> dict[str, Any]:
+    """Reset to default instructions by deleting custom instructions.
+
+    Removes any custom project-specific instructions, causing the system
+    to revert to using the default embedded instructions.
+
+    Returns:
+        A dictionary containing:
+        - status: "completed" or "error"
+        - message: Description of what happened
+        - error: Error message (if failed)
+
+    Example response (when custom instructions existed):
+        {
+            "status": "completed",
+            "message": "Custom instructions deleted. Now using defaults."
+        }
+
+    Example response (when no custom instructions):
+        {
+            "status": "completed",
+            "message": "No custom instructions to delete. Already using defaults."
+        }
+
+    """
+    try:
+        # Use current working directory as project directory
+        manager = TicketInstructionsManager(project_dir=Path.cwd())
+
+        # Check if custom instructions exist
+        if not manager.has_custom_instructions():
+            return {
+                "status": "completed",
+                "message": "No custom instructions to delete. Already using defaults.",
+            }
+
+        # Delete custom instructions
+        deleted = manager.delete_instructions()
+
+        if deleted:
+            return {
+                "status": "completed",
+                "message": "Custom instructions deleted. Now using defaults.",
+            }
+        else:
+            return {
+                "status": "completed",
+                "message": "No custom instructions found to delete.",
+            }
+
+    except InstructionsError as e:
+        return {
+            "status": "error",
+            "error": f"Failed to reset instructions: {str(e)}",
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Unexpected error: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def instructions_validate(content: str) -> dict[str, Any]:
+    """Validate ticket instructions content without saving.
+
+    Checks if the provided content meets validation requirements:
+    - Not empty
+    - Minimum length (100 characters)
+    - Contains markdown headers (warning only)
+
+    This allows AI agents to validate content before attempting to save it.
+
+    Args:
+        content: The instructions content to validate (markdown text)
+
+    Returns:
+        A dictionary containing:
+        - status: "valid" or "invalid"
+        - warnings: List of non-critical issues (e.g., missing headers)
+        - errors: List of critical validation failures
+        - message: Summary message
+
+    Example response (valid):
+        {
+            "status": "valid",
+            "warnings": ["No markdown headers found"],
+            "errors": [],
+            "message": "Content is valid but has 1 warning"
+        }
+
+    Example response (invalid):
+        {
+            "status": "invalid",
+            "warnings": [],
+            "errors": ["Content too short (50 characters). Minimum 100 required."],
+            "message": "Content validation failed"
+        }
+
+    """
+    warnings: list[str] = []
+    errors: list[str] = []
+
+    try:
+        # Check for empty content
+        if not content or not content.strip():
+            errors.append("Instructions content cannot be empty")
+        else:
+            # Check minimum length
+            if len(content.strip()) < 100:
+                errors.append(
+                    f"Content too short ({len(content)} characters). "
+                    "Minimum 100 characters required for meaningful guidelines."
+                )
+
+            # Check for markdown headers (warning only)
+            if not any(line.strip().startswith("#") for line in content.split("\n")):
+                warnings.append(
+                    "No markdown headers found. "
+                    "Consider using headers for better structure."
+                )
+
+        # Determine status
+        if errors:
+            status = "invalid"
+            message = "Content validation failed"
+        elif warnings:
+            status = "valid"
+            message = f"Content is valid but has {len(warnings)} warning(s)"
+        else:
+            status = "valid"
+            message = "Content is valid with no issues"
+
+        return {
+            "status": status,
+            "warnings": warnings,
+            "errors": errors,
+            "message": message,
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "warnings": [],
+            "errors": [f"Validation error: {str(e)}"],
+            "message": "Validation process failed",
+        }

mcp_ticketer/mcp/server/tools/pr_tools.py

@@ -0,0 +1,154 @@
+"""Pull request integration tools for tickets.
+
+This module implements tools for linking tickets with pull requests and
+creating PRs from tickets. Note that PR functionality may not be available
+in all adapters.
+"""
+
+from typing import Any
+
+from ..server_sdk import get_adapter, mcp
+
+
+@mcp.tool()
+async def ticket_create_pr(
+    ticket_id: str,
+    title: str,
+    description: str = "",
+    source_branch: str | None = None,
+    target_branch: str = "main",
+) -> dict[str, Any]:
+    """Create a pull request linked to a ticket.
+
+    Creates a new pull request and automatically links it to the specified
+    ticket. This functionality may not be available in all adapters.
+
+    Args:
+        ticket_id: Unique identifier of the ticket to link the PR to
+        title: Pull request title
+        description: Pull request description
+        source_branch: Source branch for the PR (if not specified, may use ticket ID)
+        target_branch: Target branch for the PR (default: main)
+
+    Returns:
+        Created PR details and link information, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Check if adapter supports PR operations
+        if not hasattr(adapter, "create_pull_request"):
+            return {
+                "status": "error",
+                "error": f"Pull request creation not supported by {type(adapter).__name__} adapter",
+                "ticket_id": ticket_id,
+            }
+
+        # Read ticket to validate it exists
+        ticket = await adapter.read(ticket_id)
+        if ticket is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found",
+            }
+
+        # Use ticket ID as source branch if not specified
+        if source_branch is None:
+            source_branch = f"feature/{ticket_id}"
+
+        # Create PR via adapter
+        pr_data = await adapter.create_pull_request(  # type: ignore
+            ticket_id=ticket_id,
+            title=title,
+            description=description,
+            source_branch=source_branch,
+            target_branch=target_branch,
+        )
+
+        return {
+            "status": "completed",
+            "ticket_id": ticket_id,
+            "pull_request": pr_data,
+        }
+
+    except AttributeError:
+        return {
+            "status": "error",
+            "error": "Pull request creation not supported by this adapter",
+            "ticket_id": ticket_id,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to create pull request: {str(e)}",
+            "ticket_id": ticket_id,
+        }
+
+
+@mcp.tool()
+async def ticket_link_pr(
+    ticket_id: str,
+    pr_url: str,
+) -> dict[str, Any]:
+    """Link an existing pull request to a ticket.
+
+    Associates an existing pull request (identified by URL) with a ticket.
+    This is typically done by adding the PR URL to the ticket's metadata
+    or as a comment.
+
+    Args:
+        ticket_id: Unique identifier of the ticket
+        pr_url: URL of the pull request to link
+
+    Returns:
+        Link confirmation and updated ticket details, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Read ticket to validate it exists
+        ticket = await adapter.read(ticket_id)
+        if ticket is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found",
+            }
+
+        # Check if adapter has specialized PR linking
+        if hasattr(adapter, "link_pull_request"):
+            result = await adapter.link_pull_request(  # type: ignore
+                ticket_id=ticket_id, pr_url=pr_url
+            )
+            return {
+                "status": "completed",
+                "ticket_id": ticket_id,
+                "pr_url": pr_url,
+                "result": result,
+            }
+
+        # Fallback: Add PR link as comment
+        from ....core.models import Comment
+
+        comment = Comment(
+            ticket_id=ticket_id,
+            content=f"Pull Request: {pr_url}",
+        )
+
+        created_comment = await adapter.add_comment(comment)
+
+        return {
+            "status": "completed",
+            "ticket_id": ticket_id,
+            "pr_url": pr_url,
+            "method": "comment",
+            "comment": created_comment.model_dump(),
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to link pull request: {str(e)}",
+            "ticket_id": ticket_id,
+        }

mcp_ticketer/mcp/server/tools/search_tools.py

@@ -0,0 +1,206 @@
+"""Search and query tools for finding tickets.
+
+This module implements advanced search capabilities for tickets using
+various filters and criteria.
+"""
+
+from typing import Any
+
+from ....core.models import Priority, SearchQuery, TicketState
+from ..server_sdk import get_adapter, mcp
+
+
+@mcp.tool()
+async def ticket_search(
+    query: str | None = None,
+    state: str | None = None,
+    priority: str | None = None,
+    tags: list[str] | None = None,
+    assignee: str | None = None,
+    limit: int = 10,
+) -> dict[str, Any]:
+    """Search tickets using advanced filters.
+
+    Searches for tickets matching the specified criteria. All filters are
+    optional and can be combined.
+
+    Args:
+        query: Text search query to match against title and description
+        state: Filter by state - must be one of: open, in_progress, ready, tested, done, closed, waiting, blocked
+        priority: Filter by priority - must be one of: low, medium, high, critical
+        tags: Filter by tags - tickets must have all specified tags
+        assignee: Filter by assigned user ID or email
+        limit: Maximum number of results to return (default: 10, max: 100)
+
+    Returns:
+        List of tickets matching search criteria, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Validate and build search query
+        state_enum = None
+        if state is not None:
+            try:
+                state_enum = TicketState(state.lower())
+            except ValueError:
+                return {
+                    "status": "error",
+                    "error": f"Invalid state '{state}'. Must be one of: open, in_progress, ready, tested, done, closed, waiting, blocked",
+                }
+
+        priority_enum = None
+        if priority is not None:
+            try:
+                priority_enum = Priority(priority.lower())
+            except ValueError:
+                return {
+                    "status": "error",
+                    "error": f"Invalid priority '{priority}'. Must be one of: low, medium, high, critical",
+                }
+
+        # Create search query
+        search_query = SearchQuery(
+            query=query,
+            state=state_enum,
+            priority=priority_enum,
+            tags=tags,
+            assignee=assignee,
+            limit=min(limit, 100),  # Enforce max limit
+        )
+
+        # Execute search via adapter
+        results = await adapter.search(search_query)
+
+        return {
+            "status": "completed",
+            "tickets": [ticket.model_dump() for ticket in results],
+            "count": len(results),
+            "query": {
+                "text": query,
+                "state": state,
+                "priority": priority,
+                "tags": tags,
+                "assignee": assignee,
+            },
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to search tickets: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def ticket_search_hierarchy(
+    query: str,
+    include_children: bool = True,
+    max_depth: int = 3,
+) -> dict[str, Any]:
+    """Search tickets and include their hierarchy.
+
+    Performs a text search and returns matching tickets along with their
+    hierarchical context (parent epics/issues and child issues/tasks).
+
+    Args:
+        query: Text search query to match against title and description
+        include_children: Whether to include child tickets in results
+        max_depth: Maximum hierarchy depth to include (1-3, default: 3)
+
+    Returns:
+        List of tickets with hierarchy information, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Validate max_depth
+        if max_depth < 1 or max_depth > 3:
+            return {
+                "status": "error",
+                "error": "max_depth must be between 1 and 3",
+            }
+
+        # Create search query
+        search_query = SearchQuery(
+            query=query,
+            limit=50,  # Reasonable limit for hierarchical search
+        )
+
+        # Execute search via adapter
+        results = await adapter.search(search_query)
+
+        # Build hierarchical results
+        hierarchical_results = []
+        for ticket in results:
+            ticket_data = {
+                "ticket": ticket.model_dump(),
+                "hierarchy": {},
+            }
+
+            # Get parent epic if applicable
+            parent_epic_id = getattr(ticket, "parent_epic", None)
+            if parent_epic_id and max_depth >= 2:
+                try:
+                    parent_epic = await adapter.read(parent_epic_id)
+                    if parent_epic:
+                        ticket_data["hierarchy"][
+                            "parent_epic"
+                        ] = parent_epic.model_dump()
+                except Exception:
+                    pass  # Parent not found, continue
+
+            # Get parent issue if applicable (for tasks)
+            parent_issue_id = getattr(ticket, "parent_issue", None)
+            if parent_issue_id and max_depth >= 2:
+                try:
+                    parent_issue = await adapter.read(parent_issue_id)
+                    if parent_issue:
+                        ticket_data["hierarchy"][
+                            "parent_issue"
+                        ] = parent_issue.model_dump()
+                except Exception:
+                    pass  # Parent not found, continue
+
+            # Get children if requested
+            if include_children and max_depth >= 2:
+                children = []
+
+                # Get child issues (for epics)
+                child_issue_ids = getattr(ticket, "child_issues", [])
+                for child_id in child_issue_ids:
+                    try:
+                        child = await adapter.read(child_id)
+                        if child:
+                            children.append(child.model_dump())
+                    except Exception:
+                        pass  # Child not found, continue
+
+                # Get child tasks (for issues)
+                child_task_ids = getattr(ticket, "children", [])
+                for child_id in child_task_ids:
+                    try:
+                        child = await adapter.read(child_id)
+                        if child:
+                            children.append(child.model_dump())
+                    except Exception:
+                        pass  # Child not found, continue
+
+                if children:
+                    ticket_data["hierarchy"]["children"] = children
+
+            hierarchical_results.append(ticket_data)
+
+        return {
+            "status": "completed",
+            "results": hierarchical_results,
+            "count": len(hierarchical_results),
+            "query": query,
+            "max_depth": max_depth,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to search with hierarchy: {str(e)}",
+        }