smart-terminal-mcp 1.2.27 → 1.2.30

package/.claude/settings.local.json

@@ -2,7 +2,8 @@
   "permissions": {
     "allow": [
       "WebSearch",
-      "Bash(dir:*)"
+      "Bash(dir:*)",
+      "Bash(npm test:*)"
     ]
   }
 }

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.29] - 2026-04-03
+
+### Added
+- **`terminal_extra` meta-tool**: Convenience tools (`terminal_run_paged`, `terminal_retry`, `terminal_diff`, `terminal_resize`, `terminal_send_key`, `terminal_get_history`, `terminal_write_file`) are now collected behind a single lightweight meta-tool by default, reducing tool definition token overhead by ~50%. The agent can discover schemas via `list: true` and call any extra tool through `terminal_extra`.
+- **`SMART_TERMINAL_DISABLED_TOOLS` env var**: Customize which tools are moved behind `terminal_extra`. Set to empty string to register all 15 tools with full schemas.
+
+### Changed
+- Stripped redundant `.describe()` calls from tool parameter schemas where the parameter name is self-documenting (e.g. `sessionId`, `command`, `cwd`, `timeout`). Keeps only 6 essential descriptions for non-obvious parameters.
+
+### Fixed
+- Fixed `terminal_start` test that expected auto-detect hint when no shell was explicitly provided.
+
 ## [1.2.12] - 2026-03-08
 
 ### Added

package/README.md

@@ -68,6 +68,55 @@ The main benefit is **model-context efficiency**, not guaranteed savings in the
 
 In practice, this lets agents inspect terminal state more selectively instead of repeatedly dumping large logs back into the conversation.
 
+### Reducing tool definition overhead
+
+By default, the 8 most-used tools are registered with full schemas and 7 convenience tools are collected behind a single lightweight `terminal_extra` meta-tool (~30 tokens instead of ~1,500).
+
+**Default core tools**: `terminal_start`, `terminal_exec`, `terminal_run`, `terminal_read`, `terminal_write`, `terminal_wait`, `terminal_stop`, `terminal_list`
+
+**Default extra tools** (behind `terminal_extra`): `terminal_run_paged`, `terminal_retry`, `terminal_diff`, `terminal_resize`, `terminal_send_key`, `terminal_get_history`, `terminal_write_file`
+
+Extra tools are **not hidden** — the agent sees the tool names in the `terminal_extra` description and can:
+
+- **Discover schemas**: `terminal_extra({ list: true })` → returns full parameter schemas
+- **Call any extra tool**: `terminal_extra({ tool: "terminal_resize", args: { sessionId: "...", cols: 200, rows: 50 } })`
+
+Use `SMART_TERMINAL_DISABLED_TOOLS` to customize which tools are extra, or set it to an empty string to register all 15 tools with full schemas:
+
+**All tools with full schemas** (no meta-tool):
+
+```json
+{
+  "mcpServers": {
+    "smart-terminal": {
+      "command": "npx",
+      "args": ["-y", "smart-terminal-mcp@stable"],
+      "env": { "SMART_TERMINAL_DISABLED_TOOLS": "" }
+    }
+  }
+}
+```
+
+**Minimal setup** — only `terminal_exec` for simple command execution:
+
+```json
+"env": {
+  "SMART_TERMINAL_DISABLED_TOOLS": "terminal_run,terminal_run_paged,terminal_retry,terminal_diff,terminal_write_file,terminal_resize,terminal_send_key,terminal_get_history"
+}
+```
+
+5 core tools + `terminal_extra` holding 10 tools on demand.
+
+**Agent-focused setup** — `terminal_run` instead of `terminal_exec`:
+
+```json
+"env": {
+  "SMART_TERMINAL_DISABLED_TOOLS": "terminal_exec,terminal_diff,terminal_retry,terminal_resize,terminal_send_key,terminal_write,terminal_read,terminal_get_history"
+}
+```
+
+7 core tools + `terminal_extra` holding 8 tools on demand.
+
 ## Installation
 
 Recommended: run the stable release directly via `npx`:
@@ -134,6 +183,10 @@ If you want to pin an exact release instead of following the stable tag, replace
 
 ## Tools
 
+By default, 8 core tools are registered with full schemas and 7 convenience tools are available on demand via `terminal_extra` (see [Reducing tool definition overhead](#reducing-tool-definition-overhead)).
+
+### Core tools
+
 ### `terminal_start`
 
 Start a new interactive terminal session.
@@ -182,23 +235,6 @@ Run a one-shot non-interactive command using `cmd + args` with `shell=false`. Sa
 
 **Returns**: `ok`, `cmd`, `args`, `cwd`, `exitCode`, `timedOut`, `durationMs`, `stdout.raw`, `stdout.parsed`, optional `stdout.summary`, `stderr.raw`, optional `checks`, optional `hint`
 
-### `terminal_run_paged`
-
-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 |
-|-------|------|---------|-------------|
-| `cmd` | string | *required* | Read-only executable to run |
-| `args` | string[] | `[]` | Argument array passed directly to the executable |
-| `cwd` | string | server CWD | Working directory |
-| `timeout` | number | 30000 | Timeout in ms |
-| `maxOutputBytes` | number | 102400 | Max combined stdout/stderr bytes to capture |
-| `page` | number | 0 | 0-indexed page number |
-| `pageSize` | number | 100 | Lines per page |
-| `summary` | boolean | `false` | Return a concise summary when supported |
-
-**Returns**: Same envelope as `terminal_run`, plus `pageInfo.page`, `pageInfo.pageSize`, `pageInfo.totalLines`, `pageInfo.hasNext`
-
 ### `terminal_write`
 
 Write raw data to a terminal (for interactive programs). Follow with `terminal_read`.
@@ -221,20 +257,51 @@ Read buffered output with idle detection. Large outputs are truncated to head +
 
 **Returns**: `output`, `timedOut`
 
-### `terminal_get_history`
+### `terminal_wait`
 
-Retrieve past terminal output without consuming it. Non-destructive — returns historical output from a rolling buffer (last ~10,000 lines). Useful for reviewing output that was already read or missed.
+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 |
 |-------|------|---------|-------------|
 | `sessionId` | string | *required* | Session ID |
-| `offset` | number | 0 | Lines to skip from the end (0 = most recent). Use for pagination. |
-| `maxLines` | number | 200 | Max lines to return |
-| `format` | string | `"lines"` | Response format: `lines` or `text` |
+| `pattern` | string | *required* | String or regex pattern |
+| `timeout` | number | 30000 | Timeout in ms |
+| `returnMode` | string | `"tail"` | Response mode: `tail`, `full`, `match-only` |
+| `tailLines` | number | 50 | Number of tail lines to return |
 
-**Returns**: `lines` or `text`, plus `totalLines`, `returnedFrom`, `returnedTo`
+**Returns**: `output`, `matched`, `timedOut` (`output` may be empty in `match-only` mode)
+
+### `terminal_stop`
+
+Stop and clean up a terminal session.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `sessionId` | string | Session ID to stop |
+
+### `terminal_list`
+
+List all active terminal sessions.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `verbose` | boolean | `true` | Include full metadata |
+
+**Returns**: `sessions`, `count` (`verbose: false` returns `id`, `name`, `cwd`, `alive`, `busy` only)
+
+### Extra tools (via `terminal_extra`)
+
+The following tools are available by default through the `terminal_extra` meta-tool. The agent can discover their schemas via `terminal_extra({ list: true })` and call them via `terminal_extra({ tool: "<name>", args: { ... } })`.
+
+### `terminal_extra`
+
+Meta-tool for discovering and calling extra tools.
 
-These defaults favor agent usability while still allowing tool callers to lower `maxLines` or `pageSize` explicitly when they want tighter responses.
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `list` | boolean | `false` | Return full parameter schemas for all extra tools |
+| `tool` | string | -- | Name of the extra tool to call |
+| `args` | object | -- | Arguments to pass to the extra tool |
 
 ### `terminal_send_key`
 
@@ -247,19 +314,35 @@ Send a named special key.
 
 **Supported keys**: `ctrl+c`, `ctrl+d`, `ctrl+z`, `ctrl+l`, `ctrl+a`, `ctrl+e`, `ctrl+u`, `ctrl+k`, `ctrl+w`, `tab`, `enter`, `escape`, `up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown`, `backspace`, `delete`, `f1`-`f12`
 
-### `terminal_wait`
+### `terminal_run_paged`
 
-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.
+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 |
 |-------|------|---------|-------------|
-| `sessionId` | string | *required* | Session ID |
-| `pattern` | string | *required* | String or regex pattern |
+| `cmd` | string | *required* | Read-only executable to run |
+| `args` | string[] | `[]` | Argument array passed directly to the executable |
+| `cwd` | string | server CWD | Working directory |
 | `timeout` | number | 30000 | Timeout in ms |
-| `returnMode` | string | `"tail"` | Response mode: `tail`, `full`, `match-only` |
-| `tailLines` | number | 50 | Number of tail lines to return |
+| `maxOutputBytes` | number | 102400 | Max combined stdout/stderr bytes to capture |
+| `page` | number | 0 | 0-indexed page number |
+| `pageSize` | number | 100 | Lines per page |
+| `summary` | boolean | `false` | Return a concise summary when supported |
 
-**Returns**: `output`, `matched`, `timedOut` (`output` may be empty in `match-only` mode)
+**Returns**: Same envelope as `terminal_run`, plus `pageInfo.page`, `pageInfo.pageSize`, `pageInfo.totalLines`, `pageInfo.hasNext`
+
+### `terminal_get_history`
+
+Retrieve past terminal output without consuming it. Non-destructive — returns historical output from a rolling buffer (last ~10,000 lines). Useful for reviewing output that was already read or missed.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `sessionId` | string | *required* | Session ID |
+| `offset` | number | 0 | Lines to skip from the end (0 = most recent). Use for pagination. |
+| `maxLines` | number | 200 | Max lines to return |
+| `format` | string | `"lines"` | Response format: `lines` or `text` |
+
+**Returns**: `lines` or `text`, plus `totalLines`, `returnedFrom`, `returnedTo`
 
 ### `terminal_retry`
 
@@ -304,14 +387,6 @@ Resize terminal dimensions.
 | `cols` | number | New width |
 | `rows` | number | New height |
 
-### `terminal_stop`
-
-Stop and clean up a terminal session.
-
-| Param | Type | Description |
-|-------|------|-------------|
-| `sessionId` | string | Session ID to stop |
-
 ### `terminal_write_file`
 
 Write content directly to a file on disk. Resolves paths relative to the session's CWD. Safer and more robust than piping content through `echo` — handles special characters, newlines, and large files correctly.
@@ -326,16 +401,6 @@ Write content directly to a file on disk. Resolves paths relative to the session
 
 **Returns**: `success`, `path` (absolute), `size` (bytes), `append`
 
-### `terminal_list`
-
-List all active terminal sessions.
-
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `verbose` | boolean | `true` | Include full metadata |
-
-**Returns**: `sessions`, `count` (`verbose: false` returns `id`, `name`, `cwd`, `alive`, `busy` only)
-
 ## Usage Examples
 
 ### Run a command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-terminal-mcp",
-  "version": "1.2.27",
+  "version": "1.2.30",
   "description": "MCP PTY server providing AI agents with real interactive terminal access",
   "mcpName": "io.github.pungggi/smart-terminal",
   "repository": {
@@ -15,7 +15,7 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "node --test",
-    "stable": "npm dist-tag add smart-terminal-mcp@1.2.27 stable",
+    "stable": "npm dist-tag add smart-terminal-mcp@1.2.29 stable",
     "release": "node scripts/publish.js"
   },
   "keywords": [
@@ -27,7 +27,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "node-pty": "^1.1.0",
     "zod": "^3.25.76"
   },
@@ -36,7 +36,7 @@
     "@babel/parser": "^7.29.0",
     "@babel/traverse": "^7.29.0",
     "@babel/types": "^7.29.0",
-    "@smithery/cli": "^4.6.0",
-    "esbuild": "^0.27.0"
+    "@smithery/cli": "^4.7.4",
+    "esbuild": "^0.28.0"
   }
 }

package/scripts/publish.js

@@ -297,7 +297,7 @@ async function discoverTools() {
     const child = spawn('node', ['src/index.js'], {
       cwd: ROOT,
       stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, SMITHERY_SCAN: '1' },
+      env: process.env,
     });
 
     let buffer = '';

package/server-card.json

@@ -0,0 +1,306 @@
+{
+  "serverInfo": {
+    "name": "smart-terminal-mcp",
+    "version": "1.2.30"
+  },
+  "tools": [
+    {
+      "name": "terminal_start",
+      "description": "Start a terminal session. Auto-detects shell if omitted.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "shell": {
+            "type": "string"
+          },
+          "cols": {
+            "type": "integer",
+            "minimum": 20,
+            "maximum": 500,
+            "default": 120
+          },
+          "rows": {
+            "type": "integer",
+            "minimum": 5,
+            "maximum": 200,
+            "default": 30
+          },
+          "cwd": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "env": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
+    {
+      "name": "terminal_exec",
+      "description": "Run a command in a session and wait for completion.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "sessionId": {
+            "type": "string"
+          },
+          "command": {
+            "type": "string"
+          },
+          "timeout": {
+            "type": "integer",
+            "minimum": 1000,
+            "maximum": 600000,
+            "default": 30000
+          },
+          "maxLines": {
+            "type": "integer",
+            "minimum": 10,
+            "maximum": 10000,
+            "default": 200
+          }
+        },
+        "required": [
+          "sessionId",
+          "command"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
+    {
+      "name": "terminal_run",
+      "description": "Run a binary directly; no shell quoting needed.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "cmd": {
+            "type": "string"
+          },
+          "args": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "default": []
+          },
+          "cwd": {
+            "type": "string"
+          },
+          "timeout": {
+            "type": "integer",
+            "minimum": 1000,
+            "maximum": 600000,
+            "default": 30000
+          },
+          "maxOutputBytes": {
+            "type": "integer",
+            "minimum": 1024,
+            "maximum": 1048576,
+            "default": 102400
+          },
+          "parse": {
+            "type": "boolean",
+            "default": true,
+            "description": "Parse structured output"
+          },
+          "parseOnly": {
+            "type": "boolean",
+            "default": false,
+            "description": "Omit raw when parsed"
+          },
+          "summary": {
+            "type": "boolean",
+            "default": false
+          },
+          "successExitCode": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": 0,
+            "description": "null=any"
+          },
+          "successFile": {
+            "type": "string"
+          },
+          "successFilePattern": {
+            "type": "string",
+            "description": "Regex"
+          }
+        },
+        "required": [
+          "cmd"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
+    {
+      "name": "terminal_write",
+      "description": "Write raw data to a terminal session.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "sessionId": {
+            "type": "string"
+          },
+          "data": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "sessionId",
+          "data"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
+    {
+      "name": "terminal_read",
+      "description": "Read new output from a terminal session.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "sessionId": {
+            "type": "string"
+          },
+          "timeout": {
+            "type": "integer",
+            "minimum": 500,
+            "maximum": 300000,
+            "default": 30000
+          },
+          "idleTimeout": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 10000,
+            "default": 500,
+            "description": "Must be < timeout"
+          },
+          "maxLines": {
+            "type": "integer",
+            "minimum": 10,
+            "maximum": 10000,
+            "default": 200
+          }
+        },
+        "required": [
+          "sessionId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
+    {
+      "name": "terminal_wait",
+      "description": "Wait for a pattern to appear in terminal output.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "sessionId": {
+            "type": "string"
+          },
+          "pattern": {
+            "type": "string"
+          },
+          "timeout": {
+            "type": "integer",
+            "minimum": 1000,
+            "maximum": 600000,
+            "default": 30000
+          },
+          "returnMode": {
+            "type": "string",
+            "enum": [
+              "tail",
+              "full",
+              "match-only"
+            ],
+            "default": "tail"
+          },
+          "tailLines": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "default": 50
+          }
+        },
+        "required": [
+          "sessionId",
+          "pattern"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
+    {
+      "name": "terminal_stop",
+      "description": "Stop a terminal session.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "sessionId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "sessionId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
+    {
+      "name": "terminal_list",
+      "description": "List active terminal sessions.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "verbose": {
+            "type": "boolean",
+            "default": true
+          }
+        },
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
+    {
+      "name": "terminal_extra",
+      "description": "7 more tools: terminal_run_paged, terminal_get_history, terminal_resize, terminal_send_key, terminal_retry, terminal_diff, terminal_write_file. list=true for full schemas, or pass tool + args to call.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "list": {
+            "type": "boolean",
+            "default": false
+          },
+          "tool": {
+            "type": "string"
+          },
+          "args": {
+            "type": "object",
+            "additionalProperties": {}
+          }
+        },
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    }
+  ],
+  "resources": [],
+  "prompts": []
+}

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pungggi/smart-terminal-mcp",
     "source": "github"
   },
-  "version": "1.2.27",
+  "version": "1.2.30",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "smart-terminal-mcp",
-      "version": "1.2.27",
+      "version": "1.2.30",
       "transport": {
         "type": "stdio"
       }

package/smithery.json

@@ -1,7 +1,7 @@
 {
   "name": "pungggi/smart-terminal",
   "description": "MCP PTY server providing AI agents with real interactive terminal access",
-  "version": "1.2.27",
+  "version": "1.2.30",
   "repository": "https://github.com/pungggi/smart-terminal-mcp",
   "tags": [
     "terminal",

package/src/index.js

@@ -10,7 +10,7 @@ const log = (msg) => process.stderr.write(`[smart-terminal-mcp] ${msg}\n`);
 export function createSandboxServer() {
   const server = new McpServer({
     name: 'smart-terminal-mcp',
-    version: '1.2.27',
+    version: '1.2.29',
   });
   const manager = new SessionManager();
   registerTools(server, manager);
@@ -22,7 +22,7 @@ async function main() {
   const manager = new SessionManager();
   const server = new McpServer({
     name: 'smart-terminal-mcp',
-    version: '1.2.27',
+    version: '1.2.29',
   });
   registerTools(server, manager);
 

package/src/pty-session.js

@@ -245,7 +245,7 @@ export class PtySession {
       throw new Error(`Session ${this.id} is no longer alive.`);
     }
     this.process.write(data);
-    if (data.includes('\x03') || data.includes('\x04') || data.includes('\x1A')) {
+    if (data.includes('\x03') || data.includes('\x04')) {
       this.busy = false;
       this._pendingMarker = null;
     }