fix: pin jupyter-mcp-server==0.23.0 in the .mcp.json jupyter entry

[KadenMc]

Summary

Follow-up to #20. _jupyter_mcp_entries() emitted an unpinned jupyter-mcp-server, which uvx resolves to "latest" — currently the v1.0.x line. Since v1.0.0 (2026-04-03), jupyter-mcp-server makes server-startup auth mandatory: it reads JUPYTER_URL / JUPYTER_TOKEN / MCP_TOKEN from the environment when the process starts.

Claude Code spawns this server over stdio with no such env block, so on v1.0.x the process comes up but never completes the MCP handshake — the jupyter server hangs at "connecting" and exposes no tools. An unpinned entry therefore shipped broken-by-default for any fresh aexp install --with-jupyter.

This pins the entry to jupyter-mcp-server==0.23.0 — the last pre-auth release, which supports the runtime connect_to_jupyter(jupyter_url, jupyter_token) call this integration is built on. Pinning forward to v1.0.x is the wrong fix: the cluster JupyterLab URL/token rotate per compute-node session, so a static startup-env model does not fit. 0.23.0 is the version verified against the electricrag deployment (2026-05-15).

Why this is a follow-up and not part of #20: #20 had already merged when the unpinned-default bug surfaced. #20 made it acute — jupyter is now the only Jupyter MCP server, so the broken-by-default resolution has no jupyter-compute fallback — but the unpinned args predate #20.

Changes

• install.py — _jupyter_mcp_entries() pins jupyter-mcp-server==0.23.0. The full rationale lives in the function docstring (the obvious place a future reader will look) plus a short inline comment at the args line, so the pin is not a mystery.
• docs/setup/jupyter-mcp.md — the .mcp.json example, the uvx verification line, and the "Environment reference" table updated to the pin; a new troubleshooting row for the "jupyter server hangs at connecting" symptom.
• tests/test_install.py — asserts the exact pinned args.
• CHANGELOG.md — ### Fixed entry under [Unreleased].

Not in scope

• The [jupyter] pip extra still constrains jupyter-mcp-server (>=1.0.2,<2.0.0). That extra is the cluster-side install (pip install agentic-experiments[jupyter]), a separate concern from the laptop-side .mcp.json entry fixed here, and reconciling it belongs with the deferred cluster-side migration.
• Whether v1.0.x's auth model can eventually be wired up cleanly (and the pin moved forward) is left as a future investigation — noted in the _jupyter_mcp_entries() docstring.

Consumer impact

Existing consumer .mcp.json files keep whatever jupyter entry they already have — the install merge is additive and never overwrites an existing jupyter block. A consumer whose entry predates this fix should add ==0.23.0 to that entry's args by hand. (The electricrag deployment already hand-pinned to ==0.23.0, so it is unaffected.)

Testing

• tests/test_install.py — 59/59 pass
• ruff check src/aexp/install.py — clean

🤖 Generated with Claude Code