创世双子MCP
项目介绍
技术文档摘要
Genesis-Gemini-MCP (非官方扩展)
该项目是对Genesis进行修改并集成Google Gemini AI的一种Model Context Protocol (MCP)风格实现。
-
Genesis MCP (此仓库): https://github.com/nitichidasho/genesis_gemini_mcp
许可证：MIT License。详情见LICENSE文件。 -
Genesis (原始框架): https://github.com/Genesis-Embodied-AI/Genesis
许可证：Apache License 2.0。
此仓库提供了一个基于Genesis的MCP风格接口，用于自然语言驱动的模拟。
致谢
- 该项目基于Genesis (Apache 2.0许可证)构建
- 扩展和修改由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及以上版本
- 操作系统: 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 客户端启动
📝 输入模拟内容: 三个红色球体下落的模拟
🧠 Gemini AI正在生成代码...
🔄 正在执行Genesis模拟...
✅ 模拟完成 - 请通过VNC查看3D显示
演示模式
$ python genesis_client.py --demo
🎪 Genesis MCP 演示运行
📺 演示 1/3: 红色球体下落的模拟
📺 演示 2/3: 两个箱子接触的模拟
📺 演示 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隧道 (端口 5900)
Linux Server (VNC Server)
↓ 显示器 :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连接成功')
"
性能问题
# 检查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) 以提高性能
开发
开发环境设置
# 安装开发依赖
uv pip install -e ".[dev]"
# 运行测试
python -m pytest tests/
# 运行综合测试
python tests/integration_test.py
# 检查代码质量
black src/ tests/
isort src/ tests/
flake8 src/ tests/
添加新功能
- 添加模板: 在
genesis_templates.py中添加模式 - 改进AI提示: 编辑
src/genesis_mcp/services/gemini_service.py - 优化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以上）
- 网络: 稳定的宽带连接
支持的操作系统
- ✅ Ubuntu 20.04+ (推荐)
- ✅ CentOS/RHEL 8+
- ✅ macOS 12+
- ⚠️ Windows (通过WSL2有限支持)
许可证
本项目包含以下组件：
- Genesis MCP，采用MIT许可证。
- Genesis，采用Apache License 2.0。
版权所有 © 2024 Genesis作者 修改和附加代码 © 2025 Shota Chida。
致谢
- Google Gemini: 提供高质量的AI代码生成
- Model Context Protocol: 标准化的AI通信协议
🎬 通过Genesis MCP，体验AI创造的下一代物理仿真！