🚀 VibeCraft

Minecraft用のAI搭載WorldEdit — AIアシスタントとの自然言語対話を通じて、壮大な建造物を構築します。

✨ 主な機能

• 🎯 46のMCPツール – 構造化されたツールと安全対策を備えた、完全なWorldEditカバレッジ（130以上のコマンド）
• ⚡ 高速実行 – リアルタイムのコマンド実行とフィードバックを伴う直接的なRCON接続
• 🤖 AIネイティブ設計 – トークン最適化されたコンテキストファイル、専門エージェントのプロンプト、構造化されたワークフロー
• 🏗️ スマートな建造ツール – 家具配置、建築パターン、パラメトリックテンプレート、地形生成
• 🧠 空間認識 – 高速かつ正確なスキャンにより、一般的な配置エラーを防止する高度なシステム
• 📚 知識ベース – 1,375のMinecraftアイテム、70以上のパターン、66の家具デザイン、スケール参照
• 🧰 コンテキスト認識型建造 – AIは精選されたドキュメントを読み取り、WorldEditが適さない場合でも、ブロックパレット、家具レイアウト、デフォルトの/fillワークフローを用いて計画を立案できます
• 🛠️ 本番環境対応 – Dockerベースのセットアップ、自動テスト、包括的なエラーハンドリング
• 🔄 マルチクライアント対応 – Claude Code、Claude Desktop、Cursor、およびMCP互換のAIで動作します

コンテキストライブラリとデフォルトコマンド

VibeCraftは単なるWorldEditのラッパーではありません。リポジトリには、context/に完全なAI読み取り可能な知識ベースが含まれています。ブロックカタログ、建築パターン、家具レイアウト、スケール参照、地形レシピなどが含まれます。エージェントは建造する前にこれらのファイルを読み取り、材料、比率、スタイル規則を理解します。タスクがバニラの/fillまたは/setblockワークフロー（農場プロット、レッドストーンの詳細、小さな室内調整）を必要とする場合、追加のコンテキストにより、AIは標準コマンドとWorldEditを組み合わせて正確な結果を得ることができます。

📦 インストール

前提条件

• uv — 高速なPythonパッケージマネージャ — curl -LsSf https://astral.sh/uv/install.sh | shでインストール
• Python 3.10以上 — ダウンロード
• Docker Compose付きのDocker Desktop — ダウンロード
• MCP互換のAIクライアント — Claude Code、Claude Desktop、またはCursor

セットアップ

1. クローンしてセットアップスクリプトを実行する：

git clone https://github.com/amenti-labs/vibecraft.git
cd vibecraft
./setup-all.sh

このスクリプトは自動的に以下を行います：

• ✅ uv（高速で最新のPythonパッケージマネージャ）で依存関係をインストールする
• ✅ DockerでPaperMC 1.21.3 + WorldEdit 7.3.17をダウンロードして起動する
• ✅ セキュアに自動生成されたパスワードでRCONを設定する
• ✅ AIクライアントの設定ファイルを作成する
• ✅ すべての接続をテストする

2. サーバーモードを選択する： VibeCraftは2つの実行方法をサポートしています。

モード1：stdio/コマンドモード（単一クライアントにおすすめ）

最適な使用シーン： 日常使用、シンプルなセットアップ、単一のAIクライアント AIクライアントは必要に応じてMCPサーバーをサブプロセスとして起動します。

設定：

この設定を追加します：
```json
{
  "mcpServers": {
    "vibecraft": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.vibecraft.server"],
      "cwd": "/absolute/path/to/vibecraft/mcp-server",
      "env": {
        "VIBECRAFT_RCON_HOST": "127.0.0.1",
        "VIBECRAFT_RCON_PORT": "25575",
        "VIBECRAFT_RCON_PASSWORD": "your_password_from_setup"
      }
    }
  }
}

モード2：HTTP/SSEサーバーモード（デバッグと複数クライアントに最適）

最適な使用シーン： デバッグ、複数のAIクライアント、リアルタイムログの確認 VibeCraftを複数のクライアントが接続できるスタンドアロンサーバーとして実行します。

サーバーを起動する（プロジェクトのルートから）：

# vibecraftのルートディレクトリから
cd mcp-server
./start-vibecraft.sh

次のような表示がされます：

🎮 VibeCraft MCP Server - HTTP/SSE Mode
   All 45 tools available
============================================================
📡 RCON Host: 127.0.0.1:25575
✅ RCON connected
✅ WorldEdit 7.3.17 detected
🚀 Server running at http://127.0.0.1:8765/sse

設定：

SSEモードの利点：

• ✅ すべてのRCONコマンドをリアルタイムで確認できる
• ✅ 完全なログで問題をデバッグできる
• ✅ 複数のAIクライアントを同時に接続できる
• ✅ サーバーを再起動せずにクライアントを再起動できる

3. RCONパスワードを取得する： セットアップが完了した後、パスワードを見つけます：

cat .rcon_password

上記の設定でyour_password_from_setupをこのパスワードに置き換えます。

4. AIクライアントを完全に再起動する

5. セットアップを確認する：

AIに「Minecraftサーバーに接続できますか？」と尋ねます。

AIがサーバー情報で応答したら、建造準備完了です！ 🎉

💻 使用例

建造物の構築

ユーザー: "各角に塔のある15x20の中世城を建てて"
AI: *地形を分析し、基礎を作成し、石レンガで壁を建て、
     角に塔を追加し、城壁を作成し、オークのドアを設置する*

インテリアデザイン

ユーザー: "大ホールにダイニングエリアと玉座を配置して"
AI: *部屋の寸法をスキャンし、椅子付きのダイニングテーブルを配置し、
     シャンデリアを追加し、高台に玉座の台を作成する*

地形整形

ユーザー: "城の周りにオークの木がある起伏のある丘を作って"
AI: *エリアを分析し、パーリンノイズで地形を生成し、
     草と土でテクスチャを適用し、戦略的に木を植える*

高度なプロジェクト

ユーザー: "5つの独特な家、市場、教会がある村を建てて"
AI: *建築テンプレートを使用し、各建造物をカスタマイズし、
     道路を配置し、照明を追加し、室内を家具で飾る*

📚 ドキュメント

MCPアーキテクチャ

VibeCraftは、AIアシスタントをMinecraftに接続するためにModel Context Protocol (MCP) を実装しています：

1. MCPサーバー (Python) — WorldEditコマンドを構造化されたツールとして公開する
2. RCONブリッジ — Minecraftサーバーへの直接接続（モッド不要）
3. AIクライアント — ツール定義を受け取り、自然言語でコマンドを実行する

建造プロセス

1. ユーザーの要求 — AIに対する自然言語の指示
2. AIの計画立案 — 要求を分析し、適切なツールを選択する
3. 空間認識 — 配置エラーを防止するために環境をスキャンする
4. コマンド実行 — RCONを介してWorldEditコマンドを実行する
5. 検証 — 結果を確認し、必要に応じて調整し、完了を報告する

安全機能

• コマンドサニタイズ — すべてのコマンドを実行前に検証する
• 座標境界 — オプションの建造エリア制限
• 非同期防止 — コマンド実行時の競合状態を防止する
• 元に戻しサポート — //undoと//redoによる完全なWorldEdit履歴
• 空間スキャン — 必須のスキャンにより、家具/屋根の配置エラーを防止する

プロジェクト構造

vibecraft/
├── mcp-server/                # コアMCPサーバー
│   ├── src/vibecraft/
│   │   ├── server.py          # メインMCPサーバー
│   │   ├── rcon_manager.py    # RCON接続ハンドラー
│   │   ├── sanitizer.py       # コマンド検証
│   │   ├── tools/             # ツールハンドラー (47のツール)
│   │   └── minecraft_items_loader.py  # アイテムデータベース
│   ├── tests/                 # 単体テスト
│   ├── pyproject.toml         # プロジェクトメタデータと依存関係
│   └── uv.lock                # ロックされた依存関係 (uvによって管理)
├── context/                   # AI知識ベース
│   ├── minecraft_items_filtered.json  # 1,375のアイテム
│   ├── minecraft_furniture_catalog.json  # 66のデザイン
│   ├── building_patterns.json  # 29の建築パターン
│   ├── terrain_patterns.json  # 41の地形パターン
│   └── building_templates.json  # 5つのパラメトリックテンプレート
├── AGENTS/                    # 専門AIプロンプト
│   ├── minecraft-master-planner.md
│   ├── minecraft-shell-engineer.md
│   ├── minecraft-facade-architect.md
│   ├── minecraft-roofing-specialist.md
│   └── minecraft-interior-designer.md
├── SYSTEM_PROMPT.md           # メインAI指示
├── docs/                      # セットアップガイド
├── scripts/                   # ヘルパースクリプト
├── setup-all.sh               # 自動セットアップ
└── docker-compose.yml         # Minecraftサーバー設定

# 使用中に生成される:
minecraft-data/                # Dockerボリューム (ワールド、ログ)
.rcon_password                 # 自動生成されたRCONパスワード
claude-code-config.json        # AIクライアント設定
CLAUDE.md                      # システムプロンプト (SYSTEM_PROMPT.mdのコピー)
mcp-server/.venv/              # Python仮想環境 (uvによって管理)

例1: シンプルな家

ユーザー: "石の壁とオークの屋根の居心地の良いコテージを建てて"

AIが作成する:

• 10×12ブロックの基礎
• 角柱付きのコブルストーンの壁
• 適切な張り出しのあるオークの階段屋根
• 枠付きの窓、オークのドア
• 室内の床と天井

例2: 複雑な城

ユーザー: "本丸、4つの角塔、中庭のある中世の要塞を建てて"

AIが作成する:

• 地形分析と基礎の水平化
• 複数の階層を持つ30×30の本丸
• 壁で接続された4つの8×8の角塔
• 入り口ゲート付きの中庭
• 家具のある室内
• 全体に照明

例3: 景観デザイン

ユーザー: "鯉の池、石畳の道、桜の木のある日本庭園を作って"

AIが作成する:

• 自然な曲線のある池を掘る
• 水とスイレンを配置する
• 飛び石付きの砂利道を作る
• 桜の木（ピンクのコンクリートの葉）を植える
• 石灯籠と竹を追加する

その他の例

詳細な会話形式の例とワークフローについては、examples/ディレクトリを参照してください。

• 基本的な建造 (examples/basic_building_example.txt) — 基本: //pos1と//pos2で位置を設定し、壁/床/屋根を作成し、材料を効果的に使用する
• 家具配置 (examples/furniture_example.txt) — インテリアデザインワークフロー: spatial_awareness_scanを使用して床/天井のレベルを見つけ、家具カタログを参照し、正しく（埋め込まれずに）床に家具を配置し、完全な部屋のレイアウトを作成する
• 地形生成 (examples/terrain_example.txt) — 自然な景観の作成: 丘/山/谷を生成し、リアルなテクスチャを適用し、自然な外観に平滑化する
• MCP設定 (examples/configs/) — Claude Code、Claude Desktop、および他のMCPクライアントの設定ファイルの例 これらは、典型的なAI支援建造ワークフローを示す会話例であり、そのまま使用するか、必要に応じて適応させることができます。

高度な機能

空間認識

高度な空間分析により、一般的な配置エラーを防止します：

• 🏠 床検出 — 正確な床/天井のY座標を見つけます
• 📏 クリアランス分析 — すべての6方向の空間をチェックします
• 🧱 材料検出 — スタイルを一致させるために建築材料を識別します
• 🏗️ 構造分析 — 屋根、壁、建造物と地形を認識します

詳細レベル：

• low (2 - 3秒) — 迅速なチェックのための高速スキャン
• medium (4 - 5秒) — おすすめ — 速度と詳細のバランスが良い
• high (8 - 10秒) — スタイル検出を伴う包括的な分析

建築テンプレート

5つのパラメトリックテンプレートで即座に建造物を作成できます：

• medieval_round_tower — らせん階段付きの円形の塔
• simple_cottage — 煙突付きのカスタマイズ可能な家
• guard_tower — 防御用の見張り塔
• wizard_tower — 神秘的な要素を持つファンタジーの塔
• simple_barn — 素朴な木造の納屋

カスタマイズ可能： 高さ、幅、材料、屋根スタイル、機能

家具システム

66の家具デザインを自動配置できます：

• すべての66の家具に正確なブロック座標があります
• place_furnitureツールを介して自動配置されます
• 空間認識により配置エラーが防止されます
• スタイルが一致する材料が使用されます

パターンライブラリ

建築要素のための70以上のパターンがあります：

• 屋根 (29) — 複数の材料の切妻、寄棟、スラブ、平屋根
• ファサード (11) — 窓、ドア、枠
• 角 (8) — 柱のスタイルと構造要素
• 詳細 (22) — 煙突、装飾要素

最適な結果を得るためのヒント

1. 詳細を具体的にする
   • 良い例: "飛び壁とローズウィンドウのある20×30のゴシック様式の大聖堂を建てて"
   • あまり良くない例: "教会を建てて"
2. 配置前にAIにスキャンさせる
   • AIは自動的に家具や屋根の配置に空間認識を使用します
   • スキャンプロセスを信頼してください — これにより99%の配置エラーが防止されます
3. 建築テンプレートを使って高速化する
   • テンプレートはゼロから建てるよりも10倍速いです
   • 完全にカスタマイズ可能（高さ、材料、機能）
4. 知識ベースを活用する
   • AIは1,375のMinecraftアイテム（Minecraft 1.21.3のブロックとアイテム）にアクセスできます
   • 「利用可能なオークのブロックは何ですか？」と尋ねることで、材料の提案を得ることができます
5. 段階的に建造する
   • 大規模なプロジェクトは段階的に進める方が良いです：外殻 → ファサード → 屋根 → 室内 → 景観
   • AIは各段階に専門エージェントを使用することができます
6. 進捗状況を確認する
   • サーバーに参加する: minecraft://localhost:25565
   • 建造物がリアルタイムで作成されるのを見ることができます

トラブルシューティング

"Minecraftサーバーが起動しない"

# Dockerの状態を確認する
docker ps

# ログを表示する
docker logs -f vibecraft-minecraft

# サーバーを再起動する
docker restart vibecraft-minecraft

"RCON接続に失敗した"

# 接続をテストする
docker exec vibecraft-minecraft rcon-cli list

# パスワードを確認する
cat .rcon_password

# MCPサーバーの設定を確認する
cat mcp-server/.env

"AIがVibeCraftに接続できない"

1. Minecraftサーバーが実行中であることを確認する: docker ps
2. MCP設定がclaude-code-config.jsonと一致することを確認する
3. AIクライアントを完全に再起動する（再読み込みではなく）
4. システムプロンプトが設定されていることを確認する（Claude Codeの場合はCLAUDE.md）
5. RCONをテストする: ./scripts/test-connection.sh

"WorldEditが 'You need to provide a world' と表示する"

このエラーは、WorldEditがRCON/コンソールからワールドコンテキストを決定できない場合に発生します。

修正方法（セットアップスクリプトによって自動的に行われます）：

# セットアップスクリプトは自動的にWorldEditを設定します
# 手動で修正する必要がある場合:
docker exec vibecraft-minecraft bash -c "sed -i 's/^    disallowed-blocks:.*/    disallowed-blocks: []/g' plugins/WorldEdit/config.yml"
docker restart vibecraft-minecraft

別の方法： WorldEditコマンドを実行するときにプレイヤーがオンラインであることを確認してください。WorldEditはアクティブなプレイヤーがワールドコンテキストを提供する場合に最適に動作します。

"WorldEditコマンドが機能しない"

問題： コマンドは実行されるが、ゲーム内で何も起こらない

解決策：

• WorldEditプラグインが読み込まれていることを確認する: 起動時のサーバーログで「WorldEdit」を確認する
• オペレーター権限を持っていることを確認する: サーバーコンソールからop <username>を実行する
• RCONからはカンマ区切りの座標を使用する: //pos1 100,64,100（//pos1 100 64 100ではない）
• 一部のコマンドはプレイヤーコンテキストを必要とする — プレイヤーがオンラインであることを確認する

"サーバーのパフォーマンスの問題"

問題： サーバーの遅延またはWorldEdit操作の低速

解決策：

• Javaバージョンを確認する: java --version（21以上である必要があります）
• 十分なRAMが割り当てられていることを確認する: 少なくとも2GBを割り当てる
• サーバーログを確認する: docker logs vibecraft-minecraft | grep ERROR
• 操作が失敗する場合は、plugins/WorldEdit/config.ymlでWorldEditの制限を増やす

🔧 技術詳細

• パッケージマネージャ: uv（pipより10 - 100倍高速）
• MCPサーバー: Python 3.10以上とMCP SDK
• Minecraftサーバー: PaperMC 1.21.3（最新版）
• WorldEdit: バージョン7.3.17
• RCONプロトコル: ポート25575へのTCP接続
• ツール: 130以上のWorldEditコマンドをカバーする46のMCPツール
• コンテキストウィンドウ: Claudeモデル用に最適化されています（200Kトークン）
• 応答時間: RCONコマンドは100ms未満で実行されます
• 安全性: コマンドサニタイズ、境界チェック、非同期防止
• Docker: 永続的なボリュームを持つコンテナ化されたMinecraftサーバー

MCPツールの内訳

• コア: 2つのツール（RCONコマンド、サーバー情報）
• WorldEdit: 20のツールカテゴリ（選択、領域、生成など）
• 高度: 13のツール（家具、パターン、地形、空間分析）
• 検証: 6つのヘルパーツール（パターン/マスク検証、アイテム検索など）
• テンプレート: 3つのツール（建築テンプレート、スキーマティック、地形パターン）

手動セットアップ（上級者向け）

自動化されたsetup-all.shスクリプトがすべてを処理します。Dockerを使用せずに手動でセットアップする場合、またはインストールをカスタマイズする必要がある場合は、docs/archive/MANUAL_SETUP.mdにアーカイブされた手動セットアップ手順があります：

• 手動でのJavaとPaperMCのインストール
• ソースからのWorldEditプラグインのセットアップ
• 手動でのRCON設定
• カスタムMCPサーバー設定

注意： ほとんどのユーザーには手動セットアップはおすすめしません。自動化されたセットアップの方が高速、安全、かつよりテストが行われています。

コントリビューション

コントリビューションを歓迎します！ 以下を確認してください：

• CONTRIBUTING.md — 開発ワークフローと標準
• CODE_OF_CONDUCT.md — コミュニティガイドライン

コントリビューションの分野：

• 追加の建築テンプレート
• さらなる家具デザイン
• 地形生成レシピ
• パターンライブラリの拡張
• バグ修正と最適化

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

サポートとコミュニティ

助けが必要であるか、質問がある場合は、サポートします：

• 📧 メール: evan@amentilabs.com — 質問、フィードバック、またはコミュニティに参加するため
• 🐛 バグレポート: 問題を開く
• 💬 ディスカッション: GitHubディスカッション

素晴らしい建造物を作る手助けをさせてください！

クレジット

• 作成者: Amenti Labs
• 提供元: Model Context Protocol (MCP)を介したAnthropicのClaude AI
• ベースとなる技術: Minecraft、PaperMC、WorldEdit、Docker
• リポジトリ: https://github.com/amenti-labs/vibecraft

スター履歴

楽しい建造を！ 🧱 助けが必要な場合は、上記のサポートとコミュニティセクションを確認するか、evan@amentilabs.comにメールを送ってください。