Cyberedu Mcp Server

CyberEdu MCP 服务

这是 CyberEdu CTF 平台（https://cyber-edu.co / https://cyberedu.ro）的官方 Model Context Protocol（MCP）服务。此服务会自动发现并将 CyberEduClient 中的所有方法公开为 MCP 工具，方便通过兼容 MCP 的客户端与 CyberEdu 平台交互。

功能

• 动态工具发现：自动发现 CyberEduClient 中的所有公共方法，并将其公开为 MCP 工具
• 新增方法无需配置：向 CyberEduClient 添加新方法后，这些方法会自动成为可用的 MCP 工具，无需修改代码
• 类型安全：根据方法签名和类型提示自动生成 JSON 架构
• 错误处理：完善的错误处理机制，并提供详细的错误消息

CyberEDU 平台概述

CyberEDU 是一个网络安全培训平台，提供动手实验、逼真的模拟环境和竞技环境。该平台面向企业安全团队、学术机构、政府机构以及个人学习者。

核心介绍

CyberEDU 是一个综合性的网络安全培训平台，提供动手实验、逼真的模拟环境和竞技环境。该平台面向企业安全团队、学术机构、政府机构以及希望通过真实场景培养实用网络安全技能的个人学习者。

主要优势

• 动手实践：交互式网络靶场，用户可以攻击和防御真实基础设施（而非只看视频或学习理论）
• MITRE ATT&CK 映射：场景映射到 MITRE ATT&CK，并使用真实恶意软件样本（在安全环境中隔离）
• 更好的知识留存：与被动学习相比，技能留存效果提升 3.5 倍
• 真实场景：模拟实际对手技术和攻击模式

平台组件

1. Cyber Range — 企业级网络战争模拟，包含复杂的网络拓扑
2. Cyber Labs — 650 多个映射到 MITRE ATT&CK、基于浏览器且自动评分的动手实验
3. Tournament Suite — 游戏化竞赛（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]"      # Installs with local cyberedu-client submodule
# Or for development:
# pip install -e ".[local,dev]"

Windows（PowerShell）：

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e ".[local]"      # Installs with local cyberedu-client submodule

Windows（命令提示符）：

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

替代方案：分别安装软件包：

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

配置

会话持久化（推荐）

MCP 服务会自动将会话凭据持久化到磁盘。这意味着：

• 使用 cyberedu_set_session_cookie 工具设置一次 Cookie，之后该 Cookie 会在各个 MCP 会话中保留
• 首次认证后，无需设置环境变量
• 切换租户时会保留租户选择

会话文件位置：

• macOS/Linux：~/.cyberedu-mcp/session.json
• Windows：%USERPROFILE%\.cyberedu-mcp\session.json（例如，C:\Users\YourName\.cyberedu-mcp\session.json）

在 Unix 系统上，该文件的权限受到限制（仅所有者可读写），以确保安全。

环境变量（替代方式）

你也可以使用环境变量。服务会按以下优先级加载凭据：

1. 磁盘上持久化的凭据（优先级最高）
2. 环境变量
3. 默认值

环境变量：

• CYBEREDU_SESSION_COOKIE：你的 CyberEdu 会话 Cookie
  • 登录 https://app.cyber-edu.co 后，可从浏览器的开发者工具中获取
  • 找到 cyberedu_session Cookie 的值
• CYBEREDU_TENANT：你的租户标识符（可选，默认为 "cyberedu"）

获取会话 Cookie

Chrome/Edge：

1. 打开开发者工具（F12）
2. 转到 Application/Storage 标签页
3. 导航至 Cookies → https://app.cyber-edu.co
4. 找到 cyberedu_session 并复制其值

Firefox：

1. 打开开发者工具（F12）
2. 转到 Storage 标签页
3. 导航至 Cookies → https://app.cyber-edu.co
4. 找到 cyberedu_session 并复制其值

用法

运行 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 store → Manage MCP Servers → View raw config 访问）：

{
  "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. 检查状态：“我的 CyberEdu 会话状态是什么？”
2. 设置 Cookie：“将我的 CyberEdu 会话 Cookie 设置为 eyJ...”（只需设置一次，之后会持久保存！）
3. 切换租户：“切换到租户 myorg”
4. 清除凭据：“清除我的 CyberEdu 会话”

身份验证与用户工具

• 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 - 订阅挑战

Flag 与提交工具（存档）

• cyberedu_get_flag - 获取 Flag／问题信息
• cyberedu_submit_flag - 提交 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 - 订阅竞赛挑战

竞赛 Flag 与提交工具

• cyberedu_get_contest_flag - 获取竞赛中的 Flag 信息
• cyberedu_submit_contest_flag - 提交竞赛中的 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