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
33
.gitignore
vendored
33
.gitignore
vendored
|
|
@ -11,6 +11,11 @@ __pycache__/
|
|||
venv/
|
||||
.venv/
|
||||
ENV/
|
||||
env/
|
||||
*.egg-info/
|
||||
dist/
|
||||
build/
|
||||
.eggs/
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
|
|
@ -18,10 +23,13 @@ ENV/
|
|||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
.project
|
||||
.pydevproject
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
*.bak
|
||||
|
||||
# Docker
|
||||
docker-compose.override.yml
|
||||
|
|
@ -31,7 +39,28 @@ docker-compose.override.yml
|
|||
logs/
|
||||
|
||||
# SSL certificates (if stored locally)
|
||||
ssl/
|
||||
nginx/ssl/
|
||||
*.pem
|
||||
*.crt
|
||||
*.key
|
||||
*.key
|
||||
|
||||
# Data and cache
|
||||
data/
|
||||
*.cache
|
||||
.cache/
|
||||
|
||||
# Coverage
|
||||
.coverage
|
||||
htmlcov/
|
||||
coverage.xml
|
||||
*.cover
|
||||
|
||||
# MyPy
|
||||
.mypy_cache/
|
||||
.dmypy.json
|
||||
|
||||
# Pytest
|
||||
.pytest_cache/
|
||||
|
||||
# Ruff
|
||||
.ruff_cache/
|
||||
387
DEVELOPMENT.md
387
DEVELOPMENT.md
|
|
@ -1,387 +0,0 @@
|
|||
# Development Guide: GeoGuessr MCP Server
|
||||
|
||||
This guide covers multiple ways to develop the GeoGuessr MCP Server using PyCharm, including remote development options.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Option 1: PyCharm Remote Development (Gateway)](#option-1-pycharm-remote-development-gateway)
|
||||
2. [Option 2: PyCharm with Docker Interpreter](#option-2-pycharm-with-docker-interpreter)
|
||||
3. [Option 3: Dev Containers](#option-3-dev-containers)
|
||||
4. [Option 4: SSH Remote Interpreter](#option-4-ssh-remote-interpreter)
|
||||
5. [Running Tests](#running-tests)
|
||||
6. [Debugging](#debugging)
|
||||
|
||||
---
|
||||
|
||||
## Option 1: PyCharm Remote Development (Gateway)
|
||||
|
||||
**Best for:** Full IDE experience on a remote server with PyCharm Professional.
|
||||
|
||||
### Prerequisites
|
||||
- PyCharm Professional 2023.2+ or JetBrains Gateway
|
||||
- SSH access to your VPS
|
||||
|
||||
### Setup Steps
|
||||
|
||||
1. **Install JetBrains Gateway** (or use PyCharm Professional's remote dev feature)
|
||||
- Download from: https://www.jetbrains.com/remote-development/gateway/
|
||||
|
||||
2. **Connect to your VPS**
|
||||
```
|
||||
Gateway → New Connection → SSH
|
||||
Host: your-vps-ip
|
||||
User: your-username
|
||||
Authentication: Key pair or password
|
||||
```
|
||||
|
||||
3. **Clone the project on the server**
|
||||
```bash
|
||||
ssh user@your-vps
|
||||
git clone https://github.com/yourusername/geoguessr-mcp.git
|
||||
cd geoguessr-mcp
|
||||
```
|
||||
|
||||
4. **Open in Gateway**
|
||||
- Select IDE: PyCharm Professional
|
||||
- Project directory: `/home/user/geoguessr-mcp`
|
||||
- Click "Download and Start IDE"
|
||||
|
||||
5. **Configure the environment**
|
||||
- Gateway will install a remote IDE backend
|
||||
- Set up your Python interpreter (see below)
|
||||
- Copy `.env.example` to `.env` and add your cookie
|
||||
|
||||
### Configure Python Interpreter in Gateway
|
||||
|
||||
1. File → Settings → Project → Python Interpreter
|
||||
2. Add Interpreter → Add Local Interpreter
|
||||
3. Select "Virtualenv Environment" → New
|
||||
4. Location: `/home/user/geoguessr-mcp/.venv`
|
||||
5. Base interpreter: `/usr/bin/python3.12`
|
||||
6. Click OK
|
||||
|
||||
---
|
||||
|
||||
## Option 2: PyCharm with Docker Interpreter
|
||||
|
||||
**Best for:** Consistent dev environment, running PyCharm locally with Docker.
|
||||
|
||||
### Prerequisites
|
||||
- PyCharm Professional
|
||||
- Docker installed locally
|
||||
- Docker Compose installed
|
||||
|
||||
### Setup Steps
|
||||
|
||||
1. **Open the project locally in PyCharm**
|
||||
|
||||
2. **Build the dev container**
|
||||
```bash
|
||||
cd geoguessr-mcp
|
||||
docker compose -f .devcontainer/docker-compose.dev.yml build
|
||||
```
|
||||
|
||||
3. **Configure Docker Interpreter**
|
||||
|
||||
a. File → Settings → Project → Python Interpreter
|
||||
|
||||
b. Click the gear icon → Add
|
||||
|
||||
c. Select "Docker Compose"
|
||||
|
||||
d. Configuration file: `.devcontainer/docker-compose.dev.yml`
|
||||
|
||||
e. Service: `dev`
|
||||
|
||||
f. Python interpreter: `/usr/local/bin/python`
|
||||
|
||||
g. Click OK
|
||||
|
||||
4. **Configure Environment Variables**
|
||||
|
||||
a. Run → Edit Configurations
|
||||
|
||||
b. Select your run configuration
|
||||
|
||||
c. Environment variables: Add `GEOGUESSR_NCFA_COOKIE=your_cookie`
|
||||
|
||||
Or create a `.env` file:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your cookie
|
||||
```
|
||||
|
||||
5. **Run/Debug**
|
||||
- Use the run configurations provided in `.idea/runConfigurations/`
|
||||
|
||||
### Docker Compose Commands
|
||||
|
||||
```bash
|
||||
# Start dev container
|
||||
docker compose -f .devcontainer/docker-compose.dev.yml up -d
|
||||
|
||||
# View logs
|
||||
docker compose -f .devcontainer/docker-compose.dev.yml logs -f
|
||||
|
||||
# Stop
|
||||
docker compose -f .devcontainer/docker-compose.dev.yml down
|
||||
|
||||
# Rebuild
|
||||
docker compose -f .devcontainer/docker-compose.dev.yml build --no-cache
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Option 3: Dev Containers
|
||||
|
||||
**Best for:** VS Code users or PyCharm 2024.1+ with Dev Containers support.
|
||||
|
||||
### Using VS Code
|
||||
|
||||
1. Install the "Dev Containers" extension
|
||||
|
||||
2. Open the project folder
|
||||
|
||||
3. Click "Reopen in Container" when prompted (or F1 → "Dev Containers: Reopen in Container")
|
||||
|
||||
4. VS Code will build and connect to the dev container
|
||||
|
||||
### Using PyCharm (2024.1+)
|
||||
|
||||
PyCharm 2024.1+ has experimental Dev Containers support:
|
||||
|
||||
1. File → Remote Development → Dev Containers
|
||||
|
||||
2. Select the `.devcontainer/devcontainer.json` file
|
||||
|
||||
3. PyCharm will build and connect to the container
|
||||
|
||||
### Manual Container Development
|
||||
|
||||
If your IDE doesn't support dev containers natively:
|
||||
|
||||
```bash
|
||||
# Start the dev container
|
||||
docker compose -f .devcontainer/docker-compose.dev.yml up -d
|
||||
|
||||
# Exec into the container
|
||||
docker exec -it geoguessr-mcp-dev-1 bash
|
||||
|
||||
# Inside container: run the server
|
||||
cd /workspace
|
||||
python server.py
|
||||
|
||||
# Inside container: run tests
|
||||
pytest -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Option 4: SSH Remote Interpreter
|
||||
|
||||
**Best for:** PyCharm Professional users who want to run code directly on VPS.
|
||||
|
||||
### Setup Steps
|
||||
|
||||
1. **Prepare your VPS**
|
||||
```bash
|
||||
ssh user@your-vps
|
||||
|
||||
# Install Python 3.12
|
||||
sudo apt update
|
||||
sudo apt install python3.12 python3.12-venv python3.12-dev
|
||||
|
||||
# Clone the project
|
||||
git clone https://github.com/yourusername/geoguessr-mcp.git
|
||||
cd geoguessr-mcp
|
||||
|
||||
# Create virtual environment
|
||||
python3.12 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt -r requirements-dev.txt
|
||||
```
|
||||
|
||||
2. **Configure PyCharm SSH Interpreter**
|
||||
|
||||
a. File → Settings → Project → Python Interpreter
|
||||
|
||||
b. Click gear → Add → SSH Interpreter
|
||||
|
||||
c. New server configuration:
|
||||
- Host: your-vps-ip
|
||||
- Username: your-username
|
||||
- Authentication: Key pair
|
||||
|
||||
d. Next → Interpreter path: `/home/user/geoguessr-mcp/.venv/bin/python`
|
||||
|
||||
e. Sync folders:
|
||||
- Local: Your local project path
|
||||
- Remote: `/home/user/geoguessr-mcp`
|
||||
|
||||
3. **Configure deployment**
|
||||
|
||||
a. Tools → Deployment → Configuration
|
||||
|
||||
b. Add SFTP server
|
||||
|
||||
c. Enable automatic upload (Tools → Deployment → Automatic Upload)
|
||||
|
||||
---
|
||||
|
||||
## Running Tests
|
||||
|
||||
### From PyCharm
|
||||
- Use the "Run Tests" configuration
|
||||
- Or right-click on `tests/` → Run 'pytest in tests'
|
||||
|
||||
### From Command Line
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest -v
|
||||
|
||||
# Run with coverage
|
||||
pytest -v --cov=. --cov-report=html
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/test_server.py -v
|
||||
|
||||
# Run only unit tests (skip integration)
|
||||
pytest -v -m "not integration"
|
||||
|
||||
# Run integration tests (requires real cookie)
|
||||
GEOGUESSR_NCFA_COOKIE=your_real_cookie pytest -v -m integration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging
|
||||
|
||||
### PyCharm Debugger
|
||||
|
||||
1. Set breakpoints by clicking in the gutter
|
||||
|
||||
2. Run → Debug 'Debug MCP Server'
|
||||
|
||||
3. Use the debugger panel to:
|
||||
- Step through code (F8)
|
||||
- Step into functions (F7)
|
||||
- Evaluate expressions
|
||||
- View variables
|
||||
|
||||
### Remote Debugging (debugpy)
|
||||
|
||||
For debugging in Docker or remote environments:
|
||||
|
||||
1. **Modify server.py** to enable debugpy:
|
||||
```python
|
||||
import debugpy
|
||||
debugpy.listen(("0.0.0.0", 5678))
|
||||
print("Waiting for debugger...")
|
||||
debugpy.wait_for_client()
|
||||
```
|
||||
|
||||
2. **Configure PyCharm Remote Debug**
|
||||
|
||||
a. Run → Edit Configurations → Add → Python Debug Server
|
||||
|
||||
b. IDE host name: `localhost`
|
||||
|
||||
c. Port: `5678`
|
||||
|
||||
d. Path mappings:
|
||||
- Local: `/path/to/local/project`
|
||||
- Remote: `/workspace`
|
||||
|
||||
3. **Start debugging**
|
||||
- Start the server (it will wait for debugger)
|
||||
- Run the "Python Debug Server" configuration in PyCharm
|
||||
- Server will continue execution
|
||||
|
||||
### Logging
|
||||
|
||||
The server uses Python's logging module. Increase verbosity:
|
||||
|
||||
```python
|
||||
# In server.py, change:
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
```
|
||||
|
||||
Or via environment:
|
||||
```bash
|
||||
export LOG_LEVEL=DEBUG
|
||||
python server.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Quality
|
||||
|
||||
### Format Code
|
||||
|
||||
```bash
|
||||
# Black
|
||||
black .
|
||||
|
||||
# Ruff (lint + fix)
|
||||
ruff check --fix .
|
||||
```
|
||||
|
||||
### Type Checking
|
||||
|
||||
```bash
|
||||
mypy server.py
|
||||
```
|
||||
|
||||
### Pre-commit Hooks
|
||||
|
||||
```bash
|
||||
# Install hooks
|
||||
pre-commit install
|
||||
|
||||
# Run manually
|
||||
pre-commit run --all-files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
geoguessr-mcp/
|
||||
├── .devcontainer/ # Dev container configuration
|
||||
│ ├── devcontainer.json
|
||||
│ ├── docker-compose.dev.yml
|
||||
│ └── Dockerfile.dev
|
||||
├── .idea/ # PyCharm settings
|
||||
│ └── runConfigurations/
|
||||
├── tests/ # Test files
|
||||
│ ├── __init__.py
|
||||
│ └── test_server.py
|
||||
├── server.py # Main MCP server
|
||||
├── requirements.txt # Production dependencies
|
||||
├── requirements-dev.txt # Development dependencies
|
||||
├── pyproject.toml # Project configuration
|
||||
├── Dockerfile # Production Dockerfile
|
||||
├── docker-compose.yml # Production compose
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Hot Reload**: Use `watchfiles` for auto-restart during development:
|
||||
```bash
|
||||
pip install watchfiles
|
||||
watchfiles "python server.py" .
|
||||
```
|
||||
|
||||
2. **Test MCP Connection**: Use the test script:
|
||||
```bash
|
||||
python test_server.py http://localhost:8000/mcp
|
||||
```
|
||||
|
||||
3. **Environment Variables**: Always use `.env` file locally, never commit secrets
|
||||
|
||||
4. **Cookie Expiration**: GeoGuessr cookies expire - if tests start failing, get a fresh cookie
|
||||
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