# 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