smart-terminal-mcp 1.2.3 → 1.2.5

package/README.md

@@ -4,24 +4,52 @@ A PTY-based MCP server with strong Windows support that gives AI agents (Claude,
 
 Unlike simple `exec`-based approaches, this provides full PTY sessions with bidirectional communication, enabling interactive CLI tools, incremental terminal reads, and PTY-backed terminal behavior.
 
+## Why use this instead of your AI client's built-in terminal?
+
+Install this if you want a more consistent terminal workflow across different AI clients, not just whatever built-in terminal behavior one client happens to provide.
+
+This MCP is most useful when you want:
+
+- **The same workflow across multiple agent platforms** -- If you move between Claude Code, Cursor, Trae, Antigravity, or other MCP-capable clients, the terminal tools stay the same.
+- **Less client-specific behavior** -- Prompts, instructions, and habits do not need to depend as much on one client's terminal UI or quirks.
+- **Reusable prompts, playbooks, and instructions** -- A workflow built around tools like `terminal_wait`, `terminal_retry`, `terminal_run_paged`, or `terminal_get_history` is easier to reuse across teams and clients.
+- **Reusable tooling with less lock-in** -- The terminal layer lives in MCP tools rather than in one client's built-in terminal behavior.
+- **Persistent terminal state** -- Keep the same shell session alive across steps, including the current folder, environment, and running processes.
+- **Better interactive behavior** -- Handle prompts, REPLs, dev servers, Ctrl+C, arrow keys, and other real terminal interactions.
+- **More control over large output** -- Truncate, page, diff, retry, wait for patterns, or fetch history instead of dumping everything at once.
+- **More predictable automation** -- Use deterministic completion markers instead of guessing when a command is done.
+
+If your AI client already gives you a stable, stateful, interactive terminal with good output handling, you may not need this MCP for basic command execution. The main reason to add it is to make terminal-driven workflows more explicit, reusable, and portable across clients.
+
 ## Features
 
-- **Marker-based completion detection** -- Deterministic command completion via unique markers injected into the shell
-- **Robust command echo removal** -- Pre-command marker helps keep output clean even with shell aliases and expansions
-- **Interactive mode** -- `terminal_write` + `terminal_read` for REPLs, prompts, and interactive programs
-- **Safer one-shot commands** -- `terminal_run` executes real binaries with `cmd + args` and `shell=false`
-- **Structured parsers** -- Supported read-only commands can return both `stdout.raw` and `stdout.parsed`
-- **Paged read-only output** -- `terminal_run_paged` returns a single page of stdout for large command output
-- **Special key support** -- Send Ctrl+C, Tab, arrow keys, etc. without knowing escape codes
-- **Pattern waiting** -- Wait for specific output (e.g. "server listening on port") before continuing
-- **Retry helper** -- Retry flaky terminal commands with bounded backoff and optional output matching
-- **Output diffing** -- Run two commands in one session and compare their outputs with a unified diff
-- **CWD tracking** -- Every `terminal_exec` response includes the current working directory
-- **Output truncation** -- `terminal_exec` and `terminal_read` truncate large outputs to head + tail
-- **Session management** -- Named sessions, TTL auto-cleanup, max 10 concurrent sessions
-- **Blocking mitigations** -- Disables pagers (`GIT_PAGER=cat`, `PAGER=cat`), suppresses PowerShell progress output, and sets UTF-8 for `cmd.exe` on Windows
-- **Best-effort progress notifications** -- Emits MCP `notifications/progress` for long-running `terminal_exec` / `terminal_wait` calls when the client provides a progress token and surfaces those notifications
-- **Shell auto-detection** -- Windows: `pwsh.exe` > `powershell.exe` > `cmd.exe`. Linux/macOS: `$SHELL` > `bash` > `sh`
+Think of this as a **controlled keyboard + screen for AI**. It can open a real terminal, type commands, read the results, and keep working in the same session.
+
+### Core terminal features
+
+- **Interactive terminal sessions** -- Keeps a real terminal open so the AI can type, read output, and continue where it left off.
+- **Deterministic command completion** -- `terminal_exec` uses unique markers so it can tell when a command has finished.
+- **Clean output** -- Pre-command markers help keep returned output readable, even when shells echo commands or expand aliases.
+- **Working directory tracking** -- `terminal_exec` reports the current folder after each command.
+
+### Long output and long-running commands
+
+- **Interactive reads and writes** -- `terminal_write` + `terminal_read` support prompts, REPLs, and other interactive programs.
+- **Pattern waiting** -- `terminal_wait` can pause until specific text appears, such as `server listening on port`.
+- **Retry helper** -- `terminal_retry` can re-run flaky commands with bounded backoff and optional output matching.
+- **Best-effort progress notifications** -- Long `terminal_exec` / `terminal_wait` calls can emit `notifications/progress` when the client provides a progress token.
+- **Output truncation** -- `terminal_exec` and `terminal_read` shorten very large output by showing the beginning and the end.
+- **Paged read-only output** -- `terminal_run_paged` lets clients fetch large read-only output one page at a time.
+- **Output diffing** -- `terminal_diff` compares two command results and returns a unified diff.
+
+### Safety and usability
+
+- **Safer one-shot commands** -- `terminal_run` executes real binaries with `cmd + args` and `shell=false`.
+- **Structured parsers** -- Some supported read-only commands can return both raw text and parsed output.
+- **Blocking mitigations** -- Disables pagers (`GIT_PAGER=cat`, `PAGER=cat`), suppresses PowerShell progress output, and sets UTF-8 for `cmd.exe` on Windows.
+- **Special key support** -- Can send Ctrl+C, Tab, arrow keys, and similar keys without manually building escape codes.
+- **Session management** -- Supports named sessions, idle cleanup, and up to 10 concurrent sessions.
+- **Shell auto-detection** -- Windows: `pwsh.exe` > `powershell.exe` > `cmd.exe`. Linux/macOS: `$SHELL` > `bash` > `sh`.
 
 Progress notifications are not the same as full stdout streaming: they currently send periodic status updates for `terminal_exec` and `terminal_wait`, typically based on elapsed time and the latest output line. Whether you actually see them depends on your MCP client.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-terminal-mcp",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "MCP PTY server providing AI agents with real interactive terminal access",
   "type": "module",
   "main": "src/index.js",