Remove DEVELOPMENT.md; update .gitignore to include additional ignored files; streamline and condense README.md.
This commit is contained in:
Yûki VACHOT
parent
1976a67a2a
commit
f6226f51e4
3 changed files with 201 additions and 641 deletions
422
README.md
422
README.md
|
|
@ -1,167 +1,53 @@
|
|||
# GeoGuessr MCP Server
|
||||
|
||||
A Model Context Protocol (MCP) server for analyzing your GeoGuessr account data. This server allows Claude AI to access and analyze your GeoGuessr statistics, game history, achievements, and more.
|
||||
A Model Context Protocol (MCP) server for analyzing GeoGuessr game statistics with **automatic API monitoring** and **dynamic schema adaptation**.
|
||||
|
||||
## Authentication Options
|
||||
## 🌟 Key Features
|
||||
|
||||
The server supports **three authentication methods**:
|
||||
### Dynamic API Monitoring
|
||||
- **Automatic endpoint discovery**: Monitors GeoGuessr API endpoints daily
|
||||
- **Schema change detection**: Automatically detects when API response formats change
|
||||
- **Self-adapting**: Updates internal data models based on actual API responses
|
||||
- **No hardcoded assumptions**: Works even when GeoGuessr changes their API
|
||||
|
||||
1. **Login with credentials** (Recommended) - Use the `login` tool with your GeoGuessr email and password
|
||||
2. **Manual cookie** - Use the `set_ncfa_cookie` tool with a cookie extracted from your browser
|
||||
3. **Environment variable** - Set `GEOGUESSR_NCFA_COOKIE` for server-wide default authentication
|
||||
### Comprehensive Analysis
|
||||
- Profile and statistics retrieval
|
||||
- Game history and round-by-round analysis
|
||||
- Performance tracking and trend detection
|
||||
- Strategy recommendations based on gameplay patterns
|
||||
|
||||
### Using Login (Easiest)
|
||||
### Easy Deployment
|
||||
- Docker Compose for simple VPS deployment
|
||||
- Production-ready with nginx and SSL support
|
||||
- Persistent schema caching between restarts
|
||||
|
||||
Simply ask Claude to login:
|
||||
```
|
||||
"Login to GeoGuessr with email: myemail@example.com and password: mypassword"
|
||||
```
|
||||
## 🚀 Quick Start
|
||||
|
||||
The server will authenticate with GeoGuessr and create a session. Your credentials are only used once to obtain an authentication token - they are **not stored** on the server.
|
||||
### Prerequisites
|
||||
- Docker and Docker Compose
|
||||
- A GeoGuessr account
|
||||
|
||||
### Security Notes
|
||||
|
||||
- Credentials are sent directly to GeoGuessr's official API over HTTPS
|
||||
- Session tokens are stored in memory only (lost on server restart)
|
||||
- For persistent authentication, use the environment variable method
|
||||
- Always use HTTPS in production to protect credentials in transit
|
||||
|
||||
## Features
|
||||
|
||||
### Authentication Tools
|
||||
- **login** - Authenticate with email/password
|
||||
- **logout** - End the current session
|
||||
- **set_ncfa_cookie** - Set authentication cookie manually
|
||||
- **set_session_token** - Restore a previous session
|
||||
- **get_auth_status** - Check current authentication status
|
||||
|
||||
### Profile & Stats
|
||||
- **get_my_profile** - Get your user profile information
|
||||
- **get_my_stats** - Get detailed statistics displayed on your profile
|
||||
- **get_extended_stats** - Get additional stats not shown on profile
|
||||
- **get_my_achievements** - Get all your achievements
|
||||
- **get_my_trophies** - Get your trophy collection
|
||||
- **get_trophy_case** - Get your displayed trophy case
|
||||
|
||||
### Games & Activity
|
||||
- **get_activity_feed** - Get recent activity (games, achievements, etc.)
|
||||
- **get_game_details** - Get detailed info about a specific game
|
||||
- **get_unfinished_games** - Get games you haven't completed
|
||||
- **get_streak_game** - Get country streak game details
|
||||
- **analyze_recent_games** - Analyze your recent games with statistics
|
||||
|
||||
### Competitive Modes
|
||||
- **get_battle_royale_game** - Get Battle Royale game stats
|
||||
- **get_duel_game** - Get duel game information
|
||||
- **get_game_lobby** - Get lobby info with player stats
|
||||
- **get_current_season_stats** - Get current season statistics
|
||||
- **get_season_game_info** - Get season info for specific game modes
|
||||
- **get_tournaments** - Get tournament information
|
||||
|
||||
### Challenges
|
||||
- **get_daily_challenge** - Get today's or previous daily challenges
|
||||
- **get_challenge_details** - Get details about a specific challenge
|
||||
|
||||
### Social
|
||||
- **get_friends** - Get your friends list
|
||||
- **get_friends_summary** - Get friends with requests and recommendations
|
||||
- **get_notifications** - Get your notifications
|
||||
- **search_user** - Search for other players
|
||||
|
||||
### Maps
|
||||
- **get_my_maps** - Get maps you've created
|
||||
- **get_liked_maps** - Get maps you've liked
|
||||
- **get_map_info** - Get info about any map
|
||||
- **get_popular_maps** - Get popular/featured/official maps
|
||||
- **get_personalized_maps** - Get map recommendations
|
||||
- **get_map_scores** - Get high scores for a map
|
||||
|
||||
### Explorer & Progress
|
||||
- **get_explorer_progress** - Get your explorer mode progress
|
||||
- **get_objectives** - Get current objectives
|
||||
- **get_unclaimed_objectives** - Get rewards to claim
|
||||
- **get_unclaimed_badges** - Get badges to claim
|
||||
|
||||
### Analysis
|
||||
- **get_performance_summary** - Get comprehensive performance overview
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Docker Compose installed on your VPS
|
||||
- A GeoGuessr account (Pro subscription recommended for full API access)
|
||||
- Your GeoGuessr `_ncfa` authentication cookie
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Clone or copy the files to your VPS
|
||||
|
||||
```bash
|
||||
mkdir -p ~/geoguessr-mcp
|
||||
cd ~/geoguessr-mcp
|
||||
# Copy all the files here
|
||||
```
|
||||
|
||||
### 2. Build and run (no configuration required!)
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
That's it! The server now supports login via credentials, so you don't need to configure anything upfront.
|
||||
|
||||
### 3. (Optional) Configure default authentication
|
||||
|
||||
If you want server-wide default authentication without logging in each time:
|
||||
|
||||
#### Option A: Get your GeoGuessr authentication cookie
|
||||
|
||||
1. Log in to [GeoGuessr](https://www.geoguessr.com) in your browser
|
||||
2. Open Developer Tools (F12 or Ctrl+Shift+I)
|
||||
3. Go to the **Application** tab (Chrome) or **Storage** tab (Firefox)
|
||||
4. Under **Cookies**, find `www.geoguessr.com`
|
||||
5. Look for the cookie named `_ncfa`
|
||||
6. Copy its value
|
||||
### 1. Clone and Configure
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/geoguessr-mcp.git
|
||||
cd geoguessr-mcp
|
||||
cp .env.example .env
|
||||
nano .env # Add your cookie
|
||||
```
|
||||
|
||||
```env
|
||||
GEOGUESSR_NCFA_COOKIE=your_actual_cookie_value_here
|
||||
```
|
||||
|
||||
#### Option B: Just use login when connected
|
||||
|
||||
When connected to Claude, simply say:
|
||||
> "Login to GeoGuessr with my email and password"
|
||||
|
||||
Claude will prompt you for credentials and authenticate.
|
||||
|
||||
### 4. Restart if you added environment variables
|
||||
### 2. Deploy
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### 5. Verify it's running
|
||||
That's it! The server is now running on port 8000.
|
||||
|
||||
```bash
|
||||
docker compose logs -f
|
||||
```
|
||||
### 3. Connect to Claude
|
||||
|
||||
You should see:
|
||||
```
|
||||
Starting GeoGuessr MCP Server on 0.0.0.0:8000 with streamable-http transport
|
||||
```
|
||||
Add to your Claude Desktop configuration:
|
||||
|
||||
## Connecting to Claude
|
||||
|
||||
### Claude Desktop (macOS/Windows)
|
||||
|
||||
Add to your Claude Desktop configuration file:
|
||||
|
||||
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
|
||||
```json
|
||||
|
|
@ -175,161 +61,193 @@ Add to your Claude Desktop configuration file:
|
|||
}
|
||||
```
|
||||
|
||||
### VS Code with Copilot
|
||||
## 🔐 Authentication
|
||||
|
||||
1. Open VS Code
|
||||
2. Run the command: `MCP: Add Server`
|
||||
3. Choose "HTTP (Streamable HTTP)" as the transport
|
||||
4. Enter URL: `http://YOUR_VPS_IP:8000/mcp`
|
||||
The server supports multiple authentication methods:
|
||||
|
||||
### Claude.ai (if MCP support is enabled)
|
||||
### Option 1: Login via Claude (Recommended)
|
||||
Simply ask Claude:
|
||||
> "Login to GeoGuessr with email: myemail@example.com and password: mypassword"
|
||||
|
||||
Add the server through Claude.ai's integrations settings with:
|
||||
- URL: `http://YOUR_VPS_IP:8000/mcp`
|
||||
- Transport: Streamable HTTP
|
||||
### Option 2: Environment Variable
|
||||
Add to your `.env` file:
|
||||
```bash
|
||||
GEOGUESSR_NCFA_COOKIE=your_cookie_value_here
|
||||
```
|
||||
|
||||
## Using with Claude
|
||||
### Option 3: Manual Cookie
|
||||
Use the `set_ncfa_cookie` tool with a cookie extracted from your browser.
|
||||
|
||||
Once connected, you can ask Claude questions like:
|
||||
## 📊 Available Tools
|
||||
|
||||
**First, authenticate (if not using environment variable):**
|
||||
- "Login to GeoGuessr with email: myemail@example.com password: mypassword"
|
||||
- "Check my GeoGuessr authentication status"
|
||||
### Authentication
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `login` | Authenticate with email/password |
|
||||
| `logout` | End current session |
|
||||
| `set_ncfa_cookie` | Set authentication cookie manually |
|
||||
| `get_auth_status` | Check authentication status |
|
||||
|
||||
**Then analyze your data:**
|
||||
- "Show me my GeoGuessr profile and stats"
|
||||
- "Analyze my last 10 games and tell me how I'm doing"
|
||||
- "What achievements have I unlocked?"
|
||||
- "How am I doing in the current competitive season?"
|
||||
- "Show me my activity feed from the last week"
|
||||
- "What maps have I liked?"
|
||||
- "Search for a player named [username]"
|
||||
- "Get the details of my last Battle Royale game"
|
||||
### Profile & Stats
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `get_my_profile` | Get your profile information |
|
||||
| `get_my_stats` | Get your game statistics |
|
||||
| `get_extended_stats` | Get additional statistics |
|
||||
| `get_achievements` | Get your achievements |
|
||||
| `get_comprehensive_profile` | Get combined profile data |
|
||||
|
||||
**When done (optional):**
|
||||
- "Logout from GeoGuessr"
|
||||
### Games & Activity
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `get_activity_feed` | Get recent activity |
|
||||
| `get_recent_games` | Get recent games with details |
|
||||
| `get_game_details` | Get specific game information |
|
||||
| `get_season_stats` | Get competitive season stats |
|
||||
| `get_daily_challenge` | Get daily challenge info |
|
||||
|
||||
## Production Deployment
|
||||
### Analysis
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `analyze_recent_games` | Analyze performance trends |
|
||||
| `get_performance_summary` | Comprehensive performance overview |
|
||||
| `get_strategy_recommendations` | Get personalized improvement tips |
|
||||
|
||||
### Adding SSL with Nginx (Recommended)
|
||||
### API Monitoring
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `check_api_status` | Check all endpoint availability |
|
||||
| `get_endpoint_schema` | Get schema for specific endpoint |
|
||||
| `list_available_endpoints` | List all known endpoints |
|
||||
| `explore_endpoint` | Discover new API endpoints |
|
||||
|
||||
For production, you should add SSL. Create an `nginx.conf`:
|
||||
## 🔄 Dynamic Schema System
|
||||
|
||||
```nginx
|
||||
events {
|
||||
worker_connections 1024;
|
||||
}
|
||||
The server automatically adapts to API changes:
|
||||
|
||||
http {
|
||||
upstream mcp_server {
|
||||
server geoguessr-mcp:8000;
|
||||
}
|
||||
```
|
||||
┌─────────────────────┐ ┌──────────────────┐
|
||||
│ API Response │ ───▶ │ Schema Detector │
|
||||
└─────────────────────┘ └────────┬─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐ ┌──────────────────┐
|
||||
│ Schema Registry │ ◀─── │ Compare Hash │
|
||||
│ (Persisted) │ └──────────────────┘
|
||||
└─────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Dynamic Response │ ───▶ Available to LLM
|
||||
│ with Schema Info │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name your-domain.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
### How It Works
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name your-domain.com;
|
||||
1. **Daily Monitoring**: The server checks all known endpoints every 24 hours
|
||||
2. **Schema Detection**: Analyzes response structure, field types, and nesting
|
||||
3. **Change Detection**: Computes schema hash to detect modifications
|
||||
4. **Persistence**: Schemas are cached to disk and survive restarts
|
||||
5. **Dynamic Access**: Tools return data with schema information for the LLM
|
||||
|
||||
ssl_certificate /etc/nginx/ssl/fullchain.pem;
|
||||
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
|
||||
### Example: Exploring Unknown Endpoints
|
||||
|
||||
location / {
|
||||
proxy_pass http://mcp_server;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 86400;
|
||||
}
|
||||
}
|
||||
```
|
||||
User: "Can you explore the /v3/some-new-endpoint API?"
|
||||
|
||||
Claude uses explore_endpoint tool:
|
||||
{
|
||||
"success": true,
|
||||
"discovered_fields": ["id", "name", "data", "timestamp"],
|
||||
"schema_description": "Endpoint: /v3/some-new-endpoint\nFields:\n - id: string\n - name: string\n - data: object\n - timestamp: datetime"
|
||||
}
|
||||
```
|
||||
|
||||
### Adding API Key Authentication
|
||||
## 🏭 Production Deployment
|
||||
|
||||
For additional security, you can add API key authentication. Modify the server.py to check for an `x-api-key` header.
|
||||
|
||||
### Firewall Configuration
|
||||
### With SSL (Recommended)
|
||||
|
||||
1. Create SSL certificates:
|
||||
```bash
|
||||
# Allow only specific IPs or use a firewall
|
||||
sudo ufw allow from YOUR_IP to any port 8000
|
||||
mkdir -p nginx/ssl
|
||||
# Add your certificates:
|
||||
# nginx/ssl/fullchain.pem
|
||||
# nginx/ssl/privkey.pem
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "GEOGUESSR_NCFA_COOKIE environment variable not set"
|
||||
|
||||
Make sure your `.env` file exists and contains the cookie:
|
||||
2. Deploy with production compose:
|
||||
```bash
|
||||
cat .env | grep GEOGUESSR
|
||||
docker compose -f docker-compose.prod.yml up -d
|
||||
```
|
||||
|
||||
### Cookie expired
|
||||
### Environment Variables
|
||||
|
||||
GeoGuessr cookies expire periodically. If API calls start failing, get a fresh cookie from your browser.
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `GEOGUESSR_NCFA_COOKIE` | - | Default authentication cookie |
|
||||
| `MCP_PORT` | 8000 | Server port |
|
||||
| `MCP_TRANSPORT` | streamable-http | MCP transport protocol |
|
||||
| `MONITORING_ENABLED` | true | Enable API monitoring |
|
||||
| `MONITORING_INTERVAL_HOURS` | 24 | Monitoring check interval |
|
||||
| `LOG_LEVEL` | INFO | Logging verbosity |
|
||||
|
||||
### Connection refused
|
||||
## 🧪 Development
|
||||
|
||||
1. Check if the container is running: `docker compose ps`
|
||||
2. Check logs: `docker compose logs geoguessr-mcp`
|
||||
3. Verify the port is exposed: `docker port geoguessr-mcp-server`
|
||||
|
||||
### API rate limiting
|
||||
|
||||
GeoGuessr may rate-limit excessive API calls. Space out requests if you're hitting limits.
|
||||
|
||||
## Cookie Security
|
||||
|
||||
⚠️ **Important Security Notes:**
|
||||
|
||||
1. The `_ncfa` cookie provides full access to your GeoGuessr account
|
||||
2. Never share your `.env` file or commit it to version control
|
||||
3. Consider running the server on a private network
|
||||
4. Use SSL in production
|
||||
5. Regularly rotate your cookie
|
||||
|
||||
## Development
|
||||
|
||||
To run locally without Docker:
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # or `venv\Scripts\activate` on Windows
|
||||
source venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
# Set environment variable
|
||||
export GEOGUESSR_NCFA_COOKIE="your_cookie_here"
|
||||
# Run tests
|
||||
pytest -v
|
||||
|
||||
# Run the server
|
||||
python server.py
|
||||
# Run server locally
|
||||
python -m geoguessr_mcp.main
|
||||
```
|
||||
|
||||
## API Reference
|
||||
### Project Structure
|
||||
|
||||
The server uses the unofficial GeoGuessr API. Key endpoints:
|
||||
```
|
||||
geoguessr-mcp/
|
||||
├── src/geoguessr_mcp/
|
||||
│ ├── api/ # API client and endpoints
|
||||
│ ├── auth/ # Authentication
|
||||
│ ├── models/ # Data models
|
||||
│ ├── monitoring/ # Schema detection & monitoring
|
||||
│ ├── services/ # Business logic
|
||||
│ ├── tools/ # MCP tool definitions
|
||||
│ ├── config.py # Configuration
|
||||
│ └── main.py # Entry point
|
||||
├── tests/
|
||||
│ ├── unit/ # Unit tests
|
||||
│ └── integration/ # Integration tests
|
||||
├── nginx/ # Production nginx config
|
||||
├── docker-compose.yml # Development deployment
|
||||
├── docker-compose.prod.yml # Production deployment
|
||||
└── Dockerfile
|
||||
```
|
||||
|
||||
- `https://www.geoguessr.com/api/v3/` - Main API (v3)
|
||||
- `https://www.geoguessr.com/api/v4/` - Newer API (v4)
|
||||
- `https://game-server.geoguessr.com/api/` - Game server API
|
||||
## 🤝 Contributing
|
||||
|
||||
Note: This is an unofficial API and may change without notice.
|
||||
Contributions are welcome! Please:
|
||||
|
||||
## License
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Add tests for new functionality
|
||||
4. Submit a pull request
|
||||
|
||||
MIT License - Feel free to modify and distribute.
|
||||
## 📝 License
|
||||
|
||||
## Disclaimer
|
||||
MIT License - see LICENSE file for details.
|
||||
|
||||
This project is not affiliated with, endorsed by, or connected to GeoGuessr AB. Use at your own risk and in accordance with GeoGuessr's Terms of Service.
|
||||
## ⚠️ Disclaimer
|
||||
|
||||
This project uses the unofficial GeoGuessr API which may change without notice. The dynamic schema system helps mitigate this, but some features may break if GeoGuessr makes significant API changes.
|
||||
|
||||
This project is not affiliated with GeoGuessr AB.
|
||||
Loading…
Add table
Add a link
Reference in a new issue