houdini-mcp-server 0.4.0__tar.gz

houdini_mcp_server-0.4.0/.gitignore

@@ -0,0 +1,30 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Test artifacts
+.pytest_cache/
+
+# Hip ingest output (generated via scripts/ingest/)
+hip_parsed.json
+hda_parsed.json
+hip_patterns/
+hip_patterns_index.json
+
+# env files
+.env
+.env.*
+
+# agent environment-specific 
+.claude
+
+# generally ignore hidden files and directories except for .gitignore
+.*
+!.gitignore

houdini_mcp_server-0.4.0/AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md
+
+Project information: @README.md
+
+## Guides
+
+- [Architecture](agents/architecture.md) — the three layers, and which file owns what.
+- [Deployment](agents/deployment.md) — this repo is canonical; Houdini reads copies.
+- [Code](agents/code.md) — one source of truth, small modules, no legacy paths.
+- [Testing](agents/testing.md) — test the change, do not commit the test.
+- [Houdini API](agents/houdini-api.md) — the API is the authority, not your memory.
+- [Issues](agents/issues.md) — where specs live.
+
+## Rules
+
+- Use ASD-STE100 Simplified Technical English in all writing: replies, comments,
+  commits, pull requests.
+- Do not keep backward compatibility. Delete the old path. Do not add fallbacks,
+  shims, or migrations.
+- Do not write documentation that a person can get from the code. Write a short
+  comment in the code instead.
+- Do not record a fact that goes stale: tool counts, version numbers, file
+  inventories, status tables, audit results. Point to the code that holds it.
+- Do not add a file to this repo unless the product needs it. Scratch work goes
+  in a temporary directory.
+- Do not commit or publish SideFX content or any other copyrighted material.
+  This includes help pages, images from the Houdini install, and test fixtures
+  made from them. Make a fixture on the machine that runs the test.
+- Look at the change in a live Houdini before you report it done. Code that
+  imports is not a plugin that answers. See [Deployment](agents/deployment.md):
+  Houdini runs a copy, so run the installer and restart Houdini first.

houdini_mcp_server-0.4.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+
+Copyright (c) 2025 Capoom
+Copyright (c) 2026 John Chedeville
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

houdini_mcp_server-0.4.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: houdini-mcp-server
+Version: 0.4.0
+Summary: MCP server for SideFX Houdini: 20 tools, honest failures, version-exact documentation
+Project-URL: Repository, https://github.com/JTCHE/houdini-mcp
+Project-URL: Issues, https://github.com/JTCHE/houdini-mcp/issues
+Author: John Chedeville
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d,houdini,mcp,model-context-protocol,sidefx,vfx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: houdinimd-docs>=0.1
+Requires-Dist: mcp[cli]>=2.2
+Description-Content-Type: text/markdown
+
+# Houdini MCP
+
+<img src="public/cover.png" alt="An illustration titled &quot;Houdini MCP&quot;, showing multiple agentic platforms connected to Houdini, symbolizing a link" />
+
+<p align="center" alt="HoudiniMCP Server Glama Badge">
+  <a href="https://glama.ai/mcp/servers/JTCHE/houdini-mcp"><img src="https://glama.ai/mcp/servers/JTCHE/houdini-mcp/badges/card.svg">
+  </a>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/JTCHE/houdini-mcp?color=blue" alt="License: MIT"/></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"/></a>
+  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP Compatible"/></a>
+  <a href="https://www.sidefx.com/"><img src="https://img.shields.io/badge/Houdini-22.0-orange" alt="Houdini 22.0"/></a>
+</p>
+---
+
+Control **SideFX Houdini** from an AI client (Claude, ChatGPT Codex, Gemini) through the **Model Context Protocol**.
+
+The bridge talks to Houdini's Python API over a local TCP socket.
+
+If no Houdini GUI is running, the bridge starts a
+headless `hython` session, so you can work without the UI.
+
+- **20 tools** — one for each noun: `scene_overview`, `node_inspect`,
+  `geometry_inspect`, `stage_inspect`, `node_edit`, `parm_set`, `connect`,
+  `cook`, `execute`, `render`, `capture`, `console`, `docs`, `playbar`,
+  `scene_file`, `select`, `hda`, `pdg`, `session`, `batch`. A `mode` argument
+  chooses the action, and every tool takes one item or a list. The modules are
+  in [`src/bridge/tools/`](src/bridge/tools/).
+- **Honest failures** — a write that Houdini silently ignored is reported as
+  such, and every error names the next action.
+- **Documentation** — the official Houdini docs for the exact build on this
+  machine, read out of the install by the [HoudiniMD](https://houdinimd.com)
+  engine. No network.
+
+## Install
+
+**Prerequisites:** Python 3.10+. Houdini is optional at setup time.
+
+The script installs [uv](https://docs.astral.sh/uv/) and the `houdinimcp`
+package from PyPI, installs the Houdini plugin, and registers the bridge with
+the agent harnesses you pick.
+
+**Windows**
+
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/bootstrap.bat -OutFile bootstrap.bat; .\bootstrap.bat"
+```
+
+**Linux / macOS**
+
+```bash
+curl -sSL https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/bootstrap.sh | bash
+```
+
+At a terminal you get menus: which Houdini release to install for, which
+harnesses to configure — Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor,
+opencode, pi. pi reads MCP servers through its
+[pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) extension.
+
+Have uv already? `uv tool install houdini-mcp-server && houdinimcp-install` does the
+same thing.
+
+Working from a clone? Run the installer from the repository root:
+`uv run python -m bridge.onboarding.install`. It installs the plugin from that
+clone, and points every harness at it.
+
+<details>
+<summary><strong>Unattended install (agents, CI, scripted setup)</strong></summary>
+
+The installer never blocks without a terminal: it takes the default for every
+question and says so. Flags make each choice explicit, and `--json` reports what
+it did.
+
+```bash
+# What is on this machine, as JSON: Houdini releases, harnesses, uv
+houdinimcp-install --list
+
+# Every default: newest Houdini, every detected harness
+houdinimcp-install --yes
+
+# Explicit, and report what changed
+houdinimcp-install --houdini-version 22.0 --harness claude-code --harness codex --yes --json
+
+# Report only, change nothing
+houdinimcp-install --dry-run --yes
+```
+
+From a clone, `uv run python -m bridge.onboarding.install` takes the same flags.
+
+`bootstrap.sh` and `bootstrap.bat` pass every flag through, so the one-line
+install above works unattended too — `bash bootstrap.sh --yes` on Linux and
+macOS, `.\bootstrap.bat --yes` on Windows.
+
+Useful flags: `--houdini-version none` skips the plugin, `--prefs-dir` names the
+Houdini preferences directory outright, `--harness none` leaves every client
+alone, `--skip-deps` skips `uv sync` in a clone, `--quiet-start` stops the
+usage statistics dialog and the Start Here window that cover the viewport on
+a first launch (it adds `HOUDINI_NO_START_PAGE_SPLASH = 1` to `houdini.env`).
+
+With `--json`, stdout carries the JSON report and nothing else — the progress
+log goes to stderr. The report names every file written and every client
+configured, so it is also the verification: read `plugin.wrote` and
+`harnesses[].target` back, and check `errors` is empty. `claude mcp list` is the
+independent check for Claude Code.
+
+</details>
+
+<details>
+<summary><strong>Manual setup</strong></summary>
+
+```bash
+uv tool install houdini-mcp-server
+houdinimcp-install --harness none                              # plugin only
+claude mcp add --transport stdio houdini -- houdinimcp-bridge
+```
+
+For a client that reads a JSON config, point `command` at `houdinimcp-bridge`
+with no arguments. From a clone, point it at `uv` with
+`args: ["--directory", "/path/to/houdini-mcp", "run", "python", "houdini_mcp_server.py"]`.
+
+ChatGPT accepts remote MCP servers only. The bridge speaks stdio, so put a
+stdio-to-HTTP proxy in front of it and expose that with a tunnel.
+
+</details>
+
+## How it works
+
+```
+MCP client ──stdio──> src/bridge/ ──TCP──> src/houdinimcp/ ──> hou API
+                                  └──────> houdinimd_docs ──> $HFS/houdini/help
+
+No Houdini running? The bridge starts hython -> houdinimcp/headless.py
+```
+
+`src/bridge/` is the MCP side and holds the installer. `src/houdinimcp/` is the
+plugin, which Houdini loads from a copy in its preferences directory.
+
+The installer also adds a **HoudiniMCP** shelf with a button that starts and
+stops the TCP server.
+
+Headless mode gives you every tool except the ones that need a UI: viewport,
+screenshots and flipbooks. Set `HOUDINIMCP_NO_HEADLESS=1` to turn auto-launch off.
+For those, `session` with `action="start_gui"` starts Houdini with its window
+(and `hip=` opens a file), then waits for the plugin.
+
+On Windows, a Houdini that the bridge starts reads the same preferences as one
+started from the Start menu: the bridge sets `HOUDINI_USER_PREF_DIR` when it is
+not set. A shell that sets `HOME` (Git Bash does) otherwise sends Houdini to
+`$HOME\houdiniX.Y`.
+
+## Contributing
+
+Read [AGENTS.md](AGENTS.md) before you change anything. It carries the working
+rules and links to the short guides in [`agents/`](agents/).
+
+## Acknowledgements
+
+Built on the work of [blender-mcp](https://github.com/ahujasid/blender-mcp),
+[capoomgit/houdini-mcp](https://github.com/capoomgit/houdini-mcp),
+[eetumartola/houdini-mcp](https://github.com/eetumartola/houdini-mcp),
+[Houdini21MCP](https://github.com/orrzxz/Houdini21MCP) and
+[fxhoudinimcp](https://github.com/healkeiser/fxhoudinimcp).
+
+MIT licensed.
+
+---
+
+<sub>HoudiniMCP is an independent community project. It is not affiliated with,
+endorsed by, or sponsored by SideFX Software. Houdini and SideFX are trademarks
+of SideFX Software Inc.</sub>

houdini_mcp_server-0.4.0/README.md

@@ -0,0 +1,172 @@
+# Houdini MCP
+
+<img src="public/cover.png" alt="An illustration titled &quot;Houdini MCP&quot;, showing multiple agentic platforms connected to Houdini, symbolizing a link" />
+
+<p align="center" alt="HoudiniMCP Server Glama Badge">
+  <a href="https://glama.ai/mcp/servers/JTCHE/houdini-mcp"><img src="https://glama.ai/mcp/servers/JTCHE/houdini-mcp/badges/card.svg">
+  </a>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/JTCHE/houdini-mcp?color=blue" alt="License: MIT"/></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"/></a>
+  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP Compatible"/></a>
+  <a href="https://www.sidefx.com/"><img src="https://img.shields.io/badge/Houdini-22.0-orange" alt="Houdini 22.0"/></a>
+</p>
+---
+
+Control **SideFX Houdini** from an AI client (Claude, ChatGPT Codex, Gemini) through the **Model Context Protocol**.
+
+The bridge talks to Houdini's Python API over a local TCP socket.
+
+If no Houdini GUI is running, the bridge starts a
+headless `hython` session, so you can work without the UI.
+
+- **20 tools** — one for each noun: `scene_overview`, `node_inspect`,
+  `geometry_inspect`, `stage_inspect`, `node_edit`, `parm_set`, `connect`,
+  `cook`, `execute`, `render`, `capture`, `console`, `docs`, `playbar`,
+  `scene_file`, `select`, `hda`, `pdg`, `session`, `batch`. A `mode` argument
+  chooses the action, and every tool takes one item or a list. The modules are
+  in [`src/bridge/tools/`](src/bridge/tools/).
+- **Honest failures** — a write that Houdini silently ignored is reported as
+  such, and every error names the next action.
+- **Documentation** — the official Houdini docs for the exact build on this
+  machine, read out of the install by the [HoudiniMD](https://houdinimd.com)
+  engine. No network.
+
+## Install
+
+**Prerequisites:** Python 3.10+. Houdini is optional at setup time.
+
+The script installs [uv](https://docs.astral.sh/uv/) and the `houdinimcp`
+package from PyPI, installs the Houdini plugin, and registers the bridge with
+the agent harnesses you pick.
+
+**Windows**
+
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/bootstrap.bat -OutFile bootstrap.bat; .\bootstrap.bat"
+```
+
+**Linux / macOS**
+
+```bash
+curl -sSL https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/bootstrap.sh | bash
+```
+
+At a terminal you get menus: which Houdini release to install for, which
+harnesses to configure — Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor,
+opencode, pi. pi reads MCP servers through its
+[pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) extension.
+
+Have uv already? `uv tool install houdini-mcp-server && houdinimcp-install` does the
+same thing.
+
+Working from a clone? Run the installer from the repository root:
+`uv run python -m bridge.onboarding.install`. It installs the plugin from that
+clone, and points every harness at it.
+
+<details>
+<summary><strong>Unattended install (agents, CI, scripted setup)</strong></summary>
+
+The installer never blocks without a terminal: it takes the default for every
+question and says so. Flags make each choice explicit, and `--json` reports what
+it did.
+
+```bash
+# What is on this machine, as JSON: Houdini releases, harnesses, uv
+houdinimcp-install --list
+
+# Every default: newest Houdini, every detected harness
+houdinimcp-install --yes
+
+# Explicit, and report what changed
+houdinimcp-install --houdini-version 22.0 --harness claude-code --harness codex --yes --json
+
+# Report only, change nothing
+houdinimcp-install --dry-run --yes
+```
+
+From a clone, `uv run python -m bridge.onboarding.install` takes the same flags.
+
+`bootstrap.sh` and `bootstrap.bat` pass every flag through, so the one-line
+install above works unattended too — `bash bootstrap.sh --yes` on Linux and
+macOS, `.\bootstrap.bat --yes` on Windows.
+
+Useful flags: `--houdini-version none` skips the plugin, `--prefs-dir` names the
+Houdini preferences directory outright, `--harness none` leaves every client
+alone, `--skip-deps` skips `uv sync` in a clone, `--quiet-start` stops the
+usage statistics dialog and the Start Here window that cover the viewport on
+a first launch (it adds `HOUDINI_NO_START_PAGE_SPLASH = 1` to `houdini.env`).
+
+With `--json`, stdout carries the JSON report and nothing else — the progress
+log goes to stderr. The report names every file written and every client
+configured, so it is also the verification: read `plugin.wrote` and
+`harnesses[].target` back, and check `errors` is empty. `claude mcp list` is the
+independent check for Claude Code.
+
+</details>
+
+<details>
+<summary><strong>Manual setup</strong></summary>
+
+```bash
+uv tool install houdini-mcp-server
+houdinimcp-install --harness none                              # plugin only
+claude mcp add --transport stdio houdini -- houdinimcp-bridge
+```
+
+For a client that reads a JSON config, point `command` at `houdinimcp-bridge`
+with no arguments. From a clone, point it at `uv` with
+`args: ["--directory", "/path/to/houdini-mcp", "run", "python", "houdini_mcp_server.py"]`.
+
+ChatGPT accepts remote MCP servers only. The bridge speaks stdio, so put a
+stdio-to-HTTP proxy in front of it and expose that with a tunnel.
+
+</details>
+
+## How it works
+
+```
+MCP client ──stdio──> src/bridge/ ──TCP──> src/houdinimcp/ ──> hou API
+                                  └──────> houdinimd_docs ──> $HFS/houdini/help
+
+No Houdini running? The bridge starts hython -> houdinimcp/headless.py
+```
+
+`src/bridge/` is the MCP side and holds the installer. `src/houdinimcp/` is the
+plugin, which Houdini loads from a copy in its preferences directory.
+
+The installer also adds a **HoudiniMCP** shelf with a button that starts and
+stops the TCP server.
+
+Headless mode gives you every tool except the ones that need a UI: viewport,
+screenshots and flipbooks. Set `HOUDINIMCP_NO_HEADLESS=1` to turn auto-launch off.
+For those, `session` with `action="start_gui"` starts Houdini with its window
+(and `hip=` opens a file), then waits for the plugin.
+
+On Windows, a Houdini that the bridge starts reads the same preferences as one
+started from the Start menu: the bridge sets `HOUDINI_USER_PREF_DIR` when it is
+not set. A shell that sets `HOME` (Git Bash does) otherwise sends Houdini to
+`$HOME\houdiniX.Y`.
+
+## Contributing
+
+Read [AGENTS.md](AGENTS.md) before you change anything. It carries the working
+rules and links to the short guides in [`agents/`](agents/).
+
+## Acknowledgements
+
+Built on the work of [blender-mcp](https://github.com/ahujasid/blender-mcp),
+[capoomgit/houdini-mcp](https://github.com/capoomgit/houdini-mcp),
+[eetumartola/houdini-mcp](https://github.com/eetumartola/houdini-mcp),
+[Houdini21MCP](https://github.com/orrzxz/Houdini21MCP) and
+[fxhoudinimcp](https://github.com/healkeiser/fxhoudinimcp).
+
+MIT licensed.
+
+---
+
+<sub>HoudiniMCP is an independent community project. It is not affiliated with,
+endorsed by, or sponsored by SideFX Software. Houdini and SideFX are trademarks
+of SideFX Software Inc.</sub>

houdini_mcp_server-0.4.0/agents/architecture.md

@@ -0,0 +1,43 @@
+# Architecture
+
+Three layers. Each runs in a different process.
+
+1. **Bridge** — `src/bridge/`, started by `houdini_mcp_server.py` in a clone or
+   by the `houdinimcp-bridge` console script from the package. Speaks MCP over
+   stdio to the client, and JSON over a TCP socket to the plugin.
+   `connection.py` is the only place that touches the socket, and it starts a
+   headless Houdini when nothing listens. `tools/` holds one module for each
+   tool, and `onboarding/` holds the installer.
+2. **Plugin** — `src/houdinimcp/`. Runs inside Houdini. `server.py` accepts the
+   socket, `tools/` holds one module for each tool, and the tools call
+   `handlers/`. `headless.py` runs the plugin in hython. Only this layer imports
+   `hou`.
+3. **Documentation** — the `houdinimd-docs` wheel, the HoudiniMD engine built
+   for Python. No Houdini running and no network needed: it reads the help out
+   of the Houdini install on this machine and keeps an FTS5 index beside the
+   HoudiniMD app's own. `bridge/tools/docs.py` is the only caller.
+
+`src/houdinimcp/protocol.py` holds the port and the wire format. Both sides
+import it, so neither side can define its own port. A message is a 4-byte
+big-endian length, then the UTF-8 JSON body.
+
+## The tool surface
+
+One tool covers one noun. A `mode` argument chooses the action, and every tool
+takes one item or a list of items, so no tool has a batch twin.
+
+A tool is a pair of modules with the same name: `src/bridge/tools/<name>.py`
+holds `tool(...)`, whose docstring is what the model reads, and
+`src/houdinimcp/tools/<name>.py` holds `run(...)`, which does the work inside
+Houdini. Both sides find their modules by the file name, so a new tool needs no
+registration and no dispatch table. `MUTATES = True` on the plugin module puts
+the call in an undo group.
+
+## Boundaries
+
+- The plugin must not know about MCP. The bridge must not import `hou`.
+- Each handler module owns one Houdini context (nodes, geometry, LOPs, COPs...).
+  A new context gets a new module, not a longer existing one.
+- Handlers take plain JSON and return plain JSON. Keep Houdini types inside.
+- A failure names the next action. "Not connected" is not an answer; "start
+  Houdini, or call session with action='start'" is.

houdini_mcp_server-0.4.0/agents/code.md

@@ -0,0 +1,30 @@
+# Code
+
+## One source of truth
+
+Each value, shape, and rule lives in one place. Ports, paths, defaults, and
+patterns get one definition that every caller imports. A value written twice
+will drift.
+
+If you find the same value in two files, that is a bug. Fix the duplication
+before you fix the symptom.
+
+## Small modules
+
+Split by purpose, not by size. A module does one thing and says so in its name.
+Shared logic goes in a module both callers import — never copied, never
+re-implemented.
+
+Orchestration goes in the entry points. One-purpose logic goes in focused
+modules that the entry points call.
+
+## Change discipline
+
+- Fix the cause, not the symptom. Before you edit a function, find every caller.
+  One guard in the shared function beats a guard in each caller.
+- Choose the simplest code that meets the current requirement. Do not add
+  configuration, indirection, or abstraction for a need that does not exist yet.
+- Delete more than you add when you can.
+- Use names that explain themselves. `positionX`, not `pX`.
+- Write a comment only when the code cannot show the reason. Keep it to one or
+  two lines, next to the code it explains.

houdini_mcp_server-0.4.0/agents/deployment.md

@@ -0,0 +1,21 @@
+# Deployment
+
+This repo is the source. Houdini does not read it.
+
+Houdini loads a **copy** of the plugin from its own preferences directory.
+`src/bridge/onboarding/` makes that copy, as one Houdini package that holds the
+module, the startup script and the shelf. An edit in `src/houdinimcp/` has no
+effect on a running Houdini until you run the installer again and restart the
+plugin.
+
+The installer copies the `houdinimcp` package that it imports itself, so a clone
+installs the working tree and a PyPI install installs the package. Run it from a
+clone with `uv run python -m bridge.onboarding.install`.
+
+The repository ships `.mcp.json`, a project-scope MCP server, for work inside
+the repo. The installer writes a user-scope server as well, so a client that
+reads both reports a scope conflict on the name `houdini`. Expected when you
+install this repo onto itself; pick one scope to keep enabled.
+
+Two copies that drift apart is the most costly failure in this project. If a fix
+does not appear, confirm which copy Houdini loaded before you debug the code.

houdini_mcp_server-0.4.0/agents/houdini-api.md

@@ -0,0 +1,29 @@
+# Houdini API
+
+The `hou` module is the authority. Your memory of it is not.
+
+Houdini changes method names, enum members, and node categories between
+releases. Confirm a symbol exists before you call it: read the object with
+`dir()`, or query the live session.
+
+The product supports Houdini 21.0 and 22.0. Add a version conditional only
+where the behaviour is genuinely different. Keep it in one place inside the
+tool that needs it, and name the releases it covers in a comment. A version
+check that guards a symbol you did not confirm is a guess, not a fix.
+
+Do not record API facts in this repo. Facts about one release go stale. Use the
+`docs` tool for reference, and the live session for truth.
+
+## Failure behaviour
+
+Houdini often fails without an error. A name that does not match, a parameter
+with an expression, a node outside its frame range: each produces a wrong result
+and no message.
+
+So a handler must:
+
+- Report what Houdini reported. Pass `node.errors()` and `node.warnings()` to
+  the caller instead of a generic message.
+- Name what it could not do. A parameter that does not exist, a node that did
+  not cook, an input that it skipped — return it, do not drop it.
+- Fail loudly on a partial result. Silence reads as success to the caller.

houdini_mcp_server-0.4.0/agents/issues.md

@@ -0,0 +1,18 @@
+# Issues
+
+Issues and features live as specs in an Obsidian base, not in this repo.
+
+**Vault path:** `<value of OBSIDIAN_VAULT_PATH in @.env.obsidian>/side projects/Houdini/HoudiniMCP — Fork/HoudiniMCP — Fork.base`
+
+## Spec format
+
+Frontmatter: `Type` (Issue | Feature), `Area`, `Status` (Open | Closed),
+`Priority` (P1 | P2 | P3).
+
+Body: one short paragraph. Name the file and the behaviour. State the decision
+to make. No code blocks, no steps, no history.
+
+## Status
+
+When you commit work that closes a spec, and the user confirms it is complete,
+set `Status: Closed` in that spec.

houdini_mcp_server-0.4.0/agents/testing.md

@@ -0,0 +1,16 @@
+# Testing
+
+Test your change. Do not commit the test.
+
+Write the smallest check that fails if the logic breaks, run it, read the
+result, then delete it. A test written for one change is waste in the tree: it
+adds files to read, it goes stale, and nobody runs it again.
+
+Keep a test only if the user asks for it, or if it protects logic that a person
+cannot check by hand and that will change again.
+
+Scratch scripts, smoke tests, and one-off harnesses go in a temporary directory,
+never in the repo.
+
+Prefer a real check over a mock. A Houdini behaviour is only confirmed against
+a running Houdini or `hython`.

houdini_mcp_server-0.4.0/bootstrap.bat

@@ -0,0 +1,42 @@
+@echo off
+setlocal enabledelayedexpansion
+REM bootstrap.bat — One-command setup for HoudiniMCP (Windows).
+REM
+REM Puts uv on the machine, installs the houdinimcp package from PyPI, then
+REM hands over to the installer, which does the Houdini plugin and the MCP
+REM client configuration.
+REM
+REM Fresh install:        powershell -c "irm https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/bootstrap.bat -OutFile bootstrap.bat; .\bootstrap.bat"
+REM From inside a clone:  bootstrap.bat          (uses the code in the clone)
+REM No questions:         bootstrap.bat --yes
+REM Every installer flag is passed through: bootstrap.bat --houdini-version 22.0 --harness codex
+
+echo.
+echo === HoudiniMCP bootstrap ===
+echo.
+
+where uv >nul 2>&1
+if errorlevel 1 (
+    echo [..]   Installing uv...
+    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+    set "PATH=%USERPROFILE%\.local\bin;!PATH!"
+)
+where uv >nul 2>&1
+if errorlevel 1 (
+    echo [FAIL] uv install failed. https://docs.astral.sh/uv/
+    exit /b 1
+)
+for /f "tokens=*" %%v in ('uv --version') do echo [OK]   %%v
+
+if exist "pyproject.toml" if exist "houdini_mcp_server.py" set "IN_REPO=1"
+if defined IN_REPO (
+    echo [OK]   Inside the repository — installing from this clone
+    uv run python -m bridge.onboarding.install %*
+    exit /b !errorlevel!
+)
+
+echo [..]   Installing houdinimcp from PyPI...
+uv tool install --force houdini-mcp-server || exit /b 1
+echo [OK]   Installed
+houdinimcp-install %*
+exit /b !errorlevel!