GeoGuessrMCP/DEVELOPMENT.md

Development Guide

This guide covers local development setup, testing, and debugging the GeoGuessr MCP Server.

Table of Contents

• Development Setup
• Running Locally
• Testing with MCP Inspector
• Testing with Claude Desktop
• Running Tests
• Code Quality
• Debugging
• 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

git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git
cd GeoGuessrMCP

2. Create Virtual Environment

Using uv (recommended):

uv venv
source .venv/bin/activate  # On Linux/macOS
# OR
.venv\Scripts\activate  # On Windows

Using venv:

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):

uv pip install -e ".[dev]"
# OR
pip install -e ".[dev]"

Production dependencies only:

uv pip install -e .
# OR
pip install -e .

4. Configure Environment Variables

cp .env.example .env

Edit .env and configure:

Required for authenticated endpoints:

GEOGUESSR_NCFA_COOKIE=your_cookie_here

Optional development settings:

# 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

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:

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

Or run with npx:

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:

openssl rand -hex 32

Add to .env:

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):

{
  "has_token": false,
  "message": "No authentication cookie set. Use login() or set_ncfa_cookie()."
}

Expected response (authenticated):

{
  "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:

{
  "mcpServers": {
    "geoguessr-local": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

With authentication:

{
  "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

pytest src/tests/unit/ -v

Integration Tests

Requires authentication:

# Set GEOGUESSR_NCFA_COOKIE in .env first
pytest src/tests/integration/ -v

All Tests with Coverage

pytest --cov=src/geoguessr_mcp src/tests/ -v

Coverage Report

pytest --cov=src/geoguessr_mcp --cov-report=html src/tests/
open htmlcov/index.html  # View coverage report

Code Quality

Format Code with Black

black src/ tests/

Configuration: Line length 100 (see pyproject.toml)

Lint with Ruff

ruff check src/ tests/

Auto-fix:

ruff check --fix src/ tests/

Type Check with MyPy

mypy src/

Pre-commit Hooks

Install pre-commit hooks to automatically run checks:

pre-commit install

This will run Black, Ruff, and MyPy before each commit.

Debugging

Enable Debug Mode

Set in .env:

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:

# 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:

# 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:

ls -la data/schemas/
cat data/schemas/schemas.json | python -m json.tool

Force schema refresh:

rm -rf data/schemas/*
# Restart server - schemas will be regenerated

View Server Logs

Real-time logs:

tail -f server.log  # If using file logging

Docker logs:

docker compose logs -f geoguessr-mcp

Common Issues

Issue: Module not found errors

Solution:

# Ensure you're in the project root
pip install -e ".[dev]"

Issue: Permission denied on schema cache

Solution:

mkdir -p data/schemas
chmod 755 data/schemas

Or use a different path in .env:

SCHEMA_CACHE_DIR=/tmp/geoguessr-schemas

Issue: Port 8000 already in use

Solution:

# Use different port
echo "MCP_PORT=8001" >> .env

Or kill the process using port 8000:

# 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:

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
• FastMCP Guide
• MCP Inspector
• GeoGuessr API (unofficial)
• Starlette 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