smart-terminal

smart-terminal-mcp

PTY ベースの MCP サーバーです。Windows を強力にサポートし、MCP に対応した AI クライアントとそのエージェントに、疑似端末を介した永続的で対話型のシェルアクセスを提供します（node-pty）。

単純な exec ベースの方法とは異なり、PTY を利用したシェルセッションを手順をまたいで維持し、対話型 CLI ツールとの双方向通信、段階的な読み取り、次の手順に引き継がれるセッション状態を実現します。

最近の更新については、変更履歴をご覧ください。

AI クライアント内蔵のターミナルではなく、これを使う理由は？

特定のクライアントが提供する内蔵ターミナルの動作に依存せず、AI クライアント間で一貫したターミナルのワークフローを使いたい場合にインストールしてください。

この MCP は、次のような場合に特に役立ちます。

• クライアント間で持ち運べるワークフロー -- 同じターミナルツールと使い方を、Claude Code、Cursor、Trae、Antigravity など、MCP に対応したさまざまなクライアントで利用できます。
• 再利用可能なプロンプトとツール -- terminal_wait、terminal_retry、terminal_run_paged、terminal_get_history などのツールを中心としたワークフローは、特定のクライアントのターミナル動作に縛られにくく、チームやクライアント間で再利用しやすくなります。
• 永続的なターミナル状態 -- 現在のフォルダー、環境、実行中のプロセスを含め、同じシェルセッションを手順をまたいで維持できます。
• より優れた対話型動作 -- vim、npm のプロンプト、標準入力からパイプで入力すると停止しがちな対話型インストーラーなど、TTY の動作を必要とするツールを安全に扱えます。REPL、Ctrl+C、矢印キー、動的プロンプトを含む、完全な対話型セッションをサポートします。
• 大量の出力をより細かく制御 -- すべてを一度に出力する代わりに、出力の切り詰め、ページ分割、差分表示、再試行、パターンの待機、履歴の取得ができます。
• より予測しやすい自動化 -- コマンドの完了タイミングを推測する代わりに、決定論的な完了マーカーを使用できます。

AI クライアントが、出力を適切に処理できる安定したステートフルな対話型ターミナルをすでに備えている場合、基本的なコマンド実行にこの MCP は必要ないかもしれません。これを追加する主な理由は、ターミナルを利用したワークフローをより明確で再利用しやすく、クライアント間で持ち運びやすくすることです。

機能

これは、MCP クライアント内で動作するエージェント向けの、制御可能なキーボードとターミナルと考えてください。永続的な PTY ベースのシェルセッションを開き、エージェントはコマンドやキー入力を送信して出力を読み取り、同じセッションで作業を続けられます。

ターミナルの主な機能

• 対話型ターミナルセッション -- 永続的な PTY ベースのシェルセッションを開いたままにするため、エージェントは入力を送り、出力を読み取り、中断したところから作業を再開できます。
• 決定論的なコマンド完了検出 -- terminal_exec は一意のマーカーを使って、コマンドの完了を検出します。
• 見やすい出力 -- コマンド実行前のマーカーにより、シェルがコマンドをエコーしたりエイリアスを展開したりしても、返される出力を読みやすく保ちます。
• 作業ディレクトリの追跡 -- 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 は、大きな読み取り専用出力を一度にすべて送信する代わりに、1ページずつ返します。
• 出力の差分 — terminal_diff は2つのコマンド結果を比較し、統合差分を返します。
• セッションのスナップショット — 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）。
• シェルの自動検出 — Windows：pwsh.exe > powershell.exe > cmd.exe。Linux/macOS：$SHELL > bash > sh。

進捗通知は、完全な stdout ストリーミングとは異なります。現在は terminal_exec と terminal_wait に対して、通常は経過時間と最新の出力行に基づく定期的なステータス更新を送信します。通知が表示されるかどうかは、MCP クライアントによって異なります。

トークン効率

この MCP は、ターミナル出力を魔法のように圧縮するわけではありませんが、より小さく、より的を絞った応答を返し、必要なときだけ出力を再確認しやすくすることで、ターミナルを多用するワークフローでエージェントが使用するトークンを減らすのに役立ちます。

主な利点はモデルコンテキストの効率化であり、基盤となるコマンドの実行時間や生成される総バイト数の削減を保証するものではありません。

ポーリングと長時間実行プロセス

• 増分読み取りには terminal_read({ since }) を使用します。各呼び出しは、バッファ全体を読み直すのではなく、前回の position 以降の新しい出力のみを返します。繰り返しのポーリングでトークン使用量を最大約87％削減できます。
• 特定のパターンを待つ場合は、手動のポーリングループの代わりに terminal_watch を使用します。1回の呼び出しで、一致、無出力、タイムアウト、または終了時に結果を返し、ログ監視のワークフローでトークン使用量を最大約99％削減できます。
• 完了を示すマーカーを出力しない長時間実行コマンド（開発サーバー、ウォッチャーなど）には terminal_exec({ quietExitMs }) を使用します。ハードタイムアウトまで待つ代わりに、出力が停止すると早期に結果を返します。トークン使用量を最大約94％削減できます。

出力サイズの制御

• エージェントが返された結果を一度に1ページずつ確認したい場合は、大量の読み取り専用出力に**terminal_run_paged**を使用します。
• エージェントが出力の一部だけを必要とする場合は、maxLines、pageSize、または**tailLines**の値を小さくします。
• エージェントに生のテキストより構造化された結果が役立つ場合は、terminal_runで**summary: trueまたはparseOnly: true**を使用します。
• エージェントがパターンの出現有無だけを確認したい場合は、**terminal_wait({ returnMode: "match-only" })**を使用します。
• エージェントがセッション全体を会話に再出力せず、以前の出力を確認したい場合は、**terminal_get_history**を使用します。
• 大量のセッション履歴を応答として返さずディスクに保存するには、**terminal_stop({ transcriptPath })**を使用します。

実際には、これによりエージェントは、巨大なログを繰り返し会話に再出力するのではなく、ターミナルの状態をより選択的に確認できます。

ツール定義のオーバーヘッドの削減

デフォルトでは、使用頻度の高い8つのツールが完全なスキーマで登録され、8つの便利なツールは単一の軽量なterminal_extraメタツールの背後にまとめられます（約1,700トークンではなく約30トークン）。

デフォルトのコアツール：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個と、必要に応じて使用する9個のツールを含むterminal_extraです。

エージェント向けの構成 -- terminal_execの代わりにterminal_runを使用します。

"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

設定

シェルの選択

SMART_TERMINAL_SHELLにシェル名または絶対パスを設定すると、terminal_startのshellパラメータが省略されたときに使用するシェルを固定できます。これにより、MCP クライアント間やサーバーの再起動後も、コマンド構文と起動時の動作を一貫させられます。

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

シェルの選択には、次の優先順位が適用されます。

1. 明示的なパラメータ：terminal_start({ shell })は環境設定より優先されます。
2. 汎用の固定設定：SMART_TERMINAL_SHELLはWindows、Linux、macOSで適用されます。
3. 従来の上書き設定：Windowsでは引き続きPWSH_PATHを使用できます。
4. 自動検出：使用可能な固定設定がない場合は、既存のプラットフォーム固有の順序が適用されます。

使用できないSMART_TERMINAL_SHELLの値は無視され、従来の設定またはプラットフォームの自動検出が引き続き行われます。

起動引数は、選択したシェルに合わせて設定されます。

• PowerShell（pwsh / powershell）：明示的に指定したセッションと固定設定されたセッションは、-NoLogo -NoProfileを付けて起動します。Windowsの自動検出でも同じフラグが使用されます。
• その他のシェル：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 個のコアツールが完全なスキーマとともに登録され、8 個の便利なツールは terminal_extra を介して必要に応じて利用できます（ツール定義のオーバーヘッドを削減するを参照）。

コアツール

terminal_start

新しい対話型ターミナルセッションを開始します。

パラメーター	型	デフォルト	説明
shell	string	自動検出	シェル実行ファイル（例：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	タイムアウト（ミリ秒、最大 10 分）
maxLines	number	200	切り詰める前の出力行数の上限
quietExitMs	number	--	出力が N ミリ秒間ない場合、早期に返します
minOutputBytes	number	1	無出力検出を開始するために必要な最小バイト数

返り値：output、exitCode、cwd、timedOut、省略可能な quietExited、省略可能な hint

terminal_run

cmd + args を使って、単発の非対話型コマンドを実行します。デフォルトの shell=false は、予測可能な自動化において terminal_exec より安全です。出力は先頭と末尾を残して切り詰められるのではなく、maxOutputBytes によって上限が設定されます。dir や cd などのシェル組み込みコマンドには shell=true が必要です。

shell=true の場合、コマンドは Windows では %ComSpec%（cmd.exe）、その他のプラットフォームでは /bin/sh を介して実行されます。セッションのシェルや SMART_TERMINAL_SHELL は使用しません。この違いにより、単発の cmd.exe コマンドで PowerShell のセッション構文を誤って再利用するのを防ぎます。

Windows では、terminal_run は PATH／PATHEXT を解決し、必要に応じて .cmd／.bat ラッパーを cmd.exe 経由で起動します。特に Windows パスにスペースが含まれる場合は、powershell -Command や cmd /c でラップせず、対象の実行ファイルを cmd として直接渡してください。

常に 0 で終了するツールの場合、特定の終了コードを必須にしたり、コマンドが書き込んだファイルに対して成功を示す正規表現を検証したりできます。

パラメーター	型	デフォルト	説明
cmd	string	必須	実行する実行ファイル
args	string[]	[]	実行ファイルに直接渡す引数の配列
shell	boolean	false	組み込みコマンド、パイプ、リダイレクトに OS のシェルを使用します
cwd	string	サーバーの CWD	作業ディレクトリ
timeout	number	30000	タイムアウト（ミリ秒）
maxOutputBytes	number	102400	取得する標準出力と標準エラー出力の合計バイト数の上限
parse	boolean	true	対応コマンドの構造化解析を試みます
parseOnly	boolean	false	解析後に生の標準出力を破棄します
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 を使用してください。

Param	Type	Description
sessionId	string	セッション ID
data	string	書き込むデータ（Enter は \r、Tab は \t）

terminal_read

アイドル状態を検知しながら、バッファーに保存された出力を読み取ります。出力が大きい場合は、maxLines に基づいて先頭と末尾が返されます。since を指定すると、前回の読み取り以降の出力だけを返す差分読み取りができます。指定したバイト位置以降に出力された内容だけが返されます。

Param	Type	Default	Description
sessionId	string	required	セッション ID
timeout	number	30000	ハードタイムアウト（ミリ秒）
idleTimeout	number	500	この時間（ミリ秒）だけ出力がない場合に返します
maxLines	number	200	最大出力行数
since	number	--	以前の読み取りレスポンスで取得したバイト位置

Returns: output、timedOut、position、任意の truncated

terminal_wait

出力ストリーム内の特定のパターンを待ちます。デフォルトでは、呼び出し後に生成された出力だけが照合対象です。入力したパターンを含むエコーされたコマンドライン（完了マーカーを含む）は、呼び出し時にまだエコーがストリーミング中の場合も含め、一致として扱われません（書き込まれた入力は記憶され、エコーが届くか不一致になるまでマスクされます）。since を指定すると（terminal_read／terminal_wait／terminal_watch で以前に取得した position を指定）、その位置以降の保持された履歴もスキャンします。現在のストリーム末尾より先の since は、将来のカーソルとして扱われます（その位置より前のライブデータはスキップされます）。デフォルトでは、レスポンスには最後の tailLines 行だけが含まれます。照合された出力全体を返すには returnMode: "full" を、出力を完全に省略するには "match-only" を使用してください。MCP クライアントが progressToken を送信すると、実行時間の長い待機処理では、ベストエフォートで notifications/progress の更新も送信されることがあります。

Param	Type	Default	Description
sessionId	string	required	セッション ID
pattern	string	required	文字列または正規表現パターン
timeout	number	30000	タイムアウト（ミリ秒）
returnMode	string	"tail"	レスポンスモード：tail、full、match-only
tailLines	number	50	返す末尾の行数
since	number	--	照合を開始する文字位置。デフォルトは呼び出し時点のストリーム末尾です（出力がその位置に達すると、将来の位置も適用されます）

Returns: output、matched、timedOut、position（match-only モードでは output が空の場合があります）

terminal_stop

ターミナルセッションを停止し、クリーンアップします。停止前に、直近の出力のスナップショットを取得したり、トランスクリプト全体をディスクに書き込んだりできます。Unix では、孤立した子プロセスが残らないよう、プロセスグループ全体を終了します。

Param	Type	Default	Description
sessionId	string	required	停止するセッション ID
snapshotLines	number	0	出力の最後の N 行を返します（0 = なし）
transcriptPath	string	--	全履歴をこの絶対パスに書き込みます

Returns: success、message、任意の snapshot、任意の transcript

terminal_list

アクティブなターミナルセッションをすべて一覧表示します。

Param	Type	Default	Description
verbose	boolean	true	完全なメタデータを含めます

Returns: sessions、count（verbose: false の場合は id、name、cwd、alive、busy のみを返します）

追加ツール（terminal_extra 経由）

次のツールは、デフォルトで terminal_extra メタツールから利用できます。エージェントは terminal_extra({ list: true }) でスキーマを確認し、terminal_extra({ tool: "<name>", args: { ... } }) で呼び出すことができます。

terminal_extra

追加ツールを検出して呼び出すためのメタツールです。

Param	Type	Default	Description
list	boolean	false	すべての追加ツールのパラメータスキーマ全体を返します
tool	string	--	呼び出す追加ツールの名前
args	object	--	追加ツールに渡す引数

terminal_send_key

名前で指定した特殊キーを送信します。

Param	Type	Description
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

shell=false を指定して cmd + args を使い、読み取り専用の単発コマンドを実行し、取得した出力から標準出力の行を1ページ分返します。head + tail による切り詰めではなく、返される結果をページ分割します。ページモードでは部分的な出力の解析は行いませんが、summary: true の場合、対応する読み取り専用コマンドについて簡潔な要約を返すことができます。

Param	Type	Default	Description
cmd	string	required	実行する読み取り専用の実行ファイル
args	string[]	[]	実行ファイルに直接渡す引数の配列
cwd	string	server CWD	作業ディレクトリ
timeout	number	30000	タイムアウト（ミリ秒）
maxOutputBytes	number	102400	取得する標準出力と標準エラーの最大合計バイト数
page	number	0	0 始まりのページ番号
pageSize	number	100	1 ページあたりの行数
summary	boolean	false	対応している場合、簡潔な要約を返します

戻り値：terminal_run と同じエンベロープに、pageInfo.page、pageInfo.pageSize、pageInfo.totalLines、pageInfo.hasNext が加わります

terminal_get_history

過去のターミナル出力を消費せずに取得します。非破壊的な操作で、ローリングバッファ（直近約 10,000 行）から過去の出力を返します。すでに読み取った出力や見逃した出力を確認するのに便利です。

Param	Type	Default	Description
sessionId	string	required	セッション ID
offset	number	0	末尾からスキップする行数（0 = 最新）。ページネーションに使用します。
maxLines	number	200	返す最大行数
format	string	"lines"	応答形式：lines または text

戻り値：lines または text に加えて、totalLines、returnedFrom、returnedTo

terminal_retry

同じターミナルセッションで、コマンドが成功するか再試行回数を使い切るまで再試行します。

Param	Type	Default	Description
sessionId	string	required	セッション ID
command	string	required	実行するコマンド
maxRetries	number	3	初回実行後の再試行回数
backoff	string	"exponential"	バックオフ方式：fixed、linear、exponential
delayMs	number	1000	基本待機時間（ミリ秒）
timeout	number	30000	1 回の試行あたりのタイムアウト（ミリ秒）
maxLines	number	200	1 回の試行あたりの最大出力行数
successExitCode	number or null	0	成功とみなすために必要な終了コード
successPattern	string or null	null	出力に一致する必要がある任意の正規表現

戻り値：success、attempts、lastResult、history

terminal_diff

同じターミナルセッションで2つのコマンドを実行し、それらの出力の範囲を制限した統合差分を返します。

Param	Type	Default	Description
sessionId	string	required	セッション ID
commandA	string	required	基準コマンド
commandB	string	required	比較コマンド
timeout	number	30000	コマンドごとのタイムアウト（ミリ秒）
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	必須	セッション ID（作業ディレクトリの解決に使用）
path	string	必須	ファイルパス（セッションの CWD からの相対パス、または絶対パス）
content	string	必須	書き込むファイルのコンテンツ
encoding	string	"utf-8"	ファイルのエンコーディング（utf-8、ascii、base64、hex、latin1）
append	boolean	false	ファイルを上書きせず、追記します

戻り値：success、path（絶対パス）、size（バイト数）、append

terminal_watch

セッションの出力で 1 つ以上のトリガーパターンが現れるまで待機します。最初の一致、静寂の検出、タイムアウト、またはプロセスの終了時に戻ります。手動でのポーリングループに代わるもので、イベントが発生するまで 1 回の呼び出しで待機します。

Param	Type	Default	Description
sessionId	string	必須	セッション ID
triggers	array	必須	トリガーオブジェクト（1～10 個。以下を参照）
timeout	number	60000	ハードタイムアウト（ミリ秒、最大 1 時間）
quietExitMs	number	--	N ミリ秒間出力がない場合に戻ります
contextLines	number	3	一致箇所の前に含めるコンテキスト行数
since	number	--	このバイト位置以降の出力のみを照合します

トリガーオブジェクト：

Field	Type	Default	Description
id	string	必須	応答で返されるラベル
pattern	string	必須	正規表現またはリテラルパターン
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 } }

2 つのコマンド出力を比較する

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>

サポート対象のパーサーによる解析に成功した場合に stdout.raw を省略するには、parseOnly: true を設定します。サポート対象外のコマンドでは、引き続き stdout.raw が返され、stdout.parsed は null になります。

サポート対象のコマンドシグネチャで stdout.summary を返し、stdout.raw を省略するには、summary: true を設定します。サマリーを利用できない場合は、raw stdout が保持されます。

terminal_run_paged は、読み取り専用コマンドで summary: true をサポートしています。対象は git（branch、diff、log、ls-files、remote、rev-parse、status）、tasklist、where、which です。

解析が要求されているものの、該当するパーサーが見つからない場合、terminal_run は、raw 出力が大きい、パーサーの追加が有用なコマンドシグネチャについて、短い hint を含めることがあります。

• 現在は git と where / which のみが対象です
• コマンドが成功し、提案する価値があるほど stdout.raw が大きい場合に限ります
• 文言：Structured parser unavailable for this command signature. If you need this often, propose one.

ライセンス

MIT