opera-houdini-mcp

opera-houdini-mcp 是 capoomgit/houdini-mcp 的独立增强 fork，定位为可作为 git submodule 嵌入到任意 Houdini 插件库的 MCP server。MIT 协议，与上游完全兼容，额外提供 Tier 1 工具集、execute_code 安全护栏、零新增 pip 依赖。

当前上游基线：capoomgit/houdini-mcp @ de4fd93（2026-07-17 同步） 同步策略：cherry-pick only，禁止 merge 集成方式：作为 git submodule 嵌入到消费方 Houdini 项目（见 §3）

目录

1. Features

2. Architecture

3. Embedding as a git submodule

4. Tier 1 工具清单

5. execute_code 安全模型

6. AI 调用 hou API 的硬约束

7. Configuration

8. Upstream Sync Policy

9. Testing

10. Troubleshooting

11. Edge Cases & 集成陷阱

12. Contributing

13. Security

14. License & Acknowledgement

Related MCP server: fxhoudinimcp

Features

• 13 个 Tier 1 工具 — 场景 CRUD / 节点发现 / 图编辑 / 错误扫描（含 warnings）/ 几何摘要 / 材质 / 截图 / 文档查询 / 缓存管理 / 诊断，独立模块化

• execute_code 三档安全 policy — read-only / normal / privileged × dangerous / heavy / mutation 三类黑名单（正则 + AST 别名双检）

• 双开关 bypass — 任何 dangerous / heavy / privileged 操作都需「请求端参数 + 服务端 HOUDINI_MCP_ALLOW_BYPASS=1」同时开启

• 零新增 pip 依赖 — get_houdini_help 用 stdlib html.parser 替代 beautifulsoup4，维持 mcp[cli]==1.12.2 + requests + python-dotenv 三件套

• 结构化 audit — 每次 execute_code 响应附 _audit 块（policy / dangerous_hits / heavy_hits / mutation_hits / bypass_used / elapsed_ms / undo_group）

• local-help-first — get_houdini_help / verify_hou_api 优先打 Houdini 本地 help server（127.0.0.1:48626），失败自动回退在线 SideFX

• 自进化知识库 — 4 个 bridge-local 知识工具（search_lessons / save_lesson / read_lesson / knowledge_stats）+ 自动错误捕获 hook（零上下文成本）；多 root（个人库自动发现 + 团队库注册表声明，默认只读）；无嵌入模型（BM25 + 指纹 + 统计，全 stdlib）

Architecture

flowchart LR
    A[AI Agent<br/>Claude Desktop / Cursor / ...] -->|stdio / MCP JSON| B[houdini_mcp_server.py<br/>bridge]
    B -->|TCP 127.0.0.1:9876| C[server.py<br/>HoudiniMCPServer]
    C -->|hou API| D[Houdini main thread<br/>H21+ / Python 3.11+]
    D -.->|hou.helpServerUrl| E[Local help server<br/>127.0.0.1:48626]
    E -.->|F1 失败 fallback| F[SideFX online docs]
    C -->|RAG index build| G[scripts/build_rag_index.py]

关键约束：

• server.py 必须运行在 Houdini 主进程内（hou 是 C 扩展，跨进程 import 会 hang）

• bridge（houdini_mcp_server.py）与 server 通过 TCP 127.0.0.1:9876 通信，每次 tool call 短连接

• AI 工具看到的 MCP tool 列表来自 bridge 端（mcp[cli] SDK），实际 hou 调用发生在 Houdini 进程内

Embedding as a git submodule

1. 添加 submodule

# 在你的 Houdini 插件库根目录
git submodule add https://github.com/ChengZiiii/opera-houdini-mcp.git external/houdinimcp
git submodule update --init --recursive

2. 隔离 Python 环境

opera-houdini-mcp 与你项目里的其他工具运行环境解耦。建议目录布局：

<your-project>/
├── external/
│   ├── houdinimcp/                  # 本仓库（submodule）
│   ├── houdinimcp-env/              # 本仓库专用的 venv（python/ + pylibs/）
│   ├── <other-tool>/                # 你的其他第三方工具
│   └── <other-tool>-env/            # 各工具独立环境，互不冲突

<dirname>-env/ 不要提交进 git。env 目录名 = package 目录名 + -env，自动派生，详见 Configuration。如果你把 submodule 改名为 external/opera-houdini-mcp/，env 自动变成 external/opera-houdini-mcp-env/，跟着 rename 一下就行。

环境初始化细节（python/ 解释器 + pylibs/ 依赖）由消费方项目侧决定，可参考 pyproject.toml 的 dependencies 三件套自行装配，或用 uv pip install -p <venv-python> mcp[cli]==1.12.2 requests python-dotenv 一行命令起步。

3. 启动 server

从你的项目代码里直接 import houdinimcp 包：

import sys, os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "external"))

from houdinimcp import start_server, stop_server, is_server_running

# 启动（默认 127.0.0.1:9876）
start_server()

if is_server_running():
    print("opera-houdini-mcp is up")

houdinimcp 包对外暴露的完整 API：

4. 配置 AI 工具

任一兼容 MCP 的客户端（Claude Desktop / Cursor / ZCode / OpenCode / Codex）：

{
  "mcpServers": {
    "houdini": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "<your-project>/external/houdinimcp/houdini_mcp_server.py"
      ]
    }
  }
}

MCP JSON key 固定为 houdini（mcpServers.houdini / mcp.houdini / mcp_servers.houdini 三种形式都接受），与上游完全兼容，老用户配置零改动。

5. 升级 submodule 消费者

git submodule update --remote external/houdinimcp
git submodule sync

无需重装 env —— 运行环境独立放在 external/<工具名>-env/ 下，与源码完全解耦。

Tier 1 工具清单

以独立 PR 形式合入。完整计划与进度见 CHANGELOG.md。

自进化知识库

agent 操作 Houdini 的试错经验跨 session 持久化为可检索 lesson（模块 _lessons.py + _lessons_search.py，纯 stdlib、无嵌入模型）。触发时机：遇到报错、重试第 2 次 仍未解决、或遇到不认识的 API/参数时，先 search_lessons 检索既往经验；命中后用 read_lesson 拉全文；解决问题后用 save_lesson 沉淀。lesson 是 advisory，不替代 verify_hou_api / get_houdini_help / get_best_practices。

自动捕获（零上下文成本）：bridge 在响应出口检测 status=error 响应，把错误 事件以 append-only 方式写入个人库 inbox/events.jsonl（同指纹去重、≥3 次自动生成 draft 骨架并在检索时提示「已踩 N 次，请补充 fix」）。

存储位置（全部在个人目录 ~/.opera-houdini-mcp/，不入仓库 git）：

~/.opera-houdini-mcp/
├── config.json              # 注册表（仅声明额外团队 root，个人库自动发现）
├── knowledge/
│   ├── lessons/*.md         # draft + published lesson（9 字段 + id/status/strength/root/时间戳）
│   ├── recipes/BEST_PRACTICES.md   # 个人人工 recipes（可空）
│   └── inbox/events.jsonl   # 自动捕获原始事件
└── cache/index/<root-name>/ # 各 root BM25 索引缓存

团队库注册（config.json，可选）：path 接受三种形式——${VAR} 环境占位符、 相对路径（相对 ~/.opera-houdini-mcp/）、或绝对路径（Windows 盘符 C:\ / C:/、 POSIX 前导 /、UNC \\server\share、前导 \）。绝对路径支持团队协作中各成员 NAS 映射盘符不同的场景——config.json 是本机配置（位于 ~/.opera-houdini-mcp/，每台 机器各一份），各成员各自写自己盘符的绝对路径即可，无需统一环境变量，无跨机器误导。 writable 默认 false（AI 只读，晋升人工把关）；占位符未定义 → unconfigured 静默跳过，路径不可达（绝对/相对路径指向的目录不存在、或占位符已定义但目录不可读） → unavailable 跳过并附 _warning，均不影响个人库。含 ${ 但非纯占位符的混合 形式（如 ${VAR}/sub）仍被拒绝。

[
  { "name": "team_knowledge", "path": "${TEAM_SHARE}/houdini/knowledge", "priority": 0.8, "writable": false }
]

团队协作 NAS 示例（各成员盘符不同，各自在本机 config.json 写绝对路径；同事若 把同一 NAS 映射到其他盘符，则改成自己的盘符即可）：

[
  { "name": "team_knowledge", "path": "Z:\\team\\houdini\\knowledge", "priority": 0.8, "writable": false }
]

execute_code 安全模型

双开关原则：任何 dangerous / heavy / privileged 操作都需要「请求端参数 + 服务端环境变量」同时开启。服务端不开环境变量，再多客户端请求也无效。

Audit：每次 execute_code 调用都会在响应里附 _audit 块（policy / dangerous_hits / heavy_hits / mutation_hits / bypass_used / elapsed_ms / undo_group / exception）。

超时：执行超时不会自动 hou.undos.performUndo()，避免误回滚正常操作。客户端需根据 _audit.elapsed_ms 自行决定。

AI 调用 hou API 的硬约束

任何 AI agent 通过 execute_code 调用 hou API 之前 MUST 先 verify。hou 是 C 扩展，跨 major version 间会重命名 / 废弃 / 新增方法。假定跨版本 hou API 等价 = bug 风险（hang / type-check 失败 / 行为不一致）。

正确工作流：

1. 调 verify_hou_api('Class.method') 先看 _ai_hint，绝不直接把假设的 hou API 写进 execute_code 的 code 参数

2. 若返 status="success", methods=[]（API 不存在），改用其他等价 API（例如在 SOP 子节点设 display/render flag，而不在 OBJ 容器调不存在的 setDisplayNode）

3. 若返 status="success" 且 _ai_hint 提到 thread 安全 caveat（如 ObjNode.setInput 需 input_index + item + output_index 三参），谨慎评估是否值得在 worker thread 冒险

三级 fallback（F0 → F1 → F2 → F3）

按优先级从高到低：

• F0 — 判断 hou 版本：verification 第一步必须先 hou.version() 确认 major version，因为 hou API 在跨 major 时会重命名 / 废弃 / 新增

• F1 本地 hou help（优先，无网络依赖，最快）：调 verify_hou_api(item_name=...)；若需进一步信息，hou.node(path).help()（已存在节点）或 execute_code 跑 help(hou.<Class>.<method>)

• F2 联网 SideFX 文档（F1 拿不到时）：verify_hou_api(item_name="<Class>.<method>", help_type="python_hou") 走 stdlib urllib.request 抓 https://www.sidefx.com/docs/houdini/hom/hou/<name>.html；不引入新 pip 依赖

  • local-help-first（自动）：get_houdini_help / verify_hou_api 优先打 Houdini 本地 help server（默认 http://127.0.0.1:48626/），本地不可达 / 超时 / 白屏（HTTP 200 但内容无效）时自动回退在线。返回 _source 字段（"local" / "online" / ""）告知实际命中方，_fallback_reason 说明回退原因。健康缓存：本地失败后 60s cooldown 内跳过本地直查在线

• F3 让用户开梯子（F2 返 status="error" 且 reason 含网络关键字时）：AI agent 必须在输出里显式写出"⚠ SideFX 文档站不可达，请检查网络/梯子，或在 Houdini 内用 hou.helpServerUrl() 查本地帮助"

跨工具说明：底层 = get_houdini_help；AI-friendly wrapper = verify_hou_api。建议优先用 verify_hou_api 调 hou API，get_houdini_help 用于 SOP/OBJ 节点本身或 vex_function 查询。

详细复盘 / postmortem（含 2026-07-21 ObjNode.setInput hang 案例）见 CHANGELOG.md。

Configuration

HOUDINI_MCP_ENV_DIR 派生约定：

package at  <parent>/<dirname>/                 env 派生为  <parent>/<dirname>-env/

examples:
  opera-houdini-mcp/                            opera-houdini-mcp-env/
  external/houdinimcp/                          external/houdinimcp-env/
  external/mcp/                                 external/mcp-env/
  D:/我的项目/external/houdinimcp/              D:/我的项目/external/houdinimcp-env/

• 相对路径的 override 会被静默忽略（fallback 到默认派生），因为 bridge 进程的 cwd 取决于 AI 工具怎么 spawn 它（Claude Desktop / Cursor / ZCode 各不相同），相对路径不可靠

• 99% 的场景不需要设这个变量，保持默认派生即可

OPUS 集成（可选）

OPUS 提供大量家具 / 环境程序化资产。订阅步骤：

1. 注册 RapidAPI 账号

2. 订阅 OPUS API

3. 复制本地配置文件：

cp urls.env.example urls.env  # urls.env 已在 .gitignore

4. 编辑 urls.env 填入 key：

RAPIDAPI_HOST_URL=https://opus5.p.rapidapi.com/
RAPIDAPI_HOST=opus5.p.rapidapi.com
RAPIDAPI_KEY=<your-key>

不设 key 时 server 仍可启动，仅 OPUS 工具被禁用。OPUS 集成是可选的。

Upstream Sync Policy

为什么禁止 merge：保持 opera 自身的提交图干净可审计，区分"上游原样"与"opera 独有"的改动点。

贡献到上游：opera 独有的改进建议优先以 PR 形式回提给 capoomgit/houdini-mcp，合入后再 cherry-pick 回来。这样全社区都能受益。

Testing

# 单元测试（不依赖 Houdini）
cd tests
pytest test_common.py test_execute_code_safety.py test_help.py \
       test_three_tier_fallback.py test_verify_hou_api.py

# Live smoke（依赖运行中的 Houdini 21+）
pytest tests/h21_live_*.py

# 完整回归
pytest tests/phase5_full_regression.py

测试基线：Houdini 21.0 + Python 3.11。详细 fixture / 共享 helper 见 tests/conftest.py 与 tests/_e2e_helpers.py。

Troubleshooting

Edge Cases & 集成陷阱

改 package 目录名

env 路径自动从 package 目录名派生（<dirname>-env/）。改了 package 目录名要同步改 env 目录名，或用 HOUDINI_MCP_ENV_DIR 指过去。env 内的 Python + 依赖无需重装，纯文件系统 rename 即可：

mv external/houdinimcp external/opera-houdini-mcp
mv external/houdinimcp-env external/opera-houdini-mcp-env   # 跟着改

多个项目共享一个 env

每个项目派生的 env 路径按各自 package 目录名走，默认不会共享。多项目共享：

export HOUDINI_MCP_ENV_DIR=/shared/envs/opera-houdini-mcp-env

建议绝对路径。相对路径的 override 会被静默忽略（bridge 进程的 cwd 取决于 AI 工具怎么 spawn，跨进程不稳定）。

Windows 目录大小写

Windows 不区分大小写但 git checkout 保留原始大小写。如果你在 Windows 上 clone 后看到 Houdinimcp/ 而代码 baseline 用 houdinimcp/，basename 派生会按实际拼写走，可能导致 env 路径大小写不一致：

# 强制 git 严格大小写敏感
git config core.ignorecase false
# 如已 checkout 成错误大小写，重命名
Rename-Item external/Houdinimcp external/houdinimcp

env 跨 OS 不通用

env 内嵌的 Python 是平台相关 wheel（cp311-cp311-win_amd64 这种）。Windows env 拷到 Linux 跑不了，反之亦然。跨 OS 迁移必须重装。

改 env 路径不需要重装依赖

env 改名、移位置、改 owner，依赖本身可以原地保留：

mv external/houdinimcp-env /new-location/my-env
export HOUDINI_MCP_ENV_DIR=/new-location/my-env

无需 pip install，无需重下 Python 包。

git worktree / 多分支并行

每个 worktree 派生独立 env，不会互窜。共享 env 见上方「多个项目共享一个 env」。

权限与只读 env

env 目录存在但不可写（网络盘权限、只读 checkout）时，_consent_dir() 的 os.makedirs 兜底会抛 PermissionError。安装时确保 env 所在目录对运行用户可写。

pip install -e . 会污染全局

不要把 opera-houdini-mcp 装到全局 Python。env 是隔离的，依赖会随 env 走；全局装会污染系统 Python，且后续覆盖会破坏 env 完整性。

Contributing

1. Fork → 建分支 → commit（标题前缀 [opera]，正文引用对应上游 PR 号如有）

2. pytest tests/ 全绿

3. PR 描述里说明：

   • 改动的 Tier 1 工具编号（如果适用）

   • 是否新增 pip 依赖（不允许，除非有充分理由并单独标注）

   • 是否动到不变量（见下）

4. 等 CI / 维护者 review

不变量清单（动到任一需先在 issue 里讨论）

Security

• execute_code 是 LLM 驱动 Python 执行入口，三档 policy + 双开关 + 结构化 audit 是当前安全基线

• 漏洞报告：通过 GitHub Issue 的 Private vulnerability reporting 渠道（不要在公开 issue 里贴 PoC），或直接联系维护者

License & Acknowledgement

本仓库全部代码沿用上游 MIT License。opera-houdini-mcp 本身的改动部分同样以 MIT 协议发布。

Houdini-MCP 的最初设计参考了 blender-mcp，感谢他们的贡献。opera-houdini-mcp 是 capoomgit/houdini-mcp 的独立 fork，遵循 MIT 协议，原版权归 Capoom 2025 所有。提交通过 cherry-pick 而非 merge 同步上游。