Ludusmcp

🚀 LudusMCP

LudusMCPは、自然言語コマンドを通じてLudusラボ環境を管理するためのModel Context Protocolサーバーです。このサーバーにより、ユーザーは自然言語でLudus環境を操作し、効率的な管理が可能になります。

🚀 クイックスタート

詳細な情報については、ウィキを参照してください。

✨ 主な機能

• 自然言語コマンドを使用したLudusラボ環境の管理
• セキュアな資格情報管理
• 様々なツールを使用した範囲管理、構成管理、ドキュメント検索などの機能

📦 インストール

注意 MCPサーバーのインストールはLudusサーバーではなく、LudusサーバーにアクセスできるMCPクライアント（例：Claude Desktop）があるデバイスに行います。

グローバルインストール（推奨）

パッケージをグローバルにインストールして、システム全体で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
From within LudusMCP directory
npm install    # Installs dependencies and builds automatically
npx ludus-mcp --setup-keyring  # Use npx for local from source installations by running it from within clone/install directory

インストール要件

パッケージには、インストール中にコンパイルが必要なネイティブ依存関係が含まれています。

• ビルドツール：Node.jsビルドツール（自動的にインストールされます）
• プラットフォームライブラリ：OS資格情報マネージャーライブラリ（Windows Credential Manager、macOS Keychain、Linux libsecret）

インストールが失敗した場合は、プラットフォーム用の適切なビルドツールがインストールされていることを確認してください。

💻 使用例

基本的な使用法

通常の操作では、MCPクライアント（Claude Desktop）を起動すると、自動的に以下のことが行われます。

# サーバーが自動的に起動され、資格情報を読み込み、GitHubから最新の構成とスキーマをダウンロードし、Ludusサーバーへの接続をテストし、MCPプロトコルを開始します。

高度な使用法

サーバーを手動でテストする場合は、以下のコマンドを実行します。

ludus-mcp  # If globally installed
# OR
npx ludus-mcp  # run from cloned directory if locally installed

サーバー起動プロセス：

1. 資格情報の読み込み - OSキーリングから保存された資格情報を取得します。
2. アセットのダウンロード - GitHubから基本構成、スキーマ、およびドキュメントを更新します。
3. 接続テスト - WireGuard/SSHを介してLudusサーバーへの接続を確認します。
4. MCPプロトコル - ツール通信のためのModel Context Protocolサーバーを起動します。

利用可能なプロンプト

create-ludus-range 要件からデプロイまでの範囲作成のガイド付きワークフローを完了します。

execute-ludus-cmd 破壊的なアクション保護付きでLudus CLIコマンドを安全に実行します。

• Claude Desktopでプロンプトを使用するには、チャットバーの近くの「プラス」+ボタンを探します。
  • 「add from ludus」をクリックすると、両方のプロンプトが表示されます。使用したいものを選択します。

利用可能なツール

範囲管理

• deploy_range - 仮想化トレーニング環境をデプロイします。
• get_range_status - デプロイステータスとVMの状態を確認します。
• list_user_ranges - ユーザーのすべての範囲をリストします。
• get_connection_info - RDP/VPN接続ファイルをダウンロードします。
• destroy_range - 範囲とVMを永久に削除します。
• range_abort - 固まったデプロイを停止します。
• ludus_power - 範囲のVMを起動/停止します。

構成管理

• 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 - 構成に資格情報を挿入します（注：LLMは実際にはOS資格情報管理/キーリングとは一切やり取りせず、資格情報が保存されている名前を関数に渡します。関数が資格情報を取得し、プレースホルダーを資格情報で置き換えます）。

推奨ワークフロー

1. 範囲を計画する create-ludus-rangeプロンプトを使用して、ガイド付きの範囲作成を行います。

   Requirements: "AD environment with SCCM and 3 workstations"
   

2. 構成を確認する list_range_configsを使用して利用可能なテンプレートを確認し、read_range_configを使用して詳細を調べます。
3. デプロイ前に検証する 構成を設定する前に、常にvalidate_range_configを実行してください。
4. アクティブな構成を設定する set_range_configを使用して、デプロイ用のアクティブな構成を設定します。
5. 範囲をデプロイする deploy_rangeを使用して、仮想化環境を作成します。
6. 接続情報を取得する get_connection_infoを使用して、RDPファイルをダウンロードし、VMにアクセスします。

広範または高度なCLI操作

特定のツールでカバーされていない操作には、execute-ludus-cmdプロンプトを使用します。

Command Intent: "Check detailed logs for deployment issues"

📚 ドキュメント

ファイルの場所

構成ファイルとデータは~/.ludus-mcp/に保存されます。

~/.ludus-mcp/
├── range-config-templates/
│   └── base-configs/           # GitHub templates (auto-updated)
├── schemas/                    # Role/collection schemas (auto-updated)
│   ├── Sample-schema.yaml     # Template for custom schemas
│   ├── ludus_sccm.yaml        # Individual role schemas
│   ├── badsectorlabs.ludus_vulhub.yaml
│   ├── custom_role.yaml       # Your custom schemas (preserved)
│   └── range-config.json      # Range configuration schema
└── ludus-docs/                 # Cached documentation (auto-updated)
    ├── environment-guides/
    ├── quick-start/
    └── troubleshooting/

公式ファイルはサーバー起動時に自動的にダウンロードされ、更新されます。ユーザーが作成したカスタムファイルは保持されます。

セキュリティ

• これはラボでの使用のみを目的としています。セキュリティは限られています。OSコマンドインジェクションやパストラバーサルを制限する試みが行われています。また、資格情報はOS資格情報マネージャーを介して処理されます。

資格情報管理

• 外部サービスの資格情報（APIキー、SaaSトークン）はプレースホルダー形式{{LudusCredName-<user>-<name>}}を使用します。
• 範囲内の資格情報（ADパスワード、ドメインアカウント）は直接含まれます。
• すべての資格情報はOS資格情報マネージャーに保存されます。
• 資格情報収集にはセキュアなダイアログが使用されます。

ネットワークセキュリティ

• サーバー通信にはWireGuard VPN暗号化が使用されます。
• キーベースの認証を使用したSSHトンネルがフォールバックとして使用されます。
• SSL証明書検証（設定可能）

運用安全性

• 破壊的な操作には明示的な確認が必要です。
• デプロイ前に構成の自動検証が行われます。
• 包括的なロギングとエラー処理が行われます。

トラブルシューティング

接続問題

• WireGuardトンネルがアクティブであることを確認します：wg show
• SSH接続をテストします：ssh user@ludus-host
• APIキーを確認します：ludus --url https://your-server:8080 version

構成問題

• validate_range_configを実行して構文をチェックします。
• ludus_read_range_config_schemaを使用して構造を検証します。
• ログを確認して特定のエラーメッセージを探します。

資格情報問題

• セットアップを再実行します：npx ludus-mcp --renew-keyring
• OS資格情報マネージャーへのアクセスを確認します。
• 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 Documentation - https://docs.ludus.cloud/docs/intro

これからの変更点

• 現在の独自のキーリング構成/更新機能の代わりに、Desktop Extensionのセットアップに切り替える可能性があります。
• ネットワーク上の任意のデバイスからLudusとやり取りできるリモートMCPサーバーバージョンを作成する可能性があります。
• より多くのサンプル参照テンプレートを追加します。
• 新しいロールをLLM参照用のスキーマに追加することで、追跡を試みます。

クレジット

• Ludus - @badsectorlabs
• Claude - このプロジェクトをバイブコーディングとは言えないかもしれませんが、車の助手席で4杯のビールを飲みながらナビゲーションコマンドを叫ぶような感じです。
• Reddit MCPチャンネル - 多くの調査に役立ちました。
• MCP documentation - https://modelcontextprotocol.io/introduction
• Anthropic MCP docs - https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector
• MCP in VS Code - https://code.visualstudio.com/docs/copilot/chat/mcp-servers

📄 ライセンス

GNU General Public License v3.0