smart-terminal-mcp 1.2.1 → 1.2.3

package/README.md

@@ -1,15 +1,15 @@
 # smart-terminal-mcp
 
-A Windows-native MCP server that gives AI agents (Claude, Cursor, etc.) real interactive terminal access via pseudo-terminals ([node-pty](https://github.com/microsoft/node-pty)).
+A PTY-based MCP server with strong Windows support that gives AI agents (Claude, Cursor, etc.) interactive terminal access via pseudo-terminals ([node-pty](https://github.com/microsoft/node-pty)).
 
-Unlike simple `exec`-based approaches, this provides full PTY sessions with bidirectional communication, enabling interactive CLI tools, incremental terminal reads, and proper terminal emulation.
+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.
 
 ## Features
 
-- **Marker-based completion detection** -- 100% reliable command completion via unique markers injected into the shell
-- **Robust command echo removal** -- Pre-command marker ensures clean output, handles shell aliases and expansions correctly
+- **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
-- **Safe one-shot commands** -- `terminal_run` executes real binaries with `cmd + args` and `shell=false`
+- **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
@@ -17,24 +17,14 @@ Unlike simple `exec`-based approaches, this provides full PTY sessions with bidi
 - **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** -- Large outputs are automatically truncated to head + tail
+- **Output truncation** -- `terminal_exec` and `terminal_read` truncate large outputs to head + tail
 - **Session management** -- Named sessions, TTL auto-cleanup, max 10 concurrent sessions
-- **Anti-blocking** -- Disables pagers (`GIT_PAGER=cat`), progress bars, and sets UTF-8 on Windows
+- **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` or `bash`
+- **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.
 
-## Requirements
-
-- **Node.js** >= 18
-
-`node-pty` ships prebuilt binaries for most platforms. If prebuilds are unavailable for your OS/architecture, a C/C++ toolchain is needed as fallback:
-
-- **Windows**: [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (select "Desktop development with C++")
-- **macOS**: Xcode Command Line Tools (`xcode-select --install`)
-- **Linux**: `build-essential` and Python 3 (`sudo apt install build-essential python3`)
-
 ## Installation
 
 Recommended: run the stable release directly via `npx`:
@@ -118,7 +108,7 @@ Start a new interactive terminal session.
 
 ### `terminal_exec`
 
-Execute a command with deterministic completion detection. If the MCP client sends a `progressToken`, long-running calls may also emit best-effort `notifications/progress` updates.
+Execute a command with deterministic completion detection. Large outputs are truncated to head + tail based on `maxLines`. If the MCP client sends a `progressToken`, long-running calls may also emit best-effort `notifications/progress` updates.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -131,7 +121,7 @@ Execute a command with deterministic completion detection. If the MCP client sen
 
 ### `terminal_run`
 
-Run a one-shot non-interactive command using `cmd + args` with `shell=false`. Safer than `terminal_exec` for predictable automation. Shell built-ins such as `dir` or `cd` are not supported. On Windows, `terminal_run` resolves `PATH`/`PATHEXT` and launches `.cmd` / `.bat` wrappers via `cmd.exe` when needed.
+Run a one-shot non-interactive command using `cmd + args` with `shell=false`. Safer than `terminal_exec` for predictable automation. Output is capped by `maxOutputBytes` rather than head + tail truncation. Shell built-ins such as `dir` or `cd` are not supported. On Windows, `terminal_run` resolves `PATH`/`PATHEXT` and launches `.cmd` / `.bat` wrappers via `cmd.exe` when needed.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -148,7 +138,7 @@ Run a one-shot non-interactive command using `cmd + args` with `shell=false`. Sa
 
 ### `terminal_run_paged`
 
-Run a read-only one-shot command using `cmd + args` with `shell=false` and return a single page of stdout lines. Paged mode does not parse partial output, but it can return a concise summary for supported read-only commands when `summary: true`.
+Run a read-only one-shot command using `cmd + args` with `shell=false` and return a single page of stdout lines. This uses paging rather than head + tail truncation. Paged mode does not parse partial output, but it can return a concise summary for supported read-only commands when `summary: true`.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -174,7 +164,7 @@ Write raw data to a terminal (for interactive programs). Follow with `terminal_r
 
 ### `terminal_read`
 
-Read buffered output with idle detection.
+Read buffered output with idle detection. Large outputs are truncated to head + tail based on `maxLines`.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -213,7 +203,7 @@ Send a named special key.
 
 ### `terminal_wait`
 
-Wait for a specific pattern in the output stream. If the MCP client sends a `progressToken`, long-running waits may also emit best-effort `notifications/progress` updates.
+Wait for a specific pattern in the output stream. By default, responses return only the last `tailLines`; use `returnMode: "full"` for the full matched output or `"match-only"` to suppress output entirely. If the MCP client sends a `progressToken`, long-running waits may also emit best-effort `notifications/progress` updates.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|

package/package.json

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

package/src/pty-session.js

@@ -16,6 +16,23 @@ export const DEFAULT_HISTORY_FORMAT = 'lines';
 const DEFAULT_WAIT_RETURN_MODE = 'tail';
 const DEFAULT_WAIT_TAIL_LINES = 50;
 
+export function buildSessionEnv(customEnv = {}, platformName = platform()) {
+  const env = {
+    ...process.env,
+    ...customEnv,
+    GIT_PAGER: 'cat',
+    PAGER: 'cat',
+    LESS: '-FRX',
+    TERM: 'xterm-256color',
+  };
+
+  if (platformName !== 'win32') {
+    env.DEBIAN_FRONTEND = 'noninteractive';
+  }
+
+  return env;
+}
+
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -100,18 +117,7 @@ export class PtySession {
     /** @type {((data: string) => void)[]} */
     this._dataListeners = [];
 
-    const env = {
-      ...process.env,
-      ...customEnv,
-      GIT_PAGER: 'cat',
-      PAGER: 'cat',
-      LESS: '-FRX',
-      TERM: 'xterm-256color',
-    };
-
-    if (platform() !== 'win32') {
-      env.DEBIAN_FRONTEND = 'noninteractive';
-    }
+    const env = buildSessionEnv(customEnv);
 
     this.process = pty.spawn(shell, shellArgs, {
       name: 'xterm-256color',

package/test/pty-session.test.js

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { PtySession } from '../src/pty-session.js';
+import { buildSessionEnv, PtySession } from '../src/pty-session.js';
 
 function createSession() {
   return Object.create(PtySession.prototype);
@@ -14,6 +14,23 @@ function createWaitSession(buffer = '') {
   return session;
 }
 
+test('buildSessionEnv applies anti-blocking environment defaults', () => {
+  const env = buildSessionEnv({ CUSTOM_ENV: 'yes', GIT_PAGER: 'less' }, 'linux');
+
+  assert.equal(env.CUSTOM_ENV, 'yes');
+  assert.equal(env.GIT_PAGER, 'cat');
+  assert.equal(env.PAGER, 'cat');
+  assert.equal(env.LESS, '-FRX');
+  assert.equal(env.TERM, 'xterm-256color');
+  assert.equal(env.DEBIAN_FRONTEND, 'noninteractive');
+});
+
+test('buildSessionEnv skips noninteractive override on Windows', () => {
+  const env = buildSessionEnv({}, 'win32');
+
+  assert.equal(env.DEBIAN_FRONTEND, undefined);
+});
+
 test('PowerShell wrapper uses safe marker interpolation', () => {
   const session = createSession();
   session.shellType = 'powershell';
@@ -24,6 +41,40 @@ test('PowerShell wrapper uses safe marker interpolation', () => {
   assert.match(command, /__CWD_\$\(\(Get-Location\)\.Path\)__/);
 });
 
+test('_initShell suppresses PowerShell progress output', async () => {
+  const session = createSession();
+  const writes = [];
+  let resetCalls = 0;
+  session.shellType = 'powershell';
+  session.process = { write: (value) => writes.push(value) };
+  session._readUntilIdle = async () => '';
+  session._resetBuffer = () => {
+    resetCalls++;
+  };
+
+  await session._initShell();
+
+  assert.deepEqual(writes, ["$ProgressPreference = 'SilentlyContinue'\r"]);
+  assert.equal(resetCalls, 1);
+});
+
+test('_initShell sets cmd sessions to UTF-8', async () => {
+  const session = createSession();
+  const writes = [];
+  let resetCalls = 0;
+  session.shellType = 'cmd';
+  session.process = { write: (value) => writes.push(value) };
+  session._readUntilIdle = async () => '';
+  session._resetBuffer = () => {
+    resetCalls++;
+  };
+
+  await session._initShell();
+
+  assert.deepEqual(writes, ['chcp 65001 > nul\r']);
+  assert.equal(resetCalls, 1);
+});
+
 test('_parseOutput ignores echoed wrapper text and keeps real output', () => {
   const session = createSession();
   const preMarker = '__MCP_PRE_abc__';
@@ -48,6 +99,16 @@ test('_parseOutput ignores echoed wrapper text and keeps real output', () => {
   });
 });
 
+test('_truncateOutput keeps the head and tail when output exceeds maxLines', () => {
+  const session = createSession();
+  const output = ['line 1', 'line 2', 'line 3', 'line 4', 'line 5', 'line 6'].join('\n');
+
+  assert.equal(
+    session._truncateOutput(output, 4),
+    ['line 1', 'line 2', '', '... 2 lines omitted ...', '', 'line 5', 'line 6'].join('\n')
+  );
+});
+
 test('read returns unread buffered output once', async () => {
   const session = createSession();
   session.alive = true;