mcp-interminal 0.2.0__tar.gz

mcp_interminal-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__
+venv
+.kilo
+.claude
+.vscode
+uv.lock

mcp_interminal-0.2.0/CLAUDE.md

@@ -0,0 +1,148 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Interminal** is an MCP server that gives AI assistants terminal access — SSH and local shells — with support for interactive commands. It is distributed via `uvx` and has no build step.
+
+## Running & Installation
+
+```powershell
+# Run directly (no install)
+python mcp_server.py
+
+# Install from source
+pip install .
+
+# Run via uvx (published package)
+uvx interminal
+```
+
+There are no test, lint, or build commands configured in this project.
+
+## Architecture
+
+```
+mcp_server.py          ← FastMCP tool definitions (7 tools)
+    ↓
+session_manager.py     ← SessionManager: SSH + local session lifecycle
+    ↓
+channel.py             ← Channel abstraction (SSHChannel | LocalChannel | PtyChannel)
+    ↓
+command.py             ← RunningCommand: background read loop, UTF-8 decoding
+```
+
+### Key design decisions
+
+**Channel duck-typing** — `SSHChannel`, `LocalChannel`, and `PtyChannel` share an interface without ABC/abstractmethod. All three implement `read()`, `write()`, `close()`, `send_control()`, and `is_finished()`.
+
+**Two-phase timeout** (`_wait_for_result` in `session_manager.py`) — Phase 1 waits up to `pause_timeout + 1s` for the first byte; if it times out we return immediately (already satisfies the "silent for pause_timeout" contract — going into Phase 2 would waste another full pause_timeout). Phase 2 only runs when bytes are actually arriving, collecting until a `pause_timeout` gap or `total_timeout` hits.
+
+**PtyChannel platform split** — Windows uses `pywinpty.PtyProcess`; Unix uses `stdlib pty` with `fcntl` non-blocking I/O. `pywinpty` is an optional dependency.
+
+**SSHChannel stdin reference** — `session_manager.py` explicitly retains a reference to `stdin` to prevent Python GC from calling `__del__` and closing the paramiko channel prematurely.
+
+**Incremental UTF-8 decoding** — `command.py` uses `codecs.getincrementaldecoder` so multibyte characters split across reads are assembled correctly.
+
+**pyte integration** (`_render_pyte` in `session_manager.py`) — optional ANSI escape sequence cleaning via a `pyte.Screen` subclass that works around a signature mismatch in the upstream library.
+
+**`RunningCommand.close` ordering** — closes the channel *before* awaiting `read_task`. Windows PTY's `read()` runs inside `asyncio.to_thread(pty.read)`, which `task.cancel()` cannot actually interrupt — the future stays pending until the underlying thread exits, and the thread won't exit until the PTY is closed. Closing the channel first unblocks the read, then cancel + await tears the task down cleanly.
+
+**`_read_loop` uses `try/finally`** — `CancelledError` is a `BaseException` subclass, not `Exception`, so a cancel on the read task bypasses the inner `except Exception`. The `finally` block guarantees `running=False` + `new_data_event.set()` always run, so any `_wait_for_result` waiter wakes immediately on cancel instead of stalling until its own `pause_timeout` fires.
+
+### Session lifecycle
+
+1. `create_local()` or `connect_ssh()` creates a `Session` dataclass entry in `SessionManager.sessions`.
+2. `execute()` wraps the session's shell in a `Channel`, then a `RunningCommand` with a background `asyncio` read loop.
+3. `respond()` / `send_control()` write directly to the running command's channel.
+4. `disconnect()` closes the channel, terminates the subprocess/SSH client, and removes the session.
+
+## Using TUI multiplexers (zellij, tmux) over interminal
+
+Each `execute()` call creates an independent `exec_command` channel — there is no
+persistent shell between calls.
+
+### Why `zellij ... &` fails
+
+Backgrounding a TUI multiplexer with `&` does **not** work, but not because of
+SIGHUP. The failure is in zellij's init sequence:
+
+1. Shell parses `zellij &`, forks zellij into a **background process group**, and
+   immediately exits (only command in the shell was the backgrounded one).
+2. zellij's early init does TTY setup (`tcsetattr`, query terminal size, raw
+   mode). A background process group can't safely do this — it triggers
+   SIGTTOU/SIGTTIN, and the operations fail.
+3. Meanwhile the shell has exited, so the PTY is also collapsing.
+4. zellij aborts before it ever reaches the `fork()` + `setsid()` that would
+   daemonize the server. No server is ever created.
+
+So the surface symptom "`list-sessions` shows nothing" is correct, but the cause
+is "init never completed", not "SIGHUP killed a running server".
+
+### The working pattern
+
+Start zellij **in the foreground** (no `&`) and let `execute` return `partial`.
+zellij's server has time to fork + setsid, becoming a daemon in its own session.
+After that, the client/channel state is irrelevant — the server lives until
+explicitly killed.
+
+```
+# 1. Start the session. execute returns "partial" once init is done.
+execute("TERM=xterm-256color ~/work/zellij --session train", total_timeout=4)
+
+# 2. The partial channel can be ignored, disconnected, or left to time out.
+#    The daemonized server survives all of these.
+
+# 3. Drive the session from independent execute calls:
+execute("~/work/zellij --session train action new-pane -- bash start.sh")
+execute("~/work/zellij --session train action dump-screen")
+execute("~/work/zellij list-sessions")
+execute("~/work/zellij delete-session train --force")
+```
+
+### Running a command in a new tab's default pane
+
+zellij's `action new-tab` does **not** accept `-- command` (unlike `new-pane`).
+A naive "open a tab and train" therefore ends up as `new-tab` (creates an empty
+default pane running the shell) + `new-pane -- bash start.sh` (a second pane
+split into the tab), which leaves a leftover empty pane.
+
+To run the command in the new tab's default pane instead, chain `write-chars`
++ `write 13` — `new-tab` focuses the new tab automatically, so the keystrokes
+land in its default pane:
+
+```
+execute("~/work/zellij --session train action new-tab --name v4")
+execute("~/work/zellij --session train action write-chars 'bash start.sh'")
+execute("~/work/zellij --session train action write 13")   # 13 = Enter (CR)
+```
+
+tmux is simpler — `new-window` takes the command directly:
+
+```
+execute("tmux new-window -t main -n train 'bash start.sh'")
+```
+
+This is NOT the same as "puppeting the TUI": `write-chars` / `send-keys` are
+the multiplexer's own structured CLI for injecting input. The thing to avoid
+is using interminal's `respond` / `send_control` against the live TUI display
+— that races against the renderer.
+
+`TERM=xterm-256color` is required: zellij reads `TERM` at startup to pick its
+renderer, and the default inherited from paramiko's PTY is often missing or
+minimal. The same prefix is useful for other TUIs.
+
+tmux works similarly but supports detached startup directly:
+`tmux new-session -d -s train "bash start.sh"` returns immediately and leaves
+a usable session — no partial-channel dance needed, because tmux's `-d` flag
+explicitly forks the server before any TTY operations.
+
+## Dependencies
+
+- `mcp[cli]` — FastMCP framework
+- `paramiko` — SSH client
+- `pywinpty` (optional) — Windows PTY support
+- `pyte` (optional) — ANSI escape sequence rendering
+
+Python ≥ 3.11 required.

mcp_interminal-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 QiuwenZheng
+
+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.

mcp_interminal-0.2.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: mcp-interminal
+Version: 0.2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]
+Requires-Dist: paramiko
+Provides-Extra: ansi
+Requires-Dist: pyte; extra == 'ansi'
+Provides-Extra: pty
+Requires-Dist: pywinpty; extra == 'pty'

mcp_interminal-0.2.0/channel.py

@@ -0,0 +1,242 @@
+import asyncio
+import os
+import sys
+import signal as _signal
+
+PTY_AVAILABLE = False
+if sys.platform == "win32":
+    try:
+        from pywinpty import PtyProcess  # type: ignore
+        PTY_AVAILABLE = True
+    except ImportError:
+        pass
+else:
+    import pty as pty_mod
+    import fcntl
+    PTY_AVAILABLE = True
+
+
+if sys.platform == "win32":
+    # CREATE_NEW_PROCESS_GROUP disables CTRL_C_EVENT for the child group;
+    # CTRL_BREAK_EVENT is the only interrupt that works with that flag.
+    # Windows has no SIGTSTP, so Ctrl+Z is intentionally left unmapped.
+    _LOCAL_SIG_MAP = {b'\x03': _signal.CTRL_BREAK_EVENT}
+else:
+    _LOCAL_SIG_MAP = {b'\x03': _signal.SIGINT}
+    if hasattr(_signal, 'SIGTSTP'):
+        _LOCAL_SIG_MAP[b'\x1a'] = _signal.SIGTSTP
+    if hasattr(_signal, 'SIGQUIT'):
+        _LOCAL_SIG_MAP[b'\x1c'] = _signal.SIGQUIT
+
+
+class Channel:
+    """I/O interface for a running command's data stream."""
+
+    async def read(self) -> bytes | None:
+        """Return data, None (no data yet), or b"" (EOF)."""
+
+    async def write(self, data: bytes) -> None:
+        """Send data to the command's stdin."""
+
+    async def is_finished(self) -> bool:
+        """True when the remote process has exited."""
+
+    async def get_exit_code(self) -> int | None:
+        """Return the exit code (only valid after is_finished)."""
+
+    async def close(self) -> None:
+        """Release underlying resources."""
+
+    async def send_signal(self, sig: bytes) -> None:
+        """Send a control byte (e.g., b'\\x03' for Ctrl+C)."""
+
+
+# ---------------------------------------------------------------------------
+# SSH implementation (paramiko)
+# ---------------------------------------------------------------------------
+
+class SSHChannel(Channel):
+    """Wraps a paramiko.Channel into the Channel interface."""
+
+    def __init__(self, paramiko_channel, stdin=None):
+        self._ch = paramiko_channel
+        # Keep a reference to the stdin ChannelFile so Python GC does NOT call
+        # its __del__ / shutdown_write() early, which would set eof_sent=True
+        # on the underlying channel and prevent any future writes.
+        self._stdin = stdin
+
+    async def read(self) -> bytes | None:
+        if self._ch.recv_ready():
+            return self._ch.recv(4096)
+        return None
+
+    async def write(self, data: bytes) -> None:
+        await asyncio.to_thread(self._ch.sendall, data)
+
+    async def is_finished(self) -> bool:
+        return self._ch.exit_status_ready()
+
+    async def get_exit_code(self) -> int | None:
+        # recv_exit_status() is a blocking socket read. Normally is_finished()
+        # has already returned True (exit_status_ready), so it returns at
+        # once — but EOF can arrive a beat before the exit-status message,
+        # and a sync call there would stall the whole event loop.
+        return await asyncio.to_thread(self._ch.recv_exit_status)
+
+    async def close(self) -> None:
+        try:
+            self._ch.close()
+        except Exception:
+            pass
+
+    async def send_signal(self, sig: bytes) -> None:
+        await self.write(sig)
+
+
+# ---------------------------------------------------------------------------
+# Local subprocess implementation
+# ---------------------------------------------------------------------------
+
+class LocalChannel(Channel):
+    """Wraps an asyncio.subprocess.Process into the Channel interface."""
+
+    def __init__(self, process: asyncio.subprocess.Process):
+        self._proc = process
+
+    async def read(self) -> bytes | None:
+        try:
+            data = await asyncio.wait_for(
+                self._proc.stdout.read(4096), timeout=0.05
+            )
+            # read() returns b"" on EOF
+            return data
+        except asyncio.TimeoutError:
+            return None
+
+    async def write(self, data: bytes) -> None:
+        self._proc.stdin.write(data)
+        await self._proc.stdin.drain()
+
+    async def is_finished(self) -> bool:
+        return self._proc.returncode is not None
+
+    async def get_exit_code(self) -> int | None:
+        return self._proc.returncode
+
+    async def close(self) -> None:
+        if self._proc.returncode is None:
+            self._proc.terminate()
+        try:
+            await asyncio.wait_for(self._proc.wait(), timeout=2.0)
+        except asyncio.TimeoutError:
+            self._proc.kill()
+            await self._proc.wait()
+
+    async def send_signal(self, sig: bytes) -> None:
+        os_sig = _LOCAL_SIG_MAP.get(sig)
+        if os_sig:
+            self._proc.send_signal(os_sig)
+
+
+# ---------------------------------------------------------------------------
+# PTY implementation (pywinpty on Windows, stdlib pty on Linux)
+# ---------------------------------------------------------------------------
+
+if PTY_AVAILABLE:
+    import subprocess
+
+    class PtyChannel(Channel):
+        """PTY-backed channel. Windows: pywinpty. Linux: stdlib pty."""
+
+        def __init__(self, command: str, shell: str):
+            self._finished = False
+            self._exit_code = None
+
+            if sys.platform == "win32":
+                self._pty = PtyProcess.spawn(f'{shell} /c {command}')
+                self._fd = None
+                self._proc = None
+            else:
+                master, slave = pty_mod.openpty()
+                try:
+                    self._proc = subprocess.Popen(
+                        [shell, "-c", command],
+                        stdin=slave, stdout=slave, stderr=slave,
+                        preexec_fn=os.setsid,
+                    )
+                except Exception:
+                    # Popen failed (bad shell path, ENOMEM, EPERM, ...).
+                    # Without this both PTY fds would leak.
+                    os.close(master)
+                    os.close(slave)
+                    raise
+                os.close(slave)
+                self._fd = master
+                flags = fcntl.fcntl(self._fd, fcntl.F_GETFL)
+                fcntl.fcntl(self._fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+                self._pty = None
+
+        async def read(self) -> bytes | None:
+            if sys.platform == "win32":
+                try:
+                    data = await asyncio.to_thread(self._pty.read, 4096)
+                    return data.encode() if isinstance(data, str) else data
+                except EOFError:
+                    self._finished = True
+                    return b""
+            else:
+                try:
+                    return os.read(self._fd, 4096)
+                except BlockingIOError:
+                    return None
+                except OSError:
+                    return b""
+
+        async def write(self, data: bytes) -> None:
+            if sys.platform == "win32":
+                # bytes.decode() defaults to utf-8 regardless of locale, so
+                # the normal path is fine. errors='replace' is defensive:
+                # if upstream ever hands us non-utf-8 bytes, we'd rather
+                # write a replacement char than crash the read loop.
+                self._pty.write(data.decode('utf-8', errors='replace'))
+            else:
+                os.write(self._fd, data)
+
+        async def is_finished(self) -> bool:
+            if self._finished:
+                return True
+            if sys.platform == "win32":
+                if not self._pty.isalive():
+                    self._exit_code = self._pty.exitstatus
+                    self._finished = True
+            else:
+                ret = self._proc.poll()
+                if ret is not None:
+                    self._exit_code = ret
+                    self._finished = True
+            return self._finished
+
+        async def get_exit_code(self) -> int | None:
+            return self._exit_code
+
+        async def close(self) -> None:
+            if sys.platform == "win32":
+                if self._pty.isalive():
+                    self._pty.close()
+            else:
+                try:
+                    os.close(self._fd)
+                except OSError:
+                    pass
+                if not self._finished:
+                    self._proc.terminate()
+                    try:
+                        await asyncio.to_thread(self._proc.wait, 2.0)
+                    except subprocess.TimeoutExpired:
+                        self._proc.kill()
+                        await asyncio.to_thread(self._proc.wait)
+
+        async def send_signal(self, sig: bytes) -> None:
+            await self.write(sig)
+            if sys.platform == "win32" and sig == b'\x03':
+                self._finished = True

mcp_interminal-0.2.0/command.py

@@ -0,0 +1,105 @@
+import asyncio
+import codecs
+import logging
+
+from channel import Channel
+
+logger = logging.getLogger("interminal.command")
+
+
+class RunningCommand:
+    """Manages one running command with background output buffering."""
+
+    def __init__(self, channel: Channel, session_id: str):
+        self.channel = channel
+        self.session_id = session_id
+
+        self.buffer = ""
+        self.running = True
+        self.exit_code = None
+        self.new_data_event = asyncio.Event()
+        self.decoder = codecs.getincrementaldecoder('utf-8')('replace')
+        # Wall-clock of the last byte arrival. Lets _wait_for_result compute
+        # "already silent for X seconds" across calls so a poll on a quiet
+        # stream returns without re-waiting the full pause_timeout.
+        # Initialized to now so the first Phase 2 entry without prior data
+        # doesn't short-circuit.
+        self.last_data_time = asyncio.get_running_loop().time()
+        self.read_task = asyncio.create_task(self._read_loop())
+
+    async def _read_loop(self):
+        # The finally block matters: CancelledError isn't an Exception subclass
+        # (it's BaseException), so a cancel on this task skips the except below.
+        # Without finally, running=False + event.set() would never run on
+        # cancel, leaving any waiter on new_data_event stuck until its own
+        # pause_timeout fires.
+        try:
+            while self.running:
+                try:
+                    raw = await self.channel.read()
+                    has_data = False
+
+                    if raw is not None and raw != b"":
+                        self.buffer += self.decoder.decode(raw)
+                        has_data = True
+                        self.last_data_time = asyncio.get_running_loop().time()
+                        self.new_data_event.set()
+
+                    is_eof = (raw == b"")
+
+                    if is_eof or await self.channel.is_finished():
+                        self.exit_code = await self.channel.get_exit_code()
+                        # 排空 read() 和 is_finished() 之间可能积累的数据（SSH 必需）
+                        while True:
+                            remaining = await self.channel.read()
+                            if remaining is None or remaining == b"":
+                                break
+                            self.buffer += self.decoder.decode(remaining)
+                        tail = self.decoder.decode(b'', final=True)
+                        if tail:
+                            self.buffer += tail
+                        break
+                    elif not has_data:
+                        await asyncio.sleep(0.05)
+                except Exception as e:
+                    logger.warning("_read_loop error: %s", e)
+                    # Best-effort exit code so the caller doesn't see
+                    # status="completed" + exit_code=None for an abnormal exit.
+                    try:
+                        self.exit_code = await self.channel.get_exit_code()
+                    except Exception:
+                        pass
+                    break
+        finally:
+            self.running = False
+            self.new_data_event.set()
+
+    def read_output(self) -> str:
+        data = self.buffer
+        self.buffer = ""
+        return data
+
+    async def write_input(self, text: str) -> None:
+        await self.channel.write(text.encode('utf-8'))
+
+    def check_status(self) -> tuple[bool, int | None]:
+        return not self.running, self.exit_code
+
+    async def close(self):
+        self.running = False
+        # Wake any waiter on new_data_event immediately — the read_task's
+        # finally will set it too, but doing it here means waiters see
+        # running=False without having to wait for the task to actually
+        # tear down.
+        self.new_data_event.set()
+        # Close the channel first so any blocking read (notably Windows PTY,
+        # which sits in asyncio.to_thread(pty.read) and can't be cancelled)
+        # unblocks. Only then await the read task — otherwise the to_thread
+        # future will hold us until the thread itself exits, which it can't
+        # do while the PTY is still open.
+        await self.channel.close()
+        self.read_task.cancel()
+        try:
+            await self.read_task
+        except (asyncio.CancelledError, Exception):
+            pass