Katamari MCP Server

# Katamari MCP - MVP Deployment Guide ## Quick Start The Katamari MCP server is now fully functional with working capabilities! Here's how to deploy and use it. ### Prerequisites - Python 3.9+ - Virtual environment (recommended) ### Installation 1. **Clone and setup:** ```bash git clone <repository-url> cd katamari-mcp python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate ``` 2. **Install dependencies:** ```bash # Install CPU-only PyTorch (faster download) pip install torch --index-url https://download.pytorch.org/whl/cpu # Install remaining dependencies pip install transformers pydantic aiohttp mcp pytest-asyncio beautifulsoup4 psutil ``` 3. **Verify installation:** ```bash python -c "from katamari_mcp.server import KatamariServer; print('✅ Server import successful')" ``` ### Running the Server **Basic startup:** ```bash source .venv/bin/activate python -m katamari_mcp.server ``` The server will: - Initialize the adaptive learning engine - Load the tiny LLM (Qwen2-0.5B) on first use - ~~Start MCP stdio interface~~ ~~(REMOVED)~~ - Start MCP web interfaces (SSE/WebSocket) - Create `.katamari/acp/` directories for learning data ### Available Capabilities #### 1. Web Search (`web_search`) Search the web without API tokens using multiple engines. **Parameters:** - `query` (string, required): Search query - `max_results` (integer, optional, default=5): Number of results **Example:** ```json { "tool": "web_search", "arguments": { "query": "adaptive learning systems", "max_results": 5 } } ``` #### 2. Web Scraping (`web_scrape`) Extract content from web pages in text or markdown format. **Parameters:** - `url` (string, required): URL to scrape - `format` (string, optional, default="markdown"): "text" or "markdown" **Example:** ```json { "tool": "web_scrape", "arguments": { "url": "https://example.com", "format": "markdown" } } ``` #### 3. ACP Feedback & Learning Phase 2 adaptive learning capabilities: - `acp_feedback_submit`: Submit execution feedback - `acp_feedback_summary`: Get feedback analytics - `acp_performance_metrics`: View capability performance - `acp_learning_summary`: Learning progress overview - `acp_inspect`: System inspection - `acp_propose`: Propose new capabilities ### MCP Client Integration **Claude Desktop integration:** Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "katamari": { "command": "python", "args": ["-m", "katamari_mcp.server"], "cwd": "/path/to/katamari-mcp", "env": { "VIRTUAL_ENV": "/path/to/katamari-mcp/.venv" } } } } ``` **Other MCP clients:** The server uses ~~stdio transport~~ ~~(REMOVED)~~ web transports (SSE/WebSocket), compatible with any MCP client that supports remote connections. ### Configuration Environment variables: - `DEBUG=true`: Enable debug logging - `KATAMARI_WORKSPACE_ROOT`: Override workspace directory ### Features #### ✅ Working Now - **Web Search**: DuckDuckGo + Brave Search API integration - **Web Scraping**: HTML parsing with markdown conversion - **Adaptive Learning**: Heuristic adjustment based on usage - **Performance Tracking**: Real-time capability monitoring - **Feedback System**: Multi-channel feedback collection - **Security**: Input validation and URL safety checks #### 🔄 Learning Behavior The system automatically: - Tracks execution success/failure patterns - Adjusts heuristics based on performance - Stores feedback for continuous improvement - Monitors capability health scores (0-100) ### Troubleshooting **Server won't start:** ```bash # Check dependencies pip list | grep -E "(torch|transformers|mcp)" # Test import python -c "from katamari_mcp.server import KatamariServer" ``` **LLM download issues:** The tiny LLM downloads on first use (≈500MB). Ensure: - Stable internet connection - Sufficient disk space - Firewall allows HuggingFace downloads **Web search failures:** - DuckDuckGo: No API key required - Brave Search: Free tier, may have rate limits ### Development **Run tests:** ```bash source .venv/bin/activate pytest tests/test_adaptive_learning.py ``` **Code style:** ```bash source .venv/bin/activate ruff check . # Linting black . # Formatting ``` ### Architecture ``` katamari-mcp/ ├── katamari_mcp/ │ ├── server.py # Main MCP server │ ├── router/ # Intelligent routing with tiny LLM │ ├── capabilities/ # Web search & scraping │ ├── acp/ # Adaptive learning system │ ├── security/ # Input validation │ └── utils/ # Configuration & helpers ├── tests/ # Test suite └── .katamari/acp/ # Learning data (auto-created) ``` ### Next Steps The MVP is fully functional! Future enhancements: - More web search engines - File processing capabilities - Advanced workflow composition - GUI for learning analytics --- **🎉 Congratulations! You now have a working Katamari MCP server with adaptive learning capabilities!**