Add MCP server authentication and update Docker configuration

This commit implements several key improvements to the GeoGuessr MCP server:

## MCP Server Authentication
- Add Bearer token authentication for MCP server access control
- New middleware in src/geoguessr_mcp/middleware/auth.py
- Configuration via MCP_AUTH_ENABLED and MCP_API_KEYS environment variables
- Support for multiple API keys (comma-separated)
- Optional authentication - can be disabled for trusted deployments
- Clients connect using Authorization: Bearer YOUR_API_KEY header

## Docker Configuration Updates
- Update to use official pre-built image: nyxiumyuuki/geoguessr-mcp:latest
- Remove DOCKER_USERNAME and IMAGE_TAG from environment variables
- Simplify docker-compose.yml and docker-compose.prod.yml
- Remove healthcheck configuration (not necessary for the deployment)

## Deployment Improvements
- Move deploy.sh to scripts/deploy.sh for better organization
- Update deploy.sh to use official Docker image
- Add authentication validation in deployment script
- Improve deployment logging and error messages

## Documentation Updates
- Update README.md with authentication configuration examples
- Add MCP server authentication section with setup instructions
- Update environment variables table
- Simplify deployment instructions
- Update CLAUDE.md with new authentication architecture
- Add .env.example configuration for MCP authentication

## Technical Details
- Authentication middleware integrates with FastMCP's Starlette ASGI app
- Middleware validates Bearer tokens on all requests except /health
- Logs authentication attempts and failures
- Returns proper 401/403 HTTP status codes
- Validates configuration on startup to prevent misconfiguration

Resolves TODO items:
- [x] Fix Docker username in compose files and env vars
- [x] Add authentication to MCP server to allow access only to specific users
This commit is contained in:
Claude 2025-11-29 22:16:01 +00:00
parent 52d2f864a8
commit 07b1cb84b2
No known key found for this signature in database
10 changed files with 346 additions and 151 deletions

View file

@ -12,7 +12,8 @@ This document provides context for AI assistants (like Claude) working on the Ge
geoguessr-mcp/
├── src/geoguessr_mcp/
│ ├── api/ # GeoGuessr API client and response handling
│ ├── auth/ # Authentication management
│ ├── 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
@ -21,6 +22,8 @@ geoguessr-mcp/
│ ├── 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
@ -54,9 +57,19 @@ Tools are organized by domain:
Each tool returns a `DynamicResponse` which includes both the data and schema information.
### 3. Authentication Flow
### 3. Authentication Systems
The server supports three authentication methods:
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
@ -65,6 +78,10 @@ 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:
@ -76,9 +93,19 @@ The Dockerfile uses a multi-stage approach:
### Deployment Options
1. **Local Build**: `docker compose up -d --build`
2. **Docker Hub**: Build, tag, push, then pull on VPS
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