# Katamari MCP Server

An adaptive MCP (Model Context Protocol) server with ACP (Agent Control Protocol) that grows and evolves based on user needs through adaptive learning.

## Features

### Core Architecture
- **Intelligent Routing**: Tiny LLM model for efficient call routing
- **Modular Capabilities**: Plugin-based architecture with environment isolation
- **Hot Reload**: Development-friendly reload after test completion
- **Security**: Sandboxed execution and package validation
- **Asset Tracking**: Complete provenance tracking for all components

### ACP Self-Modification (Phase 1)
- **Self-Inspection**: Analyze current capabilities and system state
- **Capability Generation**: Create new capabilities based on needs
- **Workflow Composition**: Combine capabilities into workflows
- **Self-Healing**: Detect and fix system issues
- **Heuristic Governance**: 7-tag safety system for all operations

### Adaptive Learning (Phase 2) ✨ NEW
- **Dynamic Heuristics**: Self-adjusting decision making based on performance
- **Multi-Channel Feedback**: User satisfaction, automatic monitoring, test results
- **Performance Analytics**: Real-time capability health scoring and trends
- **Learning Engine**: Pattern recognition and confidence-weighted adaptations
- **Feedback Loops**: Continuous improvement from every execution

### Advanced Agency (Phase 3) 🚀 NEW
- **Workflow Optimizer**: Parallel execution, pattern recognition, auto-optimization
- **Predictive Analytics**: Performance prediction, proactive alerts, resource forecasting
- **Knowledge Transfer**: Cross-component learning, artifact sharing, similarity analysis
- **Self-Healing System**: Enhanced error recovery, pattern recognition, resilience policies

## Quick Start

### 🚀 Option 1: Automated Setup (Recommended)

```bash
# Clone and run the auto-setup script
git clone <repository-url>
cd katamari-mcp
./start_server.sh
```

The `start_server.sh` script automatically:
- ✅ Checks Python 3.9+ compatibility
- ✅ Creates and activates virtual environment
- ✅ Installs all dependencies (PyTorch CPU-only for faster setup)
- ✅ Verifies server functionality
- ✅ Creates necessary data directories
- ✅ Starts the MCP server

### 🔧 Option 2: Manual Setup

```bash
# 1. Clone and setup environment
git clone <repository-url>
cd katamari-mcp
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Install dependencies
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install transformers pydantic aiohttp mcp pytest-asyncio beautifulsoup4 psutil

# 3. Verify installation
python -c "from katamari_mcp.server import KatamariServer; print('✅ Ready')"

# 4. Start server
python -m katamari_mcp.server
```

### 🧪 Testing

```bash
# Run all tests
pytest

# Run Phase 2 adaptive learning tests
pytest tests/test_adaptive_learning.py

# Run Phase 3 advanced agency tests
pytest tests/test_phase3_simple.py tests/test_phase3_integration.py

# Test specific functionality
pytest tests/test_adaptive_learning.py::test_feedback_submission
```

## Project Structure

```
katamari-mcp/
├── katamari_mcp/          # Core server code
│   ├── router/           # LLM routing system with Phase 2 endpoints
│   ├── acp/              # ACP self-modification system
│   │   ├── adaptive_learning.py    # Dynamic heuristic adjustment
│   │   ├── feedback.py             # Feedback collection system
│   │   ├── performance_tracker.py  # Performance analytics
│   │   ├── data_models.py          # Centralized data structures
│   │   ├── controller.py          # ACP main orchestrator
│   │   ├── heuristics.py          # 7-tag safety system
│   │   ├── testing.py             # Parallel testing
│   │   ├── git_tracker.py         # Version control integration
│   │   ├── workflow_optimizer.py   # Phase 3: Workflow optimization
│   │   ├── predictive_engine.py    # Phase 3: Predictive analytics
│   │   ├── knowledge_transfer.py   # Phase 3: Cross-component learning
│   │   └── self_healing.py        # Phase 3: Enhanced error recovery
│   ├── security/         # Security and validation
│   └── utils/           # Utilities and helpers
├── tests/               # Test suite
│   ├── test_adaptive_learning.py  # Phase 2 comprehensive tests
│   ├── test_phase3_simple.py      # Phase 3 basic functionality tests
│   └── test_phase3_integration.py # Phase 3 integration tests
├── capabilities/         # Individual capability implementations
├── PLAN.md              # Detailed project plan with Phase 2 details
└── README.md            # This file
```

## Usage Examples

### MCP Client Integration

**Claude Desktop:**
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "katamari": {
      "command": "bash",
      "args": ["/path/to/katamari-mcp/start_server.sh"],
      "cwd": "/path/to/katamari-mcp"
    }
  }
}
```

**Direct MCP Usage:**
```python
# List available capabilities
capabilities = await router.list_capabilities()

# Use web search
results = await router.call("web_search", {
    "query": "adaptive learning systems",
    "max_results": 5
})

# Use web scraping
content = await router.call("web_scrape", {
    "url": "https://example.com",
    "format": "markdown"
})

# Submit feedback for learning
await router.call("acp_feedback_submit", {
    "capability_id": "web_search",
    "rating": 5,
    "comment": "Great results!"
})
```

### Available Capabilities

| Capability | Description | Parameters |
|------------|-------------|-------------|
| `web_search` | Search web without API tokens | `query` (string), `max_results` (int) |
| `web_scrape` | Extract web page content | `url` (string), `format` (string) |
| `acp_feedback_submit` | Submit execution feedback | `capability_id`, `rating`, `comment` |
| `acp_performance_metrics` | View capability analytics | `capability_id` (optional) |
| `acp_learning_summary` | Learning progress overview | None |
| `acp_inspect` | System inspection | None |
| `phase3_workflow_status` | Workflow optimization status | `workflow_id` (optional) |
| `phase3_predictions` | Predictive analytics | `capability_id` (optional) |
| `phase3_knowledge_artifacts` | Knowledge transfer artifacts | `capability_id` (optional) |
| `phase3_healing_status` | Self-healing system status | `capability_id` (optional) |

### ACP Self-Modification
```python
# Inspect system capabilities
inspection = await router.call("acp_inspect", {})

# Propose new capability
proposal = await router.call("acp_propose", {
    "need": "data visualization capability",
    "context": {"user_preference": "chart generation"}
})

# Compose workflow
workflow = await router.call("acp_compose", {
    "capabilities": ["web_search", "data_analysis"],
    "workflow_name": "research_pipeline"
})
```

### Phase 2 Adaptive Learning
```python
# Submit feedback for capability
await router.call("acp_feedback_submit", {
    "capability_id": "web_search",
    "rating": 5,
    "comment": "Excellent results!"
})

# Get performance analytics
metrics = await router.call("acp_performance_metrics", {
    "capability_id": "web_search",
    "days_back": 7
})

# Get learning summary
learning = await router.call("acp_learning_summary", {})
```

## Build/Test Commands

### Setup & Running
- `./start_server.sh` - **Recommended**: Auto-setup and start server
- `python -m katamari_mcp.server` - Start server (manual setup required)

### Testing
- `pytest` - Run all tests
- `pytest tests/test_adaptive_learning.py` - Run Phase 2 adaptive learning tests
- `pytest -k "test_name"` - Run specific test

### Development (Manual Setup)
- `source .venv/bin/activate` - Activate virtual environment
- `pip install torch --index-url https://download.pytorch.org/whl/cpu` - Install PyTorch
- `pip install transformers pydantic aiohttp mcp pytest-asyncio beautifulsoup4 psutil` - Install deps
- `ruff check .` - Lint code
- `black .` - Format code
- `mypy .` - Type checking

## Development

See [PLAN.md](PLAN.md) for detailed architecture and implementation roadmap.

### Phase 2 Features
- ✅ **Adaptive Learning Engine** - Dynamic heuristic adjustment
- ✅ **Feedback Collection** - Multi-channel feedback system
- ✅ **Performance Tracking** - Real-time analytics and health scoring
- ✅ **Data Models** - Centralized validation and serialization
- ✅ **Router Integration** - New MCP endpoints for learning features
- ✅ **Comprehensive Testing** - Full test coverage for adaptive components

### Phase 3 Features
- ✅ **Workflow Optimizer** - Parallel execution, pattern recognition, auto-optimization
- ✅ **Predictive Analytics Engine** - Performance prediction, proactive alerts, resource forecasting
- ✅ **Knowledge Transfer System** - Cross-component learning, artifact sharing, similarity analysis
- ✅ **Self-Healing System** - Enhanced error recovery, pattern recognition, resilience policies
- ✅ **System Integration** - All Phase 3 components integrated with main server
- ✅ **Comprehensive Testing** - Full test coverage for Phase 3 components

### Architecture Evolution
- **Phase 1**: Foundation - ACP self-modification and basic capabilities
- **Phase 2**: Intelligence - Adaptive learning and feedback systems
- **Phase 3**: Agency - Advanced workflow optimization, predictive capabilities, and self-healing

### Future Stretch Goals 🚀
See [TODO.md](TODO.md) for planned enhancements:
- **Named Pipe Communication** - Faster startup and persistent context
- **MCP TaskMaster** - Stateful background task management
- **Enhanced Context Management** - Cross-call conversation context
- **Performance Optimization Suite** - Advanced monitoring and tuning