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