GeoSight MCP Server

# 🖥️ Development Environment Setup Guide ## Quick Comparison | Environment | Best For | Setup Time | Cost | |-------------|----------|------------|------| | **VS Code (Local)** ⭐ | Full development, debugging | 15 min | Free | | **PyCharm** | Heavy Python development | 20 min | Free/Paid | | **GitHub Codespaces** | Cloud development, collaboration | 5 min | Free tier available | | **Docker Dev Container** | Consistent environment | 10 min | Free | | **Google Colab** | Quick testing only | 2 min | Free | --- ## Option 1: VS Code (Local) ⭐ RECOMMENDED ### Prerequisites - Python 3.11+ - Docker Desktop - Git ### Step-by-Step Setup ```bash # 1. Download and extract project unzip geosight-mcp.zip cd geosight-mcp # 2. Open in VS Code code . # 3. When VS Code opens, it will: # - Detect Python and ask to select interpreter # - Recommend extensions to install # - Click "Install All" for recommended extensions # 4. Open terminal in VS Code (Ctrl+` or Cmd+`) # 5. Create virtual environment python -m venv venv # 6. Activate it # On macOS/Linux: source venv/bin/activate # On Windows: # .\venv\Scripts\activate # 7. Install dependencies pip install -e ".[dev]" # 8. Copy environment file cp .env.example .env # 9. Start infrastructure (optional) docker-compose up -d redis postgres minio ``` ### Running in VS Code **Method 1: Using Run/Debug (F5)** 1. Open `src/geosight/server.py` 2. Press `F5` or click "Run and Debug" 3. Select "Run MCP Server" configuration **Method 2: Using Terminal** ```bash # In VS Code terminal python -m geosight.server ``` **Method 3: Using Tasks** 1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac) 2. Type "Tasks: Run Task" 3. Select "Run MCP Server" ### VS Code Keyboard Shortcuts | Action | Windows/Linux | Mac | |--------|---------------|-----| | Run/Debug | F5 | F5 | | Open Terminal | Ctrl+` | Cmd+` | | Run Task | Ctrl+Shift+P | Cmd+Shift+P | | Format Code | Shift+Alt+F | Shift+Option+F | | Go to Definition | F12 | F12 | | Find All References | Shift+F12 | Shift+F12 | --- ## Option 2: PyCharm ### Setup ```bash # 1. Download PyCharm Community (Free) or Professional # https://www.jetbrains.com/pycharm/ # 2. Open the project folder # 3. PyCharm will detect requirements and offer to: # - Create virtual environment # - Install dependencies # 4. Configure Python interpreter: # Settings → Project → Python Interpreter → Add → Virtualenv ``` ### Running in PyCharm 1. Right-click on `src/geosight/server.py` 2. Select "Run 'server'" 3. Or create a Run Configuration --- ## Option 3: GitHub Codespaces (Cloud) ### Why Use This? - No local setup needed - Works from any browser - Pre-configured environment - Great for collaboration ### Setup 1. Push project to GitHub: ```bash git init git add . git commit -m "Initial commit" git remote add origin https://github.com/yourusername/geosight-mcp.git git push -u origin main ``` 2. On GitHub: - Go to your repository - Click "Code" → "Codespaces" → "Create codespace on main" 3. Wait for environment to build (~2-3 minutes) 4. Run the project: ```bash pip install -e ".[dev]" python -m geosight.server ``` ### Codespace Configuration Create `.devcontainer/devcontainer.json`: ```json { "name": "GeoSight Development", "image": "mcr.microsoft.com/devcontainers/python:3.11", "features": { "ghcr.io/devcontainers/features/docker-in-docker:2": {} }, "postCreateCommand": "pip install -e '.[dev]'", "customizations": { "vscode": { "extensions": [ "ms-python.python", "ms-python.vscode-pylance", "ms-azuretools.vscode-docker" ] } }, "forwardPorts": [8000, 8501, 6379, 5432] } ``` --- ## Option 4: Docker Dev Container ### Why Use This? - Exact same environment everywhere - All dependencies pre-installed - Works with VS Code Remote Containers ### Setup 1. Install "Dev Containers" VS Code extension 2. Create `.devcontainer/devcontainer.json`: ```json { "name": "GeoSight Dev", "dockerComposeFile": "../docker-compose.yml", "service": "geosight", "workspaceFolder": "/app", "customizations": { "vscode": { "extensions": [ "ms-python.python", "ms-python.vscode-pylance" ] } } } ``` 3. In VS Code: - Press `Ctrl+Shift+P` - Select "Dev Containers: Reopen in Container" --- ## Option 5: Google Colab (Quick Testing Only) ### Limitations - Not suitable for full development - No persistent environment - Limited to notebooks - Can't run MCP server properly ### Use For - Quick testing of analysis functions - Demonstrating results - Sharing experiments ### Setup ```python # In Colab notebook # Install dependencies !pip install numpy rasterio geopandas folium httpx # Clone repo !git clone https://github.com/yourusername/geosight-mcp.git %cd geosight-mcp # Test a function import sys sys.path.insert(0, 'src') from geosight.tools.geocoding import get_location_info import asyncio result = await get_location_info(location_name="Mumbai, India") print(result) ``` --- ## Recommended Setup: VS Code + Docker This is the **production-grade setup** I recommend: ```bash # Terminal 1: Start infrastructure docker-compose up -d redis postgres minio # Terminal 2: Run MCP server (for Claude Desktop) source venv/bin/activate python -m geosight.server # Terminal 3: Run dashboard (optional) streamlit run dashboard/app.py ``` ### Directory Structure in VS Code ``` 📁 geosight-mcp ├── 📁 .vscode # VS Code config (auto-created) │ ├── settings.json │ ├── launch.json │ ├── tasks.json │ └── extensions.json ├── 📁 src/geosight # Main source code ├── 📁 tests # Test files ├── 📁 dashboard # Streamlit UI ├── 📁 config # Configuration ├── 📁 scripts # Utility scripts ├── 📁 docs # Documentation ├── 📄 docker-compose.yml ├── 📄 Dockerfile ├── 📄 Makefile ├── 📄 pyproject.toml └── 📄 README.md ``` --- ## Connecting to Claude Desktop After setting up your development environment: ### 1. Find your Python path ```bash # In your activated venv which python # Example output: /Users/you/geosight-mcp/venv/bin/python ``` ### 2. Configure Claude Desktop **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "geosight": { "command": "/Users/you/geosight-mcp/venv/bin/python", "args": ["-m", "geosight.server"], "cwd": "/Users/you/geosight-mcp", "env": { "PYTHONPATH": "/Users/you/geosight-mcp/src" } } } } ``` ### 3. Restart Claude Desktop Completely quit and reopen Claude Desktop. ### 4. Test In Claude Desktop, try: > "Calculate NDVI for Mumbai, India for January 2024" --- ## Troubleshooting ### VS Code: Python interpreter not found ```bash # Ensure venv is created python -m venv venv source venv/bin/activate # In VS Code: Ctrl+Shift+P → "Python: Select Interpreter" # Choose: ./venv/bin/python ``` ### VS Code: Import errors ```bash # Add to settings.json or run: export PYTHONPATH="${PWD}/src:$PYTHONPATH" ``` ### Docker: Permission denied ```bash # Add user to docker group (Linux) sudo usermod -aG docker $USER # Log out and back in ``` ### Claude Desktop: Tools not showing 1. Check config file syntax (valid JSON) 2. Use absolute paths everywhere 3. Check Claude Desktop logs 4. Restart Claude Desktop completely --- ## Summary | Your Situation | Best Choice | |----------------|-------------| | New to development | VS Code (Local) | | Team collaboration | GitHub Codespaces | | Need consistent env | Docker Dev Container | | Professional Python dev | PyCharm | | Quick demo/testing | Google Colab | **My recommendation: Start with VS Code locally.** It's free, powerful, and gives you the best debugging experience for this project.