yvachot/GeoGuessrMCP
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add multi-user support - each API key gets own GeoGuessr session

Browse source 
Implements comprehensive multi-user support allowing multiple users to
access the same MCP server instance with their own independent GeoGuessr
accounts. Each API key now has its own session storage and context.

## Multi-User Architecture

### New Components

**User Context System** (src/geoguessr_mcp/auth/user_context.py):
- UserContext dataclass tracks API key and associated GeoGuessr session
- Properties for user_id, username, ncfa_cookie, is_authenticated
- Automatically attached to each request

**Multi-User Session Manager** (src/geoguessr_mcp/auth/multi_user_session.py):
- MultiUserSessionManager manages separate SessionManager per API key
- Maps API keys to their own GeoGuessr sessions
- Methods: get_user_context, login_user, logout_user, set_user_cookie
- Global instance: multi_user_session_manager

**Request Context** (src/geoguessr_mcp/auth/request_context.py):
- ContextVar for accessing current user context in tools
- Functions: get_current_user_context, require_user_context, set_current_user_context
- Enables tools to access user-specific sessions automatically

### Updated Components

**Authentication Middleware** (src/geoguessr_mcp/middleware/auth.py):
- Now creates user context for each authenticated request
- Attaches context to both request.state and ContextVar
- Supports both authenticated and unauthenticated modes
- Default user context created when auth is disabled

**Authentication Tools** (src/geoguessr_mcp/tools/auth_tools.py):
- Completely rewritten for multi-user support
- login(): Creates session tied to caller's API key
- logout(): Logs out only the calling user's session
- set_ncfa_cookie(): Sets cookie for calling user only
- get_auth_status(): Returns calling user's auth status
- All tools use get_current_user_context() automatically

**GeoGuessr Client** (src/geoguessr_mcp/api/geoguessr_client.py):
- _get_authenticated_client() checks user context first
- Falls back to session_manager for backward compatibility
- Automatically uses caller's session when available
- No changes needed in services (profile, game, analysis)

## How It Works

1. User connects with API key in Authorization header
2. Middleware validates API key and creates/retrieves UserContext
3. UserContext attached to request.state and ContextVar
4. Tools call get_current_user_context() to access caller's session
5. Client automatically uses correct session for API calls
6. Each user's session is completely isolated

## Usage Example

```bash
# Configure multiple API keys
MCP_AUTH_ENABLED=true
MCP_API_KEYS=alice_key,bob_key,charlie_key

# Alice connects with: Authorization: Bearer alice_key
# Bob connects with: Authorization: Bearer bob_key
# Each can login to their own GeoGuessr account
# Sessions are completely independent
```

## Key Features

- **Zero Interference**: Users don't affect each other's sessions
- **Automatic Routing**: Requests automatically use correct user's session
- **Hot Reload**: Add new API keys and restart in ~2-3 seconds
- **Backward Compatible**: Still works with single-user mode
- **Fallback Support**: GEOGUESSR_NCFA_COOKIE still works as default

## Documentation Updates

- README.md: Added Multi-User Mode section with examples
- README.md: Updated authentication section with multi-user details
- README.md: Added "Adding New Users" workflow
- Key Features section now highlights multi-user support

## Technical Details

- Uses Python ContextVar for request-scoped user context
- Each API key gets its own SessionManager instance
- Session storage is in-memory (persists across requests, not restarts)
- Default cookie (GEOGUESSR_NCFA_COOKIE) used as fallback for all users
- Fully async/await compatible throughout
This commit is contained in:
Claude 2025-11-29 22:30:55 +00:00
parent 07b1cb84b2
commit 80ed791b01
No known key found for this signature in database
8 changed files with 551 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

91
README.md
View file

@ -12,6 +12,12 @@ A Model Context Protocol (MCP) server for analyzing GeoGuessr game statistics wi
## 🌟 Key Features
### Multi-User Support
- **Independent Sessions**: Each API key gets its own GeoGuessr session
- **Multiple Accounts**: Different users can access their own GeoGuessr accounts
- **Single Server**: No need to deploy separate instances per user
- **Automatic Context**: User sessions are automatically managed per request
### Dynamic API Monitoring
- **Automatic endpoint discovery**: Monitors GeoGuessr API endpoints daily
- **Schema change detection**: Automatically detects when API response formats change
@ -101,12 +107,14 @@ Add to your Claude Desktop configuration:
## 🔐 Authentication
The server supports two types of authentication:
The server supports two types of authentication with **multi-user support**:
### MCP Server Authentication (Controls Access to the MCP Server)
Secures who can connect to your MCP server. When enabled, clients must provide a valid API key.
**Multi-User Support:** Each API key can have its own GeoGuessr session, allowing multiple users to use the same MCP server instance with their own accounts!
**Enable in `.env`:**
```bash
MCP_AUTH_ENABLED=true
@ -133,9 +141,19 @@ openssl rand -hex 32
}
```
**Multi-User Example:**
```bash
# Give each user their own API key
MCP_API_KEYS=alice_key_abc123,bob_key_def456,charlie_key_ghi789
# Alice connects with Authorization: Bearer alice_key_abc123
# Bob connects with Authorization: Bearer bob_key_def456
# Each can login to their own GeoGuessr account!
```
### GeoGuessr API Authentication (Access GeoGuessr Data)
The server also needs authentication to access GeoGuessr's API. Multiple methods supported:
The server also needs authentication to access GeoGuessr's API. In multi-user mode, **each API key holder can login to their own GeoGuessr account:**
### Option 1: Login via Claude (Recommended)
Simply ask Claude:
@ -150,6 +168,75 @@ GEOGUESSR_NCFA_COOKIE=your_cookie_value_here
### Option 3: Manual Cookie
Use the `set_ncfa_cookie` tool with a cookie extracted from your browser.
## 👥 Multi-User Mode
The server supports multiple users, each with their own GeoGuessr account, using a single MCP server instance.
### How It Works
1. **API Keys**: Each user gets a unique API key
2. **Independent Sessions**: Each API key has its own GeoGuessr login session
3. **Automatic Routing**: The server automatically routes requests to the correct user's session
4. **No Interference**: Users don't affect each other's sessions
### Setup Example
**1. Configure Multiple API Keys:**
```bash
# .env file
MCP_AUTH_ENABLED=true
MCP_API_KEYS=alice_key,bob_key,charlie_key
```
**2. Restart Server:**
```bash
# Development
docker compose restart
# Production
docker compose -f docker-compose.prod.yml restart
```
**3. Each User Connects:**
```json
// Alice's Claude Desktop config
{
"mcpServers": {
"geoguessr": {
"url": "https://your-domain.com/mcp",
"headers": {"Authorization": "Bearer alice_key"}
}
}
}
// Bob's Claude Desktop config
{
"mcpServers": {
"geoguessr": {
"url": "https://your-domain.com/mcp",
"headers": {"Authorization": "Bearer bob_key"}
}
}
}
```
**4. Each User Logs In:**
- Alice asks Claude: "Login to GeoGuessr with my credentials"
- Bob asks Claude: "Login to GeoGuessr with my credentials"
- Sessions are completely independent!
### Adding New Users
To add a new user to an existing deployment:
1. Edit `.env` and add the new API key to `MCP_API_KEYS`
2. Restart the server: `docker compose restart`
3. Share the new API key with the user
4. User configures their Claude Desktop with the API key
5. User logs in to their GeoGuessr account via Claude
**The server restarts in ~2-3 seconds** and all existing users remain logged in!
## 📊 Available Tools
### Authentication