GeoGuessrMCP/CLAUDE.md

# CLAUDE.md - Development Guide for AI Assistants

This document provides context for AI assistants (like Claude) working on the GeoGuessr MCP Server project.

## Project Overview

**GeoGuessr MCP Server** is a Model Context Protocol (MCP) server that provides Claude with tools to analyze GeoGuessr game statistics. The server features automatic API monitoring and dynamic schema adaptation to handle API changes gracefully.

### Key Architecture Components

```
geoguessr-mcp/
├── src/geoguessr_mcp/
│   ├── api/              # GeoGuessr API client and response handling
│   ├── auth/             # GeoGuessr authentication management
│   ├── middleware/       # MCP server authentication middleware
│   ├── models/           # Data models (Profile, Stats, Games, etc.)
│   ├── monitoring/       # Dynamic schema detection and API monitoring
│   │   ├── endpoint/     # Endpoint monitoring logic
│   │   └── schema/       # Schema detection and registry
│   ├── services/         # Business logic services
│   ├── tools/            # MCP tool definitions
│   ├── config.py         # Configuration and settings
│   └── main.py           # Application entry point
├── scripts/              # Deployment scripts
│   └── deploy.sh         # Automated production deployment
├── tests/                # Unit and integration tests
├── Dockerfile            # Container definition
├── docker-compose.yml    # Development deployment
└── docker-compose.prod.yml # Production deployment with nginx
```

## Core Concepts

### 1. Dynamic Schema System

The server automatically adapts to GeoGuessr API changes:

- **Schema Detection**: Analyzes API responses to detect field types, structure, and nesting
- **Change Detection**: Uses hash-based comparison to identify schema modifications
- **Persistence**: Caches schemas to disk for survival across restarts
- **Monitoring**: Runs periodic checks (every 24 hours by default) on all known endpoints

**Key Files**:
- `src/geoguessr_mcp/monitoring/schema/schema_detector.py` - Analyzes response structure
- `src/geoguessr_mcp/monitoring/schema/schema_registry.py` - Manages schema storage
- `src/geoguessr_mcp/monitoring/endpoint/endpoint_monitor.py` - Periodic monitoring

### 2. MCP Tool Architecture

Tools are organized by domain:
- **auth_tools.py** - Authentication (login, logout, cookie management)
- **profile_tools.py** - User profiles and statistics
- **game_tools.py** - Game history and details
- **analysis_tools.py** - Performance analysis and recommendations
- **monitoring_tools.py** - API health and endpoint exploration

Each tool returns a `DynamicResponse` which includes both the data and schema information.

### 3. Authentication Systems

The server has two authentication layers:

#### MCP Server Authentication (Access Control)
Controls who can connect to the MCP server:
- **Bearer Token**: API key-based authentication via `Authorization` header
- **Configuration**: `MCP_AUTH_ENABLED` and `MCP_API_KEYS` environment variables
- **Middleware**: `src/geoguessr_mcp/middleware/auth.py` - Validates API keys
- **Optional**: Can be disabled for local/trusted deployments

#### GeoGuessr API Authentication (Data Access)
The server supports three methods to access GeoGuessr's API:
1. **Environment variable**: `GEOGUESSR_NCFA_COOKIE` in .env
2. **Login tool**: Email/password authentication via MCP
3. **Manual cookie**: Direct cookie setting via tool

Session state is managed in `src/geoguessr_mcp/auth/session.py`.

## Docker Deployment

### Official Docker Image

The server is available as a pre-built image: **`nyxiumyuuki/geoguessr-mcp:latest`**

### Build Process

The Dockerfile uses a multi-stage approach:
1. Install dependencies from `pyproject.toml` using `uv` for speed
2. Copy source code
3. Run the server via `python -m geoguessr_mcp.main`

**Important**: The Dockerfile does NOT use a separate `requirements.txt`. It installs directly from `pyproject.toml`.

### Deployment Options

1. **Pre-built Image**: `docker compose up -d` (uses nyxiumyuuki/geoguessr-mcp:latest)
2. **Local Build**: Uncomment build section in docker-compose.yml
3. **Production**: Use `docker-compose.prod.yml` with nginx reverse proxy
4. **Automated**: Use `./scripts/deploy.sh` for production deployment

### MCP Server Authentication Configuration

The server supports optional Bearer token authentication:
- Set `MCP_AUTH_ENABLED=true` to enable
- Set `MCP_API_KEYS=key1,key2,key3` for comma-separated keys
- Generate secure keys with `openssl rand -hex 32`
- Clients connect with `Authorization: Bearer YOUR_API_KEY` header
- Middleware is in `src/geoguessr_mcp/middleware/auth.py`

### Monitoring Configuration

Monitoring runs every 24 hours by default:
- Set `MONITORING_ENABLED=true` to enable
- Set `MONITORING_INTERVAL_HOURS=24` for interval
- Schemas are persisted in `/app/data/schemas` volume

## Development Workflow

### Running Tests

```bash
# Unit tests
pytest tests/unit/ -v

# Integration tests (requires auth)
pytest tests/integration/ -v

# With coverage
pytest --cov=src/geoguessr_mcp tests/
```

### Local Development

```bash
# Install dependencies
pip install -e ".[dev]"

# Run server locally
python -m geoguessr_mcp.main

# Or use the entry point
geoguessr-mcp
```

### Code Quality

- **Formatter**: Black (line length 100)
- **Linter**: Ruff
- **Type Checker**: MyPy (strict mode)

Run checks:
```bash
black src/ tests/
ruff check src/ tests/
mypy src/
```

## Common Tasks

### Adding a New Tool

1. Create tool function in appropriate `tools/*.py` file
2. Use `@mcp.tool()` decorator
3. Return `DynamicResponse` or structured data
4. Add to tool registration in `__init__.py`
5. Write unit tests

Example:
```python
@mcp.tool()
async def my_new_tool(param: str) -> str:
    """Tool description for Claude."""
    # Implementation
    return result
```

### Adding a New Endpoint to Monitor

1. Add endpoint definition to `MONITORED_ENDPOINTS` in `endpoint_monitor.py`
2. Specify path, method, params, and description
3. Schema detection happens automatically

Example:
```python
EndpointDefinition(
    path="/v3/profiles/new-data",
    description="New profile data endpoint",
)
```

### Updating Configuration

Configuration is managed via environment variables in `config.py`:
- Add new setting to `Settings` dataclass
- Use `field(default_factory=lambda: os.getenv(...))` pattern
- Document in README.md environment variables section

## Testing Strategy

### Unit Tests
- Mock external API calls using `respx`
- Test each component in isolation
- Located in `tests/unit/`

### Integration Tests
- Use fixtures from `tests/conftest.py`
- Mock authentication for CI/CD
- Test full request/response flows
- Located in `tests/integration/`

### Fixtures
- `mock_auth_session` - Provides authenticated session
- `mock_http_client` - Mocked httpx client
- `sample_*` - Sample API responses

## Key Dependencies

- **mcp[cli]** - Model Context Protocol framework
- **httpx** - Async HTTP client for API calls
- **uvicorn** - ASGI server
- **starlette** - Web framework (used by FastMCP)
- **python-dotenv** - Environment variable management

## Troubleshooting

### Common Issues

1. **"server.py not found"**: The entry point is `main.py`, not `server.py`
2. **Schema not persisting**: Check volume mount for `/app/data/schemas`
3. **Monitoring not running**: Verify `MONITORING_ENABLED=true` and check logs
4. **Auth failures**: Ensure valid NCFA cookie or use login tool

### Debugging

Enable debug logging:
```bash
LOG_LEVEL=DEBUG docker compose up
```

Check monitoring status via tool:
```python
# In Claude
check_api_status()
```

## CI/CD Considerations

### Building for Production

```bash
# Multi-architecture build
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t username/geoguessr-mcp:latest \
  --push .

# Single architecture
docker build -t username/geoguessr-mcp:latest .
docker push username/geoguessr-mcp:latest
```

### Environment Variables for Deployment

Required:
- `GEOGUESSR_NCFA_COOKIE` - For authenticated endpoints

Optional:
- `MONITORING_INTERVAL_HOURS` - Default: 24
- `LOG_LEVEL` - Default: INFO
- `MCP_PORT` - Default: 8000

## Schema Registry Details

### Schema Hash Computation

Schemas are identified by a hash of:
- Field names and types
- Nested structure
- Array element types
- Null/undefined handling

### Schema Change Detection

When a schema changes:
1. New hash is computed
2. Comparison with previous hash
3. If different, `schema_changed` flag is set
4. New schema is persisted to disk
5. Monitoring result includes change notification

### Schema Persistence Format

Schemas are stored as JSON in `SCHEMA_CACHE_DIR`:
```json
{
  "endpoint": "/v3/profiles",
  "schema_hash": "abc123...",
  "fields": [...],
  "last_updated": "2025-11-29T...",
  "http_status": 200
}
```

## API Monitoring System

### Monitored Endpoints

Currently monitoring ~15 endpoints:
- Profile & Stats (v3, v4)
- Games & Social (feed, friends, badges)
- Competitive (seasons)
- Explorer & Objectives
- Challenges (daily)

### Monitoring Loop

1. Every 24 hours (configurable)
2. Checks each endpoint sequentially
3. 0.5s delay between requests (rate limiting)
4. Updates schema registry on changes
5. Logs availability and response times
6. Generates monitoring report

### Monitoring Tools

Users can:
- `check_api_status()` - Get current status of all endpoints
- `get_endpoint_schema(path)` - Get schema for specific endpoint
- `list_available_endpoints()` - List all known endpoints
- `explore_endpoint(path)` - Manually check a new endpoint

## Best Practices

1. **Always use DynamicResponse** for tools that return API data
2. **Mock authentication** in tests using fixtures
3. **Keep schemas generic** - don't hardcode field expectations
4. **Log schema changes** at INFO level for visibility
5. **Use async/await** consistently throughout the codebase
6. **Handle rate limiting** with delays between requests
7. **Validate configuration** in Settings.__post_init__
8. **Document tools** with clear docstrings for Claude

## Future Enhancements

Potential areas for improvement:
- [ ] Add metrics collection (Prometheus/Grafana)
- [ ] Implement rate limiting middleware
- [ ] Add caching layer for frequently accessed data
- [ ] Support for webhooks/real-time updates
- [ ] Advanced analytics and ML-based recommendations
- [ ] Multi-user support with session management
- [ ] GraphQL endpoint for flexible queries

## Resources

- [MCP Documentation](https://modelcontextprotocol.io/)
- [FastMCP Guide](https://github.com/jlowin/fastmcp)
- [GeoGuessr API (unofficial)](https://www.geoguessr.com/api)
- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)

---

**Last Updated**: 2025-11-29
**Maintainer**: See pyproject.toml for author information