Skip to content

fix(claude-code-mcp): make run_mcp.sh bootstrap idempotent on Windows#1565

Open
ottopichlhoefer wants to merge 1 commit into
vectorize-io:mainfrom
ottopichlhoefer:fix/claude-code-windows-venv-bootstrap
Open

fix(claude-code-mcp): make run_mcp.sh bootstrap idempotent on Windows#1565
ottopichlhoefer wants to merge 1 commit into
vectorize-io:mainfrom
ottopichlhoefer:fix/claude-code-windows-venv-bootstrap

Conversation

@ottopichlhoefer
Copy link
Copy Markdown

Summary

  • Resolves the venv interpreter via both bin/python and bin/python.exe. On Windows-built venvs the file is python.exe, and bash's [ -x ] test does not honor PATHEXT — so the previous probe never matched and the bootstrap branch fired on every session start.
  • Splits venv creation from pip-sync. Pip now reruns only when the requirements cache is missing, requirements drifted, or mcp is not importable from the venv. Warm starts now skip both venv recreation and pip install, which also stops the cascade where re-running pip over the in-use venv hit ERROR_SHARING_VIOLATION on Windows and left orphan pip.exe/python3.exe processes locking the venv files.
  • Aborts with a clear stderr message if venv creation still produces no usable interpreter, rather than failing later inside exec.

Fixes #1564.

Why

On Windows (msys2 bash + C:\msys64\mingw64\bin\python.exe), Claude Code logged Failed to reconnect to plugin:hindsight-memory:hindsight. at every session start. bash -x scripts/run_mcp.sh showed the bootstrap branch firing every time, falling back to python -m venv over an in-use venv, and erroring [Errno 13] Permission denied: '.../venv/bin/python3.exe'. Full reproduction in #1564.

Test plan

  • bash -n hindsight-integrations/claude-code/scripts/run_mcp.sh — clean.
  • Cold start (no venv): bootstrap creates the venv, pip installs, exec reaches mcp_server.py.
  • Warm start (venv + cache present, mcp importable): both bootstrap probes short-circuit; script reaches exec without touching pip or recreating the venv. Verified on Windows 11 / msys2 5.2.37 / Python 3.12.11.
  • Linux/macOS warm + cold smoke (would appreciate a CI check — I only have Windows handy).

Notes

  • Behavior on systems where bin/python exists as an extensionless symlink (Linux/macOS) is unchanged: the first branch of resolve_py still hits.
  • The script remains a single-file shell change; no Python/Node touched, so I skipped ./scripts/hooks/lint.sh.
  • I'm not adding a tests/ entry — the existing pytest suite under hindsight-integrations/claude-code/tests/ covers Python modules, not the bootstrap shell. Happy to wire up a tiny shell-test harness if you want it.

The interpreter probe `[ -x "${VENV}/bin/python" ]` never matches on a
Windows-built venv, where the file is `python.exe` and bash's `-x` test
does not honor PATHEXT. As a result the bootstrap branch fired on every
session start, and `python -m venv` collided with the previously spawned
MCP server still holding `python3.exe`/`pip.exe` open, surfacing as
"Failed to reconnect to plugin:hindsight-memory:hindsight." in Claude
Code.

This change:

- Probes both `bin/python` and `bin/python.exe`, exposing the resolved
  interpreter as `${PY}`/`${PIP}` for the rest of the script.
- Splits venv creation from pip-sync. Pip now reruns only when the
  requirements cache is missing, requirements drifted, or `mcp` is not
  importable from the venv — so warm starts skip pip entirely and avoid
  re-running it over a venv that's already in use.
- Aborts with a clear stderr message if venv creation produces no usable
  interpreter (rather than failing later inside `exec`).

Fixes vectorize-io#1564.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

run_mcp.sh re-bootstraps venv every session on Windows; [ -x bin/python ] never matches python.exe

1 participant