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
2025-12-01 01:26:05 +00:00 · 2025-12-01 01:26:05 +00:00 · 5e2f6078a1
commit 5e2f6078a1
parent dda0003226
1 changed files with 581 additions and 0 deletions
--- a/DEVELOPMENT.md
+++ 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 <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