INSTALL.md•5.81 kB
# EdgeLake MCP Server - Installation Guide
## Prerequisites
### System Requirements
- **Python**: 3.10 or higher
- **Operating System**: Linux, macOS, or Windows
- **EdgeLake Node**: Running and accessible with REST API enabled
### Check Python Version
```bash
python --version
# or
python3 --version
```
Should output Python 3.10.x or higher.
## Installation Steps
### 1. Navigate to MCP Server Directory
```bash
cd /path/to/EdgeLake/edge_lake/mcp-server
```
### 2. Create Virtual Environment (Recommended)
```bash
# Create virtual environment
python3 -m venv venv
# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate
```
### 3. Install Dependencies
```bash
pip install --upgrade pip
pip install -r requirements.txt
```
### 4. Configure Environment Variables
Copy the example configuration:
```bash
cp .env.example .env
```
Edit `.env` and set your EdgeLake connection details:
```bash
# Edit with your preferred editor
nano .env
# or
vim .env
# or
code .env
```
Example configuration:
```env
EDGELAKE_HOST=192.168.1.106
EDGELAKE_PORT=32049
EDGELAKE_TIMEOUT=30
EDGELAKE_MAX_WORKERS=10
LOG_LEVEL=INFO
```
### 5. Test Installation
#### Test EdgeLake Connection
```bash
# Test that EdgeLake node is accessible
curl -H "User-Agent: anylog" -H "command: get status" http://192.168.1.106:32049
```
Should return JSON with node status.
#### Test MCP Server
```bash
# Run server in test mode
python server.py
```
The server should start without errors and wait for input.
To test, send a JSON-RPC request:
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python server.py
```
Press Ctrl+C to stop the server.
## Integration with MCP Clients
### Claude Desktop
1. **Locate Claude Desktop config file:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
2. **Add EdgeLake MCP Server:**
```json
{
"mcpServers": {
"edgelake": {
"command": "python",
"args": ["/absolute/path/to/EdgeLake/edge_lake/mcp-server/server.py"],
"env": {
"EDGELAKE_HOST": "192.168.1.106",
"EDGELAKE_PORT": "32049"
}
}
}
}
```
**Important**: Use absolute paths, not relative paths!
3. **Restart Claude Desktop**
4. **Verify Connection:**
- Open Claude Desktop
- Look for the MCP server indicator
- Try a query: "List all databases in EdgeLake"
### Other MCP Clients
For other MCP clients, consult their documentation for adding MCP servers. The general pattern is:
- Command: `python /path/to/server.py`
- Transport: stdio
- Environment variables: Set EDGELAKE_HOST and EDGELAKE_PORT
## Verification
### Check Server Logs
```bash
# View log file
tail -f edgelake_mcp.log
```
### Test Resources
Using the MCP client (or manual JSON-RPC):
```json
{"jsonrpc":"2.0","id":1,"method":"resources/list","params":{}}
```
Should return list of databases and tables.
### Test Query Tool
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "query",
"arguments": {
"database": "your_database",
"table": "your_table",
"limit": 5
}
}
}
```
Should return query results.
## Troubleshooting
### ImportError: No module named 'mcp'
**Problem**: MCP SDK not installed
**Solution**:
```bash
pip install mcp
```
### Connection Refused
**Problem**: Cannot connect to EdgeLake node
**Solutions**:
1. Verify EdgeLake is running:
```bash
curl http://your-edgelake-host:32049
```
2. Check firewall settings
3. Verify EDGELAKE_HOST and EDGELAKE_PORT in configuration
### Permission Denied
**Problem**: Cannot execute server.py
**Solution**:
```bash
chmod +x server.py
```
Or run with python explicitly:
```bash
python server.py
```
### Virtual Environment Not Activating
**Problem**: Virtual environment activation fails
**Solutions**:
On Linux/macOS:
```bash
source venv/bin/activate
```
On Windows PowerShell:
```powershell
venv\Scripts\Activate.ps1
```
On Windows CMD:
```cmd
venv\Scripts\activate.bat
```
### Module Not Found After Installing
**Problem**: Modules installed but Python can't find them
**Solution**: Ensure you're using the same Python that has the modules:
```bash
# Check which python
which python
# or
where python
# Install with specific python
python3 -m pip install -r requirements.txt
```
## Upgrading
### Update Dependencies
```bash
pip install --upgrade -r requirements.txt
```
### Update Server Code
```bash
# Pull latest changes
git pull origin main
# Reinstall dependencies if requirements changed
pip install -r requirements.txt
```
## Uninstallation
### Remove Virtual Environment
```bash
# Deactivate if active
deactivate
# Remove directory
rm -rf venv
```
### Remove from MCP Client
Remove the server entry from your MCP client configuration file.
### Remove Files
```bash
# Remove entire mcp-server directory if desired
rm -rf /path/to/EdgeLake/edge_lake/mcp-server
```
## Next Steps
- Read [README.md](README.md) for usage instructions
- Check [examples/query_examples.md](examples/query_examples.md) for query patterns
- Review [Design/mcp_service.md](Design/mcp_service.md) for architecture details
## Support
For issues:
1. Check `edgelake_mcp.log` for error messages
2. Verify EdgeLake node is accessible and responding
3. Check MCP client logs for connection issues
4. Review GitHub issues: https://github.com/EdgeLake/EdgeLake
## Development Setup
For development:
```bash
# Install development dependencies
pip install -r requirements.txt
# Install testing tools
pip install pytest pytest-asyncio black mypy
# Run tests
pytest tests/
# Format code
black *.py
# Type check
mypy *.py
```