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。