smart-terminal-mcp 1.2.0 → 1.2.2

package/README.md

@@ -2,7 +2,7 @@
 
 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)).
 
-Unlike simple `exec`-based approaches, this provides full PTY sessions with bidirectional communication, enabling interactive CLI tools, real-time output streaming, 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 proper terminal emulation.
 
 ## Features
 
@@ -19,19 +19,11 @@ Unlike simple `exec`-based approaches, this provides full PTY sessions with bidi
 - **CWD tracking** -- Every `terminal_exec` response includes the current working directory
 - **Output truncation** -- Large outputs are automatically truncated 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
-- **Progress notifications** -- Real-time MCP progress updates during long-running commands
+- **Anti-blocking** -- 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`
 
-## 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`)
+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.
 
 ## Installation
 
@@ -116,7 +108,7 @@ Start a new interactive terminal session.
 
 ### `terminal_exec`
 
-Execute a command with deterministic completion detection.
+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.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -211,7 +203,7 @@ Send a named special key.
 
 ### `terminal_wait`
 
-Wait for a specific pattern in the output stream.
+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.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-terminal-mcp",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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__';