smart-terminal

smart-terminal-mcp

一款基于 PTY 的 MCP 服务，具备出色的 Windows 支持，可让支持 MCP 的 AI 客户端及其 Agent 通过伪终端（node-pty）持久、交互式地访问 shell。

与简单的基于 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 客户端中的 Agent 所使用的受控键盘和终端。它会打开由 PTY 支持的持久 shell 会话，让 Agent 能够发送命令和按键、读取输出，并在同一会话中继续工作。

核心终端功能

• 交互式终端会话——保持由 PTY 支持的 shell 会话持续运行，让 Agent 能够发送输入、读取输出，并从上次中断处继续。
• 确定性的命令完成检测——terminal_exec 使用唯一标记来判断命令是否已完成。
• 干净的输出——命令前标记有助于保持返回内容易读，即使 shell 会回显命令或展开别名也不例外。
• 工作目录跟踪——terminal_exec 会在每条命令执行后报告当前文件夹。

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

• 交互式读写 —— terminal_write + terminal_read 支持提示、REPL 和其他交互式程序，无需离开当前会话。
• 增量读取 —— terminal_read 接受 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 比较两个命令结果，并返回统一差异。
• 会话快照 —— terminal_stop 可以在停止前捕获末尾快照，或将完整记录写入磁盘。

安全性和易用性

• 更安全的一次性命令 —— terminal_run 直接使用 cmd + args 和 shell=false 执行二进制文件，使自动化更可预测。
• 结构化解析器 —— 某些受支持的只读命令可以同时返回原始文本和解析后的输出。
• 阻塞缓解措施 —— 禁用分页器（GIT_PAGER=cat、PAGER=cat），抑制 PowerShell 进度输出，并在 Windows 上为 cmd.exe 设置 UTF-8。
• 特殊按键支持 —— 可以发送 Ctrl+C、Tab、方向键等按键，无需手动构造转义序列。
• 进程组清理 —— terminal_stop 在 Unix 上会终止整个进程组，防止遗留子进程。
• 会话管理 —— 支持命名会话、空闲清理和最多 10 个并发会话。会话 ID 易于阅读（例如 calm-reef）。
• Shell 自动检测 —— Windows：pwsh.exe > powershell.exe > cmd.exe。Linux/macOS：$SHELL > bash > sh。

进度通知不同于完整的 stdout 流式传输。目前，它会为 terminal_exec 和 terminal_wait 发送定期状态更新，通常依据已用时间和最新输出行生成。是否能看到这些通知取决于你的 MCP 客户端。

令牌效率

这个 MCP 不会自动压缩终端输出，但它可以通过返回更精简、更有针对性的响应，并让你在需要时更轻松地重新查看输出，帮助 Agent 在终端密集型工作流中减少令牌用量。

主要优势在于模型上下文效率，而非保证节省底层命令的运行时间或产生的总字节数。

轮询和长时间运行的进程

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

控制输出大小

• 当 Agent 想要一次查看一页返回结果时，对大型只读输出使用 terminal_run_paged。
• 当 Agent 只需要查看输出中的一小段时，调低 maxLines、pageSize 或 tailLines。
• 当 Agent 更需要结构化结果而非原始文本时，在 terminal_run 中使用 summary: true 或 parseOnly: true。
• 当 Agent 只需要知道某个模式是否出现时，使用 terminal_wait({ returnMode: "match-only" })。
• 当 Agent 需要回看先前的输出，而不想将整个会话重新转储到对话中时，使用 terminal_get_history。
• 使用 terminal_stop({ transcriptPath }) 将大型会话历史保存到磁盘，而不是在响应中返回。

实际上，这让 Agent 能够更有选择地检查终端状态，而不是反复将大型日志转储到对话中。

减少工具定义开销

默认情况下，使用最多的 8 个工具会以完整 schema 注册，另外 8 个便捷工具则收纳在一个轻量级的 terminal_extra 元工具之后（约 30 个 token，而非约 1,700 个）。

默认核心工具：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

额外工具并未隐藏——Agent 可以在 terminal_extra 描述中看到工具名称，并且可以：

• 查看 schema：terminal_extra({ list: true }) → 返回完整的参数 schema
• 调用任意额外工具：terminal_extra({ tool: "terminal_resize", args: { sessionId: "...", cols: 200, rows: 50 } })

使用 SMART_TERMINAL_DISABLED_TOOLS 自定义额外工具，或将其设为空字符串，以完整 schema 注册全部 15 个工具：

所有工具均使用完整 schema（无元工具）：

{
  "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 个核心工具 + 按需提供 9 个工具的 terminal_extra。

面向 Agent 的设置——使用 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 个核心工具 + 按需提供 9 个工具的 terminal_extra。

安装

推荐：通过 npx 直接运行稳定版：

npx smart-terminal-mcp@stable

或全局安装：

npm install -g smart-terminal-mcp

或克隆项目用于开发：

git clone <repo-url>
cd smart-terminal-mcp
npm install

配置

Shell 选择

将 SMART_TERMINAL_SHELL 设置为 shell 名称或绝对路径，以指定 terminal_start 在省略 shell 参数时使用的 shell。这样可确保不同 MCP 客户端和服务重启之间的命令语法与启动行为保持一致。

"env": {
  "SMART_TERMINAL_SHELL": "pwsh"
}

Shell 的选择优先级如下：

1. 显式参数：terminal_start({ shell }) 优先于环境设置。
2. 通用指定：SMART_TERMINAL_SHELL 适用于 Windows、Linux 和 macOS。
3. 旧版覆盖项：Windows 上仍可使用 PWSH_PATH。
4. 自动检测：未设置可用的指定值时，沿用现有的平台专用顺序。

如果 SMART_TERMINAL_SHELL 的值不可用，则会忽略该值，并继续使用旧版设置或平台检测。

启动参数会根据所选 shell 而定：

• PowerShell（pwsh / powershell）：显式指定和固定的会话将使用 -NoLogo -NoProfile 启动。Windows 自动检测也使用相同标志。
• 其他 shell：cmd、bash、zsh、fish 和 sh 启动时不添加参数。

这可以避免 PowerShell 配置文件、别名和提示符自定义导致自动化行为在不同机器上不一致。

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

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

Claude Code

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

Augment Code

将以下内容添加到你的 Augment MCP 设置中：

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

如果你想固定使用某个特定版本，而不是跟随稳定标签，请将 @stable 替换为某个版本号，例如 @1.0.1。

工具

默认情况下会注册 8 个核心工具，并可通过 terminal_extra 按需使用 8 个便捷工具（参见减少工具定义开销）。

核心工具

terminal_start

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

参数	类型	默认值	描述
shell	string	自动检测	Shell 可执行文件（例如 pwsh.exe、bash）
cols	number	120	终端宽度
rows	number	30	终端高度
cwd	string	服务端 CWD	工作目录
name	string	--	易记的会话名称
env	object	--	自定义环境变量（例如 { "NODE_ENV": "test" }）

返回：sessionId、shell、shellType、cwd、banner

terminal_exec

执行命令，并以确定性方式检测命令是否完成。大容量输出会根据 maxLines 截取开头和结尾。如果 MCP 客户端发送了 progressToken，长时间运行的调用也可能尽力发送 notifications/progress 更新。

参数	类型	默认值	描述
sessionId	string	必填	会话 ID
command	string	必填	要执行的命令
timeout	number	30000	超时时间，单位为 ms（最长 10min）
maxLines	number	200	截断前允许的最大输出行数
quietExitMs	number	--	如果输出静默 N ms，则提前返回
minOutputBytes	number	1	静默检测触发前所需的最少字节数

返回：output、exitCode、cwd、timedOut、可选的 quietExited、可选的 hint

terminal_run

使用 cmd + args 运行一次性非交互式命令。默认的 shell=false 比 terminal_exec 更安全，适用于可预测的自动化。输出会按 maxOutputBytes 限制，而不是截取开头和结尾。dir 或 cd 等 Shell 内置命令需要设置 shell=true。

设置 shell=true 时，命令在 Windows 上通过 %ComSpec%（cmd.exe）运行，在其他平台上则通过 /bin/sh 运行。它不会使用会话 Shell 或 SMART_TERMINAL_SHELL。这一区别可避免在一次性 cmd.exe 命令中意外重用 PowerShell 会话语法。

在 Windows 上，terminal_run 会解析 PATH/PATHEXT，并在需要时通过 cmd.exe 启动 .cmd / .bat 包装脚本。建议直接将目标可执行文件作为 cmd 传入，而不是用 powershell -Command 或 cmd /c 包装，尤其是在 Windows 路径包含空格时。

对于始终以 0 退出的工具，可以要求指定退出代码，和/或根据命令写入的文件验证成功正则表达式。

参数	类型	默认值	描述
cmd	string	必填	要运行的可执行文件
args	string[]	[]	直接传递给可执行文件的参数数组
shell	boolean	false	使用操作系统 Shell 执行内置命令、管道和重定向
cwd	string	服务端 CWD	工作目录
timeout	number	30000	超时时间，单位为 ms
maxOutputBytes	number	102400	要捕获的 stdout/stderr 总字节数上限
parse	boolean	true	尝试对受支持的命令进行结构化解析
parseOnly	boolean	false	解析后丢弃原始 stdout
summary	boolean	false	在受支持时返回简洁摘要
successExitCode	number or null	0	成功所要求的退出代码
successFile	string	--	退出后要验证的可选文件
successFilePattern	string	--	必须与 successFile 匹配的正则表达式

返回：ok、cmd、args、cwd、exitCode、timedOut、durationMs、stdout.raw、stdout.parsed、可选的 stdout.summary、stderr.raw、可选的 checks、可选的 hint

terminal_write

向终端写入原始数据（用于交互式程序）。之后使用 terminal_read。

参数	类型	说明
sessionId	string	会话 ID
data	string	要写入的数据（按 Enter 使用 \r，按 Tab 使用 \t）

terminal_read

读取缓冲输出，并检测空闲状态。大量输出会根据 maxLines 截断，保留开头和结尾。传入 since 可增量读取——仅返回指定字节位置之后产生的输出。

参数	类型	默认值	说明
sessionId	string	必填	会话 ID
timeout	number	30000	硬超时时间，单位为 ms
idleTimeout	number	500	静默达到此时长后返回，单位为 ms
maxLines	number	200	最大输出行数
since	number	--	上一次读取响应中的字节位置

返回：output、timedOut、position、可选的 truncated

terminal_wait

等待输出流中出现特定模式。默认仅匹配调用后产生的输出——回显的命令行（其中包含输入的任何模式，包括完成标记）永远不会触发匹配；即使开始等待时回显仍在传输，也不会触发匹配（已写入的输入会被记录并屏蔽，直到其回显到达或不匹配）。传入 since（此前从 terminal_read/terminal_wait/terminal_watch 获取的 position），还可从该位置扫描保留的历史记录；若 since 超出当前流的末尾，则会作为未来游标处理（跳过其之前的实时数据）。默认情况下，响应仅返回最后 tailLines 行；使用 returnMode: "full" 返回完整匹配输出，或使用 "match-only" 完全不返回输出。如果 MCP 客户端发送了 progressToken，长时间运行的等待还可能尽力发送 notifications/progress 更新。

参数	类型	默认值	说明
sessionId	string	必填	会话 ID
pattern	string	必填	字符串或正则表达式模式
timeout	number	30000	超时时间，单位为 ms
returnMode	string	"tail"	响应模式：tail、full、match-only
tailLines	number	50	返回的末尾行数
since	number	--	匹配的起始字符位置；默认从调用时的流末尾开始（输出到达未来位置后会遵从该位置）

返回：output、matched、timedOut、position（在 match-only 模式下，output 可能为空）

terminal_stop

停止并清理终端会话。停止前，可选择捕获近期输出快照，或将完整记录写入磁盘。在 Unix 上，会终止整个进程组，以防留下孤立的子进程。

参数	类型	默认值	说明
sessionId	string	必填	要停止的会话 ID
snapshotLines	number	0	返回最后 N 行输出（0 = 不返回）
transcriptPath	string	--	将完整历史记录写入此绝对路径

返回：success、message、可选的 snapshot、可选的 transcript

terminal_list

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

参数	类型	默认值	说明
verbose	boolean	true	包含完整元数据

返回：sessions、count（verbose: false 时仅返回 id、name、cwd、alive、busy）

额外工具（通过 terminal_extra）

以下工具默认通过 terminal_extra 元工具提供。Agent 可通过 terminal_extra({ list: true }) 获取其架构，并通过 terminal_extra({ tool: "<name>", args: { ... } }) 调用。

terminal_extra

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

参数	类型	默认值	描述
list	boolean	false	返回所有额外工具的完整参数架构
tool	string	--	要调用的额外工具名称
args	object	--	传递给额外工具的参数

terminal_send_key

发送指定的特殊按键。

参数	类型	描述
sessionId	string	会话 ID
key	string	按键名称（见下文）

支持的按键：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 行。该模式会对返回结果分页，而不是使用 head + tail 截断。分页模式不会解析部分输出，但对于支持的只读命令，可以在 summary: true 时返回简明摘要。

参数	类型	默认值	描述
cmd	string	required	要运行的只读可执行文件
args	string[]	[]	直接传递给可执行文件的参数数组
cwd	string	服务端 CWD	工作目录
timeout	number	30000	超时时间，单位为 ms
maxOutputBytes	number	102400	要捕获的 stdout/stderr 总字节数上限
page	number	0	从 0 开始计数的页码
pageSize	number	100	每页行数
summary	boolean	false	在支持时返回简明摘要

返回值：与 terminal_run 使用相同的封装，另含 pageInfo.page、pageInfo.pageSize、pageInfo.totalLines、pageInfo.hasNext

terminal_get_history

在不消耗历史输出的情况下检索终端历史输出。此操作不会修改数据，会从滚动缓冲区（最近约 10,000 行）中返回历史输出。适用于查看已读取或错过的输出。

参数	类型	默认值	描述
sessionId	string	required	会话 ID
offset	number	0	从末尾开始跳过的行数（0 = 最近的内容）。用于分页。
maxLines	number	200	要返回的最大行数
format	string	"lines"	响应格式：lines 或 text

返回值：lines 或 text，以及 totalLines、returnedFrom、returnedTo

terminal_retry

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

参数	类型	默认值	描述
sessionId	string	required	会话 ID
command	string	required	要执行的命令
maxRetries	number	3	首次尝试后的重试次数
backoff	string	"exponential"	退避模式：fixed、linear、exponential
delayMs	number	1000	基础延迟，单位为 ms
timeout	number	30000	每次尝试的超时时间，单位为 ms
maxLines	number	200	每次尝试的最大输出行数
successExitCode	number or null	0	成功所需的退出代码
successPattern	string or null	null	可选的正则表达式，输出必须与之匹配

返回值：success、attempts、lastResult、history

terminal_diff

在同一终端会话中运行两条命令，并返回其输出的有限长度统一差异。

参数	类型	默认值	描述
sessionId	string	required	会话 ID
commandA	string	required	基准命令
commandB	string	required	对比命令
timeout	number	30000	每条命令的超时时间，单位为 ms
maxLines	number	200	每条命令的最大输出行数
contextLines	number	3	差异上下文行数

返回值：resultA、resultB、diff、identical

terminal_resize

调整终端尺寸。

Param	Type	Description
sessionId	string	会话 ID
cols	number	新宽度
rows	number	新高度

terminal_write_file

直接将内容写入磁盘上的文件。路径相对于会话的 CWD 解析。与通过 echo 管道传递内容相比，这种方式更安全、更可靠，能正确处理特殊字符、换行符和大文件。

Param	Type	Default	Description
sessionId	string	required	会话 ID（用于解析工作目录）
path	string	required	文件路径（相对于会话 CWD，或绝对路径）
content	string	required	要写入的文件内容
encoding	string	"utf-8"	文件编码（utf-8、ascii、base64、hex、latin1）
append	boolean	false	追加到文件，而不是覆盖

返回值：success、path（绝对路径）、size（字节数）、append

terminal_watch

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

Param	Type	Default	Description
sessionId	string	required	会话 ID
triggers	array	required	1–10 个触发对象（见下文）
timeout	number	60000	硬超时时间，单位为毫秒（最长 1 小时）
quietExitMs	number	--	若 N 毫秒内没有输出则返回
contextLines	number	3	匹配项之前的上下文行数
since	number	--	仅匹配此字节位置之后的输出

触发对象：

Field	Type	Default	Description
id	string	required	在响应中返回的标签
pattern	string	required	正则表达式或字面模式
isRegex	boolean	true	设为 false 时进行字面匹配
cooldownMs	number	0	此触发条件两次匹配之间的最短间隔（毫秒）

返回值：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: [] } } }

对于安装在 Program Files 下的 Windows 工具，优先使用以下形式，而不是 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 <count>
• 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 <name> / which <name>

设置 parseOnly: true，即可在支持的解析器解析成功时省略 stdout.raw。不支持的命令仍会返回 stdout.raw；stdout.parsed 为 null。

设置 summary: true，即可为支持的命令签名返回 stdout.summary，并省略 stdout.raw。如果没有可用的摘要，则会保留原始标准输出。

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.

许可证

MIT