Smart Terminal MCP

智能终端mcp

 ](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.pungggi/smart-terminal)

基于PTY的MCP服务器，具有强大的Windows支持，通过伪终端为支持MCP的AI客户端及其代理提供持久、交互式的shell访问(节点pty).

与简单不同 exec-基于方法，这使PTY支持的shell会话跨步骤保持活动状态，并为交互式CLI工具、增量读取和会话状态提供双向通信。

看 更新日志 查看最新更新。

为什么使用它而不是AI客户端的内置终端？

如果你想在AI客户端之间实现更一致的终端工作流程，而不是依赖于单个客户端碰巧提供的任何内置终端行为，请安装这个。

当您需要时，此MCP最有用：

• 跨客户端的可移植工作流 --相同的终端工具和习惯适用于Claude Code、Cursor、Trae、Antigravity和其他支持MCP的客户端。
• 可重复使用的提示和工具 --围绕以下工具构建的工作流 terminal_wait, terminal_retry, terminal_run_paged，以及 terminal_get_history 更容易在团队和客户之间重用，对一个客户的终端行为的锁定更少。
• 持久终端状态 --跨步骤保持相同的shell会话活动，包括当前文件夹、环境和正在运行的进程。
• 更好的互动行为 --安全地处理预期TTY行为的工具，例如 vim, npm 提示，或通常挂在标准管道stdin上的交互式安装程序。支持使用REPL、Ctrl+C、箭头键和动态提示的完整交互式会话。
• 对大输出的更多控制 --截断、分页、差异、重试、等待模式或获取历史记录，而不是一次转储所有内容。
• 更可预测的自动化 --使用确定性完成标记，而不是猜测命令何时完成。

如果你的AI客户端已经提供了一个稳定、有状态、交互式的终端，具有良好的输出处理能力，那么你可能不需要这个MCP来执行基本的命令。添加它的主要原因是使终端驱动的工作流在客户端之间更加明确、可重用和可移植。

特性

将此视为 MCP客户端内运行的代理的受控键盘+终端。它打开一个持久的PTY支持的shell会话，这样代理就可以发送命令和按键，读取输出，并在同一会话中继续工作。

核心终端功能

• 交互式终端会话 --保持PTY支持的持久shell会话打开，以便代理可以发送输入、读取输出，并从停止的地方继续。
• 确定性命令完成 -- terminal_exec 使用唯一的标记，这样它就可以知道命令何时完成。
• 清洁输出 --即使shell回显命令或展开别名，预命令标记也有助于保持返回的输出可读。
• 工作目录跟踪 -- terminal_exec 在每个命令后报告当前文件夹。

长输出和长时间运行的命令

• 交互式读写 -- terminal_write + terminal_read 支持提示、REPL和其他交互式程序，而无需离开当前会话。
• 增量读取 -- terminal_read 接受a since 字节位置仅返回自上次读取以来的新输出，避免在每次轮询时重新读取整个缓冲区。
• 图案等待 -- terminal_wait 可以暂停，直到出现特定文本，例如 server listening on port.
• 事件驱动的监控 -- terminal_watch 等待会话输出中的触发模式，仅在匹配、安静、超时或退出时返回。消除轮询循环令牌浪费。
• 静音出口检测 -- terminal_exec 当输出变为静音时，可以提前返回(quietExitMs)，而不是等待一个艰难的超时。
• 重试助手 -- terminal_retry 可以重新运行具有有界退避和可选输出匹配的古怪命令。
• 尽力进度通知 --长 terminal_exec / terminal_wait 呼叫可以发出 notifications/progress 当客户端提供进度令牌时。
• 输出截断 -- terminal_exec 和 terminal_read 通过返回开头和结尾来缩短非常大的输出。
• 分页只读输出 -- terminal_run_paged 一次返回一页的大型只读输出，而不是一次发送完整结果。
• 输出差异 -- terminal_diff 比较两个命令结果并返回统一的diff。
• 会话快照 -- terminal_stop 可以在停止之前捕获尾部快照或将完整转录写入磁盘。

安全性和可用性

• 更安全的一次性命令 -- terminal_run 直接执行二进制文件 cmd + args 和 shell=false 以实现更可预测的自动化。
• 结构化解析器 --一些支持的只读命令可以返回原始文本和解析输出。
• 阻断缓解措施 --禁用寻呼机(GIT_PAGER=cat, PAGER=cat)，抑制PowerShell进度输出，并为设置UTF-8 cmd.exe 在Windows上。
• 特殊密钥支持 --可以发送Ctrl+C、Tab、箭头键和类似键，而无需手动构造转义序列。
• 流程组清理 -- terminal_stop 杀死Unix上的整个进程组，防止孤儿进程。
• 会话管理 --支持命名会话、空闲清理和最多10个并发会话。会话ID是人类可读的（例如。 calm-reef).
• 外壳自动检测 --视窗： pwsh.exe > powershell.exe > cmd.exeLinux/macOS： $SHELL > bash > sh.

进度通知与完整的stdout流不同。他们目前定期发送以下内容的状态更新 terminal_exec 和 terminal_wait，通常基于经过的时间和最新的输出行。您是否看到它们取决于您的MCP客户端。

代币效率

此MCP不会神奇地压缩终端输出，但它 可以帮助代理在终端繁重的工作流中使用更少的令牌 通过返回更小、更有针对性的响应，并使仅在需要时更容易重新访问输出。

主要好处是 模型上下文效率，不能保证节省底层命令的运行时间或产生的总字节数。

轮询和长时间运行的流程

• 使用 terminal_read({ since }) 以增量方式读取。每次调用只返回自上次以来的新输出 position，而不是重新读取整个缓冲区。在重复轮询时，令牌使用量最多可减少约87%。
• 使用 terminal_watch 而不是在等待特定模式时进行手动轮询循环。一次调用会在匹配、安静、超时或退出时返回，这将日志监视工作流的令牌使用率降低了约99%。
• 使用 terminal_exec({ quietExitMs }) 对于从不产生完成标记的长时间运行的命令（开发服务器、监视器）。输出停止时提前返回，而不是等待硬超时。将令牌使用量减少高达约94%。

输出尺寸控制

• 使用 terminal_run_paged 用于大的只读输出 代理人 每次只需要返回一页结果。
• 降低 maxLines, pageSize，或 tailLines 当 代理人 只需要输出的一小部分。
• 使用 summary: true 或 parseOnly: true 和 terminal_run 当 代理人 结构化结果比原始文本更有益。
• 使用 terminal_wait({ returnMode: "match-only" }) 当代理只需要知道模式是否出现时。
• 使用 terminal_get_history 当 代理人 需要重新访问之前的输出，而无需将整个会话重新转储到对话中。
• 使用 terminal_stop({ transcriptPath }) 将大型会话历史记录卸载到磁盘，而不是在响应中返回。

在实践中，这使代理能够更有选择性地检查终端状态，而不是反复将大量日志转储回对话中。

减少工具定义开销

默认情况下，8个最常用的工具以完整模式注册，8个便利工具被收集在一个轻量级工具后面 terminal_extra 元工具（约30个令牌，而不是约1700个）。

默认核心工具: terminal_start, terminal_exec, terminal_run, terminal_read, terminal_write, terminal_wait, terminal_stop, terminal_list

默认附加工具 （后面 terminal_extra): terminal_run_paged, terminal_retry, terminal_diff, terminal_resize, terminal_send_key, terminal_get_history, terminal_write_file, terminal_watch

额外的工具包括 未隐藏 --代理在中看到工具名称 terminal_extra 描述，并可以：

• 发现模式: terminal_extra({ list: true }) → 返回完整的参数模式
• 调用任何额外工具: terminal_extra({ tool: "terminal_resize", args: { sessionId: "...", cols: 200, rows: 50 } })

使用 SMART_TERMINAL_DISABLED_TOOLS 要自定义哪些工具是额外的，或将其设置为空字符串以使用完整模式注册所有15个工具：

所有具有完整模式的工具 （无元工具）：

{
  "mcpServers": {
    "smart-terminal": {
      "command": "npx",
      "args": ["-y", "smart-terminal-mcp@stable"],
      "env": { "SMART_TERMINAL_DISABLED_TOOLS": "" }
    }
  }
}

最小设置 --只有 terminal_exec 对于简单的命令执行：

"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,terminal_watch"
}

5个核心工具+ terminal_extra 按需持有9个工具。

以代理为中心的设置 -- terminal_run 而不是 terminal_exec:

"env": {
  "SMART_TERMINAL_DISABLED_TOOLS": "terminal_exec,terminal_diff,terminal_retry,terminal_resize,terminal_send_key,terminal_write,terminal_read,terminal_get_history,terminal_watch"
}

7核心工具+ terminal_extra 按需持有9个工具。

安装

建议：直接通过运行稳定版本 npx:

npx smart-terminal-mcp@stable

或全局安装：

npm install -g smart-terminal-mcp

或克隆开发：

git clone 
cd smart-terminal-mcp
npm install

配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "smart-terminal": {
      "command": "npx",
      "args": ["-y", "smart-terminal-mcp@stable"]
    }
  }
}

克劳德代码

claude mcp add smart-terminal -- npx -y smart-terminal-mcp@stable

增强代码

添加到您的增强MCP设置中：

{
  "mcpServers": {
    "Smart Terminal": {
      "command": "npx",
      "args": [
        "smart-terminal-mcp@stable"
      ]
    }
  }
}

如果你想固定一个精确的释放，而不是遵循稳定的标签，请更换 @stable 版本如 @1.0.1.

工具

默认情况下，8个核心工具以完整模式注册，8个便利工具可通过以下方式按需使用 terminal_extra （参见 减少工具定义开销).

核心工具

terminal_start

启动新的交互式终端会话。

退货: sessionId, shell, shellType, cwd, banner

terminal_exec

执行具有确定性完成检测的命令。根据以下内容，大输出被截断为头尾 maxLines如果MCP客户端发送 progressToken，长时间运行的调用也可能会尽最大努力 notifications/progress 更新。

退货: output, exitCode, cwd, timedOut，可选 quietExited，可选 hint

terminal_run

使用以下命令运行一次性非交互式命令 cmd + args 和 shell=false.比 terminal_exec 为了实现可预测的自动化。输出上限为 maxOutputBytes 而不是头尾截断。壳牌内置组件，如 dir 或 cd 不支持。在Windows上， terminal_run 解决 PATH/PATHEXT 并发射 .cmd / .bat 包装通过 cmd.exe 必要时。更喜欢将目标可执行文件直接传递为 cmd 而不是把它包起来 powershell -Command 或 cmd /c，尤其是当Windows路径包含空格时。适用于始终退出的工具 0，您可以要求特定的退出代码和/或根据命令编写的文件验证成功正则表达式。

退货: ok, cmd, args, cwd, exitCode, timedOut, durationMs, stdout.raw, stdout.parsed，可选 stdout.summary, stderr.raw，可选 checks，可选 hint

terminal_write

将原始数据写入终端（用于交互式程序）。跟随 terminal_read.

terminal_read

读取带有空闲检测的缓冲输出。根据以下内容，大输出被截断为头尾 maxLines.通行证 since 递增读取——仅返回给定字节位置后发出的输出。

退货: output, timedOut, position，可选 truncated

terminal_wait

等待输出流中的特定模式。默认情况下，响应只返回最后一个 tailLines；使用 returnMode: "full" 对于完全匹配的输出，或 "match-only" 以完全抑制输出。如果MCP客户端发送 progressToken，长时间的等待也可能会付出最大的努力 notifications/progress 更新。

退货: output, matched, timedOut (output 可能为空 match-only 模式）

terminal_stop

停止并清理终端会话。（可选）捕获最近输出的快照，或在停止之前将完整转录写入磁盘。在Unix上，杀死整个进程组以防止孤儿进程。

退货: success, message，可选 snapshot，可选 transcript

terminal_list

列出所有活动的终端会话。

退货: sessions, count (verbose: false 回报 id, name, cwd, alive, busy 仅）

额外工具（通过 terminal_extra)

默认情况下，以下工具可通过 terminal_extra 元工具。代理可以通过以下方式发现他们的模式 terminal_extra({ list: true }) 并通过以下方式给他们打电话 terminal_extra({ tool: "", args: { ... } }).

terminal_extra

用于发现和调用额外工具的元工具。

terminal_send_key

发送一个命名的特殊密钥。

支持的密钥: 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_run_paged

使用以下命令运行只读一次性命令 cmd + args 和 shell=false 并从捕获的输出中返回一页stdout行。这将分页返回的结果，而不是使用头尾截断。分页模式不解析部分输出，但在以下情况下，它可以返回支持的只读命令的简明摘要 summary: true.

退货：信封与 terminal_run，加 pageInfo.page, pageInfo.pageSize, pageInfo.totalLines, pageInfo.hasNext

terminal_get_history

检索过去的终端输出而不使用它。非破坏性--从滚动缓冲区返回历史输出（最后约10000行）。可用于查看已读或遗漏的输出。

退货: lines 或 text，加 totalLines, returnedFrom, returnedTo

terminal_retry

在同一终端会话中重试命令，直到成功或重试次数用尽。

退货: success, attempts, lastResult, history

terminal_diff

在同一终端会话中运行两个命令，并返回其输出的有界统一差分。

退货: resultA, resultB, diff, identical

terminal_resize

调整端子尺寸。

terminal_write_file

将内容直接写入磁盘上的文件。解析与会话CWD相关的路径。比管道内容物更安全、更坚固 echo --正确处理特殊字符、换行符和大文件。

退货: success, path （绝对）， size （字节）， append

terminal_watch

等待会话输出中的一个或多个触发模式。首次匹配、静默检测、超时或进程退出时返回。替换手动轮询循环——单个调用会一直阻塞，直到事件触发。

触发器对象:

退货: reason (trigger/quiet/timeout/exit), position, timedOut，可选 triggerId, matchedLine, context

用法示例

运行命令

terminal_start()                           -> { sessionId: "calm-reef" }
terminal_exec({ sessionId, command: "ls -la" })  -> { output: "...", exitCode: 0, cwd: "/home/user" }

运行安全的一次性命令

terminal_run({ cmd: "git", args: ["status", "--porcelain=v1", "--branch"] })
-> { ok: true, stdout: { raw: "...", parsed: { branch: {...}, staged: [], modified: [], untracked: [] } } }

对于安装在下的Windows工具 Program Files，更喜欢这种形状 powershell -Command:

terminal_run({ cmd: "C:\\Program Files\\Vendor\\Tool.exe", args: ["/flag:value", "/other"] })

对于只在日志文件中报告成功的编译器：

terminal_run({
  cmd: "C:\\Program Files\\Vendor\\Tool.exe",
  args: ["/compile:script.mq5", "/log:build.log"],
  successFile: "build.log",
  successFilePattern: "0 error"
})

浏览大型只读输出

terminal_run_paged({ cmd: "git", args: ["log", "--oneline"], page: 0, pageSize: 100 })
-> { ok: true, stdout: { raw: "...", parsed: null }, pageInfo: { totalLines: 120, hasNext: true } }

交互式Python REPL

terminal_start({ name: "python" })
terminal_write({ sessionId, data: "python3\r" })
terminal_read({ sessionId })                     -> Python banner
terminal_write({ sessionId, data: "2 + 2\r" })
terminal_read({ sessionId })                     -> "4"
terminal_send_key({ sessionId, key: "ctrl+d" })  -> exit Python

等待服务器启动

terminal_start({ name: "dev-server" })
terminal_write({ sessionId, data: "npm run dev\r" })
terminal_wait({ sessionId, pattern: "listening on port", timeout: 60000 })
terminal_wait({ sessionId, pattern: "listening on port", returnMode: "full" })

关注构建事件

terminal_extra({ tool: "terminal_watch", args: {
  sessionId,
  triggers: [
    { id: "success", pattern: "webpack: Compiled successfully" },
    { id: "error", pattern: "ERROR in" }
  ],
  timeout: 120000,
  quietExitMs: 10000
}})
-> { reason: "trigger", triggerId: "success", matchedLine: "webpack: Compiled successfully", context: [...], position: 184320 }

逐步轮询构建日志

const r1 = terminal_read({ sessionId })           -> { output: "Building...", position: 5000 }
const r2 = terminal_read({ sessionId, since: 5000 }) -> { output: "Done.", position: 5200 }

安静退出开发服务器

terminal_exec({ sessionId, command: "npm run dev", quietExitMs: 3000, minOutputBytes: 50 })
-> { output: "webpack: Compiled successfully", quietExited: true, hint: "Command is still running..." }

请停止阅读成绩单

terminal_stop({ sessionId, snapshotLines: 20, transcriptPath: "/tmp/session.log" })
-> { success: true, snapshot: { text: "...", lineCount: 20, totalLines: 500 }, transcript: { path: "/tmp/session.log", bytes: 12345 } }

重试一个古怪的命令

terminal_retry({ sessionId, command: "npm test", maxRetries: 2, backoff: "fixed", delayMs: 1000 })
-> { success: true, attempts: 2, lastResult: { output: "...", exitCode: 0, cwd: "...", timedOut: false } }

区分两个命令输出

terminal_diff({ sessionId, commandA: "git show HEAD~1:README.md", commandB: "type README.md" })
-> { identical: false, diff: "--- git show HEAD~1:README.md\n+++ type README.md\n@@ @@\n..." }

建筑

src/
  index.js            Entry point, server bootstrap, graceful shutdown
  tools.js            MCP tool registrations with Zod schemas
  command-runner.js   One-shot non-interactive command execution (shell=false)
  command-parsers.js  Structured parsers for supported read-only commands
  pager.js            Line-based pagination helper for large stdout
  pty-session.js      PTY session: marker injection, idle read, buffer mgmt
  smart-tools.js      Retry and diff helpers for higher-level terminal tools
  regex-utils.js      Shared user-regex validation and compilation
  session-id.js       Human-readable session ID generation
  session-manager.js  Session lifecycle, TTL cleanup, concurrency limits
  shell-detector.js   Cross-platform shell auto-detection
  ansi.js             ANSI escape code stripping

结构化解析器支持

terminal_run 当前解析一小部分只读命令签名：

• git log --oneline
• git log --oneline -n
• git status --porcelain=v1 --branch
• git status --short --branch
• git status --short
• git branch
• git branch --all / git branch --remotes
• git branch -vv
• git branch --show-current
• git rev-parse --abbrev-ref HEAD
• git rev-parse --show-toplevel
• git rev-parse --is-inside-work-tree
• git diff --name-only
• git diff --name-status
• git diff --stat
• git diff --shortstat
• git ls-files
• git remote -v
• tasklist /fo csv /nh
• where / which

集 parseOnly: true 省略 stdout.raw 当支持的解析器成功时。不支持的命令仍然返回 stdout.raw; stdout.parsed 是 null.

集 summary: true 返回 stdout.summary 并抑制 stdout.raw 用于支持的命令签名。如果没有可用的摘要，则保留原始stdout。

terminal_run_paged 支持 summary: true 对于只读命令： git (branch, diff, log, ls-files, remote, rev-parse, status), tasklist, where，以及 which.

当请求解析但没有匹配的解析器时， terminal_run 可能包括短片 hint 对于具有较大原始输出的解析器级命令签名：

• 目前仅限于 git 加 where / which
• 只有当命令成功并且 stdout.raw 足够大，值得推荐
• 措辞： Structured parser unavailable for this command signature. If you need this often, propose one.

许可证

麻省理工学院