overte-mcp

overte-mcp

此项目封装的内容

适用于 Overte 的 MCP 服务。Overte 是一个开源社交 VR 平台，由 C++ 桌面客户端（“Interface”）、域服务器和实体服务器组成，源自 High Fidelity 代码库。它与当前的“Vircadia”并非同一项目——完整的区分说明和官方链接（网站、文档、社区）请参阅 docs/WRAPPEE.md。它与工具集中的其他虚拟世界服务互为补充：resonite-mcp、vrchat-mcp、 godot-mcp、unity3d-mcp、gazebo-mcp。

另外还提供配套的 React Web 控制面板。

可以做什么

运行方式：Overte（域服务器 + Interface）是需要自行安装的独立 应用，不会随本项目打包。overte_domain_status 只需连接域服务器即可运行（无需 GUI）。overte_entity_spawn 和 overte_script_inject 需要运行中的 Interface 客户端，并加载 scripts/overte-mcp-bridge.js，因为 Overte 的实体服务器没有普通 HTTP“创建实体”端点——只能通过 Interface 的 JavaScript API 创建实体。首次设置请参阅 docs/ONBOARDING.md。

方向	内容	说明
输入	实体属性（位置、缩放、类型）、JS 行为脚本、GLB/FBX/OBJ 模型 URL	通过 MCP 工具调用或控制面板的 Entities/Scripting 页面操作
输出	实时域服务器遥测数据、已生成的世界内实体、带动画或脚本的实体	每个响应都会标注 source: "live" 或 source: "simulated"，绝不会悄悄伪装成功

工具——三个核心工具均已在 Overte 2026.04.1 上通过实时验证（2026-07-30）：

工具	状态
overte_domain_status	已通过实时验证——真实域服务器 /nodes.json + /settings.json 管理 API，端口为 40100
overte_entity_spawn	已通过实时验证——通过 WebSocket 桥接在世界内生成实体；设置 permanent=True 可在重启后保留
overte_script_inject	已通过实时验证——通过 WebSocket 桥接在世界内注入 JS 行为
overte_sampling_assist	当宿主支持时，通过 ctx.sample() 进行多步规划

控制面板页面：

页面	路由	功能
控制面板	/	域状态、节点列表、设置查看器
Avatars	/avatars	已连接的 avatar-mixer/agent 节点
Entities	/entities	生成表单 + 实体浏览器
Scripting	/scripting	JS 代码编辑器 + 脚本注入
Chat	/chat	以技能为先的 LLM 聊天，提供 4 种个性
Settings	/settings	后端健康状态 + LLM 提供商检测
Tools	/tools	动态工具发现 + 搜索
Skills	/skills	技能内容查看器（markdown）
Logs	/logs	带级别筛选的环形缓冲区日志查看器
Help	/help	域设置 + JS API 参考

快速安装

Claude Desktop（.mcpb）

1. 构建：just mcpb-pack → dist/overte-mcp.mcpb
2. 将 .mcpb 拖入 Claude Desktop（需要 Python 3.12+，且 uv 已加入 PATH）。

不使用 MCPB 的 Stdio 方式：uv run overte-mcp。完整安装路径请参阅：INSTALL.md。

完整栈（控制面板 + 桥接）

./start.ps1

同步依赖，启动 FastAPI 后端（11110）和 Vite 控制面板（11111）， 并打开浏览器。然后启动 Overte domain-server.exe，打开 Interface， 加载 scripts/overte-mcp-bridge.js，以启用实时生成/注入功能——请参阅 docs/ONBOARDING.md。

示例提示词

• “我的 Overte 域状态如何？”
• “在原点生成一个永久方块实体”
• “将舞蹈脚本附加到该实体”

Lint / 测试

just lint      # Ruff + Biome
just test      # unit + e2e
just mcpb-pack # validate + pack Claude Desktop bundle

文档

• docs/WRAPPEE.md — Overte 是什么、与 Vircadia 的区别、官方链接
• docs/ARCHITECTURE.md — 数据流、端口、WebSocket 桥接
• INSTALL.md — Overte 安装、MCPB、Claude Desktop 配置
• STATUS.md — 当前验证状态、待完成工作
• ASSESSMENT.md — 集群审计结果和改进计划
• PROJECT_PAGE.md — 路线图和任务跟踪
• CHANGELOG.md — 发行说明
• docs/ONBOARDING.md — 首次安装 Overte 和配置桥接
• docs/CONFIGURATION.md — 环境变量、端口
• docs/DEVELOPMENT.md — 开发环境设置、贡献指南
• docs/TOOLS.md — 完整的 MCP 工具参考
• docs/TROUBLESHOOTING.md — 常见问题
• llms.txt / llms-full.txt — LLM 索引和完整语料
• mcpb/README.md — Claude Desktop 捆绑包布局

要求

• Python 3.12+ 和 uv
• Bun（webapp + Biome）
• 需单独安装 Overte Client + Server，以使用实时域和桥接功能

许可证

MIT