Omniverse_usd_mcpserver

Omniverse USD MCP 服务

用于处理 Universal Scene Description (USD) 和 NVIDIA Omniverse 的 Model Context Protocol (MCP) 服务。该服务为基本的 USD 操作提供标准化 API。

核心功能

该服务目前提供以下核心 USD 操作：

• 创建、打开和保存 USD 场景
• 列出并分析场景内容
• 创建 prim 并定义基本几何体
• 添加对外部 USD 文件的引用
• 妥善管理资源，并在场景清理时释放资源

安装

# Clone the repository
git clone https://github.com/yourusername/omniverse-usd-mcp-server.git
cd omniverse-usd-mcp-server

# Install dependencies
pip install -r requirements.txt

快速开始

# Start the server with stdio protocol (for CLI interaction)
python -m usd_mcp_server

# Start the server with HTTP protocol (for web clients)
python -m usd_mcp_server --protocol=http --host=0.0.0.0 --port=5000

使用服务

该服务可与任何 Model Context Protocol (MCP) 客户端配合使用。以下是使用内置 Python 客户端的示例：

import asyncio
import sys
import os

# Add the parent directory to the path
sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))
from usd_mcp_client import UsdMcpClient

async def run_example():
    # Create client and connect
    client = UsdMcpClient("stdio", ["python", "-m", "usd_mcp_server"])
    await client.connect()
    
    try:
        # Create a new stage
        result = await client.call_tool("create_new_stage", {
            "file_path": "example.usda",
            "template": "basic",
            "up_axis": "Y"
        })
        stage_id = result["data"]["stage_id"]
        
        # Add a cube
        await client.call_tool("define_stage_prim", {
            "stage_id": stage_id,
            "prim_path": "/World/Cube",
            "prim_type": "Cube"
        })
        
        # Save the stage
        await client.call_tool("save_usd_stage", {
            "stage_id": stage_id
        })
        
        # Close and cleanup the stage when done
        await client.call_tool("close_stage", {
            "stage_id": stage_id
        })
        
    finally:
        await client.close()

# Run the example
asyncio.run(run_example())

服务协议

该服务支持多种通信协议：

• stdio：标准输入/输出（默认，用于嵌入应用程序）
• http：供 Web 客户端使用的 HTTP 协议
• websocket：供实时应用程序使用的 WebSocket 协议
• sse：用于单向实时更新的服务器发送事件
• tcp：原始 TCP 协议
• zmq：供高性能应用程序使用的 ZeroMQ 协议

可用工具

该服务提供以下 USD 操作工具：

核心 USD 工具

• create_new_stage：创建新的 USD 场景
• open_usd_stage：打开现有 USD 场景
• save_usd_stage：保存对场景所做的更改
• close_stage：关闭并卸载场景，释放资源
• list_stage_prims：列出场景中的所有 prim
• analyze_usd_stage：分析场景内容
• define_stage_prim：创建新的 prim
• create_stage_reference：创建对其他 USD 文件的引用
• create_stage_mesh：使用几何数据创建网格

示例脚本

在 examples/ 目录中，你可以找到演示如何使用该服务的示例脚本：

• basic_example.py：演示基本的场景创建和操作

生产就绪性：

要达到企业级标准，还需要约 20 小时的完善工作（测试、CI、错误处理）。

此实现基础扎实，但仍需加固，才能用于关键任务工作流。如果你愿意贡献缺失的测试或维护工具，它将是 USD 自动化的可行起点。

未来路线图

未来版本将扩展功能，包括：

• 物理模拟工具
• 材质创建和管理
• 动画关键帧
• 场景图可视化
• 高级几何操作

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 Pixar USD 团队提供 USD 核心库
• 感谢 NVIDIA Omniverse 团队提供 Omniverse 平台
• 感谢 Model Context Protocol 团队实现 AI 与工具的集成

---

由 Jan Haluszka 维护