feat(mcp): preinstall asyncssh in pinned interpreter (#344)

andrewgazelka · web-flow · commit e234e50f49bd · 2026-05-29T21:43:58.000-07:00
`asyncssh` is now default-installed in the MCP's pinned Python
interpreter, so every persistent session can `import asyncssh` with no
install step, the same way `numpy` and the bundled `tui` module already
are. It is added to the `mcpPython` `withPackages` list in
`packages/mcp/default.nix`, and the initialize-time discovery text in
`server_instructions.txt` now mentions it.

This gives sessions a production-grade option for remote process control
over SSH (run commands on remote hosts, SFTP). AsyncSSH is the
async-native fit for these sessions, which run on one shared persistent
asyncio event loop, so it slots into the existing top-level-`await`
model without spinning up its own loop.

Made with AI (Claude, Opus 4.8).
diff --git a/packages/mcp/default.nix b/packages/mcp/default.nix
@@ -57,6 +57,7 @@ let
   # `--system-site-packages`, so `tui` and numpy are importable by default while
   # an in-session `pip install` still writes to the per-session venv.
   mcpPython = pkgs.python3.withPackages (ps: [
+    ps.asyncssh
     ps.numpy
     tuiModule
   ]);
diff --git a/packages/mcp/src/server_instructions.txt b/packages/mcp/src/server_instructions.txt
@@ -1,4 +1,4 @@
-Persistent Python sessions on a pinned interpreter. Every session can `import tui` with no install step: `tui` is the bundled PyO3 PTY driver (spawn and drive PTY-backed processes with full vt100 emulation, scrollback, and optional NumPy access to per-cell data; the API is async-only, so use it from python_exec/python_eval with top-level await). numpy is preinstalled too, and each session's writable venv keeps `pip install` working for anything else.
+Persistent Python sessions on a pinned interpreter. Every session can `import tui` with no install step: `tui` is the bundled PyO3 PTY driver (spawn and drive PTY-backed processes with full vt100 emulation, scrollback, and optional NumPy access to per-cell data; the API is async-only, so use it from python_exec/python_eval with top-level await). numpy is preinstalled too, as is `asyncssh` for SSH-based remote process control (run commands on remote hosts, SFTP) that fits the shared async event loop, and each session's writable venv keeps `pip install` working for anything else.
 
 Execution model: each session is single-threaded with one persistent asyncio event loop, reused across calls. Write top-level `await` directly (e.g. `rows = await pool.fetch(sql)`); because the loop is shared, an async client or pool created in one call stays usable in later ones. Do not call `asyncio.run()`: inside an awaited block it raises `RuntimeError: asyncio.run() cannot be called from a running event loop`, and outside one it spins up a throwaway loop your resources cannot outlive. `asyncio.get_running_loop()` resolves only inside awaited code. A blocking synchronous call (heavy CPU, `time.sleep`, sync network I/O) freezes the whole session, so reach for the async equivalent.
 

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-Persistent Python sessions on a pinned interpreter. Every session can `import tui` with no install step: `tui` is the bundled PyO3 PTY driver (spawn and drive PTY-backed processes with full vt100 emulation, scrollback, and optional NumPy access to per-cell data; the API is async-only, so use it from python_exec/python_eval with top-level await). numpy is preinstalled too, and each session's writable venv keeps `pip install` working for anything else.
	`1`	+Persistent Python sessions on a pinned interpreter. Every session can `import tui` with no install step: `tui` is the bundled PyO3 PTY driver (spawn and drive PTY-backed processes with full vt100 emulation, scrollback, and optional NumPy access to per-cell data; the API is async-only, so use it from python_exec/python_eval with top-level await). numpy is preinstalled too, as is `asyncssh` for SSH-based remote process control (run commands on remote hosts, SFTP) that fits the shared async event loop, and each session's writable venv keeps `pip install` working for anything else.
`2`	`2`
`3`	`3`	Execution model: each session is single-threaded with one persistent asyncio event loop, reused across calls. Write top-level `await` directly (e.g. `rows = await pool.fetch(sql)`); because the loop is shared, an async client or pool created in one call stays usable in later ones. Do not call `asyncio.run()`: inside an awaited block it raises `RuntimeError: asyncio.run() cannot be called from a running event loop`, and outside one it spins up a throwaway loop your resources cannot outlive. `asyncio.get_running_loop()` resolves only inside awaited code. A blocking synchronous call (heavy CPU, `time.sleep`, sync network I/O) freezes the whole session, so reach for the async equivalent.
`4`	`4`