codepp 0.0.437__py3-none-any.whl

code_puppy/mcp_/status_tracker.py

@@ -0,0 +1,355 @@
+"""
+Server Status Tracker for monitoring MCP server runtime status.
+
+This module provides the ServerStatusTracker class that tracks the runtime
+status of MCP servers including state, metrics, and events.
+"""
+
+import logging
+import threading
+from collections import defaultdict, deque
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Optional
+
+from .managed_server import ServerState
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Event:
+    """Data class representing a server event."""
+
+    timestamp: datetime
+    event_type: str  # "started", "stopped", "error", "health_check", etc.
+    details: Dict
+    server_id: str
+
+
+class ServerStatusTracker:
+    """
+    Tracks the runtime status of MCP servers including state, metrics, and events.
+
+    This class provides in-memory storage for server states, metadata, and events
+    with thread-safe operations using locks. Events are stored using collections.deque
+    for automatic size limiting.
+
+    Example usage:
+        tracker = ServerStatusTracker()
+        tracker.set_status("server1", ServerState.RUNNING)
+        tracker.record_event("server1", "started", {"message": "Server started successfully"})
+        events = tracker.get_events("server1", limit=10)
+    """
+
+    def __init__(self):
+        """Initialize the status tracker with thread-safe data structures."""
+        # Thread safety lock
+        self._lock = threading.RLock()
+
+        # Server states (server_id -> ServerState)
+        self._server_states: Dict[str, ServerState] = {}
+
+        # Server metadata (server_id -> key -> value)
+        self._server_metadata: Dict[str, Dict[str, Any]] = defaultdict(dict)
+
+        # Server events (server_id -> deque of events)
+        # Using deque with maxlen for automatic size limiting
+        self._server_events: Dict[str, deque] = defaultdict(lambda: deque(maxlen=1000))
+
+        # Server timing information
+        self._start_times: Dict[str, datetime] = {}
+        self._stop_times: Dict[str, datetime] = {}
+
+        logger.info("ServerStatusTracker initialized")
+
+    def set_status(self, server_id: str, state: ServerState) -> None:
+        """
+        Set the current state of a server.
+
+        Args:
+            server_id: Unique identifier for the server
+            state: New server state
+        """
+        with self._lock:
+            old_state = self._server_states.get(server_id)
+            self._server_states[server_id] = state
+
+            # Record state change event
+            self.record_event(
+                server_id,
+                "state_change",
+                {
+                    "old_state": old_state.value if old_state else None,
+                    "new_state": state.value,
+                    "message": f"State changed from {old_state.value if old_state else 'unknown'} to {state.value}",
+                },
+            )
+
+            logger.debug(f"Server {server_id} state changed: {old_state} -> {state}")
+
+    def get_status(self, server_id: str) -> ServerState:
+        """
+        Get the current state of a server.
+
+        Args:
+            server_id: Unique identifier for the server
+
+        Returns:
+            Current server state, defaults to STOPPED if not found
+        """
+        with self._lock:
+            return self._server_states.get(server_id, ServerState.STOPPED)
+
+    def set_metadata(self, server_id: str, key: str, value: Any) -> None:
+        """
+        Set metadata value for a server.
+
+        Args:
+            server_id: Unique identifier for the server
+            key: Metadata key
+            value: Metadata value (can be any type)
+        """
+        with self._lock:
+            if server_id not in self._server_metadata:
+                self._server_metadata[server_id] = {}
+
+            old_value = self._server_metadata[server_id].get(key)
+            self._server_metadata[server_id][key] = value
+
+            # Record metadata change event
+            self.record_event(
+                server_id,
+                "metadata_update",
+                {
+                    "key": key,
+                    "old_value": old_value,
+                    "new_value": value,
+                    "message": f"Metadata '{key}' updated",
+                },
+            )
+
+            logger.debug(f"Server {server_id} metadata updated: {key} = {value}")
+
+    def get_metadata(self, server_id: str, key: str) -> Any:
+        """
+        Get metadata value for a server.
+
+        Args:
+            server_id: Unique identifier for the server
+            key: Metadata key
+
+        Returns:
+            Metadata value or None if not found
+        """
+        with self._lock:
+            return self._server_metadata.get(server_id, {}).get(key)
+
+    def record_event(self, server_id: str, event_type: str, details: Dict) -> None:
+        """
+        Record an event for a server.
+
+        Args:
+            server_id: Unique identifier for the server
+            event_type: Type of event (e.g., "started", "stopped", "error", "health_check")
+            details: Dictionary containing event details
+        """
+        with self._lock:
+            event = Event(
+                timestamp=datetime.now(),
+                event_type=event_type,
+                details=details.copy()
+                if details
+                else {},  # Copy to prevent modification
+                server_id=server_id,
+            )
+
+            # Add to deque (automatically handles size limiting)
+            self._server_events[server_id].append(event)
+
+            logger.debug(f"Event recorded for server {server_id}: {event_type}")
+
+    def get_events(self, server_id: str, limit: int = 100) -> List[Event]:
+        """
+        Get recent events for a server.
+
+        Args:
+            server_id: Unique identifier for the server
+            limit: Maximum number of events to return (default: 100)
+
+        Returns:
+            List of events ordered by timestamp (most recent first)
+        """
+        with self._lock:
+            events = list(self._server_events.get(server_id, deque()))
+
+            # Return most recent events first, limited by count
+            events.reverse()  # Most recent first
+            return events[:limit]
+
+    def clear_events(self, server_id: str) -> None:
+        """
+        Clear all events for a server.
+
+        Args:
+            server_id: Unique identifier for the server
+        """
+        with self._lock:
+            if server_id in self._server_events:
+                self._server_events[server_id].clear()
+                logger.info(f"Cleared all events for server: {server_id}")
+
+    def get_uptime(self, server_id: str) -> Optional[timedelta]:
+        """
+        Calculate uptime for a server based on start/stop times.
+
+        Args:
+            server_id: Unique identifier for the server
+
+        Returns:
+            Server uptime as timedelta, or None if server never started
+        """
+        with self._lock:
+            start_time = self._start_times.get(server_id)
+            if start_time is None:
+                return None
+
+            # If server is currently running, calculate from start time to now
+            current_state = self.get_status(server_id)
+            if current_state == ServerState.RUNNING:
+                return datetime.now() - start_time
+
+            # If server is stopped, calculate from start to stop time
+            stop_time = self._stop_times.get(server_id)
+            if stop_time is not None and stop_time > start_time:
+                return stop_time - start_time
+
+            # If we have start time but no valid stop time, assume currently running
+            return datetime.now() - start_time
+
+    def record_start_time(self, server_id: str) -> None:
+        """
+        Record the start time for a server.
+
+        Args:
+            server_id: Unique identifier for the server
+        """
+        with self._lock:
+            start_time = datetime.now()
+            self._start_times[server_id] = start_time
+
+            # Record start event
+            self.record_event(
+                server_id,
+                "started",
+                {"start_time": start_time.isoformat(), "message": "Server started"},
+            )
+
+            logger.info(f"Recorded start time for server: {server_id}")
+
+    def record_stop_time(self, server_id: str) -> None:
+        """
+        Record the stop time for a server.
+
+        Args:
+            server_id: Unique identifier for the server
+        """
+        with self._lock:
+            stop_time = datetime.now()
+            self._stop_times[server_id] = stop_time
+
+            # Calculate final uptime
+            start_time = self._start_times.get(server_id)
+            uptime = None
+            if start_time:
+                uptime = stop_time - start_time
+
+            # Record stop event
+            self.record_event(
+                server_id,
+                "stopped",
+                {
+                    "stop_time": stop_time.isoformat(),
+                    "uptime_seconds": uptime.total_seconds() if uptime else None,
+                    "message": "Server stopped",
+                },
+            )
+
+            logger.info(f"Recorded stop time for server: {server_id}")
+
+    def get_all_server_ids(self) -> List[str]:
+        """
+        Get all server IDs that have been tracked.
+
+        Returns:
+            List of all server IDs
+        """
+        with self._lock:
+            # Combine all sources of server IDs
+            all_ids = set()
+            all_ids.update(self._server_states.keys())
+            all_ids.update(self._server_metadata.keys())
+            all_ids.update(self._server_events.keys())
+            all_ids.update(self._start_times.keys())
+            all_ids.update(self._stop_times.keys())
+
+            return sorted(list(all_ids))
+
+    def get_server_summary(self, server_id: str) -> Dict[str, Any]:
+        """
+        Get comprehensive summary of server status.
+
+        Args:
+            server_id: Unique identifier for the server
+
+        Returns:
+            Dictionary containing current state, metadata, recent events, and uptime
+        """
+        with self._lock:
+            return {
+                "server_id": server_id,
+                "state": self.get_status(server_id).value,
+                "metadata": self._server_metadata.get(server_id, {}).copy(),
+                "recent_events_count": len(self._server_events.get(server_id, deque())),
+                "uptime": self.get_uptime(server_id),
+                "start_time": self._start_times.get(server_id),
+                "stop_time": self._stop_times.get(server_id),
+                "last_event_time": (
+                    list(self._server_events.get(server_id, deque()))[-1].timestamp
+                    if server_id in self._server_events
+                    and len(self._server_events[server_id]) > 0
+                    else None
+                ),
+            }
+
+    def cleanup_old_data(self, days_to_keep: int = 7) -> None:
+        """
+        Clean up old data to prevent memory bloat.
+
+        Args:
+            days_to_keep: Number of days of data to keep (default: 7)
+        """
+        cutoff_time = datetime.now() - timedelta(days=days_to_keep)
+
+        with self._lock:
+            cleaned_servers = []
+
+            for server_id in list(self._server_events.keys()):
+                events = self._server_events[server_id]
+                if events:
+                    # Filter out old events
+                    original_count = len(events)
+                    # Convert to list, filter, then create new deque
+                    filtered_events = [
+                        event for event in events if event.timestamp >= cutoff_time
+                    ]
+
+                    # Replace the deque with filtered events
+                    self._server_events[server_id] = deque(filtered_events, maxlen=1000)
+
+                    if len(filtered_events) < original_count:
+                        cleaned_servers.append(server_id)
+
+            if cleaned_servers:
+                logger.info(f"Cleaned old events for {len(cleaned_servers)} servers")

code_puppy/mcp_/system_tools.py

@@ -0,0 +1,209 @@
+"""
+System tool detection and validation for MCP server requirements.
+"""
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+
+@dataclass
+class ToolInfo:
+    """Information about a detected system tool."""
+
+    name: str
+    available: bool
+    version: Optional[str] = None
+    path: Optional[str] = None
+    error: Optional[str] = None
+
+
+class SystemToolDetector:
+    """Detect and validate system tools required by MCP servers."""
+
+    # Tool version commands
+    VERSION_COMMANDS = {
+        "node": ["node", "--version"],
+        "npm": ["npm", "--version"],
+        "npx": ["npx", "--version"],
+        "python": ["python", "--version"],
+        "python3": ["python3", "--version"],
+        "pip": ["pip", "--version"],
+        "pip3": ["pip3", "--version"],
+        "git": ["git", "--version"],
+        "docker": ["docker", "--version"],
+        "java": ["java", "-version"],
+        "go": ["go", "version"],
+        "rust": ["rustc", "--version"],
+        "cargo": ["cargo", "--version"],
+        "julia": ["julia", "--version"],
+        "R": ["R", "--version"],
+        "php": ["php", "--version"],
+        "ruby": ["ruby", "--version"],
+        "perl": ["perl", "--version"],
+        "swift": ["swift", "--version"],
+        "dotnet": ["dotnet", "--version"],
+        "jupyter": ["jupyter", "--version"],
+        "code": ["code", "--version"],  # VS Code
+        "vim": ["vim", "--version"],
+        "emacs": ["emacs", "--version"],
+    }
+
+    @classmethod
+    def detect_tool(cls, tool_name: str) -> ToolInfo:
+        """Detect if a tool is available and get its version."""
+        # First check if tool is in PATH
+        tool_path = shutil.which(tool_name)
+
+        if not tool_path:
+            return ToolInfo(
+                name=tool_name, available=False, error=f"{tool_name} not found in PATH"
+            )
+
+        # Try to get version
+        version_cmd = cls.VERSION_COMMANDS.get(tool_name)
+        version = None
+        error = None
+
+        if version_cmd:
+            try:
+                # Run version command
+                result = subprocess.run(
+                    version_cmd, capture_output=True, text=True, timeout=10
+                )
+
+                if result.returncode == 0:
+                    # Parse version from output
+                    output = result.stdout.strip() or result.stderr.strip()
+                    version = cls._parse_version(tool_name, output)
+                else:
+                    error = f"Version check failed: {result.stderr.strip()}"
+
+            except subprocess.TimeoutExpired:
+                error = "Version check timed out"
+            except Exception as e:
+                error = f"Version check error: {str(e)}"
+
+        return ToolInfo(
+            name=tool_name, available=True, version=version, path=tool_path, error=error
+        )
+
+    @classmethod
+    def detect_tools(cls, tool_names: List[str]) -> Dict[str, ToolInfo]:
+        """Detect multiple tools."""
+        return {name: cls.detect_tool(name) for name in tool_names}
+
+    @classmethod
+    def _parse_version(cls, tool_name: str, output: str) -> Optional[str]:
+        """Parse version string from command output."""
+        if not output:
+            return None
+
+        # Common version patterns
+        import re
+
+        # Try to find version pattern like "v1.2.3" or "1.2.3"
+        version_patterns = [
+            r"v?(\d+\.\d+\.\d+(?:\.\d+)?)",  # Standard semver
+            r"(\d+\.\d+\.\d+)",  # Simple version
+            r"version\s+v?(\d+\.\d+\.\d+)",  # "version 1.2.3"
+            r"v?(\d+\.\d+)",  # Major.minor only
+        ]
+
+        for pattern in version_patterns:
+            match = re.search(pattern, output, re.IGNORECASE)
+            if match:
+                return match.group(1)
+
+        # If no pattern matches, return first line (common for many tools)
+        first_line = output.split("\n")[0].strip()
+        if len(first_line) < 100:  # Reasonable length for a version string
+            return first_line
+
+        return None
+
+    @classmethod
+    def check_package_dependencies(cls, packages: List[str]) -> Dict[str, bool]:
+        """Check if package dependencies are available."""
+        results = {}
+
+        for package in packages:
+            available = False
+
+            # Try different package managers/methods
+            if package.startswith("@") or "/" in package:
+                # Likely npm package
+                available = cls._check_npm_package(package)
+            elif package in ["jupyter", "pandas", "numpy", "matplotlib"]:
+                # Python packages
+                available = cls._check_python_package(package)
+            else:
+                # Try both npm and python
+                available = cls._check_npm_package(
+                    package
+                ) or cls._check_python_package(package)
+
+            results[package] = available
+
+        return results
+
+    @classmethod
+    def _check_npm_package(cls, package: str) -> bool:
+        """Check if an npm package is available."""
+        try:
+            result = subprocess.run(
+                ["npm", "list", "-g", package],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            return result.returncode == 0
+        except Exception:
+            return False
+
+    @classmethod
+    def _check_python_package(cls, package: str) -> bool:
+        """Check if a Python package is available."""
+        try:
+            import importlib
+
+            importlib.import_module(package)
+            return True
+        except ImportError:
+            return False
+
+    @classmethod
+    def get_installation_suggestions(cls, tool_name: str) -> List[str]:
+        """Get installation suggestions for a missing tool."""
+        suggestions = {
+            "node": [
+                "Install Node.js from https://nodejs.org",
+                "Or use package manager: brew install node (macOS) / sudo apt install nodejs (Ubuntu)",
+            ],
+            "npm": ["Usually comes with Node.js - install Node.js first"],
+            "npx": ["Usually comes with npm 5.2+ - update npm: npm install -g npm"],
+            "python": [
+                "Install Python from https://python.org",
+                "Or use package manager: brew install python (macOS) / sudo apt install python3 (Ubuntu)",
+            ],
+            "python3": ["Same as python - install Python 3.x"],
+            "pip": ["Usually comes with Python - try: python -m ensurepip"],
+            "pip3": ["Usually comes with Python 3 - try: python3 -m ensurepip"],
+            "git": [
+                "Install Git from https://git-scm.com",
+                "Or use package manager: brew install git (macOS) / sudo apt install git (Ubuntu)",
+            ],
+            "docker": ["Install Docker from https://docker.com"],
+            "java": [
+                "Install OpenJDK from https://openjdk.java.net",
+                "Or use package manager: brew install openjdk (macOS) / sudo apt install default-jdk (Ubuntu)",
+            ],
+            "jupyter": ["Install with pip: pip install jupyter"],
+        }
+
+        return suggestions.get(tool_name, [f"Please install {tool_name} manually"])
+
+
+# Global detector instance
+detector = SystemToolDetector()

code_puppy/mcp_prompts/__init__.py

@@ -0,0 +1 @@
+# MCP Prompts for Code Puppy

code_puppy/mcp_prompts/hook_creator.py

@@ -0,0 +1,103 @@
+"""
+Hook Creator MCP Prompt
+
+Simple MCP prompt that injects hook creation documentation/instructions
+before user prompts for creating Code Puppy hooks.
+"""
+
+HOOK_CREATION_PROMPT = """
+# Creating Hooks in Code Puppy
+
+You are helping a user create hooks for Code Puppy. Code Puppy has two hook systems:
+
+## System 1: Lifecycle Callbacks (Python)
+Register Python functions that run at specific phases:
+- `startup` - Application boot
+- `shutdown` - Application exit
+- `custom_command` - User types /slash command
+- `pre_tool_call` - Before any tool executes
+- `post_tool_call` - After a tool finishes
+- `agent_run_start` - Agent run begins
+- `agent_run_end` - Agent run completes
+- `custom_command_help` - Build /help menu
+
+Example lifecycle callback:
+```python
+from code_puppy.callbacks import register_callback
+
+async def _on_startup():
+    print("Started!")
+    
+register_callback("startup", _on_startup)
+```
+
+## System 2: Event-Based Hooks (Shell/JSON)
+Configure shell commands responding to Code Puppy events in `.claude/settings.json`:
+- `PreToolUse` - Before a tool executes (can block with exit code 2)
+- `PostToolUse` - After a tool succeeds
+- `SessionStart` - Session begins/resumes
+- `Stop` - Claude finishes responding
+
+Example event hook configuration:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ./scripts/validate-command.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Example bash hook script:
+```bash
+#!/bin/bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
+
+# Block dangerous commands
+if echo "$COMMAND" | grep -q "drop table"; then
+  echo "Blocked: SQL injection attempt" >&2
+  exit 2
+fi
+
+exit 0
+```
+
+## Decision Tree
+Use **lifecycle callbacks** for:
+- Pure Python logic (initialization, cleanup, monitoring)
+- Custom /commands
+- Startup/shutdown tasks
+
+Use **event-based hooks** for:
+- Deterministic shell commands (validation, formatting)
+- Blocking/allowing tool calls
+- Pre/post-processing
+
+When the user asks about creating a hook, ask them:
+1. What should the hook do?
+2. When should it run? (Which phase/event?)
+3. Should it be Python or shell? (Lifecycle vs Event)
+4. Then provide the exact code/config they need.
+"""
+
+
+def inject_hook_prompt(user_message: str) -> str:
+    """
+    Inject hook creation instructions before user message.
+    Use this to add to the system prompt when handling hook creation requests.
+    """
+    return HOOK_CREATION_PROMPT + "\n\nUser question:\n" + user_message
+
+
+if __name__ == "__main__":
+    print(HOOK_CREATION_PROMPT)