Cyberedu MCP

🚀 CyberEdu MCP 服務器

這是 CyberEdu CTF 平臺（https://cyber-edu.co / https://cyberedu.ro）的官方模型上下文協議（MCP）服務器。該服務器會自動發現 CyberEduClient 中的所有方法，並將其作為 MCP 工具公開，方便通過兼容 MCP 的客戶端與 CyberEdu 平臺進行交互。

🚀 快速開始

克隆倉庫

cyberedu-client 作為 Git 子模塊包含在內。使用 --recursive 參數進行克隆以獲取所有內容：

git clone --recursive https://github.com/CyberEDU-Cyber-Range/cyberedu-mcp.git
cd cyberedu-mcp

如果之前克隆時未使用 --recursive 參數，可以初始化子模塊：

git submodule update --init --recursive

安裝包

安裝客戶端和 MCP 服務器兩個包：

macOS/Linux：

python3 -m venv venv  
source venv/bin/activate
pip install -e ".[local]"      # 使用本地 cyberedu-client 子模塊進行安裝
# 或者用於開發：
# pip install -e ".[local,dev]"

Windows（PowerShell）：

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e ".[local]"      # 使用本地 cyberedu-client 子模塊進行安裝

Windows（命令提示符）：

python -m venv venv
venv\Scripts\activate.bat
pip install -e ".[local]"

替代方法：分別安裝包：

pip install -e ./cyberedu-client
pip install -e .

✨ 主要特性

• 動態工具發現：自動發現 CyberEduClient 中的所有公共方法，並將其作為 MCP 工具公開。
• 新方法零配置：當向 CyberEduClient 添加新方法時，它們會自動作為 MCP 工具可用，無需進行任何代碼更改。
• 類型安全：根據方法簽名和類型提示自動生成 JSON 模式。
• 錯誤處理：具備全面的錯誤處理機制，提供詳細的錯誤信息。

📚 CyberEDU 平臺概述

核心描述

CyberEDU 是一個全面的網絡安全培訓平臺，提供實踐實驗室、逼真的模擬環境和競爭環境。它專為企業安全團隊、學術機構、政府機構和希望通過實際場景培養實用網絡安全技能的個人學習者而設計。

關鍵差異化優勢

• 實踐方法：提供交互式網絡靶場，用戶可以攻擊和防禦真實的基礎設施（而非僅僅觀看視頻或學習理論）。
• MITRE ATT&CK 映射：場景與 MITRE ATT&CK 映射，使用真實的惡意軟件樣本（安全隔離）。
• 更好的知識保留：與被動學習相比，技能保留率提高 3.5 倍。
• 真實場景：模擬實際的對手技術和攻擊模式。

平臺組件

1. 網絡靶場：企業級網絡戰模擬，具備複雜的網絡拓撲結構。
2. 網絡實驗室：650 多個與 MITRE ATT&CK 映射的實踐實驗室，基於瀏覽器且自動評分。
3. 競賽套件：遊戲化競賽（CTF、紅藍對抗、戰爭遊戲）。

關鍵統計數據

• 全球 30,000 多個活躍用戶
• 650 多個實踐實驗室
• 1,400 多個模擬配置文件
• 舉辦 500 多個活動
• 服務 45 多個國家
• 250 多個小時的培訓內容

目標受眾

• 學生：通過 CTF 挑戰和排行榜進行以職業為導向的培訓。
• 學術界：與 LMS 集成並自動評分的課程。
• 企業：技術招聘評估、團隊培訓、合規映射。
• 政府：氣隙部署、OT/SCADA 模擬、關鍵基礎設施防禦。

部署選項

• 雲託管 SaaS（基於瀏覽器，無需安裝）
• 本地部署（VMware、Proxmox、裸機）
• 機密環境的氣隙部署

📦 安裝指南

克隆倉庫

cyberedu-client 作為 Git 子模塊包含在內。使用 --recursive 參數進行克隆以獲取所有內容：

git clone --recursive https://github.com/CyberEDU-Cyber-Range/cyberedu-mcp.git
cd cyberedu-mcp

如果之前克隆時未使用 --recursive 參數，可以初始化子模塊：

git submodule update --init --recursive

安裝包

安裝客戶端和 MCP 服務器兩個包：

macOS/Linux：

python3 -m venv venv  
source venv/bin/activate
pip install -e ".[local]"      # 使用本地 cyberedu-client 子模塊進行安裝
# 或者用於開發：
# pip install -e ".[local,dev]"

Windows（PowerShell）：

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e ".[local]"      # 使用本地 cyberedu-client 子模塊進行安裝

Windows（命令提示符）：

python -m venv venv
venv\Scripts\activate.bat
pip install -e ".[local]"

替代方法：分別安裝包：

pip install -e ./cyberedu-client
pip install -e .

💻 使用示例

運行 MCP 服務器

可以直接運行服務器進行測試：

macOS/Linux：

python3 -m venv venv

source venv/bin/activate
python -m cyberedu_mcp

Windows：

python -m venv venv
.\venv\Scripts\Activate.ps1
python -m cyberedu_mcp

MCP 客戶端配置

要將此服務器與 MCP 客戶端（Cursor IDE 或 Claude Desktop）一起使用，請將其添加到 MCP 配置中。

重要提示：使用虛擬環境中 Python 可執行文件的完整路徑。MCP 客戶端在外部運行服務器，無法訪問已激活的虛擬環境。

macOS/Linux 示例

Cursor IDE (~/.cursor/mcp.json)：

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Windows 示例

Cursor IDE (%APPDATA%\Cursor\User\mcp.json 或 C:\Users\YourName\.cursor\mcp.json)：

{
  "mcpServers": {
    "cyberedu": {
      "command": "C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json)：

{
  "mcpServers": {
    "cyberedu": {
      "command": "C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

跨平臺示例

VS Code (.vscode/mcp.json 在工作區中)：

{
  "servers": {
    "cyberedu": {
      "type": "stdio",
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Windows：使用 C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe

Antigravity / Windsurf (mcp_config.json - 通過 MCP 商店 → 管理 MCP 服務器 → 查看原始配置訪問)：

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"],
      "env": {}
    }
  }
}

Windows：使用 C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe

注意：會話憑證會持久化到 ~/.cyberedu-mcp/session.json，因此在通過 cyberedu_set_session_cookie 工具進行首次身份驗證後，無需再設置環境變量。

可用工具

服務器會自動將 CyberEduClient 中的所有公共方法作為 MCP 工具公開。工具以 cyberedu_ 為前綴，以避免命名衝突。

會話管理工具

這些工具允許你在不重啟 MCP 服務器的情況下管理身份驗證和租戶切換。憑證會自動持久化到 ~/.cyberedu-mcp/session.json：

• cyberedu_get_session_status - 檢查是否已認證、選擇了哪個租戶以及憑證是否已持久化。
• cyberedu_set_session_cookie - 設置/更新用於身份驗證的會話 cookie（持久化到磁盤）。
• cyberedu_switch_tenant - 切換到不同的租戶/組織（持久化到磁盤）。
• cyberedu_clear_session - 從磁盤和內存中清除存儲的憑證。

示例用法：

1. 檢查狀態："What's my CyberEdu session status?"
2. 設置 cookie："Set my CyberEdu session cookie to eyJ..."（僅需設置一次，會持久化！）
3. 切換租戶："Switch to tenant myorg"
4. 清除憑證："Clear my CyberEdu session"

身份驗證和用戶工具

• cyberedu_check_auth - 驗證身份驗證並獲取用戶信息。
• cyberedu_get_user_info - 獲取完整的用戶信息。
• cyberedu_list_tenants - 列出所有可用的租戶。
• cyberedu_get_current_tenant_info - 獲取當前租戶的信息。
• cyberedu_get_user - 通過 ID 獲取用戶信息。

挑戰工具（存檔）

• cyberedu_list_challenges - 列出所有挑戰（可選過濾條件）。
• cyberedu_get_challenge - 獲取挑戰詳情。
• cyberedu_get_challenge_difficulties - 獲取可用的難度級別。
• cyberedu_get_challenge_tags - 獲取可用的挑戰標籤。
• cyberedu_subscribe_to_challenge - 訂閱挑戰。

旗幟和提交工具（存檔）

• cyberedu_get_flag - 獲取旗幟/問題信息。
• cyberedu_submit_flag - 提交旗幟/答案。

文件工具（存檔）

• cyberedu_download_file - 下載挑戰文件（使用可選的 save_path 參數直接保存到磁盤）。

服務工具（存檔）

• cyberedu_start_service - 啟動挑戰服務。
• cyberedu_get_service_status - 獲取服務狀態。
• cyberedu_extend_service - 延長服務時間。
• cyberedu_restart_service - 重啟服務。

競賽工具

• cyberedu_list_contests - 列出所有可用的競賽。
• cyberedu_get_contest - 獲取競賽詳情。
• cyberedu_get_contest_ranks - 獲取競賽排行榜。
• cyberedu_get_contest_challenge - 獲取競賽中的挑戰詳情。
• cyberedu_subscribe_to_contest_challenge - 訂閱競賽挑戰。

競賽旗幟和提交工具

• cyberedu_get_contest_flag - 獲取競賽中的旗幟信息。
• cyberedu_submit_contest_flag - 提交競賽中的旗幟。

競賽文件工具

• cyberedu_download_contest_file - 從競賽挑戰中下載文件（使用可選的 save_path 參數直接保存到磁盤）。

競賽服務工具

• cyberedu_start_contest_service - 啟動競賽中的服務。
• cyberedu_get_contest_service_status - 獲取競賽中的服務狀態。
• cyberedu_extend_contest_service - 延長競賽中的服務時間。
• cyberedu_restart_contest_service - 重啟競賽中的服務。

使用示例和提示

與 CyberEdu MCP 服務器交互的示例提示：

會話和身份驗證

"Check my CyberEdu session status"
"Set my CyberEdu session cookie to eyJpdiI6Ik..."
"Switch to tenant 'mycompany'"

挑戰（存檔）

"List all web security challenges"
"Show me the easiest challenges from tenant unbreakable/rocsc"
"Show me hard difficulty forensics challenges"
"Get details for challenge abc123"
"Subscribe me to this challenge and start the service"
"Download challenge files to ./downloads/"
"Submit flag 'CTF{i-like-web-security-ctf-challenges}' for this challenge"

競賽

"List available CTF contests"
"Show leaderboard for contest 'defcamp ctf quals 2025'"
"Get challenge abc123 from contest 'rocsc26-quals'"
"Start service for this contest challenge"
"Submit flag 'FLAG{solved}' for contest challenge"

工作流示例

1. "List easy web challenges from tenant rocsc"
2. "Subscribe to 'why-xor' and start the service"
3. "Download the challenge files"
4. [Solve...]
5. "Submit flag 'CTF{xor-is-not-safe}'"

🔧 技術細節

動態工具發現

服務器使用 Python 的 inspect 模塊自動發現 CyberEduClient 類中的所有公共方法。對於每個方法：

1. 方法發現：掃描類中的公共方法（排除私有方法和輔助方法）。
2. 模式生成：根據方法簽名和類型提示自動生成 JSON 模式。
3. 工具註冊：將每個方法作為 MCP 工具註冊，並附帶適當的元數據。

工具註冊表

ToolRegistry 類提供了一個靈活的工具管理系統：

• 自動發現：使用自省功能從類中發現方法。
• 手動註冊：允許手動註冊自定義方法。
• 分類組織：自動對方法進行分類（身份驗證、挑戰、競賽、服務等）。

可擴展性

要添加新功能：

1. 向 CyberEduClient 添加方法：只需向 CyberEduClient 類添加新的公共方法。
2. 自動公開：MCP 服務器將自動發現並公開新方法。
3. 無需更改 MCP 代碼：無需對 MCP 服務器代碼進行更改。

對於不直接映射到客戶端方法的自定義工具：

from cyberedu_mcp.tool_registry import ToolRegistry

registry = ToolRegistry()

def custom_tool(param1: str, param2: int) -> dict:
    """Custom tool description."""
    return {"result": f"{param1}: {param2}"}

registry.register_method(
    name="custom_tool",
    method=custom_tool,
    description="A custom tool",
    category="custom"
)

錯誤處理

服務器提供全面的錯誤處理：

• HTTP 錯誤：返回詳細的 HTTP 錯誤信息，包括狀態碼和響應體。
• 驗證錯誤：為缺失或無效的參數返回清晰的錯誤消息。
• 客戶端錯誤：為所有異常返回結構化的錯誤信息。

📚 詳細文檔

更多文檔可在 docs/ 文件夾中找到：

• docs/index.md - 文檔概述和快速參考。
• docs/architecture.md - 服務器設計、工具發現和會話管理。
• docs/extending.md - 如何添加自定義工具和修改行為。

📄 許可證

MIT