Genesis-Gemini-MCP (Unofficial Extension)

This project is a modified implementation of Genesis integrated with Google Gemini AI in a Model Context Protocol (MCP) style.

• Genesis MCP (this repository): https://github.com/nitichidasho/genesis_gemini_mcp
  Licensed under MIT License. See the LICENSE file for details.

• Genesis (original framework): https://github.com/Genesis-Embodied-AI/Genesis
  Licensed under Apache License 2.0.

This repository provides an MCP-style interface on top of Genesis for natural language-driven simulation.

Acknowledgements

• This project builds upon Genesis (Apache 2.0 license)
• Extensions and modifications by Shota Chida

🚀 AI駆動の物理シミュレーション - Genesis World をGemini AIと統合したModel Context Protocol (MCP) サーバー

Genesis WorldとGoogle Gemini AIを組み合わせ、自然言語から物理シミュレーションコードを生成。VNC機能により、SSH/リモート環境でも3D表示を実現します。

---

主な特徴

🧠 Gemini AI統合

• 自然言語からGenesis Worldコードを自動生成
• 物理シミュレーション特化のテンプレートシステム
• インテリジェントなコード補完と最適化

🖥️ VNC最適化表示

• SSH環境でGenesis World 3Dビューアーをリアルタイム表示
• 低遅延のx11vnc最適化設定（800x600@15fps）
• Windows/Mac/LinuxのVNCクライアント対応

⚡ 高性能アーキテクチャ

• Model Context Protocol (MCP) による標準化された通信
• 非同期処理によるレスポンス向上
• UV高速パッケージ管理とクリーンな仮想環境

🎯 開発者体験

• ワンコマンド環境セットアップ
• 統合テストとデバッグツール

---

クイックスタート

📋 前提条件

• Python: 3.11以上
• OS: Linux (推奨) / macOS / Windows (WSL2)
• GPU: CUDA対応GPU (推奨、CPUでも動作)
• Gemini API: Google AI Studio APIキー

1️⃣ プロジェクト取得

git clone https://github.com/dustland/genesis-mcp.git
cd genesis-mcp

2️⃣ 環境設定

# Gemini APIキーを設定
cp .env.example .env

# .envファイルを編集してGEMINI_API_KEY=your_api_key_here を設定
# または、setup.pyを使って設定
python setup.py --gemini-key YOUR_KEY  # APIキー設定

# 自動セットアップ
python setup.py --all

# 環境チェック
python setup.py --check

3️⃣ VNC環境セットアップ（リモート表示用）

# VNC環境構築
python start_vnc.py --start

# VNC接続確認
python start_vnc.py --status

# 接続: VNCクライアントで localhost:5900

4️⃣ 実行

# 仮想環境アクティベート
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# インタラクティブモード（推奨）
python genesis_client.py

# デモ実行
python genesis_client.py --demo

# MCPサーバー起動
python genesis_server.py

---

使用例

基本的な使用方法

$ python genesis_client.py
🤖 Genesis MCP クライアント起動
📝 シミュレーション内容を入力: 赤い球体が3つ落下するシミュレーション

🧠 Gemini AIでコード生成中...
🔄 Genesis シミュレーション実行中...
✅ シミュレーション完了 - VNCで3D表示を確認してください

デモモード

$ python genesis_client.py --demo
🎪 Genesis MCP デモ実行

📺 デモ 1/3: 赤い球体が落下するシミュレーション
📺 デモ 2/3: 2つの箱が接触するシミュレーション  
📺 デモ 3/3: 球体が箱の上を転がるシミュレーション

✅ 全デモ完了

生成されるコード例

入力: "青い箱と赤い球が衝突するシミュレーション"

Gemini AI生成コード:

import genesis as gs

# 初期化（GPU使用）
gs.init(backend=gs.gpu)

# シーン作成（VNC最適化）
scene = gs.Scene(
    viewer_options=gs.options.ViewerOptions(
        resolution=(800, 600),
        max_FPS=15,
        camera_pos=(3.0, 2.0, 2.0)
    ),
    show_viewer=True
)

# 地面
plane = scene.add_entity(gs.morphs.Plane())

# 青い箱
box_material = gs.materials.Rigid(color=(0.0, 0.0, 1.0))
box = scene.add_entity(
    gs.morphs.Box(size=(1, 1, 1)),
    pos=(0, 0, 2),
    material=box_material
)

# 赤い球
sphere_material = gs.materials.Rigid(color=(1.0, 0.0, 0.0))
sphere = scene.add_entity(
    gs.morphs.Sphere(radius=0.5),
    pos=(2, 0, 4),
    material=sphere_material
)

# シーンビルド
scene.build()

# 物理シミュレーション実行
for i in range(1000):
    scene.step()

---

プロジェクト構造

genesis-mcp/
├── 🔧 コアファイル
│   ├── genesis_client.py        # メインクライアント
│   ├── genesis_server.py        # MCPサーバー
│   ├── genesis_templates.py     # AIテンプレートシステム
│   ├── setup.py                 # 統合セットアップ
│   └── start_vnc.py            # VNC環境管理
│
├── 📦 パッケージ
│   ├── src/genesis_mcp/
│   │   ├── models.py           # データモデル
│   │   └── services/
│   │       ├── simulation.py   # シミュレーション制御
│   │       └── gemini_service.py # Gemini AI統合
│   │
├── ⚙️ 設定ファイル
│   ├── pyproject.toml          # パッケージ設定
│   ├── .env.example            # 環境変数テンプレート
│   └── uv.lock                 # 依存関係ロック
│
├── � ドキュメント
│   ├── docs/                   # 詳細ドキュメント
│   ├── VNC_OPTIMIZATION_GUIDE.md # VNC最適化ガイド
│   └── USAGE_GUIDE.md          # 使用方法詳細
│
└── 🧪 テスト
    └── tests/
        ├── integration_test.py  # 統合テスト
        └── test_services.py    # サービステスト

---

設定オプション

セットアップオプション

# 個別セットアップ
python setup.py --env      # 仮想環境のみ
python setup.py --vnc      # VNC環境のみ  
python setup.py --genesis  # Genesis Worldのみ
python setup.py --gemini-key YOUR_KEY  # APIキー設定

# 環境確認
python setup.py --check

VNC設定

# VNC詳細操作
python start_vnc.py --start     # VNC開始
python start_vnc.py --stop      # VNC停止
python start_vnc.py --status    # 状況確認
python start_vnc.py --cleanup   # クリーンアップ
python start_vnc.py --display   # 利用可能ディスプレイ

クライアントオプション

# 表示モード指定
python genesis_client.py --vnc     # VNC表示モード
python genesis_client.py --gui     # 直接GUI表示
python genesis_client.py --web     # Web表示（実験的）

# デバッグモード
python genesis_client.py --debug
python genesis_server.py --debug

---

VNC リモート接続

Windows → Linux サーバー

# 1. サーバー側でVNC起動
python start_vnc.py --start

# 2. SSH接続でポートフォワーディング
ssh -L 5900:localhost:5900 user@your-server

# 3. WindowsのVNCクライアントで接続
# 接続先: localhost:5900

接続フロー

Windows PC (VNC Viewer)
    ↓ SSH Tunnel (Port 5900)
Linux Server (VNC Server)
    ↓ DISPLAY :1
Genesis World 3D Viewer (800x600@15fps)
    ↓ 最適化転送
Windows PC (リアルタイム3D表示)

---

API リファレンス

MCPサーバー ツール

run_simulation

Genesis Worldシミュレーションを実行

パラメータ:

• code: Pythonコード（Gemini生成またはカスタム）
• description: シミュレーション説明
• options: 実行オプション

get_simulation_template

テンプレートベースのコード生成

パラメータ:

• keywords: 検索キーワード
• style: テンプレートスタイル

MCPサーバー リソース

world_info://features

Genesis World機能情報

simulation_state://current

現在のシミュレーション状態

---

トラブルシューティング

VNC接続できない

# VNC再起動
python start_vnc.py --cleanup
python start_vnc.py --start

# ポート確認
netstat -tlnp | grep :5900

# ファイアウォール確認
sudo ufw allow 5900

Genesis World表示されない

# DISPLAY設定確認
echo $DISPLAY

# X11テスト
export DISPLAY=:1
xclock

# Genesis Worldテスト
python -c "import genesis as gs; print('Genesis OK')"

Gemini AI接続エラー

# APIキー確認
cat .env | grep GEMINI_API_KEY

# 接続テスト
python -c "
import os
import google.generativeai as genai
genai.configure(api_key=os.getenv('GEMINI_API_KEY'))
print('Gemini API接続OK')
"

パフォーマンス問題

# GPU確認
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}')"

# VNC最適化確認
python start_vnc.py --status

# 解像度調整（pyproject.tomlで設定可能）
# resolution=(800, 600) → (640, 480) for better performance

---

開発

開発環境セットアップ

# 開発用依存関係インストール
uv pip install -e ".[dev]"

# テスト実行
python -m pytest tests/

# 統合テスト
python tests/integration_test.py

# コード品質チェック
black src/ tests/
isort src/ tests/
flake8 src/ tests/

新機能追加

1. テンプレート追加: genesis_templates.pyにパターン追加
2. AIプロンプト改善: src/genesis_mcp/services/gemini_service.pyを編集
3. VNC最適化: start_vnc.pyのx11vncパラメータ調整

プロファイリング

# パフォーマンス計測
python -m cProfile -o profile.stats genesis_client.py --demo

# メモリ使用量監視
python -m memory_profiler genesis_client.py

---

システム要件

最小要件

• CPU: Intel/AMD x64 または Apple Silicon
• RAM: 4GB以上
• ストレージ: 2GB以上
• ネットワーク: インターネット接続（Gemini API用）

推奨要件

• CPU: 4コア以上
• RAM: 8GB以上
• GPU: CUDA対応GPU（RTX系、GTX 1060以上）
• ネットワーク: 安定したブロードバンド接続

対応OS

• ✅ Ubuntu 20.04+ (推奨)
• ✅ CentOS/RHEL 8+
• ✅ macOS 12+
• ⚠️ Windows (WSL2経由で制限付き対応)

---

License

This project includes components from:

• Genesis MCP, licensed under the MIT License.
• Genesis, licensed under the Apache License 2.0.

Copyright © 2024 Genesis Authors Modifications and additional code © 2025 Shota Chida.

---

謝辞

• Google Gemini: 高品質なAIコード生成
• Model Context Protocol: 標準化されたAI通信プロトコル

---

🎬 Genesis MCP で、AIが創造する次世代物理シミュレーションを体験しよう！