MIGRATION.md•13.4 kB
# Migration Guide - Moving EdgeLake MCP Server to Standalone Project
This guide covers moving the MCP server from `EdgeLake/edge_lake/mcp-server/` to a standalone repository.
## Pre-Migration Checklist
- [ ] Decide on new repository name (e.g., `edgelake-mcp-server`)
- [ ] Create new repository on GitHub/GitLab
- [ ] Verify current MCP server works in EdgeLake project
- [ ] Document any custom EdgeLake dependencies (there should be none!)
## Migration Steps
### Step 1: Analyze Dependencies
The MCP server is **already standalone** with no EdgeLake code dependencies:
#### ✅ What's Already Standalone
- `server.py` - Pure MCP implementation, no EdgeLake imports
- `edgelake_client.py` - Only uses `requests` library
- `query_builder.py` - Pure Python, no external dependencies
- `config.py` - Standard environment variable handling
- All documentation files
#### ⚠️ Potential Issues to Check
None! The server was designed to be standalone from the start.
### Step 2: Create New Project Structure
Recommended structure for standalone project:
```
edgelake-mcp-server/
├── README.md
├── LICENSE # Add MPL-2.0 license
├── INSTALL.md
├── QUICKSTART.md
├── MIGRATION.md # This file
├── .gitignore
├── .env.example
├── requirements.txt
├── setup.py # NEW - for pip installation
├── pyproject.toml # NEW - modern Python packaging
│
├── src/
│ └── edgelake_mcp/
│ ├── __init__.py
│ ├── server.py
│ ├── client.py # Renamed from edgelake_client.py
│ ├── query.py # Renamed from query_builder.py
│ └── config.py
│
├── examples/
│ ├── claude_desktop_config.json
│ ├── query_examples.md
│ └── sample_queries.py # NEW - Python examples
│
├── tests/
│ ├── __init__.py
│ ├── test_query.py # Renamed from test_query_builder.py
│ ├── test_client.py # NEW
│ └── test_integration.py # NEW
│
├── docs/
│ ├── architecture.md # From Design/mcp_service.md
│ ├── api_reference.md # NEW
│ └── diagrams/
│ └── architecture.png
│
└── scripts/
├── install.sh # NEW - Installation script
├── test.sh # NEW - Run all tests
└── docker/
├── Dockerfile # NEW - Docker support
└── docker-compose.yml
```
### Step 3: Files to Copy Directly (No Changes)
These files can be copied as-is:
```bash
# Copy these without modification
README.md
INSTALL.md
QUICKSTART.md
.env.example
requirements.txt
# Examples
examples/claude_desktop_config.json
examples/query_examples.md
# Tests (may need import path updates)
tests/test_query_builder.py
```
### Step 4: Files Requiring Refactoring
#### A. Rename for Better Module Structure
**Current → New:**
- `server.py` → `src/edgelake_mcp/server.py`
- `edgelake_client.py` → `src/edgelake_mcp/client.py`
- `query_builder.py` → `src/edgelake_mcp/query.py`
- `config.py` → `src/edgelake_mcp/config.py`
#### B. Update Import Paths
**In `server.py`:**
```python
# OLD (current)
from edgelake_client import EdgeLakeClient
from query_builder import QueryBuilder
from config import Config
# NEW (standalone)
from edgelake_mcp.client import EdgeLakeClient
from edgelake_mcp.query import QueryBuilder
from edgelake_mcp.config import Config
```
**In `tests/test_query.py`:**
```python
# OLD
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from query_builder import QueryBuilder
# NEW
from edgelake_mcp.query import QueryBuilder
```
### Step 5: New Files to Create
#### A. `setup.py` (for pip installation)
```python
from setuptools import setup, find_packages
with open("README.md", "r", encoding="utf-8") as fh:
long_description = fh.read()
with open("requirements.txt", "r", encoding="utf-8") as fh:
requirements = [line.strip() for line in fh if line.strip() and not line.startswith("#")]
setup(
name="edgelake-mcp-server",
version="1.0.0",
author="EdgeLake",
author_email="info@anylog.co",
description="MCP server for EdgeLake distributed database",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/EdgeLake/edgelake-mcp-server",
packages=find_packages(where="src"),
package_dir={"": "src"},
classifiers=[
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"License :: OSI Approved :: Mozilla Public License 2.0 (MPL-2.0)",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
],
python_requires=">=3.10",
install_requires=requirements,
entry_points={
"console_scripts": [
"edgelake-mcp-server=edgelake_mcp.server:main",
],
},
)
```
#### B. `pyproject.toml` (modern Python packaging)
```toml
[build-system]
requires = ["setuptools>=65.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "edgelake-mcp-server"
version = "1.0.0"
description = "MCP server for EdgeLake distributed database"
readme = "README.md"
requires-python = ">=3.10"
license = {text = "MPL-2.0"}
authors = [
{name = "EdgeLake", email = "info@anylog.co"}
]
keywords = ["edgelake", "mcp", "model-context-protocol", "database", "distributed"]
classifiers = [
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"License :: OSI Approved :: Mozilla Public License 2.0 (MPL-2.0)",
"Programming Language :: Python :: 3",
]
dependencies = [
"mcp>=1.0.0",
"requests>=2.32.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"pytest-asyncio>=0.21.0",
"black>=23.0.0",
"mypy>=1.0.0",
]
[project.urls]
Homepage = "https://github.com/EdgeLake/edgelake-mcp-server"
Documentation = "https://edgelake.github.io/edgelake-mcp-server"
Repository = "https://github.com/EdgeLake/edgelake-mcp-server"
Issues = "https://github.com/EdgeLake/edgelake-mcp-server/issues"
[project.scripts]
edgelake-mcp-server = "edgelake_mcp.server:main"
[tool.black]
line-length = 120
target-version = ['py310', 'py311', 'py312']
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
```
#### C. `.gitignore`
```gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
# Virtual environments
venv/
env/
ENV/
.venv
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# Testing
.pytest_cache/
.coverage
htmlcov/
.tox/
# Logs
*.log
edgelake_mcp.log
# Environment
.env
.env.local
# Distribution
dist/
build/
```
#### D. `LICENSE` (MPL-2.0)
```text
Mozilla Public License Version 2.0
==================================
1. Definitions
--------------
[Full MPL-2.0 license text]
```
#### E. `src/edgelake_mcp/__init__.py`
```python
"""
EdgeLake MCP Server
A Model Context Protocol server for EdgeLake distributed database.
License: Mozilla Public License 2.0
"""
__version__ = "1.0.0"
__author__ = "EdgeLake"
__license__ = "MPL-2.0"
from .server import EdgeLakeMCPServer
from .client import EdgeLakeClient
from .query import QueryBuilder
from .config import Config
__all__ = [
"EdgeLakeMCPServer",
"EdgeLakeClient",
"QueryBuilder",
"Config",
]
```
### Step 6: Update Entry Point
Modify `server.py` to support both script and package usage:
```python
# At the bottom of server.py
async def main():
"""Main entry point"""
# Load configuration
config = Config.from_env()
# Create and run server
server = EdgeLakeMCPServer(config)
await server.run()
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
logger.info("Server stopped by user")
except Exception as e:
logger.error(f"Server error: {e}", exc_info=True)
sys.exit(1)
```
### Step 7: Docker Support (Optional but Recommended)
#### `scripts/docker/Dockerfile`
```dockerfile
FROM python:3.11-slim
WORKDIR /app
# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Copy application
COPY src/ ./src/
COPY setup.py .
COPY pyproject.toml .
# Install package
RUN pip install -e .
# Default environment variables
ENV EDGELAKE_HOST=127.0.0.1
ENV EDGELAKE_PORT=32049
ENV LOG_LEVEL=INFO
# Run server
CMD ["edgelake-mcp-server"]
```
#### `scripts/docker/docker-compose.yml`
```yaml
version: '3.8'
services:
edgelake-mcp:
build:
context: ../..
dockerfile: scripts/docker/Dockerfile
environment:
- EDGELAKE_HOST=${EDGELAKE_HOST:-127.0.0.1}
- EDGELAKE_PORT=${EDGELAKE_PORT:-32049}
- EDGELAKE_TIMEOUT=${EDGELAKE_TIMEOUT:-20}
- LOG_LEVEL=${LOG_LEVEL:-INFO}
stdin_open: true
tty: true
volumes:
- ./logs:/app/logs
```
### Step 8: Testing After Migration
```bash
# 1. Install in development mode
pip install -e .
# 2. Run tests
pytest tests/
# 3. Test command-line entry point
edgelake-mcp-server
# 4. Test import as module
python -c "from edgelake_mcp import EdgeLakeMCPServer; print('Import successful!')"
# 5. Run with environment variables
EDGELAKE_HOST=192.168.1.106 edgelake-mcp-server
```
### Step 9: Update Documentation
#### Update README.md
Add installation via pip:
```markdown
## Installation
### From PyPI (when published)
```bash
pip install edgelake-mcp-server
```
### From Source
```bash
git clone https://github.com/EdgeLake/edgelake-mcp-server.git
cd edgelake-mcp-server
pip install -e .
```
### Usage
Run the server:
```bash
edgelake-mcp-server
```
Or with custom configuration:
```bash
EDGELAKE_HOST=192.168.1.106 EDGELAKE_PORT=32049 edgelake-mcp-server
```
```
#### Update Claude Desktop Config
```json
{
"mcpServers": {
"edgelake": {
"command": "edgelake-mcp-server",
"env": {
"EDGELAKE_HOST": "192.168.1.106",
"EDGELAKE_PORT": "32049"
}
}
}
}
```
## Migration Checklist
### Pre-Migration
- [ ] Test current version works
- [ ] Review all files for EdgeLake-specific code
- [ ] Document current configuration
### During Migration
- [ ] Create new repository
- [ ] Copy files to new structure
- [ ] Update import paths
- [ ] Create setup.py and pyproject.toml
- [ ] Add .gitignore and LICENSE
- [ ] Update __init__.py files
### Post-Migration
- [ ] Test installation: `pip install -e .`
- [ ] Run all tests: `pytest tests/`
- [ ] Test CLI entry point: `edgelake-mcp-server`
- [ ] Test with Claude Desktop
- [ ] Update all documentation
- [ ] Create GitHub releases
## Refactoring Checklist
### Code Changes
- [ ] Rename `edgelake_client.py` → `client.py`
- [ ] Rename `query_builder.py` → `query.py`
- [ ] Update all import statements
- [ ] Add proper module exports in `__init__.py`
- [ ] Update test imports
### Documentation Changes
- [ ] Update installation instructions
- [ ] Update import examples in docs
- [ ] Update Claude Desktop config examples
- [ ] Add PyPI badges to README
- [ ] Update all file paths in documentation
### Optional Enhancements
- [ ] Add CI/CD (GitHub Actions)
- [ ] Add code coverage reporting
- [ ] Add pre-commit hooks
- [ ] Add Docker support
- [ ] Add Makefile for common tasks
- [ ] Publish to PyPI
## Common Refactoring Patterns
### Pattern 1: Import Path Updates
**Before:**
```python
from edgelake_client import EdgeLakeClient
```
**After:**
```python
from edgelake_mcp.client import EdgeLakeClient
```
### Pattern 2: Relative Imports (within package)
**In `src/edgelake_mcp/server.py`:**
```python
from .client import EdgeLakeClient
from .query import QueryBuilder
from .config import Config
```
### Pattern 3: Test Imports
**Before:**
```python
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from query_builder import QueryBuilder
```
**After:**
```python
from edgelake_mcp.query import QueryBuilder
```
## Helpful Scripts
### `scripts/install.sh`
```bash
#!/bin/bash
set -e
echo "Installing EdgeLake MCP Server..."
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Upgrade pip
pip install --upgrade pip
# Install dependencies
pip install -r requirements.txt
# Install package in development mode
pip install -e .
echo "Installation complete!"
echo "Run: edgelake-mcp-server"
```
### `scripts/test.sh`
```bash
#!/bin/bash
set -e
# Run tests with coverage
pytest tests/ -v --cov=src/edgelake_mcp --cov-report=html
# Type checking
mypy src/
# Code formatting check
black --check src/ tests/
echo "All tests passed!"
```
## Support After Migration
Once migrated, I can help with:
1. **Debugging import issues**
2. **Optimizing package structure**
3. **Adding new features**
4. **CI/CD setup**
5. **Publishing to PyPI**
6. **Docker optimization**
7. **Performance tuning**
8. **Additional documentation**
## Contact
After migration, open issues on the new repository and I'll assist with any refactoring needs!
---
**Ready to migrate?** Just let me know and I'll guide you through each step! 🚀