MCP Memory Service

# Dual Service Deployment - FastMCP + HTTP Dashboard ## Overview This deployment provides both **FastMCP Protocol** and **HTTP Dashboard** services running simultaneously, eliminating Node.js SSL issues while maintaining full functionality. ## Architecture ### Service 1: FastMCP Server (Port 8000) - **Purpose**: Native MCP protocol for Claude Code clients - **Protocol**: JSON-RPC 2.0 over Server-Sent Events - **Access**: `http://[IP]:8000/mcp` - **Service**: `mcp-memory.service` ### Service 2: HTTP Dashboard (Port 8080) - **Purpose**: Web dashboard and HTTP API - **Protocol**: Standard HTTP/REST - **Access**: `http://[IP]:8080/` - **API**: `http://[IP]:8080/api/*` - **Service**: `mcp-http-dashboard.service` ## Deployment ### Quick Deploy ```bash ./deploy_dual_services.sh ``` ### Manual Setup ```bash # Install FastMCP service sudo cp /tmp/fastmcp-server-with-mdns.service /etc/systemd/system/mcp-memory.service # Install HTTP Dashboard service sudo cp /tmp/mcp-http-dashboard.service /etc/systemd/system/mcp-http-dashboard.service # Enable and start services sudo systemctl daemon-reload sudo systemctl enable mcp-memory mcp-http-dashboard sudo systemctl start mcp-memory mcp-http-dashboard ``` ## Access URLs Replace `[IP]` with your actual server IP address (e.g., `10.0.1.30`): - **FastMCP Protocol**: `http://[IP]:8000/mcp` (for Claude Code) - **Web Dashboard**: `http://[IP]:8080/` (for monitoring) - **Health API**: `http://[IP]:8080/api/health` - **Memory API**: `http://[IP]:8080/api/memories` - **Search API**: `http://[IP]:8080/api/search` ## Service Management ### Status Checks ```bash sudo systemctl status mcp-memory # FastMCP server sudo systemctl status mcp-http-dashboard # HTTP dashboard ``` ### View Logs ```bash sudo journalctl -u mcp-memory -f # FastMCP logs sudo journalctl -u mcp-http-dashboard -f # Dashboard logs ``` ### Control Services ```bash # Start services sudo systemctl start mcp-memory mcp-http-dashboard # Stop services sudo systemctl stop mcp-memory mcp-http-dashboard # Restart services sudo systemctl restart mcp-memory mcp-http-dashboard ``` ## mDNS Discovery Both services advertise via mDNS for network discovery: ```bash # Browse HTTP services avahi-browse -t _http._tcp # Browse MCP services (if supported) avahi-browse -t _mcp._tcp # Resolve hostname avahi-resolve-host-name memory.local ``` **Services Advertised:** - `MCP Memory Dashboard._http._tcp.local.` (port 8080) - `MCP Memory FastMCP._mcp._tcp.local.` (port 8000) ## Dependencies Ensure these packages are installed in the virtual environment: - `mcp` - MCP Protocol support - `fastapi` - Web framework - `uvicorn` - ASGI server - `zeroconf` - mDNS advertising - `aiohttp` - HTTP client/server - `sqlite-vec` - Vector database - `sentence-transformers` - Embeddings ## Configuration ### Environment Variables - `MCP_MEMORY_STORAGE_BACKEND=sqlite_vec` - `MCP_MDNS_ENABLED=true` - `MCP_HTTP_ENABLED=true` - `MCP_SERVER_HOST=0.0.0.0` - `MCP_SERVER_PORT=8000` - `MCP_HTTP_PORT=8080` ### Storage Both services share the same SQLite-vec database: - **Path**: `~/.local/share/mcp-memory/sqlite_vec.db` - **Backend**: `sqlite_vec` - **Model**: `all-MiniLM-L6-v2` ## Troubleshooting ### Services Not Accessible 1. Check if services are running: `systemctl status [service]` 2. Verify ports are listening: `ss -tlnp | grep -E ":800[08]"` 3. Test direct IP access instead of hostname 4. Check firewall rules if accessing remotely ### mDNS Not Working 1. Ensure avahi-daemon is running: `systemctl status avahi-daemon` 2. Install missing dependencies: `pip install zeroconf aiohttp` 3. Restart services after installing dependencies ### FastMCP Protocol Issues 1. Ensure client accepts `text/event-stream` headers 2. Use JSON-RPC 2.0 format for requests 3. Access `/mcp` endpoint, not root `/` ## Client Configuration ### Claude Code Configure MCP client to use: ``` http://[SERVER_IP]:8000/mcp ``` ### curl Examples ```bash # Health check curl http://[SERVER_IP]:8080/api/health # Store memory curl -X POST http://[SERVER_IP]:8080/api/memories \ -H "Content-Type: application/json" \ -d '{"content": "test memory", "tags": ["test"]}' # Search memories curl -X POST http://[SERVER_IP]:8080/api/search \ -H "Content-Type: application/json" \ -d '{"query": "test", "limit": 5}' ``` ## Benefits ✅ **No Node.js SSL Issues** - Pure Python implementation ✅ **Dual Protocol Support** - Both MCP and HTTP available ✅ **Network Discovery** - mDNS advertising for easy access ✅ **Production Ready** - systemd managed services ✅ **Backward Compatible** - HTTP API preserved for existing tools ✅ **Claude Code Ready** - Native MCP protocol support