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

claude_mpm/services/events/README.md

@@ -0,0 +1,303 @@
+# Event Bus System
+
+A decoupled, reliable event system for Claude MPM that separates event producers from consumers, enabling better testing, maintenance, and extensibility.
+
+## Overview
+
+The Event Bus system provides a central hub for all events in the Claude MPM framework. Instead of components directly calling Socket.IO or other services, they publish events to the bus, which routes them to interested consumers.
+
+## Architecture
+
+```
+Producers → Event Bus → Consumers
+```
+
+### Key Components
+
+- **EventBus**: Central routing and queuing system
+- **Event**: Standard event format with metadata
+- **Producers**: Publish events without knowing consumers
+- **Consumers**: Subscribe to topics and process events
+- **Topics**: Hierarchical event categorization
+
+## Benefits
+
+### 1. Decoupling
+- Producers don't know about consumers
+- Socket.IO is just another consumer
+- Easy to add/remove consumers without affecting producers
+
+### 2. Reliability
+- Events queued when consumers unavailable
+- Retry logic with exponential backoff
+- Dead letter queue for failed events
+- Graceful degradation
+
+### 3. Testability
+- Test producers without Socket.IO
+- Mock event bus for unit tests
+- Test consumers in isolation
+- Deterministic event flow
+
+### 4. Observability
+- Central metrics collection
+- Event flow monitoring
+- Performance tracking
+- Debug logging
+
+### 5. Flexibility
+- Topic-based filtering
+- Event transformation
+- Batch processing
+- Priority queuing
+
+## Usage
+
+### Basic Setup
+
+```python
+from claude_mpm.services.events import EventBus, SocketIOConsumer, LoggingConsumer
+
+# Create and start event bus
+bus = EventBus()
+await bus.start()
+
+# Add consumers
+socketio_consumer = SocketIOConsumer()
+await bus.subscribe(socketio_consumer)
+
+logging_consumer = LoggingConsumer(topics=["hook.**"])
+await bus.subscribe(logging_consumer)
+```
+
+### Publishing Events
+
+```python
+from claude_mpm.services.events import HookEventProducer
+
+# Create producer
+producer = HookEventProducer(bus)
+
+# Publish events
+await producer.publish_response({
+    "content": "Assistant response text",
+    "model": "claude-3",
+})
+
+await producer.publish_tool_use(
+    tool_name="Read",
+    tool_params={"file_path": "/path/to/file"},
+    tool_result="File contents",
+)
+```
+
+### Creating Custom Consumers
+
+```python
+from claude_mpm.services.events import IEventConsumer, ConsumerConfig
+
+class CustomConsumer(IEventConsumer):
+    def __init__(self):
+        self._config = ConsumerConfig(
+            name="CustomConsumer",
+            topics=["system.**"],  # Subscribe to system events
+            priority=ConsumerPriority.NORMAL,
+        )
+    
+    async def consume(self, event: Event) -> bool:
+        # Process event
+        print(f"Processing: {event.topic} - {event.type}")
+        return True
+    
+    # Implement other required methods...
+```
+
+## Topic Hierarchy
+
+Events are organized in a hierarchical topic structure:
+
+```
+hook.*          # Hook system events
+  .response     # Assistant responses
+  .tool         # Tool usage
+  .subagent.*   # Subagent events
+  .error        # Hook errors
+
+system.*        # System events
+  .lifecycle.*  # Service startup/shutdown
+  .health       # Health status
+  .config       # Configuration changes
+  .performance  # Performance metrics
+  .error        # System errors
+  .warning      # System warnings
+
+cli.*           # CLI command events
+agent.*         # Agent events
+build.*         # Build monitoring events
+```
+
+### Topic Patterns
+
+- `hook.*` - Matches `hook.response` but not `hook.tool.usage`
+- `hook.**` - Matches all hook events including nested
+- `**` - Matches all events
+
+## Event Format
+
+```python
+@dataclass
+class Event:
+    id: str                    # Unique event ID
+    topic: str                 # Event topic
+    type: str                  # Event type
+    timestamp: datetime        # Creation time
+    source: str               # Event source
+    data: Dict[str, Any]      # Event payload
+    metadata: EventMetadata   # Processing metadata
+    correlation_id: str       # Track related events
+    priority: EventPriority   # Processing priority
+```
+
+## Consumers
+
+### Built-in Consumers
+
+#### SocketIOConsumer
+- Emits events via Socket.IO
+- Batching for efficiency
+- Automatic reconnection
+- Connection pooling
+
+#### LoggingConsumer
+- Logs events for debugging
+- Configurable log levels
+- JSON formatting
+- Topic filtering
+
+#### MetricsConsumer
+- Collects event statistics
+- Rate calculation
+- Latency tracking
+- Top event analysis
+
+#### DeadLetterConsumer
+- Stores failed events
+- Event replay capability
+- Retention policies
+- Failure analysis
+
+## Producers
+
+### Built-in Producers
+
+#### HookEventProducer
+- Publishes hook system events
+- Helper methods for common events
+- Correlation tracking
+
+#### SystemEventProducer
+- Publishes system-level events
+- Service lifecycle events
+- Health and metrics
+- Configuration changes
+
+## Configuration
+
+### EventBus Options
+
+```python
+EventBus(
+    max_queue_size=10000,      # Maximum queued events
+    process_interval=0.01,     # Processing frequency
+    batch_timeout=0.1,         # Batch wait time
+    enable_metrics=True,       # Track metrics
+    enable_persistence=False,  # Persist to disk
+)
+```
+
+### Consumer Configuration
+
+```python
+ConsumerConfig(
+    name="MyConsumer",
+    topics=["hook.**"],           # Topics to subscribe
+    priority=ConsumerPriority.HIGH,
+    batch_size=10,                # Process in batches
+    batch_timeout=0.5,            # Batch wait time
+    max_retries=3,                # Retry failed events
+    retry_backoff=2.0,            # Backoff multiplier
+    filter_func=my_filter,        # Event filter
+    transform_func=my_transform,  # Event transformer
+)
+```
+
+## Migration Guide
+
+### Updating Hook Handler
+
+Before (Direct Socket.IO):
+```python
+# Old: Direct Socket.IO dependency
+socketio_client = socketio.Client()
+socketio_client.emit("hook_event", event_data)
+```
+
+After (Event Bus):
+```python
+# New: Publish to event bus
+producer = HookEventProducer(event_bus)
+await producer.publish_response(response_data)
+```
+
+### Testing
+
+Before:
+```python
+# Hard to test - needs Socket.IO server
+def test_hook_handler():
+    # Complex setup with Socket.IO
+    pass
+```
+
+After:
+```python
+# Easy to test - mock event bus
+def test_hook_handler():
+    mock_bus = Mock()
+    producer = HookEventProducer(mock_bus)
+    await producer.publish_response(data)
+    mock_bus.publish.assert_called_once()
+```
+
+## Performance
+
+- **Publish Latency**: <1ms average
+- **Processing Throughput**: 10,000+ events/sec
+- **Memory Usage**: ~100 bytes per queued event
+- **CPU Overhead**: <5% for typical load
+
+## Best Practices
+
+1. **Use Topics Wisely**: Create logical topic hierarchies
+2. **Set Priorities**: Critical events should have higher priority
+3. **Handle Errors**: Consumers should handle their own errors
+4. **Monitor Metrics**: Track queue size and processing rates
+5. **Test in Isolation**: Test producers and consumers separately
+6. **Batch When Possible**: Improve efficiency with batching
+7. **Clean Shutdown**: Always call `bus.stop()` for graceful shutdown
+
+## Examples
+
+See the `scripts/` directory for complete examples:
+- `test_event_bus.py` - Basic event bus demonstration
+- `hook_handler_with_event_bus.py` - Hook handler integration
+
+## Future Enhancements
+
+- [ ] Persistent event storage
+- [ ] Event replay from timestamp
+- [ ] Distributed event bus (Redis/RabbitMQ backend)
+- [ ] Event schema validation
+- [ ] Advanced routing rules
+- [ ] Event compression
+- [ ] WebSocket consumer for real-time streaming

claude_mpm/services/events/consumers/logging.py

@@ -133,8 +133,7 @@ class LoggingConsumer(IEventConsumer):
         """Format an event for logging."""
         # Build base message
         message = (
-            f"[{event.topic}] {event.type} "
-            f"(id={event.id[:8]}, source={event.source})"
+            f"[{event.topic}] {event.type} (id={event.id[:8]}, source={event.source})"
         )
 
         # Add data if configured

claude_mpm/services/framework_claude_md_generator/README.md

@@ -0,0 +1,119 @@
+# 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/infrastructure/monitoring/resources.py

@@ -177,7 +177,7 @@ class ResourceMonitorService(BaseMonitoringService):
         # Load average (Unix only)
         try:
             if hasattr(psutil, "getloadavg"):
-                load1, load5, load15 = psutil.getloadavg()
+                load1, load5, _load15 = psutil.getloadavg()
                 cpu_count = psutil.cpu_count()
 
                 # Load is concerning if > cpu_count

claude_mpm/services/local_ops/__init__.py

@@ -86,6 +86,7 @@ from claude_mpm.services.core.models.process import (
     PROTECTED_PORT_RANGES,
     DeploymentState,
     ProcessInfo,
+    ProcessStatus,
     StartConfig,
     is_port_protected,
 )
@@ -147,6 +148,7 @@ __all__ = [
     "PortConflictError",
     "ProcessInfo",
     "ProcessSpawnError",
+    "ProcessStatus",
     # Data models - Process
     "ResourceMonitor",
     "ResourceUsage",

claude_mpm/services/local_ops/process_manager.py

@@ -187,7 +187,7 @@ class LocalProcessManager(SyncBaseService, ILocalProcessManager):
             # Check if process is still running
             if process.poll() is not None:
                 # Process died immediately
-                stdout, stderr = process.communicate()
+                _stdout, stderr = process.communicate()
                 error_msg = stderr.decode("utf-8", errors="replace") if stderr else ""
                 raise ProcessSpawnError(
                     f"Process died immediately. Exit code: {process.returncode}. "

claude_mpm/services/local_ops/resource_monitor.py

@@ -102,7 +102,7 @@ class ResourceMonitor(SyncBaseService, IResourceMonitor):
         self._initialized = True
         self.log_info(
             f"Resource monitor initialized "
-            f"(fd_threshold={self.fd_threshold_percent*100:.0f}%, "
+            f"(fd_threshold={self.fd_threshold_percent * 100:.0f}%, "
             f"thread_threshold={self.thread_threshold}, "
             f"connection_threshold={self.connection_threshold}, "
             f"disk_threshold={self.disk_threshold_mb}MB)"
@@ -304,7 +304,7 @@ class ResourceMonitor(SyncBaseService, IResourceMonitor):
             return 0
 
         try:
-            soft_limit, hard_limit = resource_module.getrlimit(
+            soft_limit, _hard_limit = resource_module.getrlimit(
                 resource_module.RLIMIT_NOFILE
             )
             return soft_limit

claude_mpm/services/mcp_gateway/README.md

@@ -0,0 +1,185 @@
+# 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.