From 5e2f6078a18beecd922dcd20b456f27265f7cf1f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 1 Dec 2025 01:26:05 +0000 Subject: [PATCH] Add comprehensive development guide with MCP Inspector instructions Created DEVELOPMENT.md with detailed instructions for: - Local development setup - Testing with MCP Inspector (with/without auth) - Testing with Claude Desktop - Running tests and code quality checks - Debugging common issues - Troubleshooting connection problems Key sections: - Complete MCP Inspector setup guide - Authentication configuration - Debug logging setup - Common error fixes (CORS, auth, sessions) - Project structure overview --- DEVELOPMENT.md | 581 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 581 insertions(+) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..58ab08f --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,581 @@ +# Development Guide + +This guide covers local development setup, testing, and debugging the GeoGuessr MCP Server. + +## Table of Contents + +- [Development Setup](#development-setup) +- [Running Locally](#running-locally) +- [Testing with MCP Inspector](#testing-with-mcp-inspector) +- [Testing with Claude Desktop](#testing-with-claude-desktop) +- [Running Tests](#running-tests) +- [Code Quality](#code-quality) +- [Debugging](#debugging) +- [Common Issues](#common-issues) + +## Development Setup + +### Prerequisites + +- Python 3.11 or higher +- `uv` (recommended) or `pip` +- Git +- A GeoGuessr account (for authenticated endpoints) + +### 1. Clone the Repository + +```bash +git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git +cd GeoGuessrMCP +``` + +### 2. Create Virtual Environment + +**Using uv (recommended):** +```bash +uv venv +source .venv/bin/activate # On Linux/macOS +# OR +.venv\Scripts\activate # On Windows +``` + +**Using venv:** +```bash +python -m venv .venv +source .venv/bin/activate # On Linux/macOS +# OR +.venv\Scripts\activate # On Windows +``` + +### 3. Install Dependencies + +**Development dependencies (includes testing tools):** +```bash +uv pip install -e ".[dev]" +# OR +pip install -e ".[dev]" +``` + +**Production dependencies only:** +```bash +uv pip install -e . +# OR +pip install -e . +``` + +### 4. Configure Environment Variables + +```bash +cp .env.example .env +``` + +Edit `.env` and configure: + +**Required for authenticated endpoints:** +```bash +GEOGUESSR_NCFA_COOKIE=your_cookie_here +``` + +**Optional development settings:** +```bash +# Disable authentication for local testing +MCP_AUTH_ENABLED=false + +# Enable debug logging +LOG_LEVEL=DEBUG + +# Local schema cache +SCHEMA_CACHE_DIR=./data/schemas + +# Server configuration +MCP_HOST=0.0.0.0 +MCP_PORT=8000 +MCP_TRANSPORT=streamable-http +``` + +## Running Locally + +### Start the Server + +```bash +python -m src.geoguessr_mcp.main +``` + +The server will start on `http://0.0.0.0:8000` by default. + +**Expected output:** +``` +INFO - Starting GeoGuessr MCP Server on 0.0.0.0:8000 with streamable-http transport +INFO - MCP server authentication is DISABLED - server is publicly accessible +INFO - Started server process [12345] +INFO - Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) +``` + +### Enable Debug Logging + +Set `LOG_LEVEL=DEBUG` in `.env` to see detailed request/response logs: + +```bash +LOG_LEVEL=DEBUG +``` + +This enables: +- Request method and path logging +- Request headers logging +- Authentication flow details +- MCP protocol messages +- Schema detection changes + +## Testing with MCP Inspector + +**MCP Inspector** is a web-based tool for testing MCP servers interactively. It's the recommended way to develop and debug MCP servers. + +### 1. Install MCP Inspector + +Download from: [https://github.com/modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector) + +Or run with npx: +```bash +npx @modelcontextprotocol/inspector +``` + +MCP Inspector will start on `http://localhost:6274` by default. + +### 2. Configure Connection + +#### Without Authentication + +In MCP Inspector: +1. Select **"Server-Sent Events (SSE)"** or **"Streamable HTTP"** transport +2. Set URL: `http://localhost:8000/mcp` +3. Click **"Connect"** + +#### With Authentication + +In MCP Inspector: +1. Select **"Streamable HTTP"** transport +2. Set URL: `http://localhost:8000/mcp` +3. Click **"Custom Headers"** +4. Add header: + - **Name:** `Authorization` + - **Value:** `Bearer YOUR_API_KEY` +5. Click **"Connect"** + +**Generate API key:** +```bash +openssl rand -hex 32 +``` + +Add to `.env`: +```bash +MCP_AUTH_ENABLED=true +MCP_API_KEYS=your-generated-key-here +``` + +### 3. Test the Connection + +After connecting, you should see: +- ✅ **Connection Status:** Connected +- ✅ **Protocol Version:** 2025-06-18 +- ✅ **Server Info:** GeoGuessr MCP v1.22.0 + +### 4. Explore Available Tools + +In the **"Tools"** tab, you should see: + +**Authentication Tools:** +- `login(email, password)` - Login with GeoGuessr credentials +- `logout()` - Logout current session +- `set_ncfa_cookie(cookie)` - Set authentication cookie manually +- `get_current_session_token()` - Get current session status + +**Profile Tools:** +- `get_profile(username)` - Get user profile +- `get_current_user_profile()` - Get your profile +- `get_user_stats(user_id)` - Get detailed stats + +**Game Tools:** +- `get_game(game_id)` - Get game details +- `get_recent_games(count)` - Get recent games +- `get_activity_feed(count)` - Get activity feed + +**Analysis Tools:** +- `get_performance_summary()` - Comprehensive performance overview +- `analyze_recent_games(count)` - Analyze recent gameplay +- `get_strategy_recommendations()` - Get improvement tips + +**Monitoring Tools:** +- `check_api_status()` - Check API endpoint availability +- `list_available_endpoints()` - List all monitored endpoints +- `get_endpoint_schema(path)` - Get schema for specific endpoint +- `explore_endpoint(path)` - Manually explore new endpoints + +### 5. Test a Tool + +Try calling a simple tool: + +1. Select `get_current_session_token()` from the tools list +2. Click **"Call Tool"** +3. Check the response + +**Expected response (not authenticated):** +```json +{ + "has_token": false, + "message": "No authentication cookie set. Use login() or set_ncfa_cookie()." +} +``` + +**Expected response (authenticated):** +```json +{ + "has_token": true, + "user_id": "your-user-id", + "username": "your-username" +} +``` + +### 6. Debugging Connection Issues + +If you see errors in MCP Inspector, check the server logs: + +**Common issues:** + +**❌ OPTIONS 405 Method Not Allowed** +- **Cause:** CORS middleware not configured +- **Fix:** Ensure middleware is properly applied (should be fixed in latest version) + +**❌ POST 401 Unauthorized** +- **Cause:** Missing or invalid API key +- **Fix:** Add correct `Authorization: Bearer YOUR_KEY` header + +**❌ POST 400 Bad Request** +- **Cause:** Session ID not maintained (CORS headers not exposed) +- **Fix:** Ensure `expose_headers` includes `mcp-session-id` (should be fixed in latest version) + +**❌ Connection timeout** +- **Cause:** Server not running or firewall blocking +- **Fix:** Check server is running on `localhost:8000` + +## Testing with Claude Desktop + +For testing the full MCP integration with Claude Desktop: + +### 1. Configure Claude Desktop + +**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` +**Windows:** `%APPDATA%\Claude\claude_desktop_config.json` + +**Without authentication:** +```json +{ + "mcpServers": { + "geoguessr-local": { + "type": "streamable-http", + "url": "http://localhost:8000/mcp" + } + } +} +``` + +**With authentication:** +```json +{ + "mcpServers": { + "geoguessr-local": { + "type": "streamable-http", + "url": "http://localhost:8000/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` + +### 2. Restart Claude Desktop + +After modifying the config, completely quit and restart Claude Desktop. + +### 3. Test in Claude + +In a new conversation: + +``` +Can you check my GeoGuessr profile? +``` + +Claude should automatically use the MCP server tools to fetch your profile. + +## Running Tests + +### Unit Tests + +```bash +pytest src/tests/unit/ -v +``` + +### Integration Tests + +**Requires authentication:** +```bash +# Set GEOGUESSR_NCFA_COOKIE in .env first +pytest src/tests/integration/ -v +``` + +### All Tests with Coverage + +```bash +pytest --cov=src/geoguessr_mcp src/tests/ -v +``` + +### Coverage Report + +```bash +pytest --cov=src/geoguessr_mcp --cov-report=html src/tests/ +open htmlcov/index.html # View coverage report +``` + +## Code Quality + +### Format Code with Black + +```bash +black src/ tests/ +``` + +**Configuration:** Line length 100 (see `pyproject.toml`) + +### Lint with Ruff + +```bash +ruff check src/ tests/ +``` + +**Auto-fix:** +```bash +ruff check --fix src/ tests/ +``` + +### Type Check with MyPy + +```bash +mypy src/ +``` + +### Pre-commit Hooks + +Install pre-commit hooks to automatically run checks: + +```bash +pre-commit install +``` + +This will run Black, Ruff, and MyPy before each commit. + +## Debugging + +### Enable Debug Mode + +Set in `.env`: +```bash +LOG_LEVEL=DEBUG +``` + +Restart the server to see: +- All HTTP requests with headers +- Authentication flow +- MCP protocol messages +- Schema detection and changes + +### Debug Authentication + +Check if your GeoGuessr cookie is valid: + +```bash +# In Python console +from src.geoguessr_mcp.auth import session_manager +import asyncio + +async def test(): + token = session_manager.get_current_session_token() + print(f"Token: {token}") + +asyncio.run(test()) +``` + +### Debug API Calls + +Test API endpoints directly: + +```bash +# Install httpx +pip install httpx + +# Test endpoint +python -c " +import httpx +import asyncio + +async def test(): + async with httpx.AsyncClient() as client: + response = await client.get( + 'https://www.geoguessr.com/api/v3/profiles', + cookies={'_ncfa': 'YOUR_COOKIE'} + ) + print(response.json()) + +asyncio.run(test()) +" +``` + +### Debug Schema Detection + +Check schema cache: + +```bash +ls -la data/schemas/ +cat data/schemas/schemas.json | python -m json.tool +``` + +Force schema refresh: + +```bash +rm -rf data/schemas/* +# Restart server - schemas will be regenerated +``` + +### View Server Logs + +**Real-time logs:** +```bash +tail -f server.log # If using file logging +``` + +**Docker logs:** +```bash +docker compose logs -f geoguessr-mcp +``` + +## Common Issues + +### Issue: Module not found errors + +**Solution:** +```bash +# Ensure you're in the project root +pip install -e ".[dev]" +``` + +### Issue: Permission denied on schema cache + +**Solution:** +```bash +mkdir -p data/schemas +chmod 755 data/schemas +``` + +Or use a different path in `.env`: +```bash +SCHEMA_CACHE_DIR=/tmp/geoguessr-schemas +``` + +### Issue: Port 8000 already in use + +**Solution:** +```bash +# Use different port +echo "MCP_PORT=8001" >> .env +``` + +Or kill the process using port 8000: +```bash +# Linux/macOS +lsof -ti:8000 | xargs kill -9 + +# Windows +netstat -ano | findstr :8000 +taskkill /PID /F +``` + +### Issue: CORS errors in browser + +**Solution:** +Ensure CORS middleware is properly configured with `expose_headers`: +```python +app.add_middleware( + CORSMiddleware, + allow_origins=["*"], + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], + expose_headers=["mcp-session-id", "mcp-protocol-version"], +) +``` + +### Issue: Session not maintained (400 errors) + +**Symptoms:** +- First POST succeeds (200 OK) +- Second POST fails (400 Bad Request) +- Logs show new session created each time + +**Solution:** +The `mcp-session-id` header must be exposed via CORS (fixed in latest version). + +Check server logs for: +``` +expose_headers=["mcp-session-id", "mcp-protocol-version"] +``` + +## Contributing + +### Development Workflow + +1. Create a feature branch +2. Make changes +3. Run tests: `pytest` +4. Run code quality checks: `black`, `ruff`, `mypy` +5. Commit with descriptive message +6. Push and create pull request + +### Code Style + +- **Formatting:** Black (line length 100) +- **Linting:** Ruff +- **Type hints:** Required for all functions +- **Docstrings:** Google style for public APIs +- **Tests:** Required for new features + +### Project Structure + +``` +src/geoguessr_mcp/ +├── api/ # GeoGuessr API client +├── auth/ # Authentication & session management +├── middleware/ # MCP server middleware (auth, CORS) +├── models/ # Data models (Profile, Stats, Games) +├── monitoring/ # API monitoring & schema detection +│ ├── endpoint/ # Endpoint monitoring +│ └── schema/ # Schema detection & registry +├── services/ # Business logic services +├── tools/ # MCP tool definitions +├── config.py # Configuration management +└── main.py # Application entry point +``` + +## Resources + +- [MCP Documentation](https://modelcontextprotocol.io/) +- [FastMCP Guide](https://github.com/jlowin/fastmcp) +- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) +- [GeoGuessr API (unofficial)](https://www.geoguessr.com/api) +- [Starlette Middleware](https://www.starlette.io/middleware/) + +## Support + +For issues and questions: +- Check this guide first +- Review server logs with `LOG_LEVEL=DEBUG` +- Check existing issues on GitHub +- Create a new issue with logs and reproduction steps