LudusMCP

开发 TypeScript

🚀 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

安装过程说明：

下载源代码和依赖项
为您的平台（Windows/Linux/macOS）编译原生依赖项（keytar）
将 TypeScript 源代码编译为 JavaScript（src/ → dist/）
在您的 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）时，它会自动执行以下操作：

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

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

手动服务器测试（可选）

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

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

服务器启动过程：

加载凭证：从操作系统钥匙串中检索存储的凭证
下载资源：从 GitHub 更新基本配置、模式和文档
连接测试：通过 WireGuard/SSH 验证与 Ludus 服务器的连接
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 - 将凭证注入配置（注意：大语言模型实际上不会与操作系统凭证管理/钥匙串进行交互。它将凭证存储的名称传递给函数，函数检索凭证并将占位符替换为凭证。

复杂或高级 CLI 操作

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

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

📚 详细文档

角色和集合模式

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

模式位置

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

模式工具

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

添加自定义模式

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

在 ~/.ludus-mcp/schemas/ 中创建一个 YAML 文件，遵循标准格式
使用独特的名称以避免冲突（例如，company.custom_role.yaml）
包含所有必需字段：name、type、description、variables
参考模式目录中的 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。

0 条评论
分类：开发