Ludusmcp

🚀 LudusMCP

LudusMCP 是一个模型上下文协议（MCP）服务器，可通过自然语言命令管理 Ludus 实验室环境，为用户提供便捷、高效的环境管理体验。

🚀 快速开始

LudusMCP 是用于通过自然语言命令管理 Ludus 实验室环境的模型上下文协议服务器。在使用前，请确保满足以下先决条件，并按照安装和配置步骤进行操作。

✨ 主要特性

• 自然语言交互：支持通过自然语言命令管理 Ludus 实验室环境。
• 多方式连接：提供 WireGuard VPN 和 SSH 隧道两种连接方式。
• 安全的凭证管理：使用操作系统的凭证管理器安全存储凭证。
• 丰富的工具和提示：提供多种工具和提示，方便用户进行范围管理、配置管理等操作。

📦 安装指南

安装前提

系统要求

• Node.js 18.0.0 或更高版本
• npm 包管理器
• Ludus CLI 二进制文件 已安装，并在运行 mcp-client（如 Claude Desktop）的主机的 PATH 中
• 活跃的 Ludus 服务器环境
• 通过 WireGuard VPN 或 SSH 与 Ludus 服务器建立网络连接

Ludus 服务器访问权限

确保您具备以下条件：

• Ludus 服务器 SSH 访问凭证
• Ludus API 密钥（通过 ludus user apikey 命令获取）
• WireGuard 配置文件或 SSH 隧道功能（从 Ludus CLI 获取 WireGuard 配置）
• Ludus 服务器上的管理员或用户账户。非管理员账户的使用方式将受到与使用非管理员账户的 Ludus CLI 相同的限制。

安装方式

全局安装（推荐）

全局安装该包，使 ludus-mcp 命令在系统范围内可用：

npm install -g ludus-mcp@latest
ludus-mcp --setup-keyring

安装过程说明：

1. 下载源代码和依赖项
2. 为您的平台（Windows/Linux/macOS）编译原生依赖项（keytar）
3. 将 TypeScript 源代码编译为 JavaScript（src/ → dist/）
4. 在您的 PATH 中创建全局 ludus-mcp 命令

这是一个一次性安装过程，会为您的特定平台编译所有内容。

从源代码安装（开发用途）

git clone https://github.com/NocteDefensor/LudusMCP.git
cd LudusMCP
# 在 LudusMCP 目录内
npm install    # 安装依赖项并自动构建
npx ludus-mcp --setup-keyring  # 从克隆/安装目录中运行，使用 npx 进行本地源代码安装

安装要求

该包包含在安装过程中需要编译的原生依赖项：

• 构建工具：Node.js 构建工具（自动安装）
• 平台库：操作系统凭证管理库（Windows 凭证管理器、macOS 钥匙串、Linux libsecret）

如果安装失败，请确保您具备适用于您平台的正确构建工具。

💻 使用示例

正常操作

当您启动 MCP 客户端（Claude Desktop）时，它会自动执行以下操作：

1. 启动预编译的 ludus-mcp 服务器
2. 服务器从操作系统钥匙串加载凭证
3. 从 GitHub 下载最新的配置
4. 下载更新的模式和文档
5. 测试与 Ludus 服务器的连接
6. 启动 MCP 协议以进行工具通信

无需手动启动服务器，MCP 客户端会处理一切。

手动服务器测试（可选）

为了进行故障排除或独立测试服务器，请执行以下操作：

ludus-mcp  # 如果是全局安装
# 或者
npx ludus-mcp  # 如果是本地安装，请从克隆目录中运行

服务器启动过程：

1. 加载凭证：从操作系统钥匙串中检索存储的凭证
2. 下载资源：从 GitHub 更新基本配置、模式和文档
3. 连接测试：通过 WireGuard/SSH 验证与 Ludus 服务器的连接
4. MCP 协议：启动模型上下文协议服务器以进行工具通信

可用提示

create-ludus-range

完成从需求到部署的范围创建引导式工作流程。

execute-ludus-cmd

安全执行 Ludus CLI 命令，并提供破坏性操作保护。

• 要在 Claude Desktop 中使用提示，请在聊天栏附近找到“加号” + 按钮。
  • 点击“从 ludus 添加”，您将看到两个提示。选择您需要的提示。

可用工具

范围管理

• deploy_range - 部署虚拟化训练环境
• get_range_status - 检查部署状态和虚拟机状态
• list_user_ranges - 列出用户的所有范围
• get_connection_info - 下载 RDP/VPN 连接文件
• destroy_range - 永久删除范围和虚拟机
• range_abort - 停止卡住的部署
• ludus_power - 启动/停止范围虚拟机

配置管理

• read_range_config - 读取配置文件
• write_range_config - 创建/修改范围配置
• validate_range_config - 验证 YAML 语法和模式
• list_range_configs - 浏览可用模板
• get_range_config - 获取当前活动配置
• set_range_config - 设置用于部署的活动配置

文档与研究

• ludus_docs_search - 搜索 Ludus 文档
• ludus_range_planner - 智能范围规划助手
• ludus_roles_search - 搜索可用的 Ludus 角色
• ludus_environment_guides_search - 查找环境设置指南
• ludus_networking_search - 网络配置帮助
• ludus_read_range_config_schema - 查看配置模式
• ludus_range_config_check_against_plan - 根据需求验证配置
• ludus_read_role_collection_schema - 查看角色模式
• ludus_list_role_collection_schemas - 列出所有可用的角色/集合模式

实用工具与管理

• ludus_cli_execute - 执行任意 Ludus CLI 命令
• ludus_help - 获取 Ludus 命令的帮助
• list_all_users - 列出所有 Ludus 用户（仅限管理员）
• get_credential_from_user - 安全收集凭证
• insert_creds_range_config - 将凭证注入配置（注意：大语言模型实际上不会与操作系统凭证管理/钥匙串进行交互。它将凭证存储的名称传递给函数，函数检索凭证并将占位符替换为凭证。

推荐工作流程

1. 规划范围 使用 create-ludus-range 提示进行引导式范围创建：

需求："具有 SCCM 和 3 个工作站的 AD 环境"

2. 查看配置 使用 list_range_configs 查看可用模板，并使用 read_range_config 检查它们。
3. 部署前验证 在设置配置之前，始终运行 validate_range_config。
4. 设置活动配置 使用 set_range_config 使配置可用于部署。
5. 部署范围 使用 deploy_range 创建虚拟化环境。
6. 获取连接信息 使用 get_connection_info 下载 RDP 文件并访问虚拟机。

复杂或高级 CLI 操作

对于特定工具未涵盖的操作，请使用 execute-ludus-cmd 提示：

命令意图："检查详细日志以查找部署问题"

📚 详细文档

角色和集合模式

MCP 服务器维护所有可用 Ludus 角色和集合的详细模式，以帮助大语言模型在范围规划期间理解角色功能、变量和需求。

模式位置

官方模式存储在 ~/.ludus-mcp/schemas/ 中，每个角色或集合对应一个单独的 YAML 文件。这些文件在服务器启动时会自动从 GitHub 存储库下载和更新。

模式工具

• ludus_list_role_collection_schemas - 列出所有可用的角色/集合模式文件
• ludus_read_role_collection_schema - 读取模式数据（所有模式或特定文件）

添加自定义模式

要为不在官方存储库中的自定义角色或第三方角色添加模式，请执行以下操作：

1. 在 ~/.ludus-mcp/schemas/ 中创建一个 YAML 文件，遵循标准格式
2. 使用独特的名称以避免冲突（例如，company.custom_role.yaml）
3. 包含所有必需字段：name、type、description、variables
4. 参考模式目录中的 Sample-schema.yaml 以获取正确的格式和结构

模式持久化

自定义模式在服务器重启期间会保留。更新过程仅会覆盖存储库中的官方模式，而不会影响您的自定义文件。

过滤读取

使用 ludus_read_role_collection_schema 并指定 file_names 参数以读取特定模式，而不是一次性读取所有模式。

文件位置

配置文件和数据存储在 ~/.ludus-mcp/ 中：

~/.ludus-mcp/
├── range-config-templates/
│   └── base-configs/           # GitHub 模板（自动更新）
├── schemas/                    # 角色/集合模式（自动更新）
│   ├── Sample-schema.yaml     # 自定义模式模板
│   ├── ludus_sccm.yaml        # 单个角色模式
│   ├── badsectorlabs.ludus_vulhub.yaml
│   ├── custom_role.yaml       # 您的自定义模式（保留）
│   └── range-config.json      # 范围配置模式
└── ludus-docs/                 # 缓存的文档（自动更新）
    ├── environment-guides/
    ├── quick-start/
    └── troubleshooting/

官方文件在服务器启动时会自动下载和更新。您创建的自定义文件将被保留。

🔧 技术细节

安全

凭证管理

• 外部服务凭证（API 密钥、SaaS 令牌）使用占位符格式：{{LudusCredName-<用户>-<名称>}}
• 范围内部凭证（AD 密码、域账户）直接包含
• 所有凭证存储在操作系统凭证管理器中
• 安全对话框用于凭证收集

网络安全

• WireGuard VPN 加密用于服务器通信
• SSH 隧道回退，使用基于密钥的身份验证
• SSL 证书验证（可配置）

操作安全

• 破坏性操作需要明确确认
• 部署前自动验证配置
• 全面的日志记录和错误处理

故障排除

连接问题

• 验证 WireGuard 隧道是否活跃：wg show
• 测试 SSH 连接：ssh 用户@ludus-主机
• 检查 API 密钥：ludus --url https://您的服务器:8080 version

配置问题

• 运行 validate_range_config 检查语法
• 使用 ludus_read_range_config_schema 验证结构
• 检查日志以获取特定错误消息

凭证问题

• 重新运行设置：npx ludus-mcp --renew-keyring
• 验证操作系统凭证管理器的访问权限
• 检查 WireGuard 配置文件的权限

常见错误

• "No configuration available"：运行 --setup-keyring
• "Range operations connectivity failed"：检查 WireGuard/SSH
• "Schema validation failed"：使用 validate_range_config 工具

帮助

如需更多帮助：

• 使用 ludus_help 工具获取 Ludus CLI 文档
• 使用 ludus_docs_search 获取全面指南
• 使用 read_range_config 查看生成的配置
• 查看 GitHub 存储库 以获取问题和更新信息

参考资料

• Ludus 文档 - https://docs.ludus.cloud/docs/intro

即将到来的更改

• 可能会切换到 桌面扩展 设置，而不是当前的自定义钥匙串配置/更新功能。
• 可能会推出远程 mcp 服务器版本，以便在网络上的任何设备上与 ludus 进行交互，而无需安装 ludus cli 等。
• 将添加更多示例参考模板。
• 将尝试通过将新角色添加到模式中，以跟上新角色的更新，供大语言模型参考。

鸣谢

• Ludus - @badsectorlabs
• Claude - 这个项目虽然不能完全称为氛围编程，但也许就像坐在副驾驶座上喝了 4 瓶啤酒后喊出导航命令一样有趣。
• Reddit MCP 频道提供了很多研究资料
• MCP 文档 - https://modelcontextprotocol.io/introduction
• Anthropic MCP 文档 - https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector
• VS Code 中的 MCP - https://code.visualstudio.com/docs/copilot/chat/mcp-servers

📄 许可证

本项目采用 GNU 通用公共许可证 v3.0。