Katamari MCP Server

# Katamari MCP An adaptive MCP (Model Context Protocol) server with intelligent routing, modular capabilities, and self-modification through ACP (Agent Control Protocol). ## Overview Katamari MCP is a next-generation MCP server that goes beyond static tool execution. It features intelligent routing via a tiny LLM, a plugin-based capability system, and a meta-agent layer that enables the server to analyze, modify, and improve itself based on usage patterns and user needs. The server supports multiple transport protocols (stdio, SSE, WebSocket) and comes with built-in capabilities for web access, along with a comprehensive framework for adding new capabilities safely through heuristic governance. ## Features ### Core Architecture - **Intelligent Routing**: Tiny LLM model automatically routes calls to appropriate capabilities - **Modular Capabilities**: Plugin-based architecture with environment isolation for each capability - **Multi-Transport Support**: stdio for MCP compatibility, SSE and WebSocket for web clients - **Hot Reload**: Development-friendly server restart after capability changes ### Adaptive Capabilities - **Self-Inspection**: Analyze current capabilities and usage patterns - **Dynamic Capability Generation**: Create new capabilities based on user requirements - **Workflow Composition**: Combine existing capabilities into automated workflows - **Self-Healing**: Detect and automatically fix issues in capabilities - **Adaptive Learning**: System improves through feedback loops and performance tracking ### Safety & Security - **Heuristic Governance**: 7-tag safety system for all self-modification operations - **Sandboxed Execution**: Each capability runs in isolated environment - **Security Validation**: Automated code scanning and package validation - **Data Exposure Controls**: Prevents information leakage from high-risk capabilities ## Quick Start ### Automated Setup (Recommended) ```bash # Clone and start git clone <repository-url> cd katamari-mcp ./start_server.sh ``` The setup script automatically handles Python version checks, virtual environment creation, dependency installation (using pip), and server startup. ### Manual Setup ```bash # Create virtual environment python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # Install dependencies (CPU-only PyTorch recommended) pip install torch --index-url https://download.pytorch.org/whl/cpu pip install transformers pydantic aiohttp mcp pytest-asyncio beautifulsoup4 psutil # Start server python -m katamari_mcp.server ``` ## Available Capabilities | Capability | Description | Parameters | |------------|-------------|-------------| | `web_search` | Tokenless web search using DuckDuckGo and Brave | `query` (string), `max_results` (int) | | `web_scrape` | Extract web page content and convert to markdown | `url` (string), `format` (string) | | `acp_inspect` | Analyze system capabilities and usage patterns | None | | `acp_propose` | Generate new capability proposals | `need` (string), `context` (dict) | | `acp_compose` | Create workflows from existing capabilities | `capabilities` (list), `workflow_name` (string) | | `acp_feedback_submit` | Submit performance feedback for learning | `capability_id`, `rating`, `comment` | | `acp_performance_metrics` | View capability performance analytics | `capability_id` (optional) | ## Architecture ### Components **Router System** - `IntelligentRouter`: LLM-powered call routing with context preservation - `CapabilityRegistry`: Dynamic capability discovery and registration - Transport support: stdio (via MCP library), SSE, WebSocket **Capability System** - Modular capabilities in `capabilities/` directory - Environment isolation for security and stability - Progressive discovery from basic listing to detailed usage **ACP (Agent Control Protocol)** - `Controller`: Orchestrates self-modification operations - `HeuristicEngine`: 7-tag safety governance system - `AdaptiveLearning`: Feedback-driven improvement - `PerformanceTracker`: Real-time capability health monitoring **Security Layer** - `SecurityValidator`: Code scanning and validation - `Sandbox`: Isolated execution environments - `GitTracker`: Version control for all ACP changes ### Heuristic Governance All self-modification operations are evaluated using a 7-tag heuristic system: ``` risk: low|medium|high|critical complexity: simple|moderate|complex|architectural scope: capability|workflow|core|security persistence: ephemeral|session|persistent|permanent testing: none|basic|comprehensive|parallel approval: auto|notify|confirm|manual data_exposure: none|local|internal|external|exfiltration ``` ## Configuration ### Transport Options ```bash # MCP compatible (stdio) - Default ./start_server.sh # Web clients (SSE + WebSocket) ./start_server.sh -t sse,websocket # All transports ./start_server.sh -t stdio,sse,websocket ``` **Note**: stdio transport uses MCP library's built-in stdio server for full compatibility. ### OpenCode Integration Configure in `opencode.jsonc`: ```jsonc { "mcp": { "katamari-sse": { "type": "remote", "url": "http://localhost:49152/mcp", "enabled": true }, "katamari-websocket": { "type": "remote", "url": "ws://localhost:49153", "enabled": false } } } ``` ### Claude Desktop ```json { "mcpServers": { "katamari": { "command": "bash", "args": ["/path/to/katamari-mcp/start_server.sh"], "cwd": "/path/to/katamari-mcp" } } } ``` ## Development ### Build & Test Commands ```bash # Install dependencies (uses pip, not poetry) ./start_server.sh # Handles dependency installation automatically # Manual dependency installation pip install torch --index-url https://download.pytorch.org/whl/cpu pip install transformers pydantic aiohttp mcp pytest-asyncio beautifulsoup4 psutil # Run all tests pytest # Run specific test file pytest tests/test_adaptive_learning.py # Run specific test pytest -k "test_heuristic_evaluation" # Lint and format (if poetry is available) poetry run ruff check . poetry run black . poetry run mypy . ``` ### Adding New Capabilities 1. Create capability file in `capabilities/` directory 2. Implement async methods following existing patterns 3. Add comprehensive tests in `tests/` directory 4. Use Pydantic models for data validation 5. Include proper error handling and logging Example capability structure: ```python class MyCapability: """Custom capability implementation.""" async def execute(self, **kwargs) -> Dict[str, Any]: """Execute capability with given parameters.""" # Implementation here pass ``` ## Documentation - [CONFIGURATION.md](CONFIGURATION.md) - Detailed configuration options - [AGENTS.md](AGENTS.md) - Development guidelines and code style - [TODO.md](TODO.md) - Roadmap and stretch goals - [PLAN.md](PLAN.md) - Technical implementation details ## License MIT License - see [LICENSE](LICENSE) file for details. --- **Katamari MCP** - An adaptive, self-modifying MCP server that evolves with your needs.