octane-mcp

# OctaneX MCP 本地MCP服务器，允许Hermes Agent使用 **Octane X 作为共享的可视化画布**，用于几何、数据、数学和概念可视化。 ## 许可 该存储库使用范围许可结构。阅读 [`LICENSE-SCOPE.md`](LICENSE-SCOPE.md) 以获取权威的文件和目录边界。 - **核心源代码** — [商业源代码许可 1.1](LICENSE)。BSL核心源代码可用于非生产环境，并于 **2030-07-10** 转换为Apache 2.0许可。 - **Agentic Canvas产品** — [PolyForm 非商业 1.0.0](apps/octanex-canvas/LICENSE)。Canvas主机、UI、WebGL渲染器和原始软件包资产免费用于非商业用途；商业部署、SaaS、转售和重新分发需要单独的协议。 - **原始知识和文档** — [CC BY-SA 4.0](LICENSE-KNOWLEDGE.md)。方法和研究框架、概念语法规范和教程在互惠知识共享中仍然可用。 - **数据、语料库和派生验收材料** — [CC BY-NC-SA 4.0](LICENSE-DATA.md)，受每个上游资产的许可和署名要求的约束。 商业许可、商标保留和上游第三方署名在 [COMMERCIAL-TERMS.md](COMMERCIAL-TERMS.md) 和 [NOTICE](NOTICE) 中涵盖。 ```text Hermes MCP 工具调用 -> Python MCP 服务器 -> JSON 命令队列 -> Octane Lua 桥 -> Octane X 视口/渲染目标 ``` 该桥故意避免任意的Lua执行。MCP服务器发出一个小的允许列表命令DSL，Octane端的Lua桥验证并处理这些命令。 ## 示例视觉产品 ### 真实产品工作室  配方库以可复制的视觉目标开始，而不仅仅是文字。上面的标题示例是一个具有玻璃、金属、软箱反射、相机意图、材质笔记和本地渲染验证检查清单的真实/PBR产品工作室设置。参见 [`examples/recipes/photoreal-product-studio/`](examples/recipes/photoreal-product-studio/) 以获取可重复使用的OBJ/MTL场景和MCP命令元数据。 ### 当前配方预览 公共展示现在指向当前、可复制的配方方向，而不是旧的探索行。旧的空间/数据/演示配方仍然存在于 `examples/recipes/` 中以供参考，但它们不再是README标题或活动基准测试目标，除非它们已被协调和重新门控。 | 手表 | 桌扇 | 耳机工作室 | | --- | --- | --- | | [](examples/recipes/wristwatch/) | [](examples/recipes/desk-fan/) | [](examples/recipes/headphones-studio/) | | 双色钢/金色表壳，蓝色表盘，金色数字，球面小时标记，链接表带。 | 原始Octane桌扇道具，带有管状笼，线，插头和插针。 | 对立的圆柱形杯，螺旋路径跟随线，多材料绑定。 | | 古老寺庙 | 一碗水果 | 真实花瓶工作室 | | --- | --- | --- | | [](examples/recipes/ancient-temple/) | [](examples/recipes/bowl-of-fruit/) | [](examples/recipes/photoreal-vase-studio/) | | 具有适当照明和边界感知框架的柱状结构。 | 生成的反射表面上的水果簇。 | 具有柔和照明的多花瓶真实工作室。 | | Oceananigans 浅水 | 坝体飞溅 | 布料垂挂接触 | | --- | --- | --- | | [](examples/recipes/oceananigans-shallow-water-front/) | [](examples/recipes/dam-break-splash/) | [](examples/recipes/mass-spring-cloth-drape/) | | 源代码支持的Julia/Oceananigans浅水出口，渲染为标量带和速度字形。 | SPlisHSPlasH风格的液体/泡沫粒子装置，带有本地材质组。 | 具有显式接触几何的质量弹簧布料在刚性球体上。 | | 开尔文-亥姆霍兹切片 | 刚性堆栈接触 | N体发散 | | --- | --- | --- | | [](examples/recipes/fluid-kelvin-helmholtz-slice/) | [](examples/recipes/rigid-stack-contact-forces/) | [](examples/recipes/nbody-chaotic-divergence/) | | 流体不稳定性可视化的剪切层标量场装置。 | 堆叠刚体上的接触力矢量。 | 三体轨迹发散，渲染为物理模拟配方。 | 参见 [`docs/recipe-library.md`](docs/recipe-library.md) 以获取完整的目录（40个配方），并附有可重复使用的OBJ/MTL场景和MCP命令元数据。 ## 用途 在代理需要将解释转换为渲染场景时使用此项目： - 数据以3D条形图或未来图表语法表示； - 数学以曲面和几何对象表示； - 概念以简单的分阶段场景表示； - Hermes的头像作为渲染中的视觉指南； - 本地视觉研发的快速渲染/预览/审查循环。 文档编写用于快速代理学习，包括较小的本地模型：从下面的工作流卡开始，然后复制确切的示例。 ## 当前状态 已验证或实施： - `octanex-mcp` 标准输入输出MCP服务器。 - Hermes MCP配置模式，适用于 `mcp_servers.octanex`。 - Octane X 沙盒/容器工作区路径。 - 有序JSON命令队列和 `inbox.json` 兼容性回退。 - 版本化类型命令模式、结构化验证错误代码、队列验证、`processing/` 状态和每个命令的结果JSON文件。 - 一次性Lua桥，排空 `queue/*.json` 并退出。 - 具有手动“处理下一个”/“排空队列”控件和超时回退注释的持久Lua桥窗口。 - 按需桥接控制器：状态检查和带有AppleScript支持的macOS工作流的单次/持久脚本启动尝试。 - 平行测试保持单次和持久场景命令处理器的语义对齐；它们在调度/UI行为上应该不同。 已知约束： - Octane X在macOS上是沙盒化的。Hermes必须写入实际的应用程序容器路径，而不是明显的 `~/OctaneMCP` 路径。 - 持久的Lua UI可能会阻止Octane的视口刷新。对于批量处理，当视口看起来陈旧时，优先使用一次性队列排空。 ## 安装和运行 从此存储库： ```bash uv sync PYTHONPATH= uv run octanex-mcp init PYTHONPATH= uv run octanex-mcp doctor PYTHONPATH= uv run octanex-mcp --self-test ``` `~/.hermes/config.yaml`中的Hermes配置（合并到现有的 `mcp_servers` 键中）： ```yaml mcp_servers: octanex: # 使用捆绑的启动器，而不是裸露的 `uv run` — 它剥夺了Hermes # 运行时PYTHONPATH，以便服务器使用其自己的.venv（带有 # mcp/pydantic_core）而不是Hermes的损坏的.venv，它将在导入时崩溃 # 服务器。 command: "/path/to/octanex-mcp/run_octanex_mcp.sh" args: [] timeout: 180 connect_timeout: 30 # 仅当工作区/应用程序路径与服务器解析的默认值不同时 # env: # OCTANEX_MCP_WORKSPACE: "/Users/craig/Library/Containers/com.otoy.rndrviewer/Data/OctaneMCP" # OCTANEX_APP_PATH: "/Applications/Octane X.app" ``` 对于另一个检出位置，将 `command` 指向该检出的 `run_octanex_mcp.sh`（ `--project` 路径已编译到启动器中），或在运行服务器之前设置 `OCTANEX_MCP_REPO`： MCP服务器在Hermes启动时被发现；在配置更改后重启Hermes（或在会话中使用 `/reload-mcp`），然后验证： ```bash hermes mcp list # 显示 `octanex` （✓ 已启用） hermes mcp test octanex ``` ## 工作区路径 默认情况下，Hermes写入当前macOS用户的实际Octane X沙盒容器路径： ```text ~/Library/Containers/com.otoy.rndrviewer/Data/OctaneMCP/ ``` Octane Lua可能在脚本中使用此路径： ```text ~/OctaneMCP/ ``` 为了可靠性，生成的脚本直接使用实际的容器路径。 在需要时使用环境变量覆盖路径： ```bash export OCTANEX_MCP_WORKSPACE="$HOME/Library/Containers/com.otoy.rndrviewer/Data/OctaneMCP" export OCTANEX_MCP_REPO="/path/to/octane-mcp" export OCTANEX_APP_PATH="/Applications/Octane X.app" PYTHONPATH= uv run octanex-mcp init PYTHONPATH= uv run octanex-mcp doctor ``` `octanex-mcp init` 创建工作区文件夹，在工作区中写入 `octanex-mcp.config.json`，写入 `octane_lua/config.generated.lua`，并生成带有注入的解析工作区路径的可移植桥副本。有关桥生命周期和对齐规则，请参见 [`docs/octane-bridge.md`](docs/octane-bridge.md)。 ## 所需的Octane X首选项设置 必须告诉Octane X在哪里找到Octane MCP Lua桥脚本。在运行 `octanex-mcp init` 后，打开Octane X并设置Lua脚本目录： 1. 打开 **Octane X**。 2. 打开 **首选项**。 3. 找到 **脚本路径** 设置。 4. 将 **脚本路径** 设置为此检出的Lua脚本目录： ```text /path/to/octane-mcp/octane_lua ``` 对于此存储库检出，这是在 `octane_lua/` 文件夹中包含： ```text hermes_bridge_oneshot.generated.lua hermes_bridge_persistent.generated.lua ``` 如果 `OCTANEX_MCP_REPO` 指向其他位置，请使用 `$OCTANEX_MCP_REPO/octane_lua`。在更改此首选项后，如果脚本没有立即出现，请重启Octane X。 重要文件： ```text .../OctaneMCP/inbox.json 最新命令回退 .../OctaneMCP/queue/*.json 有序命令队列 .../OctaneMCP/processing/*.json 正在处理的命令 .../OctaneMCP/processed/*.json 成功处理的命令 .../OctaneMCP/failed/*.json 失败的命令有效载荷 .../OctaneMCP/results/*.json 每个命令的成功/错误/结果元数据 .../OctaneMCP/artifacts/ 生成的非OBJ/预览工件 .../OctaneMCP/assets/ 生成的OBJ资产 .../OctaneMCP/renders/ 预览/渲染输出 .../OctaneMCP/scenes/ 保存的语义场景清单 .../OctaneMCP/status.json 桥接状态/心跳 .../OctaneMCP/bridge.log 桥接日志 ``` ## Octane端桥接脚本 ### 优先批量回退：一次性桥接 打开Octane X并运行： ```text /path/to/octane-mcp/octane_lua/hermes_bridge_oneshot.generated.lua ``` 这会排空所有有序的 `queue/*.json` 命令并退出，以便Octane的视口/渲染循环可以重绘。它还回退到 `inbox.json` 以支持旧的单命令工作流。 ### 持久桥接窗口 打开Octane X并运行： ```text /path/to/octane-mcp/octane_lua/hermes_bridge_persistent.generated.lua ``` 在与Hermes一起使用时，请保持 `Hermes Octane MCP Bridge` 窗口打开。如果定时器模式不可用，请使用 `Process next` 处理一个命令或 `Drain queue` 处理一批命令。 **不要** 在Octane Lua中添加睡眠循环；它们在UI线程上运行，可能会冻结Octane X。 如果持久桥接在 `start_render` 后状态为 `released`，这是故意的：它给了Octane渲染器一个机会来重绘。 ## MCP工具目录 ### 状态和学习 | 工具 | 目的 | | --- | --- | | `octane_status()` | 应用程序存在性、队列、已处理/失败的文件、桥接状态。 | | `octane_bridge_process_status()` | Octane进程状态、生成的桥接路径、脚本准备情况和桥接心跳年龄。 | | `octane_run_oneshot_bridge(dry_run, timeout_seconds)` | 从Octane X的 **脚本** 菜单通过AppleScript运行 `hermes_bridge_oneshot.generated.lua`；单击一次即可排空完整的队列。 | | `octane_start_persistent_bridge(dry_run, timeout_seconds)` | 从Octane X的 **脚本** 菜单通过AppleScript运行 `hermes_bridge_persistent.generated.lua`。 | | `octane_validate_command(command)` | 验证一个JSON命令信封。 | | `octane_schema()` | 返回支持的命令操作、限制、路径规则和示例。 | | `octane_validate_queue()` | 验证工作区中的队列文件。 | | `octane_recipe_book(limit_chars=12000)` | 读取本地字段笔记以获取成功、失败和陷阱。 | | `octane_record_recipe(title, outcome, context, steps, signals, follow_ups)` | 将课程追加到 `docs/recipe-book.md`。 | | `octane_recipe_index()` | 列出已检查的示例配方，附带规范的元数据和预览/本地验证状态。 | | `octane_load_recipe(slug)` | 按slug加载配方的命令序列和解析的资产路径。 | | `octane_queue_recipe(slug, overrides=None)` | 按slug排队已检查的配方命令序列。 | | `octane_validate_recipe_library()` | 验证已检查的配方文件、元数据、预览和命令有效载荷。 | ### 低级场景命令 | 工具 | 目的 | | --- | --- | | `octane_ping(message)` | 排队桥接ping。 | | `octane_create_test_cube(name, size)` | 生成立方体OBJ并排队导入。 | | `octane_import_geometry(path, name, format)` | 排队OBJ/USD/FBX/Alembic导入。 | | `octane_create_material(name, kind, color, roughness, metallic, transmission, ior, opacity, clearcoat, anisotropy, emission, texture_path, normal_path)` | 排队材质创建/更新，带有扩展的PBR字段（不支持的Octane引脚会带有警告被桥接确认）。 | | `octane_assign_material(object_name, material_name)` | 排队材质分配。 | | `octane_set_camera(position, target, fov)` | 排队相机放置。 | | `octane_set_lighting(preset)` | 排队照明预设。 | | `octane_create_light(name, light_type, intensity, position, direction, size, angle, hdr_path)` | 排队原生光源创建（`area_light`、`sun_light`、`point_light`、`spot_light`、`directional_light`、`environment`、`emissive`）。 | | `octane_start_render(samples, width, height)` | 排队渲染重启和分辨率更新。 | | `octane_save_preview(path, width, height, samples, min_samples, timeout_seconds, quality, max_render_time)` | 排队渲染就绪的PNG预览保存。 `quality` ∈ `fast`（6秒渲染/10秒墙；500 s/px创建者默认值）/ `preview`（10秒）/ `standard`（30秒）/ `high`（60秒）/ `ultra`（120秒）/ `final`（无限制，600秒墙上限）设置收敛上限；原始 `samples` / `min_samples` / `timeout_seconds` / `max_render_time` 覆盖该层级。超时时保存当前帧的最佳努力。 | | `octane_review_preview(path)` | 使用指标、诊断、可能的原因和推荐的操作查看保存的PNG预览。 | | `octane_suggest_camera_fix(preview_review, asset_bounds)` | 从预览质量控制和资产边界建议相机补丁。 | | `octane_suggest_lighting_fix(preview_review)` | 从预览质量控制建议照明/渲染补丁。 | ### 更高级的可视化工具 | 工具 | 目的 | | --- | --- | | `octane_visualize_bars(values, name)` | 构建3D条形图OBJ并排队完整场景。 | | `octane_visualize_surface(expression, name, x_min, x_max, y_min, y_max, steps)` | 构建受限的 `z=f(x,y)` 曲面并排队完整场景。 | | `octane_visualize_scatter(points, name)` | 从xyz三元组构建3D散点图OBJ并排队完整场景。 | | `octane_show_avatar(name)` | 显示Hermes的几何头像。 | | `octane_build_scene(scene_plan)` | 保存语义场景清单并排队验证的场景命令。 | | `octane_save_scene_manifest(scene_plan)` | 保存语义场景清单而不排队命令。 | | `octane_build_concept(prompt)` | 确定性MVP概念脚手架。 | ## 代理工作流卡 ### 卡1：桥接器是否存活？ 1. 调用 `octane_status()`。 2. 如果 `bridge_seen` 为假，请用户运行Octane X中的Lua桥接脚本之一。 3. 如果队列增长但已处理的不增长，请运行一次性桥接。 4. 使用 `octane_record_recipe(...)` 记录任何非显而易见的修复。 ### 卡2：显示简单对象 1. 调用 `octane_create_test_cube(name="agent_cube", size=1.0)`。 2. 如有必要，调用 `octane_start_render(samples=128)`，然后调用 `octane_save_preview()`。 3. 在Octane X中，从 **脚本** 菜单运行 `hermes_bridge_oneshot.generated` 一次以排空整个管道。 5. 调用 `octane_review_preview()` 并在声明成功之前验证 `ok=true`。 ### 卡3：快速可视化数据 1. 调用 `octane_visualize_bars(values=[3, 1, 4, 1, 5], name="pi_digits")`。 2. 在Octane X中运行/排空Lua桥接。 3. 保存预览。 4. 调用 `octane_review_preview()`；如果它报告空白/裁剪/低对比度输出，请调整生成器或相机并记录经验教训。 ### 卡片 4：可视化数学曲面 1. 调用 `octane_visualize_surface(expression="sin(r) / max(r, 0.25)", steps=36)`. 2. 使用一次性桥接器清空队列。 3. 保存/检查预览。 4. 保持表达式仅限于 `x`、`y`、`r`、`sin`、`cos`、`tan`、`sqrt`、`log`、`exp`、`pow`、`min`、`max`、`abs`、`pi` 和 `e`. ### 卡片 5：使用后自我改进 在任何成功、失败或令人惊讶的运行后，添加一个简洁的配方： ```text octane_record_recipe( title="一次性桥接器修复了条形图导入后的陈旧视口", outcome="成功", context="持久桥接器处理了队列，但Octane视口仍然陈旧。", steps=[ "将octane_visualize_bars排队，包含五个值。", "从Octane X的脚本菜单中运行hermes_bridge_oneshot.generated。", "重新启动渲染并保存预览。" ], signals=["队列/已排空", "处理/获得命令文件", "预览PNG存在"], follow_ups=["优先使用一次性桥接器进行多命令视觉场景"] ) ``` 保持条目简短和操作性。未来的本地模型应该可以直接复制模式。 ## 开发烟雾测试 ```bash cd /path/to/octane-mcp PYTHONPATH= uv run octanex-mcp --self-test PYTHONPATH= uv run python -m octanex_mcp.client_smoke PYTHONPATH= uv run python -m compileall src hermes mcp test octanex ``` `PYTHONPATH=` 避免在Hermes自己的运行时venv中意外导入软件包，在Hermes桌面终端内开发时。 ## 更多文档 - `docs/agent-quickstart.md` — 适用于小型/本地模型的简短示例。 - `docs/recipe-library.md` — 具有可重用OBJ文件、命令元数据和预览渲染的广泛示例场景。 - `docs/recipe-book.md` — 自我改进的成功、失败、部分和陷阱。 - `docs/canvas-roadmap.md` — 视觉画布路线图。 - `docs/local-model-rich-moa.md` — 本地视觉研发过程。 ## 示例配方库 可重用的示例场景位于 `examples/recipes/` 下。每个配方目录包含： - `README.md` — 提示、目的、步骤和变体； - `scene.obj` — 可重用的几何体； - `scene.json` — 相机和MCP命令序列元数据； - `preview.png` 或 `photoreal-preview.png` — 用于快速审查的预览/目标渲染。 在探索内置条形图/曲面/头像工具以外的应用程序时，从 `docs/recipe-library.md` 开始。 动画示例位于 `examples/animations/` 下。第一个示例 `orbit-reveal` 包括一个GitHub友好的GIF、MP4、PNG帧序列、OBJ帧状态和故事板元数据。当前的强大动画模式是逐帧场景生成加上 `ffmpeg` 编码；可以稍后添加本地Octane时间线控制。 --- ## 链接 - X / Twitter: [@nobulart](https://x.com/nobulart/) - 支持：[给我买杯咖啡](https://buymeacoffee.com/nobulart)