capture-hooks install rewrites Claude MCP config to packaged wrapper which cannot resolve @modelcontextprotocol/sdk

[Marsu6996]

Summary

iai-mcp capture-hooks install rewrites ~/.claude.json and ~/Library/Application Support/Claude/claude_desktop_config.json so that the iai-mcp MCP server is launched via the wrapper shipped inside the wheel:

/Users/<user>/<env>/.venv/lib/python3.11/site-packages/iai_mcp/_wrapper/index.js

That directory ships the wrapper JS files but no package.json and no node_modules/. As soon as Claude Desktop or Claude Code tries to spawn it, Node fails with:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@modelcontextprotocol/sdk' imported from
  .../site-packages/iai_mcp/_wrapper/index.js

and the MCP entry shows up as failed in the Claude Desktop developer panel.

Repro

1. Clone the repo, set up the venv, pip install . (so the wheel is installed into site-packages with the bundled _wrapper/ JS but no node deps).
2. Run iai-mcp capture-hooks install.
3. Restart Claude Desktop.
4. Open Settings → Developer → MCP. The iai-mcp entry is failed; the log shows ERR_MODULE_NOT_FOUND: @modelcontextprotocol/sdk.

Why it works on dev installs that build the wrapper separately

In a dev layout, the actually-runnable wrapper lives at mcp-wrapper/dist/index.js next to its node_modules/ (after npm install && npm run build in mcp-wrapper/). The pre-v1.2.0 Claude configs on at least this machine pointed there and worked. The new capture-hooks install replaces that path with the in-wheel one and breaks startup.

Affected versions

Observed on v1.2.0 (latest at the time of writing). Did not check whether the same rewrite happened in v1.1.x — happy to confirm if helpful.

Expected behaviour

Either:

• ship the wrapper's npm dependencies inside the wheel (so the in-wheel _wrapper/index.js is genuinely runnable as-is), or
• have capture-hooks install detect a usable mcp-wrapper/dist/index.js next to the venv root and prefer that path, or
• document that capture-hooks install is intended only for self-contained installs and skip the MCP config rewrite when the in-wheel wrapper has no node_modules/.

Local workaround

Repoint mcpServers.iai-mcp.args in both ~/.claude.json and ~/Library/Application Support/Claude/claude_desktop_config.json to <repo>/mcp-wrapper/dist/index.js, then restart Claude.

Environment

• macOS arm64, Node 26.0.0
• Python 3.11, iai-mcp 1.2.0, installed via pip install --upgrade --no-deps . against the v1.2.0 tag

[Marsu6996]

Second side-effect on the same install: capture-hooks install re-registers the SessionStart hook in ~/.claude/settings.json

Worth flagging on top of the MCP-config rewrite reported above. Observed on the same v1.2.0 box during the same capture-hooks install run:

The command re-injects an entry under hooks.SessionStart in ~/.claude/settings.json:

{
  "matcher": "startup|resume|clear|compact",
  "hooks": [
    {
      "type": "command",
      "command": "bash /Users/<me>/.claude/hooks/iai-mcp-session-recall.sh",
      "timeout": 30
    }
  ]
}

The user here had deliberately removed that SessionStart entry weeks ago (the prefix injection at every startup/resume/clear/compact was too noisy for their workflow), while keeping Stop capture and UserPromptSubmit turn capture wired. capture-hooks install silently put it back without any --force / --reinstall flag.

There is also no obvious --skip-session-start / --no-prefix opt-out today, so the workaround is the same as for the MCP-config rewrite: hand-edit ~/.claude/settings.json after every run.

Suggestion

If the command continues to (re)register Claude integration entries, two ergonomics fixes would help:

• respect an existing ~/.claude/settings.json and not re-add a SessionStart entry that was explicitly removed (e.g. via a stamped marker, or just by detecting that the user's settings already have a SessionStart block and the iai-mcp one was deliberately absent);
• expose a --components flag (e.g. --components=stop,turn to install capture without prefix injection).

Happy to expand the workaround section of the runbook for users who want the same setup.

[danielhertz1999-bit]

Thanks for the thorough report (and the spot-on root-cause on both) 🙏 — opened two focused PRs, one per half:

Part 1 — in-wheel wrapper has no node_modules → ERR_MODULE_NOT_FOUND: #28
_resolve_wrapper_path now prefers a wrapper whose deps actually resolve (a reachable node_modules/@modelcontextprotocol/sdk, matching Node's bare-import resolution), so a working mcp-wrapper/dist wins over the depless in-wheel copy. If only a depless wrapper exists it raises a clear "build it / set IAI_MCP_WRAPPER_PATH" error that routes through the existing placeholder path instead of silently wiring a broken iai-mcp entry.

Part 2 — SessionStart re-registration with no opt-out: #29
Adds --components to capture-hooks install (default stop,turn,recall = unchanged). --components=stop,turn installs ambient capture without wiring the SessionStart recall hook — your exact requested setup. It doesn't try to auto-detect "deliberately removed" (not reliably distinguishable from "never installed" without a stamped marker), so it's an explicit opt-out rather than a guess.

Both verified against a redirected temp $HOME. Workaround in the meantime is as you described. Deferring to the maintainer on whether the wheel should instead bundle the wrapper's npm deps (Part 1 alternative) — #28 makes resolution correct either way.

🤖 via Claude Code