Geoguessrmcp

🚀 GeoGuessr MCP 服務器

GeoGuessr MCP 服務器是一個基於模型上下文協議（MCP）的服務器，用於分析 GeoGuessr 遊戲統計數據。它具備自動 API 監控和動態模式自適應功能，能有效應對 GeoGuessr API 的變化，為用戶提供穩定、全面的遊戲數據分析服務。

📋 待辦事項

• [x] 修復 compose 文件和環境變量中的 Docker 用戶名
• [x] 為 MCP 服務器添加身份驗證，僅允許特定用戶訪問
• [ ] 修復測試未運行的代碼質量問題
• [ ] 修復 black 格式化的代碼質量問題
• [ ] 為新端點添加自動監控，並通過電子郵件發送通知

✨ 主要特性

多用戶支持

• 獨立會話：每個 API 密鑰都有自己的 GeoGuessr 會話。
• 多賬戶訪問：不同用戶可以訪問自己的 GeoGuessr 賬戶。
• 單服務器部署：無需為每個用戶部署單獨的實例。
• 自動上下文管理：服務器會根據每個請求自動管理用戶會話。

動態 API 監控

• 自動端點發現：每天監控 GeoGuessr API 端點。
• 模式變更檢測：自動檢測 API 響應格式的變化。
• 自適應調整：根據實際 API 響應更新內部數據模型。
• 無硬編碼假設：即使 GeoGuessr 更改其 API，服務器仍能正常工作。

全面分析

• 個人資料和統計信息檢索：獲取用戶的遊戲數據。
• 遊戲歷史和逐輪分析：深入瞭解遊戲過程。
• 性能跟蹤和趨勢檢測：掌握遊戲表現的變化。
• 基於遊戲模式的策略建議：根據玩家的遊戲習慣提供優化建議。

輕鬆部署

• Docker Compose 支持：可在 VPS 上輕鬆部署。
• 生產就緒：支持 nginx 和 SSL。
• 持久化模式緩存：重啟後仍能保留模式信息。

🚀 快速開始

前提條件

• Docker 和 Docker Compose
• 一個 GeoGuessr 賬戶

1. 克隆並配置

git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git
cd GeoGuessrMCP
cp .env.example .env

2. 部署

docker compose up -d --build

完成！服務器現在在 8000 端口上運行。

3. 配置 MCP 服務器身份驗證（可選）

若要使用 API 密鑰身份驗證保護 MCP 服務器，請編輯 .env 文件：

MCP_AUTH_ENABLED=true
MCP_API_KEYS=your-secure-api-key-here

生成安全的 API 密鑰：

openssl rand -hex 32

4. 連接到 Claude

將以下內容添加到 Claude 桌面配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

無身份驗證：

{
  "mcpServers": {
    "geoguessr": {
      "type": "streamable-http",
      "url": "http://YOUR_VPS_IP:8000/mcp"
    }
  }
}

有身份驗證：

{
  "mcpServers": {
    "geoguessr": {
      "type": "streamable-http",
      "url": "http://YOUR_VPS_IP:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-api-key-here"
      }
    }
  }
}

🔐 身份驗證

服務器支持兩種類型的身份驗證，具備多用戶支持功能。

MCP 服務器身份驗證（控制對 MCP 服務器的訪問）

確保只有授權用戶可以連接到 MCP 服務器。啟用後，客戶端必須提供有效的 API 密鑰。

多用戶支持：每個 API 密鑰可以有自己的 GeoGuessr 會話，允許多個用戶使用同一 MCP 服務器實例訪問自己的賬戶！

在 .env 中啟用：

MCP_AUTH_ENABLED=true
MCP_API_KEYS=key1,key2,key3  # 多個用戶的 API 密鑰用逗號分隔

生成安全密鑰：

openssl rand -hex 32

在 Claude 桌面配置中使用身份驗證：

{
  "mcpServers": {
    "geoguessr": {
      "type": "streamable-http",
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

多用戶示例：

# 為每個用戶分配自己的 API 密鑰
MCP_API_KEYS=alice_key_abc123,bob_key_def456,charlie_key_ghi789

# Alice 使用 Authorization: Bearer alice_key_abc123 連接
# Bob 使用 Authorization: Bearer bob_key_def456 連接
# 每個用戶都可以登錄自己的 GeoGuessr 賬戶！

GeoGuessr API 身份驗證（訪問 GeoGuessr 數據）

服務器還需要身份驗證才能訪問 GeoGuessr 的 API。在多用戶模式下，每個 API 密鑰持有者可以登錄自己的 GeoGuessr 賬戶：

選項 1：通過 Claude 登錄（推薦）

只需向 Claude 發出請求：

"使用郵箱 myemail@example.com 和密碼 mypassword 登錄 GeoGuessr"

選項 2：使用環境變量

在 .env 文件中添加以下內容：

GEOGUESSR_NCFA_COOKIE=your_cookie_value_here

選項 3：手動設置 Cookie

使用 set_ncfa_cookie 工具，並從瀏覽器中提取 Cookie。

👥 多用戶模式

服務器支持多個用戶使用同一 MCP 服務器實例，每個用戶都可以使用自己的 GeoGuessr 賬戶。

工作原理

1. API 密鑰：每個用戶獲得一個唯一的 API 密鑰。
2. 獨立會話：每個 API 密鑰都有自己的 GeoGuessr 登錄會話。
3. 自動路由：服務器自動將請求路由到正確的用戶會話。
4. 互不干擾：用戶之間的會話不會相互影響。

設置示例

1. 配置多個 API 密鑰：

# .env 文件
MCP_AUTH_ENABLED=true
MCP_API_KEYS=alice_key,bob_key,charlie_key

2. 重啟服務器：

# 開發環境
docker compose restart

# 生產環境
docker compose -f docker-compose.prod.yml restart

3. 每個用戶進行連接：

// Alice 的 Claude 桌面配置
{
  "mcpServers": {
    "geoguessr": {
      "url": "https://your-domain.com/mcp",
      "headers": {"Authorization": "Bearer alice_key"}
    }
  }
}

// Bob 的 Claude 桌面配置
{
  "mcpServers": {
    "geoguessr": {
      "url": "https://your-domain.com/mcp",
      "headers": {"Authorization": "Bearer bob_key"}
    }
  }
}

4. 每個用戶進行登錄：

• Alice 向 Claude 請求："使用我的憑據登錄 GeoGuessr"
• Bob 向 Claude 請求："使用我的憑據登錄 GeoGuessr"
• 會話完全獨立！

添加新用戶

若要向現有部署中添加新用戶，請按以下步驟操作：

1. 編輯 .env 文件，將新的 API 密鑰添加到 MCP_API_KEYS 中。
2. 重啟服務器：docker compose restart
3. 將新的 API 密鑰分享給用戶。
4. 用戶使用 API 密鑰配置其 Claude 桌面。
5. 用戶通過 Claude 登錄其 GeoGuessr 賬戶。

服務器將在約 2 - 3 秒內重啟，所有現有用戶仍保持登錄狀態！

📊 可用工具

身份驗證

工具	描述
login	使用電子郵件/密碼進行身份驗證
logout	結束當前會話
set_ncfa_cookie	手動設置身份驗證 Cookie
get_auth_status	檢查身份驗證狀態

個人資料與統計信息

工具	描述
get_my_profile	獲取您的個人資料信息
get_my_stats	獲取您的遊戲統計數據
get_extended_stats	獲取額外的統計信息
get_achievements	獲取您的成就信息
get_comprehensive_profile	獲取綜合個人資料數據

遊戲與活動

工具	描述
get_activity_feed	獲取最近的活動信息
get_recent_games	獲取最近的遊戲詳情
get_game_details	獲取特定遊戲的信息
get_season_stats	獲取競技賽季的統計數據
get_daily_challenge	獲取每日挑戰信息

分析

工具	描述
analyze_recent_games	分析性能趨勢
get_performance_summary	獲取全面的性能概述
get_strategy_recommendations	獲取個性化的改進建議

API 監控

工具	描述
check_api_status	檢查所有端點的可用性
get_endpoint_schema	獲取特定端點的模式信息
list_available_endpoints	列出所有已知的端點
explore_endpoint	發現新的 API 端點

🔄 動態模式系統

服務器能夠自動適應 API 的變化，其工作流程如下：

┌─────────────────────┐      ┌──────────────────┐
│   API 響應          │ ───▶ │  模式檢測器      │
└─────────────────────┘      └────────┬─────────┘
                                      │
                                      ▼
┌─────────────────────┐      ┌──────────────────┐
│  模式註冊表        │ ◀─── │  比較哈希值      │
│  (持久化)          │      └──────────────────┘
└─────────────────────┘
         │
         ▼
┌─────────────────────┐
│  動態響應          │ ───▶ 可供大語言模型使用
│  包含模式信息      │
└─────────────────────┘

工作原理

1. 每日監控：服務器每 24 小時檢查所有已知的端點。
2. 模式檢測：分析響應結構、字段類型和嵌套關係。
3. 變更檢測：計算模式哈希值以檢測修改。
4. 持久化：模式信息會被緩存到磁盤，重啟後仍然保留。
5. 動態訪問：工具返回包含模式信息的數據，供大語言模型使用。

示例：探索未知端點

用戶："你能探索 /v3/some-new-endpoint API 嗎？"

Claude 使用 explore_endpoint 工具：
{
  "success": true,
  "discovered_fields": ["id", "name", "data", "timestamp"],
  "schema_description": "端點：/v3/some-new-endpoint\n字段：\n  - id: 字符串\n  - name: 字符串\n  - data: 對象\n  - timestamp: 日期時間"
}

🏭 生產部署

服務器以預構建的 Docker 鏡像形式提供：nyxiumyuuki/geoguessr-mcp:latest

方法 1：使用腳本快速部署

適用於已安裝 nginx-proxy-manager 的 VPS 部署：

# 在 VPS 上克隆倉庫
git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git
cd GeoGuessrMCP

# 配置環境
cp .env.example .env
# 使用您的設置編輯 .env 文件：
# - GEOGUESSR_NCFA_COOKIE（用於訪問 GeoGuessr API）
# - MCP_AUTH_ENABLED=true（可選，用於 MCP 服務器安全）
# - MCP_API_KEYS（如果啟用身份驗證）

# 運行部署腳本
./scripts/deploy.sh

方法 2：手動使用 Docker Compose 部署

開發/測試環境設置

# 使用 docker-compose.yml（開發環境）
docker compose up -d

使用 nginx-proxy-manager 的生產環境設置

# 使用 docker-compose.prod.yml（生產環境）
docker compose -f docker-compose.prod.yml up -d

在 nginx-proxy-manager 中配置 SSL：

• 訪問管理面板：http://your-vps-ip:81
• 為您的域名添加代理主機。
• 轉發到：geoguessr-mcp-server:8000
• 使用 Let's Encrypt 啟用 SSL。

📖 有關詳細的 VPS 部署說明，請參閱 DEPLOYMENT.md

方法 3：直接使用 Docker 運行

如果您不想使用 Docker Compose，可以按以下步驟操作：

# 拉取鏡像
docker pull nyxiumyuuki/geoguessr-mcp:latest

# 創建模式緩存卷
docker volume create geoguessr-schemas

# 運行容器（無身份驗證）
docker run -d \
  --name geoguessr-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e GEOGUESSR_NCFA_COOKIE=your_cookie \
  -e MCP_AUTH_ENABLED=false \
  -e MONITORING_ENABLED=true \
  -e MONITORING_INTERVAL_HOURS=24 \
  -e LOG_LEVEL=INFO \
  -v geoguessr-schemas:/app/data/schemas \
  nyxiumyuuki/geoguessr-mcp:latest

# 啟用 MCP 身份驗證運行
docker run -d \
  --name geoguessr-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e GEOGUESSR_NCFA_COOKIE=your_cookie \
  -e MCP_AUTH_ENABLED=true \
  -e MCP_API_KEYS=your-api-key-1,your-api-key-2 \
  -e MONITORING_ENABLED=true \
  -e MONITORING_INTERVAL_HOURS=24 \
  -e LOG_LEVEL=INFO \
  -v geoguessr-schemas:/app/data/schemas \
  nyxiumyuuki/geoguessr-mcp:latest

環境變量

變量	默認值	描述
GEOGUESSR_NCFA_COOKIE	-	GeoGuessr API 身份驗證 Cookie
MCP_AUTH_ENABLED	false	啟用 MCP 服務器身份驗證
MCP_API_KEYS	-	用於 MCP 訪問的逗號分隔的 API 密鑰
MCP_PORT	8000	服務器端口
MCP_TRANSPORT	streamable-http	MCP 傳輸協議
MONITORING_ENABLED	true	啟用 API 監控
MONITORING_INTERVAL_HOURS	24	監控檢查間隔（每 24 小時運行一次）
SCHEMA_CACHE_DIR	/app/data/schemas	模式持久化目錄
LOG_LEVEL	INFO	日誌詳細程度

🧪 開發

本地開發

# 創建虛擬環境
python -m venv venv
source venv/bin/activate

# 安裝依賴
pip install -r requirements-dev.txt

# 運行測試
pytest -v

# 本地運行服務器
python -m geoguessr_mcp.main

項目結構

geoguessr-mcp/
├── src/geoguessr_mcp/
│   ├── api/              # API 客戶端和端點
│   ├── auth/             # 身份驗證
│   ├── models/           # 數據模型
│   ├── monitoring/       # 模式檢測與監控
│   ├── services/         # 業務邏輯
│   ├── tools/            # MCP 工具定義
│   ├── config.py         # 配置文件
│   └── main.py           # 入口點
├── tests/
│   ├── unit/             # 單元測試
│   └── integration/      # 集成測試
├── nginx/                # 生產環境 nginx 配置
├── docker-compose.yml    # 開發環境部署
├── docker-compose.prod.yml # 生產環境部署
└── Dockerfile

🤝 貢獻

歡迎貢獻代碼！請按以下步驟操作：

1. 分叉倉庫
2. 創建功能分支
3. 為新功能添加測試
4. 提交拉取請求

📝 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

⚠️ 免責聲明

本項目使用非官方的 GeoGuessr API，該 API 可能會在未通知的情況下發生變化。動態模式系統有助於緩解這一問題，但如果 GeoGuessr 對 API 進行重大更改，某些功能可能會失效。

本項目與 GeoGuessr AB 沒有關聯。