GeoSight MCP Server

# 🛰️ GeoSight MCP Server - Complete Implementation Guide ## Step-by-Step Implementation Procedure This guide walks you through implementing, testing, and deploying the GeoSight satellite imagery analysis MCP server from scratch. --- ## Phase 1: Environment Setup (30 minutes) ### Step 1.1: System Requirements ```bash # Check Python version (need 3.11+) python --version # Check Docker docker --version docker-compose --version # Check Git git --version ``` ### Step 1.2: Clone and Setup Project ```bash # Clone repository git clone https://github.com/yourusername/geosight-mcp.git cd geosight-mcp # Create virtual environment python -m venv venv # Activate virtual environment # On macOS/Linux: source venv/bin/activate # On Windows: # venv\Scripts\activate # Install dependencies pip install -e ".[dev]" ``` ### Step 1.3: Configure Environment Variables ```bash # Copy example environment file cp .env.example .env # Edit .env file with your credentials nano .env # or use any text editor ``` **Required configurations in `.env`:** ```bash # Minimum required for demo mode ENVIRONMENT=development LOG_LEVEL=DEBUG SERVER_MODE=stdio # For real satellite data (get free account at sentinel-hub.com) SENTINEL_HUB_CLIENT_ID=your-client-id SENTINEL_HUB_CLIENT_SECRET=your-client-secret ``` ### Step 1.4: Start Infrastructure Services ```bash # Start Redis, PostgreSQL, and MinIO docker-compose up -d redis postgres minio # Verify services are running docker-compose ps # Check logs if any issues docker-compose logs redis docker-compose logs postgres ``` --- ## Phase 2: Development & Testing (1-2 hours) ### Step 2.1: Run the MCP Server Locally ```bash # Activate virtual environment if not already source venv/bin/activate # Run the server in stdio mode (for Claude Desktop) python -m geosight.server # Or run in HTTP mode for API access SERVER_MODE=http python -m geosight.server ``` ### Step 2.2: Run Tests ```bash # Run all tests pytest # Run with verbose output pytest -v # Run with coverage report pytest --cov=geosight --cov-report=html # Open coverage report open htmlcov/index.html # macOS # xdg-open htmlcov/index.html # Linux ``` ### Step 2.3: Test Individual Tools Create a test script `test_tools.py`: ```python import asyncio from geosight.tools import ( calculate_ndvi, detect_land_cover, get_location_info, ) async def test_all_tools(): # Test geocoding print("Testing geocoding...") location = await get_location_info(location_name="Mumbai, India") print(f"Location: {location['summary']}\n") # Test NDVI print("Testing NDVI calculation...") ndvi_result = await calculate_ndvi( start_date="2024-01-01", end_date="2024-01-31", location_name="Mumbai, India", radius_km=10, ) print(f"NDVI: {ndvi_result['summary']}\n") # Test Land Cover print("Testing land cover classification...") lc_result = await detect_land_cover( date="2024-01-15", location_name="Mumbai, India", radius_km=10, ) print(f"Land Cover: {lc_result['summary']}\n") print("All tests passed!") if __name__ == "__main__": asyncio.run(test_all_tools()) ``` Run the test: ```bash python test_tools.py ``` ### Step 2.4: Code Quality Checks ```bash # Format code with Black black src/ tests/ # Lint with Ruff ruff check src/ tests/ # Type checking with MyPy mypy src/ # Fix any issues found ruff check src/ --fix ``` --- ## Phase 3: Claude Desktop Integration (15 minutes) ### Step 3.1: Configure Claude Desktop **On macOS:** ```bash # Open Claude Desktop config nano ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` **On Windows:** ```bash # Open Claude Desktop config notepad %APPDATA%\Claude\claude_desktop_config.json ``` **Add this configuration:** ```json { "mcpServers": { "geosight": { "command": "python", "args": ["-m", "geosight.server"], "cwd": "/full/path/to/geosight-mcp", "env": { "SENTINEL_HUB_CLIENT_ID": "your-client-id", "SENTINEL_HUB_CLIENT_SECRET": "your-client-secret" } } } } ``` ### Step 3.2: Restart Claude Desktop 1. Quit Claude Desktop completely 2. Reopen Claude Desktop 3. Look for the 🔧 tools icon - you should see GeoSight tools ### Step 3.3: Test in Claude Desktop Try these prompts in Claude: ``` "Show me vegetation health in the Amazon rainforest for the last month" "Detect land cover types around New Delhi, India" "Find changes in Dubai between 2020 and 2024" "Generate a report on agricultural areas near Punjab, India" ``` --- ## Phase 4: Dashboard Setup (30 minutes) ### Step 4.1: Start the Streamlit Dashboard ```bash # Navigate to dashboard directory cd dashboard # Install dashboard dependencies pip install streamlit pandas numpy plotly folium streamlit-folium httpx pillow # Run the dashboard streamlit run app.py ``` ### Step 4.2: Access the Dashboard Open your browser to: http://localhost:8501 ### Step 4.3: Dashboard Features - **Map View**: Interactive map with location selection - **Vegetation Analysis**: NDVI calculations and visualizations - **Land Cover**: ML-based classification - **Change Detection**: Temporal analysis - **Reports**: Generate PDF/HTML reports --- ## Phase 5: Docker Deployment (30 minutes) ### Step 5.1: Build Docker Images ```bash # Build all services docker-compose build # Or build just the main server docker build -t geosight:latest . ``` ### Step 5.2: Start All Services ```bash # Start everything docker-compose up -d # Check status docker-compose ps # View logs docker-compose logs -f geosight ``` ### Step 5.3: Verify Deployment ```bash # Check health endpoint (if running in HTTP mode) curl http://localhost:8000/health # Access dashboard open http://localhost:8501 # Access MinIO console open http://localhost:9001 # admin/minioadmin # Access Grafana (monitoring) open http://localhost:3000 # admin/admin ``` --- ## Phase 6: Production Deployment (1-2 hours) ### Option A: Railway Deployment ```bash # Install Railway CLI npm install -g @railway/cli # Login to Railway railway login # Initialize project railway init # Link to existing project or create new railway link # Set environment variables railway variables set ENVIRONMENT=production railway variables set SENTINEL_HUB_CLIENT_ID=xxx railway variables set SENTINEL_HUB_CLIENT_SECRET=xxx # Deploy railway up ``` ### Option B: Fly.io Deployment ```bash # Install Fly CLI curl -L https://fly.io/install.sh | sh # Login fly auth login # Launch (creates fly.toml) fly launch # Set secrets fly secrets set SENTINEL_HUB_CLIENT_ID=xxx fly secrets set SENTINEL_HUB_CLIENT_SECRET=xxx # Deploy fly deploy # Check status fly status ``` ### Option C: AWS Deployment ```bash # Build and push to ECR aws ecr get-login-password --region us-east-1 | \ docker login --username AWS --password-stdin $AWS_ACCOUNT.dkr.ecr.us-east-1.amazonaws.com docker build -t geosight:latest . docker tag geosight:latest $AWS_ACCOUNT.dkr.ecr.us-east-1.amazonaws.com/geosight:latest docker push $AWS_ACCOUNT.dkr.ecr.us-east-1.amazonaws.com/geosight:latest # Deploy with ECS (use AWS Console or Terraform) ``` --- ## Phase 7: Monitoring & Maintenance ### Step 7.1: Setup Monitoring ```bash # Start Prometheus and Grafana docker-compose up -d prometheus grafana # Access Grafana open http://localhost:3000 # Default login: admin/admin ``` ### Step 7.2: Import Grafana Dashboard 1. Go to Grafana → Dashboards → Import 2. Upload the dashboard JSON from `config/grafana/dashboards/` ### Step 7.3: Setup Alerts Configure alerts in `config/prometheus/alerts.yml`: ```yaml groups: - name: geosight rules: - alert: HighErrorRate expr: rate(geosight_errors_total[5m]) > 0.1 for: 5m labels: severity: critical annotations: summary: "High error rate detected" ``` ### Step 7.4: Log Management ```bash # View logs docker-compose logs -f geosight # Export logs docker-compose logs geosight > geosight.log # Setup log rotation (in docker-compose.yml) logging: driver: "json-file" options: max-size: "10m" max-file: "3" ``` --- ## Phase 8: Adding Real ML Models (Advanced) ### Step 8.1: Download Pre-trained Weights ```bash # Create weights directory mkdir -p models/weights # Download EuroSAT weights (example) wget -O models/weights/eurosat_resnet50.pth \ https://example.com/eurosat_resnet50.pth # Download YOLOv8 for object detection pip install ultralytics yolo export model=yolov8m.pt format=torchscript mv yolov8m.torchscript models/weights/ ``` ### Step 8.2: Fine-tune Models (Optional) ```python # Example: Fine-tune land cover classifier import torch from torchvision import models, transforms from torch.utils.data import DataLoader # Load EuroSAT dataset # ... training code ... # Save weights torch.save(model.state_dict(), 'models/weights/eurosat_finetuned.pth') ``` ### Step 8.3: Update Model Configuration In `.env`: ```bash MODEL_WEIGHTS_DIR=/app/models/weights INFERENCE_DEVICE=cuda # or cpu, mps MODEL_PRECISION=fp16 # for faster inference ``` --- ## Troubleshooting Guide ### Issue: "Sentinel Hub authentication failed" ```bash # Check credentials echo $SENTINEL_HUB_CLIENT_ID echo $SENTINEL_HUB_CLIENT_SECRET # Test authentication python -c " from sentinelhub import SHConfig config = SHConfig() config.sh_client_id = 'your-id' config.sh_client_secret = 'your-secret' print('Config valid:', config.instance_id) " ``` ### Issue: "Database connection failed" ```bash # Check PostgreSQL is running docker-compose ps postgres # Check connection docker-compose exec postgres psql -U postgres -d geosight -c "SELECT 1" # Reset database docker-compose down -v docker-compose up -d postgres ``` ### Issue: "Redis connection refused" ```bash # Check Redis docker-compose ps redis docker-compose exec redis redis-cli ping ``` ### Issue: "Out of memory during inference" ```bash # Use CPU instead of GPU export INFERENCE_DEVICE=cpu # Reduce batch size in config export MODEL_BATCH_SIZE=1 # Use lower precision export MODEL_PRECISION=int8 ``` ### Issue: "Claude Desktop not seeing tools" 1. Check config file path is correct 2. Ensure Python path is absolute 3. Check for JSON syntax errors 4. Restart Claude Desktop completely 5. Check Claude Desktop logs --- ## Performance Optimization ### Caching Strategy ```python # Enable Redis caching REDIS_URL=redis://localhost:6379/0 CACHE_TTL_SECONDS=3600 CACHE_ENABLED=true ``` ### Parallel Processing ```python # In config CELERY_WORKER_CONCURRENCY=4 MAX_PARALLEL_REQUESTS=10 ``` ### Image Optimization ```python # Reduce resolution for faster processing DEFAULT_RESOLUTION=20 # meters (instead of 10) MAX_IMAGE_SIZE=1024 # pixels ``` --- ## Next Steps 1. ✅ Complete Phase 1-3 for local development 2. ✅ Test all tools in Claude Desktop 3. ✅ Deploy dashboard for demos 4. ✅ Deploy to cloud for production 5. 🔄 Add real ML model weights 6. 🔄 Connect to real Sentinel Hub account 7. 🔄 Build demo case studies 8. 🔄 Create demo video for portfolio --- ## Resources - **Sentinel Hub Documentation**: https://docs.sentinel-hub.com/ - **Planetary Computer**: https://planetarycomputer.microsoft.com/ - **MCP Protocol**: https://modelcontextprotocol.io/ - **EuroSAT Dataset**: https://github.com/phelber/eurosat - **DOTA Dataset**: https://captain-whu.github.io/DOTA/ --- ## Support If you encounter issues: 1. Check the troubleshooting guide above 2. Review logs: `docker-compose logs -f` 3. Open an issue on GitHub 4. Check Anthropic's MCP documentation Good luck with your project! 🚀