mcp-ticketer 0.4.11__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/ticket_tools.py

@@ -4,12 +4,118 @@ This module implements the core create, read, update, delete, and list
 operations for tickets using the FastMCP SDK.
 """
 
+from pathlib import Path
 from typing import Any
 
 from ....core.models import Priority, Task, TicketState
+from ....core.project_config import ConfigResolver, TicketerConfig
 from ..server_sdk import get_adapter, mcp
 
 
+async def detect_and_apply_labels(
+    adapter: Any,
+    ticket_title: str,
+    ticket_description: str,
+    existing_labels: list[str] | None = None,
+) -> list[str]:
+    """Detect and suggest labels/tags based on ticket content.
+
+    This function analyzes the ticket title and description to automatically
+    detect relevant labels/tags from the adapter's available labels.
+
+    Args:
+        adapter: The ticket adapter instance
+        ticket_title: Ticket title text
+        ticket_description: Ticket description text
+        existing_labels: Labels already specified by user (optional)
+
+    Returns:
+        List of label/tag identifiers to apply (combines auto-detected + user-specified)
+
+    """
+    # Get available labels from adapter
+    available_labels = []
+    try:
+        if hasattr(adapter, "list_labels"):
+            available_labels = await adapter.list_labels()
+        elif hasattr(adapter, "get_labels"):
+            available_labels = await adapter.get_labels()
+    except Exception:
+        # Adapter doesn't support labels or listing failed - return user labels only
+        return existing_labels or []
+
+    if not available_labels:
+        return existing_labels or []
+
+    # Combine title and description for matching (lowercase for case-insensitive matching)
+    content = f"{ticket_title} {ticket_description or ''}".lower()
+
+    # Common label keyword patterns
+    label_keywords = {
+        "bug": ["bug", "error", "broken", "crash", "fix", "issue", "defect"],
+        "feature": ["feature", "add", "new", "implement", "create", "enhancement"],
+        "improvement": [
+            "enhance",
+            "improve",
+            "update",
+            "upgrade",
+            "refactor",
+            "optimize",
+        ],
+        "documentation": ["doc", "documentation", "readme", "guide", "manual"],
+        "test": ["test", "testing", "qa", "validation", "verify"],
+        "security": ["security", "vulnerability", "auth", "permission", "exploit"],
+        "performance": ["performance", "slow", "optimize", "speed", "latency"],
+        "ui": ["ui", "ux", "interface", "design", "layout", "frontend"],
+        "api": ["api", "endpoint", "rest", "graphql", "backend"],
+        "backend": ["backend", "server", "database", "storage"],
+        "frontend": ["frontend", "client", "web", "react", "vue"],
+        "critical": ["critical", "urgent", "emergency", "blocker"],
+        "high-priority": ["urgent", "asap", "important", "critical"],
+    }
+
+    # Match labels against content
+    matched_labels = []
+
+    for label in available_labels:
+        # Extract label name (handle both dict and string formats)
+        if isinstance(label, dict):
+            label_name = label.get("name", "")
+            label_id = label.get("id", label_name)
+        else:
+            label_name = str(label)
+            label_id = label_name
+
+        label_name_lower = label_name.lower()
+
+        # Direct match: label name appears in content
+        if label_name_lower in content:
+            if label_id not in matched_labels:
+                matched_labels.append(label_id)
+            continue
+
+        # Keyword match: check if label matches any keyword category
+        for keyword_category, keywords in label_keywords.items():
+            # Check if label name relates to the category
+            if (
+                keyword_category in label_name_lower
+                or label_name_lower in keyword_category
+            ):
+                # Check if any keyword from this category appears in content
+                if any(kw in content for kw in keywords):
+                    if label_id not in matched_labels:
+                        matched_labels.append(label_id)
+                    break
+
+    # Combine user-specified labels with auto-detected ones
+    final_labels = list(existing_labels or [])
+    for label in matched_labels:
+        if label not in final_labels:
+            final_labels.append(label)
+
+    return final_labels
+
+
 @mcp.tool()
 async def ticket_create(
     title: str,
@@ -17,15 +123,33 @@ async def ticket_create(
     priority: str = "medium",
     tags: list[str] | None = None,
     assignee: str | None = None,
+    parent_epic: str | None = None,
+    auto_detect_labels: bool = True,
 ) -> dict[str, Any]:
-    """Create a new ticket with specified details.
+    """Create a new ticket with automatic label/tag detection.
+
+    This tool automatically scans available labels/tags and intelligently
+    applies relevant ones based on the ticket title and description.
+
+    Label Detection:
+    - Scans all available labels in the configured adapter
+    - Matches labels based on keywords in title/description
+    - Combines auto-detected labels with user-specified ones
+    - Can be disabled by setting auto_detect_labels=false
+
+    Common label patterns detected:
+    - bug, feature, improvement, documentation
+    - test, security, performance
+    - ui, api, backend, frontend
 
     Args:
         title: Ticket title (required)
         description: Detailed description of the ticket
         priority: Priority level - must be one of: low, medium, high, critical
-        tags: List of tags to categorize the ticket
+        tags: List of tags to categorize the ticket (auto-detection adds to these)
         assignee: User ID or email to assign the ticket to
+        parent_epic: Parent epic/project ID to assign this ticket to (optional)
+        auto_detect_labels: Automatically detect and apply relevant labels (default: True)
 
     Returns:
         Created ticket details including ID and metadata, or error information
@@ -43,13 +167,40 @@ async def ticket_create(
                 "error": f"Invalid priority '{priority}'. Must be one of: low, medium, high, critical",
             }
 
+        # Use default_user if no assignee specified
+        final_assignee = assignee
+        if final_assignee is None:
+            resolver = ConfigResolver(project_path=Path.cwd())
+            config = resolver.load_project_config() or TicketerConfig()
+            if config.default_user:
+                final_assignee = config.default_user
+
+        # Use default_project if no parent_epic specified
+        final_parent_epic = parent_epic
+        if final_parent_epic is None:
+            resolver = ConfigResolver(project_path=Path.cwd())
+            config = resolver.load_project_config() or TicketerConfig()
+            # Try default_project first, fall back to default_epic
+            if config.default_project:
+                final_parent_epic = config.default_project
+            elif config.default_epic:
+                final_parent_epic = config.default_epic
+
+        # Auto-detect labels if enabled
+        final_tags = tags
+        if auto_detect_labels:
+            final_tags = await detect_and_apply_labels(
+                adapter, title, description or "", tags
+            )
+
         # Create task object
         task = Task(
             title=title,
             description=description or "",
             priority=priority_enum,
-            tags=tags or [],
-            assignee=assignee,
+            tags=final_tags or [],
+            assignee=final_assignee,
+            parent_epic=final_parent_epic,
         )
 
         # Create via adapter
@@ -58,6 +209,8 @@ async def ticket_create(
         return {
             "status": "completed",
             "ticket": created.model_dump(),
+            "labels_applied": created.tags or [],
+            "auto_detected": auto_detect_labels,
         }
     except Exception as e:
         return {