claude-mpm 4.25.10__py3-none-any.whl → 5.1.8__py3-none-any.whl

claude_mpm/services/framework_claude_md_generator/README.md

@@ -1,119 +0,0 @@
-# Framework CLAUDE.md Generator
-
-This directory contains the refactored framework CLAUDE.md generator service, originally a single 1,267-line file.
-
-## Structure
-
-### Core Modules
-
-- **`__init__.py`** (~250 lines) - Main facade class that coordinates all functionality
-- **`version_manager.py`** (~100 lines) - Handles version parsing, incrementing, and comparison
-- **`content_assembler.py`** (~120 lines) - Assembles sections and applies template variables
-- **`content_validator.py`** (~80 lines) - Validates generated content structure and completeness
-- **`deployment_manager.py`** (~80 lines) - Handles deployment to parent directories
-- **`section_manager.py`** (~60 lines) - Manages section registration, ordering, and updates
-
-### Section Generators
-
-The `section_generators/` subdirectory contains individual generators for each section:
-
-- **`__init__.py`** - Base classes and registry
-- **`header.py`** - Header with version metadata
-- **`role_designation.py`** - AI Assistant role designation
-- **`agents.py`** (~570 lines) - Comprehensive agents documentation (largest section)
-- **`todo_task_tools.py`** - Todo and Task Tools integration
-- **`claude_pm_init.py`** - Claude-PM initialization procedures
-- **`orchestration_principles.py`** - Core orchestration principles
-- **`subprocess_validation.py`** - Subprocess validation protocol
-- **`delegation_constraints.py`** - Critical delegation constraints
-- **`environment_config.py`** - Environment configuration
-- **`troubleshooting.py`** - Troubleshooting guide
-- **`core_responsibilities.py`** - Core responsibilities list
-- **`footer.py`** - Footer with metadata
-
-## Usage
-
-The API remains unchanged from the original implementation:
-
-```python
-from claude_pm.services.framework_claude_md_generator import FrameworkClaudeMdGenerator
-
-# Create generator instance (default: INSTRUCTIONS.md)
-generator = FrameworkClaudeMdGenerator()
-
-# Or specify a custom target filename (e.g., for legacy compatibility)
-generator = FrameworkClaudeMdGenerator(target_filename="CLAUDE.md")
-
-# Generate content
-content = generator.generate(
-    current_content=existing_content,  # Optional: for version auto-increment
-    template_variables={'PLATFORM': 'darwin', 'PYTHON_CMD': 'python3'}
-)
-
-# Deploy to parent directory
-success, message = generator.deploy_to_parent(Path('/parent/dir'))
-
-# Update a section
-generator.update_section('agents', 'Custom agents content')
-
-# Add custom section
-generator.add_custom_section('custom', 'Custom content', after='agents')
-```
-
-## Configuration Options
-
-### Target Filename
-
-The generator supports configurable target filenames for deployment:
-
-- **Default**: `"INSTRUCTIONS.md"` - The standard filename for framework instructions
-- **Legacy**: `"CLAUDE.md"` - For backward compatibility with older projects
-- **Custom**: Any filename can be specified for special use cases
-
-This configuration affects:
-- Deployment target filename
-- Backup file naming
-- Deployment check logic
-
-Example:
-```python
-# Use legacy filename for older projects
-generator = FrameworkClaudeMdGenerator(target_filename="CLAUDE.md")
-
-# Use custom filename for special environments
-generator = FrameworkClaudeMdGenerator(target_filename="PROJECT_INSTRUCTIONS.md")
-```
-
-## Design Benefits
-
-1. **Modularity**: Each concern is separated into its own module
-2. **Maintainability**: Smaller, focused modules are easier to understand and modify
-3. **Testability**: Individual components can be tested in isolation
-4. **Extensibility**: New section generators can be added easily
-5. **Performance**: Section generators are loaded on demand
-6. **Backward Compatibility**: Original API preserved through facade pattern
-
-## Section Generator Pattern
-
-To add a new section generator:
-
-1. Create a new file in `section_generators/`
-2. Inherit from `BaseSectionGenerator`
-3. Implement the `generate()` method
-4. Register in `section_generators/__init__.py`
-
-Example:
-```python
-from . import BaseSectionGenerator
-
-class CustomSectionGenerator(BaseSectionGenerator):
-    def generate(self, data: Dict[str, Any]) -> str:
-        return "## Custom Section\n\nContent here..."
-```
-
-## Refactoring Summary
-
-- **Original**: 1,267 lines in a single file
-- **Refactored**: ~250 lines in main module + well-organized submodules
-- **Total line reduction**: Main module reduced by 80%
-- **Improved organization**: 13 focused modules instead of 1 large file

claude_mpm/services/mcp_gateway/README.md

@@ -1,185 +0,0 @@
-# MCP Gateway Service
-
-## Overview
-
-The MCP Gateway is a standards-compliant implementation of the Model Context Protocol (MCP) for Claude MPM. It provides a simple, stdio-based server that enables seamless integration with Claude Code.
-
-**NOTE: MCP is ONLY for Claude Code - NOT for Claude Code.**
-Claude Code uses a different system for agent deployment via the `.claude/agents/` directory.
-
-## Architecture
-
-The MCP Gateway uses the official Anthropic MCP Python SDK with:
-
-- **Standards compliance** with the official MCP specification
-- **Stdio-based communication** for Claude Code integration
-- **Simple JSON-RPC protocol** over stdin/stdout
-- **Tool registry system** for extensible functionality
-- **Comprehensive error handling** and logging
-
-## Structure
-
-```
-mcp_gateway/
-├── core/           # Core interfaces and base classes
-│   ├── interfaces.py    # MCP service interfaces
-│   ├── base.py         # Base MCP service class
-│   └── exceptions.py   # MCP-specific exceptions
-├── config/         # Configuration management
-│   ├── configuration.py    # Main configuration service
-│   ├── config_loader.py   # Configuration discovery and loading
-│   └── config_schema.py   # Configuration validation
-├── server/         # MCP server implementation (ISS-0035)
-├── tools/          # Tool registry and adapters (ISS-0036)
-└── registry/       # Service discovery and registration
-```
-
-## Features
-
-### Implemented
-- ✅ **Official MCP Server** - Standards-compliant implementation using Anthropic's MCP SDK
-- ✅ **Tool Registry System** - Extensible tool management and discovery
-- ✅ **Stdio Communication** - Standard MCP protocol over stdin/stdout
-- ✅ **Configuration Management** - YAML-based configuration with validation
-- ✅ **Built-in Tools** - Echo, calculator, and system info tools
-- ✅ **CLI Integration** - Complete command-line interface for management
-- ✅ **Error Handling** - Comprehensive error handling and logging
-
-### Key Features
-- **Protocol Handler** - Stdio-based MCP protocol handler, not a background service
-- **Claude Code Ready** - Direct integration with Claude Code MCP client
-- **Extensible** - Easy to add new tools and capabilities
-- **Standards Compliant** - Follows official MCP specification exactly
-
-## Quick Start
-
-### 1. Check Status
-```bash
-claude-mpm mcp status
-```
-
-### 2. Test Tools
-```bash
-# Test echo tool
-claude-mpm mcp test echo --args '{"message": "Hello MCP!"}'
-
-# Test calculator
-claude-mpm mcp test calculator --args '{"operation": "add", "a": 5, "b": 3}'
-
-# Test system info
-claude-mpm mcp test system_info
-```
-
-### 3. Start MCP Gateway Handler
-```bash
-# Start gateway handler for Claude Code integration
-claude-mpm mcp start
-```
-
-The gateway handler will listen for MCP protocol messages via stdin/stdout. This is typically invoked by Claude Code, not run directly by users.
-
-### 4. Claude Code Integration
-Add to your Claude Code configuration (~/.claude.json):
-```json
-{
-  "mcpServers": {
-    "claude-mpm": {
-      "command": "python",
-      "args": ["-m", "claude_mpm.cli", "mcp", "start"],
-      "cwd": "/path/to/claude-mpm"
-    }
-  }
-}
-```
-
-## Configuration
-
-The MCP Gateway uses a hierarchical configuration system with the following priority:
-
-1. Default configuration (built-in)
-2. Configuration file (YAML)
-3. Environment variables (highest priority)
-
-### Configuration File Locations
-
-The system searches for configuration in these locations (in order):
-- `~/.claude/mcp/config.yaml` (user-specific)
-- `~/.claude/mcp_gateway.yaml`
-- `~/.config/claude-mpm/mcp_gateway.yaml`
-- `./mcp_gateway.yaml` (project-specific)
-- `./config/mcp_gateway.yaml`
-- `./.claude/mcp_gateway.yaml`
-- `/etc/claude-mpm/mcp_gateway.yaml` (system-wide)
-
-### Environment Variables
-
-Override configuration using environment variables:
-```bash
-export MCP_GATEWAY_SERVER_NAME=my-gateway
-export MCP_GATEWAY_TOOLS_TIMEOUT_DEFAULT=60
-export MCP_GATEWAY_LOGGING_LEVEL=DEBUG
-```
-
-## Usage
-
-### Basic Setup
-
-```python
-from claude_mpm.services.mcp_gateway import MCPConfiguration, MCPConfigLoader
-
-# Load configuration
-config_loader = MCPConfigLoader()
-config = MCPConfiguration()
-await config.initialize()
-
-# Access configuration
-server_name = config.get("mcp.server.name")
-tools_enabled = config.get("mcp.tools.enabled")
-```
-
-### Service Registration
-
-The MCP Gateway services are automatically registered with the claude-mpm service container:
-
-```python
-from claude_mpm.services import MCPConfiguration, BaseMCPService
-
-# Services are available through lazy loading
-config = MCPConfiguration()
-```
-
-## Development
-
-### Adding New MCP Services
-
-1. Define the interface in `core/interfaces.py`
-2. Create base implementation in appropriate module
-3. Register in service container if needed
-4. Add lazy import to `__init__.py`
-5. Update documentation
-
-### Testing
-
-Run tests with:
-```bash
-pytest tests/services/mcp_gateway/
-```
-
-## Dependencies
-
-- Python 3.8+
-- mcp>=0.1.0 (Anthropic's MCP package)
-- PyYAML for configuration
-- asyncio for async operations
-
-## Related Issues
-
-- ISS-0034: Infrastructure Setup (this implementation)
-- ISS-0035: MCP Server Core Implementation
-- ISS-0036: Tool Registry & Discovery System
-- ISS-0037: stdio Communication Handler
-- ISS-0038: Tool Adapter Framework
-
-## Notes
-
-This is the foundation implementation for the MCP Gateway. The actual server functionality, tool registry, and communication handlers will be implemented in subsequent tickets as part of the EP-0007 epic.

claude_mpm/services/socketio/handlers/connection.py.backup

@@ -1,217 +0,0 @@
-"""Connection event handlers for Socket.IO.
-
-WHY: This module handles all connection-related events including connect,
-disconnect, status requests, and history management. Separating these
-from other handlers makes connection management more maintainable.
-"""
-
-from datetime import datetime
-from typing import Any, Dict, List, Optional, Set
-
-from ....core.typing_utils import ClaudeStatus, EventData, SocketId
-from .base import BaseEventHandler
-
-
-class ConnectionEventHandler(BaseEventHandler):
-    """Handles Socket.IO connection lifecycle events.
-
-    WHY: Connection management is a critical aspect of the Socket.IO server
-    that deserves its own focused handler. This includes client connections,
-    disconnections, status updates, and event history management.
-    """
-
-    def register_events(self) -> None:
-        """Register connection-related event handlers."""
-
-        @self.sio.event
-        async def connect(sid, environ, *args):
-            """Handle client connection.
-
-            WHY: When a client connects, we need to track them, send initial
-            status information, and provide recent event history so they have
-            context for what's happening in the session.
-            """
-            self.clients.add(sid)
-            client_addr = environ.get("REMOTE_ADDR", "unknown")
-            user_agent = environ.get("HTTP_USER_AGENT", "unknown")
-            self.logger.info(f"🔗 NEW CLIENT CONNECTED: {sid} from {client_addr}")
-            self.logger.info(f"📱 User Agent: {user_agent[:100]}...")
-            self.logger.info(f"📈 Total clients now: {len(self.clients)}")
-
-            # Send initial status immediately with enhanced data
-            status_data = {
-                "server": "claude-mpm-python-socketio",
-                "timestamp": datetime.utcnow().isoformat() + "Z",
-                "clients_connected": len(self.clients),
-                "session_id": self.server.session_id,
-                "claude_status": self.server.claude_status,
-                "claude_pid": self.server.claude_pid,
-                "server_version": "2.0.0",
-                "client_id": sid,
-            }
-
-            try:
-                await self.emit_to_client(sid, "status", status_data)
-                await self.emit_to_client(
-                    sid,
-                    "welcome",
-                    {
-                        "message": "Connected to Claude MPM Socket.IO server",
-                        "client_id": sid,
-                        "server_time": datetime.utcnow().isoformat() + "Z",
-                    },
-                )
-
-                # Automatically send the last 50 events to new clients
-                await self._send_event_history(sid, limit=50)
-
-                self.logger.debug(
-                    f"✅ Sent welcome messages and event history to client {sid}"
-                )
-            except Exception as e:
-                self.log_error(f"sending welcome to client {sid}", e)
-
-        @self.sio.event
-        async def disconnect(sid):
-            """Handle client disconnection.
-
-            WHY: We need to clean up client tracking when they disconnect
-            to maintain accurate connection counts and avoid memory leaks.
-            """
-            if sid in self.clients:
-                self.clients.remove(sid)
-                self.logger.info(f"🔌 CLIENT DISCONNECTED: {sid}")
-                self.logger.info(f"📉 Total clients now: {len(self.clients)}")
-            else:
-                self.logger.warning(
-                    f"⚠️  Attempted to disconnect unknown client: {sid}"
-                )
-
-        @self.sio.event
-        async def get_status(sid):
-            """Handle status request.
-
-            WHY: Clients need to query current server status on demand
-            to update their UI or verify connection health.
-            """
-            status_data = {
-                "server": "claude-mpm-python-socketio",
-                "timestamp": datetime.utcnow().isoformat() + "Z",
-                "clients_connected": len(self.clients),
-                "session_id": self.server.session_id,
-                "claude_status": self.server.claude_status,
-                "claude_pid": self.server.claude_pid,
-            }
-            await self.emit_to_client(sid, "status", status_data)
-
-        @self.sio.event
-        async def get_history(sid, data=None):
-            """Handle history request.
-
-            WHY: Clients may need to request specific event history
-            to reconstruct state or filter by event types.
-            """
-            params = data or {}
-            event_types = params.get("event_types", [])
-            limit = min(params.get("limit", 100), len(self.event_history))
-
-            await self._send_event_history(sid, event_types=event_types, limit=limit)
-
-        @self.sio.event
-        async def request_history(sid, data=None):
-            """Handle legacy history request (for client compatibility).
-
-            WHY: Maintains backward compatibility with clients using
-            the older 'request.history' event name.
-            """
-            params = data or {}
-            event_types = params.get("event_types", [])
-            limit = min(params.get("limit", 50), len(self.event_history))
-
-            await self._send_event_history(sid, event_types=event_types, limit=limit)
-
-        @self.sio.event
-        async def subscribe(sid, data=None):
-            """Handle subscription request.
-
-            WHY: Allows clients to subscribe to specific event channels
-            for filtered event streaming.
-            """
-            channels = data.get("channels", ["*"]) if data else ["*"]
-            await self.emit_to_client(sid, "subscribed", {"channels": channels})
-
-        @self.sio.event
-        async def claude_event(sid, data):
-            """Handle events from client proxies.
-
-            WHY: Client proxies send events that need to be stored
-            in history and re-broadcast to other clients.
-            """
-            # Store in history
-            self.event_history.append(data)
-            self.logger.debug(
-                f"📚 Event from client stored in history (total: {len(self.event_history)})"
-            )
-
-            # Re-broadcast to all other clients
-            await self.broadcast_event("claude_event", data, skip_sid=sid)
-
-    async def _send_event_history(
-        self, sid: str, event_types: Optional[List[str]] = None, limit: int = 50
-    ):
-        """Send event history to a specific client.
-
-        WHY: When clients connect to the dashboard, they need context from recent events
-        to understand what's been happening. This sends the most recent events in
-        chronological order (oldest first) so the dashboard displays them properly.
-
-        Args:
-            sid: Socket.IO session ID of the client
-            event_types: Optional list of event types to filter by
-            limit: Maximum number of events to send (default: 50)
-        """
-        try:
-            if not self.event_history:
-                self.logger.debug(f"No event history to send to client {sid}")
-                return
-
-            # Limit to reasonable number to avoid overwhelming client
-            limit = min(limit, 100)
-
-            # Get the most recent events, filtered by type if specified
-            history = []
-            for event in reversed(self.event_history):
-                if not event_types or event.get("type") in event_types:
-                    history.append(event)
-                    if len(history) >= limit:
-                        break
-
-            # Reverse to get chronological order (oldest first)
-            history = list(reversed(history))
-
-            if history:
-                # Send as 'history' event that the client expects
-                await self.emit_to_client(
-                    sid,
-                    "history",
-                    {
-                        "events": history,
-                        "count": len(history),
-                        "total_available": len(self.event_history),
-                    },
-                )
-
-                self.logger.info(
-                    f"📚 Sent {len(history)} historical events to client {sid}"
-                )
-            else:
-                self.logger.debug(
-                    f"No matching events found for client {sid} with filters: {event_types}"
-                )
-
-        except Exception as e:
-            self.log_error(
-                f"sending event history to client {sid}",
-                e,
-                {"event_types": event_types, "limit": limit},
-            )

claude_mpm/services/socketio/handlers/hook.py.backup

@@ -1,154 +0,0 @@
-"""Hook event handlers for Socket.IO.
-
-WHY: This module handles hook events from Claude to track session information,
-agent delegations, and other hook-based activity for the system heartbeat.
-"""
-
-from datetime import datetime
-from typing import Any, Dict, Optional
-
-from .base import BaseEventHandler
-
-
-class HookEventHandler(BaseEventHandler):
-    """Handles hook events from Claude for session tracking.
-
-    WHY: Hook events provide rich information about Claude's activity including
-    session starts/stops, agent delegations, and tool usage. This handler
-    extracts session information to populate the system heartbeat data.
-    """
-
-    def register_events(self) -> None:
-        """Register hook event handlers."""
-
-        @self.sio.event
-        async def claude_event(sid, data):
-            """Handle claude_event which includes hook events.
-
-            WHY: Hook events are sent as claude_event with type 'hook'
-            and contain session and agent delegation information.
-            """
-            if not isinstance(data, dict):
-                return
-
-            # Check if this is a hook event
-            event_type = data.get("type")
-            if event_type != "hook":
-                return
-
-            # Extract hook event details
-            hook_event = data.get("event")
-            hook_data = data.get("data", {})
-
-            # Track sessions based on hook events
-            if hook_event == "subagent_start":
-                await self._handle_subagent_start(hook_data)
-            elif hook_event == "subagent_stop":
-                await self._handle_subagent_stop(hook_data)
-            elif hook_event == "user_prompt":
-                await self._handle_user_prompt(hook_data)
-            elif hook_event == "pre_tool":
-                await self._handle_pre_tool(hook_data)
-
-    async def _handle_subagent_start(self, data: Dict[str, Any]):
-        """Handle subagent start events.
-
-        WHY: When a subagent starts, we track it as an active session
-        with the agent type and start time for the heartbeat.
-        """
-        session_id = data.get("session_id")
-        agent_type = data.get("agent_type", "unknown")
-
-        if not session_id:
-            return
-
-        # Update or create session tracking
-        if hasattr(self.server, 'active_sessions'):
-            self.server.active_sessions[session_id] = {
-                "session_id": session_id,
-                "start_time": datetime.now().isoformat(),
-                "agent": agent_type,
-                "status": "active",
-                "prompt": data.get("prompt", "")[:100],  # First 100 chars
-                "last_activity": datetime.now().isoformat(),
-            }
-
-            self.logger.debug(
-                f"Tracked subagent start: session={session_id[:8]}..., agent={agent_type}"
-            )
-
-    async def _handle_subagent_stop(self, data: Dict[str, Any]):
-        """Handle subagent stop events.
-
-        WHY: When a subagent stops, we update its status or remove it
-        from active sessions depending on the stop reason.
-        """
-        session_id = data.get("session_id")
-
-        if not session_id:
-            return
-
-        # Update session status
-        if hasattr(self.server, 'active_sessions'):
-            if session_id in self.server.active_sessions:
-                # Mark as completed rather than removing immediately
-                self.server.active_sessions[session_id]["status"] = "completed"
-                self.server.active_sessions[session_id]["last_activity"] = datetime.now().isoformat()
-
-                self.logger.debug(
-                    f"Marked session completed: session={session_id[:8]}..."
-                )
-
-    async def _handle_user_prompt(self, data: Dict[str, Any]):
-        """Handle user prompt events.
-
-        WHY: User prompts indicate the start of a new interaction,
-        which we track as a PM session if no delegation occurs.
-        """
-        session_id = data.get("session_id")
-
-        if not session_id:
-            return
-
-        # Create or update PM session
-        if hasattr(self.server, 'active_sessions'):
-            if session_id not in self.server.active_sessions:
-                self.server.active_sessions[session_id] = {
-                    "session_id": session_id,
-                    "start_time": datetime.now().isoformat(),
-                    "agent": "pm",  # Default to PM
-                    "status": "active",
-                    "prompt": data.get("prompt_text", "")[:100],
-                    "working_directory": data.get("working_directory", ""),
-                    "last_activity": datetime.now().isoformat(),
-                }
-            else:
-                # Update last activity
-                self.server.active_sessions[session_id]["last_activity"] = datetime.now().isoformat()
-
-    async def _handle_pre_tool(self, data: Dict[str, Any]):
-        """Handle pre-tool events.
-
-        WHY: Pre-tool events with Task delegation indicate agent changes
-        that we need to track for accurate session information.
-        """
-        if data.get("tool_name") != "Task":
-            return
-
-        session_id = data.get("session_id")
-        delegation_details = data.get("delegation_details", {})
-        agent_type = delegation_details.get("agent_type", "unknown")
-
-        if not session_id:
-            return
-
-        # Update session with new agent
-        if hasattr(self.server, 'active_sessions'):
-            if session_id in self.server.active_sessions:
-                self.server.active_sessions[session_id]["agent"] = agent_type
-                self.server.active_sessions[session_id]["status"] = "delegated"
-                self.server.active_sessions[session_id]["last_activity"] = datetime.now().isoformat()
-
-                self.logger.debug(
-                    f"Updated session delegation: session={session_id[:8]}..., agent={agent_type}"
-                )

claude_mpm/services/static/.gitkeep

@@ -1,2 +0,0 @@
-# Static files directory for SocketIO service
-# This directory is created to prevent FileNotFoundError when the SocketIO service starts

claude_mpm/services/version_control/VERSION

@@ -1 +0,0 @@
-0.9.0

claude_mpm/skills/bundled/.gitkeep

@@ -1,2 +0,0 @@
-# This directory will contain bundled Claude Code skills
-# Skills will be organized by category subdirectories