Katamari MCP Server

# OpenCode Katamari MCP Configuration Configuration for using Katamari MCP as a **remote web service** with OpenCode at `/projects/katamari-mcp`. ## 🚀 Remote Service Architecture **Important**: Katamari runs as a separate web service, not as a local MCP server. OpenCode connects to it via HTTP/WebSocket endpoints. ### Architecture Overview ``` ┌─────────────────┐ HTTP/WebSocket ┌──────────────────┐ │ OpenCode │ ◄──────────────────► │ Katamari Web │ │ (Client) │ │ Service │ └─────────────────┘ └──────────────────┘ ``` ## 📋 Prerequisites ### 1. Start Katamari Web Service First, start Katamari as a web service (run once in background): ```bash cd /projects/katamari-mcp # Option 1: SSE only (recommended) python -m katamari_mcp.server sse # Option 2: WebSocket only python -m katamari_mcp.server websocket # Option 3: Full web stack python -m katamari_mcp.server sse,websocket ``` ### 2. Verify Service is Running ```bash # Check SSE status curl http://localhost:49152/status # Expected response: {"transport": "sse", "running": true, "connections": 0, "host": "localhost", "port": 49152} ``` ## 🌐 OpenCode Configuration Configure OpenCode to connect to the running Katamari web service. --- ## 📋 Option 1: SSE Transport (Recommended) **Best for**: General web access, HTTP compatibility, easy debugging ### opencode.jsonc ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "katamari-sse": { "type": "remote", "url": "http://localhost:49152/mcp", "enabled": true, "timeout": 10000 } } } ``` **Service Endpoints**: - **MCP Endpoint**: `http://localhost:49152/mcp` - **Status**: `http://localhost:49152/status` - **Transport**: Server-Sent Events (SSE) **Usage**: `use katamari-sse tool to search for information about quantum computing` **Benefits**: - ✅ HTTP-based, easy to debug - ✅ Works through proxies - ✅ CORS-friendly for web apps - ✅ Server-Sent Events for streaming --- ## ⚡ Option 2: WebSocket Transport **Best for**: Real-time bidirectional communication, persistent connections ### opencode.jsonc ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "katamari-websocket": { "type": "remote", "url": "ws://localhost:49153", "enabled": true, "timeout": 10000 } } } ``` **Service Endpoints**: - **WebSocket**: `ws://localhost:49153` - **Transport**: Full duplex WebSocket **Usage**: `use katamari-websocket tool to analyze data in real-time` **Benefits**: - ✅ Full duplex communication - ✅ Persistent connections - ✅ Lower latency for ongoing sessions - ✅ Real-time bidirectional support --- ## 🔄 Option 3: Dual Transport (Advanced) **Best for**: Maximum flexibility, redundant communication channels ### opencode.jsonc ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "katamari-sse": { "type": "remote", "url": "http://localhost:49152/mcp", "enabled": true, "timeout": 10000 }, "katamari-websocket": { "type": "remote", "url": "ws://localhost:49153", "enabled": true, "timeout": 10000 } } } ``` **Usage**: - `use katamari-sse tool to search for AI news` - `use katamari-websocket tool to analyze results in real-time` **Benefits**: - ✅ Multiple connection types - ✅ Flexible client options - ✅ Redundant communication channels --- ## 🛠️ Available Tools Once connected, Katamari provides these tools in OpenCode: ### Core Tools - `web_search` - Search web using DuckDuckGo + Brave Search - `web_scrape` - Extract and convert web content to markdown ### ACP Tools (Adaptive Learning) - `acp_feedback_collect` - Collect performance feedback - `acp_feedback_analyze` - Analyze feedback patterns - `acp_performance_metrics` - Get performance statistics - `acp_heuristics_update` - Update decision heuristics ## 🎯 Usage Examples ### Web Research ``` Search for information about quantum computing using katamari-sse tools ``` ### Real-time Analysis ``` Monitor AI news trends using katamari-websocket tools ``` ### Dual Transport ``` Research latest AI developments using katamari-sse tools, then analyze patterns using katamari-websocket tools ``` ## 🔧 Advanced Configuration ### Authentication Headers If your Katamari service requires authentication: ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "katamari-sse": { "type": "remote", "url": "http://localhost:49152/mcp", "enabled": true, "headers": { "Authorization": "Bearer {env:KATAMARI_API_KEY}", "X-Client-ID": "opencode" }, "timeout": 10000 } } } ``` ### Tool Management Enable/disable specific tools globally: ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "katamari-sse": { "type": "remote", "url": "http://localhost:49152/mcp", "enabled": true } }, "tools": { "katamari-sse": true, "katamari-websocket": false } } ``` ### Per-Agent Configuration ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "katamari-sse": { "type": "remote", "url": "http://localhost:49152/mcp", "enabled": true } }, "agent": { "web-researcher": { "description": "Agent specialized for web research", "tools": { "katamari*": true }, "rules": [ "When searching web information, use katamari web_search tool", "When scraping websites, use katamari web_scrape tool", "Always cite sources when using web_search results" ] } } } ``` ## 🧪 Testing Configuration ### 1. Start Katamari Service ```bash # Terminal 1: Start the service cd /projects/katamari-mcp python -m katamari_mcp.server sse # Expected output: INFO:katamari_mcp.transport.sse:SSE transport started on http://localhost:49152 INFO:__main__:Katamari MCP server running with transports: ['sse'] ``` ### 2. Configure OpenCode Create/update `opencode.jsonc` with remote configuration (see examples above) ### 3. Test Integration ```bash # Terminal 2: Start OpenCode opencode # In OpenCode TUI, test: use katamari-sse tool to search for test information ``` ### 4. Verify Endpoints ```bash # Test SSE endpoint directly curl -X POST http://localhost:49152/mcp \ -H "Content-Type: application/json" \ -d '{"id":"test","method":"tools/list","params":{}}' # Expected response: {"status": "received"} ``` ## 🐛 Troubleshooting ### Common Issues 1. **"katamari tool not found"** - Verify Katamari service is running: `curl http://localhost:49152/status` - Check `opencode.jsonc` syntax and URLs - Restart OpenCode after config changes 2. **"Connection refused"** ```bash # Check if service is running curl http://localhost:49152/status # Start service if not running python -m katamari_mcp.server sse ``` 3. **"Timeout errors"** - Increase timeout in config: `"timeout": 30000` - Check network connectivity - Verify firewall settings 4. **"Authentication failed"** - Check API keys in environment variables - Verify header format in configuration - Ensure service authentication is configured ### Debug Mode ```bash # Enable debug logging on Katamari service export KATAMARI_LOG_LEVEL=DEBUG python -m katamari_mcp.server sse # Monitor logs tail -f ~/.katamari/logs/server.log ``` ## 📊 Service Management ### Production Deployment For production use, run Katamari as a system service: ```bash # Using systemd sudo systemctl enable katamari-mcp sudo systemctl start katamari-mcp # Using Docker docker run -d \ --name katamari-mcp \ -p 49152:49152 \ -p 49153:49153 \ katamari-mcp:latest sse,websocket ``` ### Health Monitoring ```bash # Check service health curl -f http://localhost:49152/status || echo "Service down" # Monitor connections netstat -an | grep -E ":(49152|49153)" # Check logs tail -f /var/log/katamari-mcp/server.log ``` ## 🎉 Success Indicators Your configuration is working when: - ✅ Katamari service responds to status checks - ✅ OpenCode shows katamari tools in available tools list - ✅ `use katamari-* tool` commands work - ✅ Web search returns relevant results - ✅ Web scraping produces markdown output - ✅ ACP metrics are being collected ## 📚 Additional Resources - [OpenCode MCP Documentation](https://opencode.ai/docs/mcp-servers) - [Transport Guide](./TRANSPORT_GUIDE.md) - [Complete Configuration](./CONFIGURATION.md) - [Project README](./README.md) --- **Quick Test Command:** ```bash # Start service and test everything works python -m katamari_mcp.server sse && \ curl http://localhost:49152/status && \ echo "✅ Katamari MCP service is ready for OpenCode!" ``` This configuration correctly treats Katamari as a remote web service that OpenCode connects to, following proper MCP remote server architecture.