smart-terminal-mcp 1.2.7 → 1.2.9

package/README.md

@@ -1,12 +1,12 @@
 # smart-terminal-mcp
 
-A PTY-based MCP server with strong Windows support that gives AI agents (Claude, Cursor, etc.) persistent, interactive shell access via pseudo-terminals ([node-pty](https://github.com/microsoft/node-pty)).
+A PTY-based MCP server with strong Windows support, giving MCP-capable AI clients and their agents persistent, interactive shell access via pseudo-terminals ([node-pty](https://github.com/microsoft/node-pty)).
 
 Unlike simple `exec`-based approaches, this keeps PTY-backed shell sessions alive across steps, with bidirectional communication for interactive CLI tools, incremental reads, and session state that carries forward.
 
 ## 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.
+Install this if you want a more consistent terminal workflow across AI clients, instead of relying on whatever built-in terminal behavior a single client happens to provide.
 
 This MCP is most useful when you want:
 
@@ -17,15 +17,15 @@ This MCP is most useful when you want:
 - **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.
+If your AI client already provides 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
 
-Think of this as a **controlled keyboard + terminal for AI**. It opens a persistent PTY-backed shell session, sends commands and keystrokes, reads output, and keeps working in the same session.
+Think of this as a **controlled keyboard + terminal for an agent running inside an MCP client**. It opens a persistent PTY-backed shell session so the agent can send commands and keystrokes, read output, and continue working in the same session.
 
 ### Core terminal features
 
-- **Interactive terminal sessions** -- Keeps a persistent PTY-backed shell session open so the AI can send input, read output, and pick up where it left off.
+- **Interactive terminal sessions** -- Keeps a persistent PTY-backed shell session open so the agent can send input, read output, and pick up 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.
@@ -36,8 +36,8 @@ Think of this as a **controlled keyboard + terminal for AI**. It opens a persist
 - **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 truncation** -- `terminal_exec` and `terminal_read` shorten very large output by returning the beginning and the end.
+- **Paged read-only output** -- `terminal_run_paged` returns large read-only output one page at a time instead of sending the full result at once.
 - **Output diffing** -- `terminal_diff` compares two command results and returns a unified diff.
 
 ### Safety and usability
@@ -49,7 +49,21 @@ Think of this as a **controlled keyboard + terminal for AI**. It opens a persist
 - **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.
+Progress notifications are not the same as full stdout streaming. They currently send periodic status updates for `terminal_exec` and `terminal_wait`, usually based on elapsed time and the latest output line. Whether you see them depends on your MCP client.
+
+## Token efficiency
+
+This MCP does not magically compress terminal output, but it **can help agents use fewer tokens in terminal-heavy workflows** by returning smaller, more targeted responses and making it easier to revisit output only when needed.
+
+The main benefit is **model-context efficiency**, not guaranteed savings in the underlying command's runtime or total bytes produced.
+
+- Use **`terminal_run_paged`** for large read-only output when **the agent** wants one page of the returned result at a time.
+- Lower **`maxLines`**, **`pageSize`**, or **`tailLines`** when **the agent** only needs a narrow slice of the output.
+- Use **`summary: true`** or **`parseOnly: true`** with `terminal_run` when **the agent** benefits more from structured results than raw text.
+- Use **`terminal_wait({ returnMode: "match-only" })`** when the agent only needs to know whether a pattern appeared.
+- Use **`terminal_get_history`** when **the agent** needs to revisit earlier output without re-dumping the whole session into the conversation.
+
+In practice, this lets agents inspect terminal state more selectively instead of repeatedly dumping large logs back into the conversation.
 
 ## Installation
 
@@ -147,7 +161,7 @@ Execute a command with deterministic completion detection. Large outputs are tru
 
 ### `terminal_run`
 
-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.
+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. Prefer passing the target executable directly as `cmd` instead of wrapping it in `powershell -Command` or `cmd /c`, especially when Windows paths contain spaces.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -164,7 +178,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. 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`.
+Run a read-only one-shot command using `cmd + args` with `shell=false` and return a single page of stdout lines from the captured output. This pages the returned result instead of using 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 |
 |-------|------|---------|-------------|
@@ -214,7 +228,7 @@ Retrieve past terminal output without consuming it. Non-destructive — returns
 
 **Returns**: `lines` or `text`, plus `totalLines`, `returnedFrom`, `returnedTo`
 
-These defaults favor agent usability while still allowing callers to lower `maxLines` or `pageSize` explicitly when they want tighter responses.
+These defaults favor agent usability while still allowing tool callers to lower `maxLines` or `pageSize` explicitly when they want tighter responses.
 
 ### `terminal_send_key`
 
@@ -332,6 +346,12 @@ terminal_run({ cmd: "git", args: ["status", "--porcelain=v1", "--branch"] })
 -> { ok: true, stdout: { raw: "...", parsed: { branch: {...}, staged: [], modified: [], untracked: [] } } }
 ```
 
+For Windows tools installed under `Program Files`, prefer this shape over `powershell -Command`:
+
+```
+terminal_run({ cmd: "C:\\Program Files\\Vendor\\Tool.exe", args: ["/flag:value", "/other"] })
+```
+
 ### Page through large read-only output
 
 ```

package/package.json

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

package/src/tools.js

@@ -107,10 +107,10 @@ export function registerTools(server, manager) {
   // --- terminal_run ---
   server.tool(
     'terminal_run',
-    'Run a one-shot non-interactive command.',
+    'Run a binary directly; avoid shell quoting.',
     {
-      cmd: z.string().describe('Executable'),
-      args: z.array(z.string()).default([]).describe('Arguments'),
+      cmd: z.string().describe('Executable path or name'),
+      args: z.array(z.string()).default([]).describe('Args passed verbatim'),
       cwd: z.string().optional().describe('Working directory'),
       timeout: z.number().int().min(1000).max(600000).default(DEFAULT_TIMEOUT_MS).describe('Timeout in ms'),
       maxOutputBytes: z.number().int().min(1024).max(1048576).default(DEFAULT_MAX_OUTPUT_BYTES).describe('Max output bytes'),

package/test/command-runner.test.js

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { getStructuredParserHint, runCommand } from '../src/command-runner.js';
@@ -168,6 +168,33 @@ test('runCommand executes explicit .cmd files on Windows', async (t) => {
   }
 });
 
+test('runCommand handles explicit command paths with spaces', async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), 'smart terminal mcp-'));
+
+  try {
+    const isWindows = process.platform === 'win32';
+    const scriptPath = join(tempDir, isWindows ? 'space wrapper.cmd' : 'space-wrapper.sh');
+    const scriptBody = isWindows
+      ? '@echo off\r\necho [%~1]\r\n'
+      : '#!/bin/sh\necho "[$1]"\n';
+
+    await writeFile(scriptPath, scriptBody);
+    if (!isWindows) await chmod(scriptPath, 0o755);
+
+    const result = await runCommand({
+      cmd: scriptPath,
+      args: ['hello world'],
+      parse: false,
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.exitCode, 0);
+    assert.match(result.stdout.raw, /\[hello world\]/);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
 test('runCommand adds a helpful ENOENT hint on Windows for PATH commands', async (t) => {
   if (process.platform !== 'win32') {
     t.skip('Windows-only behavior');