Houdini MCP

面向 SideFX Houdini 的非官方第三方 MCP 工具。HMCP 让 Codex、Claude Code、 OpenClaw、Hermes、CodeBuddy 及其他 MCP Agent 通过标准 stdio 调用 Houdini， 项目与 SideFX、OpenAI、Anthropic 或任何 Agent 客户端无隶属关系。

架构

Agent client
    | MCP stdio
    v
minimal_mcp_server
    | authenticated Session Broker discovery
    v
private loopback RPC/TCP
    | Houdini owner-thread dispatch
    v
HOM / scene / node networks

• 外部协议只有 MCP stdio；Houdini 侧产品传输只有私有 loopback RPC/TCP。
• Session Broker 保存用户明确激活的唯一 GUI；未选择或会话变化时请求 fail closed。
• Houdini 主线程拥有 HOM 调用；网络线程只负责接收、排队和等待结果。
• 官方文档先映射为 capability、recipe、skill 与 validator，必要时才晋升公开工具。
• 工具返回成功不代表场景正确；写操作必须进行语义 readback。

详细设计见架构文档。

要求

• Windows 11
• Git
• 实际运行时使用已有 Python 3.11 至 3.13，或 Houdini 22 自带的 hython
• 连接和操作场景时需要 Houdini 22.0 或更高版本

首次安装 HMCP 时不要求已经安装 Houdini 或 Python。HMCP 不支持 Houdini 22.0 以下版本。

安装

$installer = Join-Path $env:TEMP ("houdini-mcp-install-{0}.ps1" -f [guid]::NewGuid().ToString("N"))
try {
    Invoke-WebRequest "https://raw.githubusercontent.com/whysoslow/houdini-mcp/main/install.ps1" -OutFile $installer
    powershell -NoProfile -ExecutionPolicy Bypass -File $installer
    if ($LASTEXITCODE -ne 0) { throw "HMCP installer failed with exit code $LASTEXITCODE." }
}
finally {
    Remove-Item -LiteralPath $installer -Force -ErrorAction SilentlyContinue
}

安装器只编排 Git、已有 Python/hython 和 HMCP setup，不安装 Python/Houdini，也不修改 Agent 客户端配置。兼容运行时存在时，同一流程会生成通用 registration，并让终端用户 选择全部、单个、多个、自定义 Houdini 用户目录或跳过 package；跳过后可随时离线重跑。 缺少运行时会返回 runtime_deferred，源码仍可先安装。AI/JSON 模式不会提示或猜测目标， 而是返回候选、阶段状态和下一条命令。完整行为见 Get Started。

pip 安装

sdist/wheel 已包含完整的 server + runtime（Houdini 菜单、启动脚本、pythonrc、验证契约）。 安装后 primary_source_root() 自动解析到 site-packages，生成的 Houdini package 指向 site-packages/runtime。

pip install hmcp
houdini-mcp init

PyPI 包名为 hmcp（houdini-mcp 在 PyPI 已被占用）；命令行仍是 houdini-mcp。 未发布前也可从 GitHub Releases 的 wheel 直接 pip install <wheel-url>。

MCP 配置

生成一份客户端中立的标准 stdio 配置：

python -m server.client.registration
python -m server.client.registration --output .\houdini-mcp.registration.json --json

通用结构如下，实际命令、项目路径与输出目录由 CLI 按当前环境生成：

{
  "mcpServers": {
    "houdini": {
      "command": "C:/Path/To/python.exe",
      "args": ["-m", "server.bridge.minimal_mcp_server"],
      "cwd": "C:/Path/To/houdini-mcp",
      "env": {
        "HOUDINI_MCP_OUTPUT_DIR": "C:/Users/name/HoudiniMCP"
      }
    }
  }
}

HMCP 只提供这份通用配置。 如何转换、合并、写入、重载或移除 Codex、Claude Code、OpenClaw、Hermes、CodeBuddy 等客户端的私有配置，由对应客户端或其 AI Agent 负责。HMCP 不读取、写入、备份、恢复或卸载客户端配置。

使用

1. 启动 Houdini。
2. 打开 Houdini MCP > Open Control Window。
3. 点击 激活此 GUI。
4. 从已配置的 Agent 客户端调用 Houdini MCP 工具。

Houdini 原生菜单保留英文；控制面板使用中文。多开 GUI 时，只有用户明确激活的 会话可以接收交互请求。关闭 GUI 后，其会话和动态端口立即失效。

需要由命令启动 Houdini 时：

python -m server.session.launch_houdini --wait-for-runtime

验证

python -m server.diag.doctor --skip-health --json
python -m server.client.mcp_probe --config .\houdini-mcp.registration.json
python -m server.diag.healthcheck

mcp_probe 验证通用 stdio 描述。真实客户端验收必须由外部已配置客户端启动 stdio server，并验证工具列表、get_mcp_settings、安全读操作及真实 Houdini 结果。

安全边界

• GUI 端口动态分配、仅监听 loopback，选择权威只有认证 Session Broker。
• 不根据版本、端口、PID 顺序、启动时间或 endpoint 文件猜测 GUI。
• 写操作受策略、确认、审计、路径边界、deadline、fence 和语义验证约束。
• 新建或修改的节点吸附网格；无关节点位置保持不动。
• 不以屏幕截图替代 Houdini runtime 或产物语义验证。

文档

• Get Started
• 快速说明与客户端边界
• 工具与能力
• 全局官方文档能力树
• 规范符合性（基础框架）
• 架构
• 安全
• 兼容性
• Skills
• 贡献指南
• 许可证