Metadata-Version: 2.4
Name: hmcp
Version: 0.1.1
Summary: Unofficial third-party MCP tooling for SideFX Houdini.
Author: Houdini MCP contributors
License: MIT
Keywords: houdini,mcp,sidefx,codex,claude-code
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.zh-CN.md
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: PyYAML>=6.0; extra == "dev"
Requires-Dist: jinja2>=3.1; extra == "dev"
Dynamic: license-file

# Houdini MCP

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

## 架构

```text
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。

详细设计见[架构文档](docs/ARCHITECTURE.md)。

## 要求

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

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

## 安装

```powershell
$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](docs/GETTING_STARTED.md)。

### pip 安装

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

```powershell
pip install hmcp
houdini-mcp init
```

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

## MCP 配置

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

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

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

```json
{
  "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 时：

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

## 验证

```powershell
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](docs/GETTING_STARTED.md)
- [快速说明与客户端边界](docs/CLIENT_SETTINGS.md)
- [工具与能力](docs/TOOLS.md)
- [全局官方文档能力树](docs/OFFICIAL_CAPABILITY_TREE.md)
- [规范符合性（基础框架）](docs/SPEC_COMPLIANCE.md)
- [架构](docs/ARCHITECTURE.md)
- [安全](docs/SECURITY.md)
- [兼容性](docs/COMPATIBILITY.md)
- [Skills](docs/SKILLS.md)
- [贡献指南](CONTRIBUTING.md)
- [许可证](LICENSE)
