🚀 永続的ターミナルMCPサーバー

このサーバーは、強力なModel Context Protocol (MCP) サーバーで、TypeScriptとnode-ptyに基づいて永続的なターミナルセッション管理を実現しています。クライアントが切断されても、ターミナルコマンドは引き続き実行され、Claude、Cursor、ClineなどのAIアシスタントが長時間のタスクを実行するのに特に適しています。

English

YouTube動画: https://youtu.be/nfLi1IZxhJs Bilibili動画: https://www.bilibili.com/video/BV14ksPzqEbM/

Windowsでのmcp設定のビデオチュートリアル: https://youtu.be/WYEKwTQCAnc

✨ 主な機能

🔥 永続的なターミナルセッション

• 長時間実行：長時間実行されるShellセッションの作成、再利用、管理が可能です。
• 切断後の再開：クライアントが切断されてもターミナルは引き続き実行され、再接続後に操作を続けることができます。
• 複数セッション管理：複数の独立したターミナルセッションを同時に管理できます。
• 自動クリーンアップ：タイムアウトしたセッションは自動的にクリーンアップされ、リソースの漏洩を防ぎます。

🧠 スマートな出力管理

• 循環バッファ：サイズを設定可能（デフォルトは10,000行）で、自動的にメモリを管理します。
• 複数の読み取りモード：
  • full：完全な出力を読み取ります。
  • head：先頭のN行のみを読み取ります。
  • tail：末尾のN行のみを読み取ります。
  • head-tail：先頭と末尾を同時に読み取ります。
• 増分読み取り：sinceパラメータを使用して、新しく追加された内容のみを読み取ります。
• トークン推定：出力のトークン数を自動的に推定し、AIがコンテキストを管理しやすくします。

🎨 Spinnerアニメーションの圧縮

• 自動検出：一般的な進行アニメーション文字（⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏, ◐◓◑◒ など）を自動的に検出します。
• スマートなスロットリング：npm install、yarn、pnpmなどのコマンドのノイズ出力を減らします。
• 重要な情報の保持：アニメーションを圧縮する際に、実際のログを保持します。
• 柔軟な設定：環境変数またはパラメータを使用して、オン/オフを制御できます。

🌐 Web可視化管理インターフェース

• リアルタイムターミナル：xterm.jsに基づくターミナルレンダリングで、完全なANSIカラーをサポートします。
• WebSocketプッシュ：ターミナルの出力がリアルタイムに表示され、ページを更新する必要がありません。
• インタラクティブ操作：ブラウザ内で直接コマンドを送信し、出力を確認できます。
• 複数インスタンスサポート：自動的なポート割り当てで、複数のAIクライアントを同時に使用できます。
• VS Codeスタイル：ダークテーマで、シンプルで美しいインターフェースデザインです。

🤖 Codexによる自動バグ修正

• 完全自動化：OpenAI Codex CLIを統合し、コードのバグを自動的に修正します。
• ドキュメント駆動：AIによる説明をMDドキュメントとして保存し、Codexがそれを読み取って修正を行います。
• 詳細なレポート：修正前後の比較を含む完全な修正レポートを生成します。
• スマートな待機：Codexの実行が完了するのを自動的に検出し、デフォルトのタイムアウトは10分です。
• 履歴記録：すべてのバグの説明と修正レポートはdocs/ディレクトリに永久に保存されます。

🔌 複数の統合方法

• MCPプロトコル：Claude Desktop、Claude Code、Cursor、Clineなどのクライアントをネイティブでサポートします。
• REST API：HTTPインターフェースを提供し、非MCPシナリオでの統合を容易にします。
• 厳密な互換性：MCP stdioプロトコル規格に完全に準拠し、stdoutはクリーンです。

🛡️ 安定性の保証

• 出力の安定性検出：wait_for_outputツールを使用して、完全な出力を取得します。
• 対話型アプリケーションのサポート：vim、npm createなどの対話型プログラムを完全にサポートします。
• ANSIエスケープシーケンスの処理：ターミナルの制御文字を正しく処理します。
• エラー回復：自動的な再接続と例外処理メカニズムがあります。

📦 インストール

✅ クイックスタート（推奨）

インストールせずに、npxを使用して直接起動できます。

npx persistent-terminal-mcp

RESTバージョンも同様にサポートされています。

npx persistent-terminal-mcp-rest

📦 既存のプロジェクトに導入

npm install persistent-terminal-mcp

インストール後、コード内ですべてのコアクラスと型を参照できます。

import { PersistentTerminalMcpServer } from "persistent-terminal-mcp";

🌐 グローバルインストール（オプション）

npm install --global persistent-terminal-mcp
persistent-terminal-mcp

💻 使用例

ローカル開発

ソースコードを変更したり、詳細なデバッグを行ったりする場合に適しています。

npm install          # 依存関係のインストール
npm run build        # TypeScriptをdist/にコンパイル
npm start            # stdioを介してMCPサーバーを起動

開発段階では、TypeScriptソースコードを直接実行することもできます。

npm run dev          # MCPサーバー (tsx)
npm run dev:rest     # RESTサーバー (tsx)

🐞 デバッグモード

デバッグログを有効にすると、stderrに出力され、MCP通信に干渉することはありません。

MCP_DEBUG=true persistent-terminal-mcp

📚 サンプルスクリプト

npm run example:basic        # 基本操作：作成 → 書き込み → 読み取り → 終了
npm run example:smart        # スマートな読み取り：head/tail/head-tailモードのデモ
npm run example:spinner      # Spinner圧縮機能のデモ
npm run example:webui        # Web UI機能のデモ
npm run test:tools           # すべてのMCPツールの全量検証
npm run test:fixes           # 重要な修正の回帰テスト

⚙️ MCPクライアントの設定

Claude Desktop

macOS / Linux

設定ファイルの場所: ~/Library/Application Support/Claude/claude_desktop_config.json

設定ファイルに以下の内容を追加します。

{
  "mcpServers": {
    "persistent-terminal": {
      "command": "npx",
      "args": ["-y", "persistent-terminal-mcp"],
      "env": {
        "MAX_BUFFER_SIZE": "10000",
        "SESSION_TIMEOUT": "86400000",
        "COMPACT_ANIMATIONS": "true",
        "ANIMATION_THROTTLE_MS": "100"
      }
    }
  }
}

説明：

• -yパラメータを使用すると、npxのダウンロード確認が自動的に行われます。
• グローバルにインストールした場合（npm install -g persistent-terminal-mcp）、commandを"persistent-terminal-mcp"に変更し、argsから-yを削除できます。

Windows

設定ファイルの場所: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "persistent-terminal": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "persistent-terminal-mcp"],
      "env": {
        "MAX_BUFFER_SIZE": "10000",
        "SESSION_TIMEOUT": "86400000",
        "COMPACT_ANIMATIONS": "true",
        "ANIMATION_THROTTLE_MS": "100"
      }
    }
  }
}

説明：

• Windowsでは、cmd /cを使用してnpxを呼び出す必要があります。
• グローバルにインストールした場合、argsを["/c", "persistent-terminal-mcp"]に変更できます。

Claude Code

macOS / Linux

コマンドラインを使用して迅速に追加できます。

claude mcp add persistent-terminal \
  --env MAX_BUFFER_SIZE=10000 \
  --env SESSION_TIMEOUT=86400000 \
  --env COMPACT_ANIMATIONS=true \
  --env ANIMATION_THROTTLE_MS=100 \
  -- npx -y persistent-terminal-mcp

または、設定ファイル~/.claude.jsonを編集します。

{
  "mcpServers": {
    "persistent-terminal": {
      "command": "npx",
      "args": ["-y", "persistent-terminal-mcp"],
      "env": {
        "MAX_BUFFER_SIZE": "10000",
        "SESSION_TIMEOUT": "86400000",
        "COMPACT_ANIMATIONS": "true",
        "ANIMATION_THROTTLE_MS": "100"
      }
    }
  }
}

Windows

⚠️ Windowsユーザーへの注意

Claude Code はWindowsでclaude mcp addコマンドにパラメータ解析の問題があります。

🚫 コマンドライン方式は推奨されません

専用の設定ドキュメントを参照してください。

📖 《Windowsでのpersistent-terminal MCPの設定》

このドキュメントには2つの推奨される方法が記載されています。

• ✅ プロジェクトレベルの設定（推奨）：プロジェクトのルートディレクトリに.mcp.jsonファイルを作成します。
• ✅ グローバル設定：Pythonスクリプトを使用して~/.claude.jsonを変更します。

Cursor / Cline

設定方法はClaude Desktopと同様です。各クライアントのMCP設定ドキュメントを参照してください。

Codex

macOS / Linux

.codex/config.tomlファイルに以下の設定を追加します。

# MCP Server Configuration (TOML Format)
# 永続的なターミナルMCPサーバーの設定

[mcp_servers.persistent-terminal]
command = "npx"
args = ["-y", "persistent-terminal-mcp"]

[mcp_servers.persistent-terminal.env]
MAX_BUFFER_SIZE = "10000"
SESSION_TIMEOUT = "86400000"
COMPACT_ANIMATIONS = "true"
ANIMATION_THROTTLE_MS = "100"

Windows

.codex/config.tomlファイルに以下の設定を追加します。

# MCP Server Configuration (TOML Format)
# 永続的なターミナルMCPサーバーの設定

[mcp_servers.persistent-terminal]
command = "cmd"
args = ["/c", "npx", "-y", "persistent-terminal-mcp"]

[mcp_servers.persistent-terminal.env]
MAX_BUFFER_SIZE = "10000"
SESSION_TIMEOUT = "86400000"
COMPACT_ANIMATIONS = "true"
ANIMATION_THROTTLE_MS = "100"

説明：Windowsでは、cmd /cを使用してnpxを呼び出す必要があります。

環境変数の説明

変数	説明	デフォルト値
MAX_BUFFER_SIZE	バッファの最大行数	10000
SESSION_TIMEOUT	セッションのタイムアウト時間（ミリ秒）	86400000 (24時間)
COMPACT_ANIMATIONS	Spinner圧縮を有効にするかどうか	true
ANIMATION_THROTTLE_MS	アニメーションのスロットリング時間（ミリ秒）	100
MCP_DEBUG	デバッグログを有効にするかどうか	false
AUTO_START_REST_SERVER	MCP起動時にRESTサーバーを自動的に起動するかどうか	false
REST_HOST	RESTサーバーのリスニングアドレス	localhost
REST_PORT	RESTサーバーのポート	3001
AUTO_START_TERMINAL_UI	REST起動時にWeb UIを自動的に起動するかどうか	true
WEB_UI_HOST	Web UIサーバーのリスニングアドレス	localhost
AUTO_OPEN_BROWSER	Web UIにアクセスするためにブラウザを自動的に開くかどうか	false
WEB_UI_PORT	Web UIサーバーのポート	3000

🚀 サーバーの自動起動設定

環境変数を使用して、サーバーの自動起動とネットワークアクセスを設定できます。

外部アクセスの設定

REST APIとWeb UIを外部ネットワークからアクセスできるようにするには、以下の環境変数を設定します。

# REST APIサーバーを自動的に起動する
AUTO_START_REST_SERVER=true

# REST APIがすべてのネットワークインターフェースをリスニングする（外部アクセスを許可する）
REST_HOST=0.0.0.0

# Web UIを自動的に起動する
AUTO_START_TERMINAL_UI=true

# Web UIがすべてのネットワークインターフェースをリスニングする（外部アクセスを許可する）
WEB_UI_HOST=0.0.0.0

# REST APIのポート（オプション）
REST_PORT=3001

# Web UIのポート（オプション）
WEB_UI_PORT=3000

# ブラウザを自動的に開くかどうか（オプション）
AUTO_OPEN_BROWSER=false

使用例

上記の環境変数を設定すると、MCPサーバーを起動するときに以下のことが行われます。

1. ✅ REST APIサーバーがhttp://0.0.0.0:3001で自動的に起動します。
2. ✅ Web UIがhttp://0.0.0.0:3000で自動的に起動します。
3. ✅ 両方のサービスが外部ネットワークからアクセスできます。
4. ✅ ブラウザを自動的に開くかどうかを選択できます。

クライアントの設定例

環境変数をMCPクライアントの設定に追加します。

Claude Desktopの設定：

{
  "mcpServers": {
    "persistent-terminal": {
      "command": "npx",
      "args": ["-y", "persistent-terminal-mcp"],
      "env": {
        "AUTO_START_REST_SERVER": "true",
        "REST_HOST": "0.0.0.0",
        "AUTO_START_TERMINAL_UI": "true",
        "WEB_UI_HOST": "0.0.0.0",
        "WEB_UI_PORT": "3000",
        "AUTO_OPEN_BROWSER": "false",
        "MAX_BUFFER_SIZE": "10000",
        "SESSION_TIMEOUT": "86400000"
      }
    }
  }
}

Claude Codeの設定：

claude mcp add persistent-terminal \
  --env AUTO_START_REST_SERVER=true \
  --env REST_HOST=0.0.0.0 \
  --env AUTO_START_TERMINAL_UI=true \
  --env WEB_UI_HOST=0.0.0.0 \
  --env WEB_UI_PORT=3000 \
  --env AUTO_OPEN_BROWSER=false \
  -- npx -y persistent-terminal-mcp

🧱 TypeScriptでのプログラム的な使用

import {
  PersistentTerminalMcpServer,
  TerminalManager,
  RestApiServer,
} from "persistent-terminal-mcp";

const manager = new TerminalManager();
const rest = new RestApiServer(manager);
await rest.start(3001);

const mcpServer = new PersistentTerminalMcpServer();
const server = mcpServer.getServer();
await server.connect(/* カスタムトランスポート */);

すべてのコアクラスと型は、パッケージのルートエントリーから取得できます。詳細はsrc/index.tsを参照してください。

🛠️ MCPツール一覧

ツール	説明	主なパラメータ
create_terminal	永続的なターミナルセッションを作成する	shell, cwd, env, cols, rows
create_terminal_basic	シンプルな作成エントリー	shell, cwd
write_terminal	ターミナルにコマンドを書き込む	terminalId, input, appendNewline
read_terminal	バッファ出力を読み取る	terminalId, mode, since, stripSpinner
wait_for_output	出力が安定するまで待つ	terminalId, timeout, stableTime
get_terminal_stats	統計情報を表示する	terminalId
list_terminals	すべてのアクティブなターミナルをリストする	なし
kill_terminal	セッションを終了する	terminalId, signal
open_terminal_ui	Web管理インターフェースを開く	port, autoOpen
fix_bug_with_codex 🆕	Codexを使用して自動的にバグを修正する	description, cwd, timeout

ツールの詳細説明

create_terminal - ターミナルの作成

新しい永続的なターミナルセッションを作成します。

パラメータ：

• shell (オプション): Shellのタイプ、例：/bin/bash、/bin/zsh
• cwd (オプション): 作業ディレクトリ
• env (オプション): 環境変数のオブジェクト
• cols (オプション): ターミナルの列数、デフォルトは80
• rows (オプション): ターミナルの行数、デフォルトは24

戻り値：

• terminalId: ターミナルのID
• status: ステータス
• pid: プロセスID
• shell: Shellのタイプ
• cwd: 作業ディレクトリ

write_terminal - コマンドの書き込み

ターミナルにコマンドまたは入力を送信します。

パラメータ：

• terminalId: ターミナルのID
• input: 送信する内容
• appendNewline (オプション): 改行を自動的に追加するかどうか、デフォルトはtrue

注：デフォルトでは、コマンドを実行するために改行が自動的に追加されます。方向キーなどの生の制御文字を送信する場合は、appendNewline: falseを設定してください。

read_terminal - 出力の読み取り

ターミナルのバッファ出力を読み取り、複数のスマートなトリミングモードをサポートします。

パラメータ：

• terminalId: ターミナルのID
• mode (オプション): 読み取りモード
  • full: 完全な出力（デフォルト）
  • head: 先頭のみを読み取る
  • tail: 末尾のみを読み取る
  • head-tail: 先頭と末尾を同時に読み取る
• since (オプション): N行目から読み取る（増分読み取り）
• maxLines (オプション): 最大行数、デフォルトは1000
• headLines (オプション): headモードの行数、デフォルトは50
• tailLines (オプション): tailモードの行数、デフォルトは50
• stripSpinner (オプション): Spinnerアニメーションを圧縮するかどうか

戻り値：

• output: 出力内容
• totalLines: 総行数
• lineRange: 実際に返された行範囲
• estimatedTokens: 推定トークン数
• truncated: トリミングされたかどうか
• spinnerCompacted: Spinner圧縮が行われたかどうか

wait_for_output - 出力が安定するまで待つ

ターミナルの出力が安定するまで待ってから読み取り、完全な出力を取得します。

パラメータ：

• terminalId: ターミナルのID
• timeout (オプション): 最大待機時間（ミリ秒）、デフォルトは5000
• stableTime (オプション): 安定時間（ミリ秒）、デフォルトは500

使用シナリオ：

• コマンドを実行した後、完全な出力を取得する
• 対話型アプリケーションの起動が完了するのを待つ

fix_bug_with_codex 🆕 - 自動バグ修正

OpenAI Codex CLIを使用して、コード内のバグを自動的に分析して修正します。

パラメータ：

• description (必須): 詳細なバグの説明、以下を含める必要があります。
  • 問題の症状（具体的なエラー動作）
  • 期待される動作（どのように動作するべきか）
  • 問題の位置（ファイルパス、行番号、関数名）
  • 関連するコード（問題のあるコードスニペット）
  • 根本原因（なぜこの問題が発生するのか）
  • 修正提案（どのように修正するか）
  • 影響範囲（他に何に影響するか）
  • 関連するファイル（すべての関連するファイルパス）
  • テストケース（修正が有効かどうかを検証する方法）
  • コンテキスト情報（問題を理解するのに役立つ背景情報）
• cwd (オプション): 作業ディレクトリ、デフォルトは現在のディレクトリ
• timeout (オプション): タイムアウト時間（ミリ秒）、デフォルトは600000（10分）

戻り値：

• terminalId: Codexを実行するターミナルのID
• reportPath: 修正レポートのパス
• reportExists: レポートが存在するかどうか
• workingDir: 作業ディレクトリ
• executionTime: 実行時間（秒）
• timedOut: タイムアウトしたかどうか
• output: ターミナルの出力
• reportPreview: レポートのプレビュー

ワークフロー：

1. AIが詳細なバグの説明を提供する
2. ツールが説明をdocs/codex-bug-description-TIMESTAMP.mdに保存する
3. Codexがドキュメントを読み取り、問題を分析する
4. Codexがバグを修正し、docs/codex-fix-TIMESTAMP.mdにレポートを生成する
5. AIがレポートを読み取り、ユーザーに要約する

重要な注意事項：

• ⚠️ このツールは完全なシステムアクセス権限（danger-full-access）を持っています。
• ⚠️ Codexは任意のファイルを変更できるため、Gitリポジトリで使用することをお勧めします。
• ✅ 英語での説明のみを使用してください（UTF-8エンコーディングの問題を避けるため）
• ✅ 説明が詳細であるほど、修正の質が高くなります。

例：

fix_bug_with_codex({
  description: `Username validation bug in auth.js file.

PROBLEM:
- File: src/auth/login.ts, line 45
- Code: const usernameRegex = /^[a-zA-Z0-9]{3,20}$/
- Symptom: Username 'user_name' is rejected with 'Invalid username' error
- Expected: Should accept usernames with underscores and hyphens

ROOT CAUSE:
- Regex [a-zA-Z0-9] only allows letters and numbers
- Missing support for underscore and hyphen characters

SUGGESTED FIX:
- Change regex to: /^[a-zA-Z0-9_-]{3,20}$/

VERIFICATION:
- Run: npm test
- Expected: all tests pass`,
  cwd: "/path/to/project",
  timeout: 600000,
});

詳細なドキュメント：

• Codex Bug Fix Toolの機能ドキュメント
• Codex Bug Fix Toolのテストレポート

💡 ヒント：Codex CLIにはOpenAI APIのアクセス権限が必要です。国内にいる場合やアクセスに問題がある場合は、Codex CLIミラーサービス（¥99/月、毎日$90のクォータ）を検討してみてください。これにより、AIによるプログラミングがよりスムーズになります。

open_terminal_ui - Web管理インターフェースの開啟

ブラウザベースの可視化ターミナル管理インターフェースを起動します。

パラメータ：

• port (オプション): ポート番号、デフォルトは3002から自動的に検索します。
• autoOpen (オプション): ブラウザを自動的に開くかどうか、デフォルトはtrue

戻り値：

• url: Web UIのアドレス
• port: 実際に使用されるポート
• mode: 起動モード（new/existing）
• autoOpened: ブラウザが自動的に開かれたかどうか

fix_bug_with_codex 🆕 - Codexを使用した自動バグ修正

OpenAI Codex CLIを呼び出して、コード内のバグを自動的に分析して修正し、詳細な修正レポートを生成します。

⚠️ 重要な注意事項：

• このツールは完全な権限モード（--sandbox danger-full-access --ask-for-approval never）を使用します。
• Codexはコードベースを完全に制御できるため、注意して使用してください。
• 使用する前にコードをバックアップするか、バージョン管理を使用することをお勧めします。

パラメータ：

• description (必須): 詳細なバグの説明、以下を含める必要があります。
  • 問題の現象（具体的なエラーの振る舞い）
  • 期待される動作（どのように動作するべきか）
  • 問題の位置（ファイルパス、行番号）
  • 関連するコードスニペット
  • 根本原因（わかっている場合）
  • 修正提案（ある場合）
  • 影響範囲（影響を受ける可能性のある機能）
  • 関連するファイル（すべての関連するファイルパス）
  • テストケース（修正が有効かどうかを検証する方法）
  • コンテキスト情報（問題を理解するのに役立つ背景情報）
• cwd (オプション): 作業ディレクトリ、デフォルトは現在のディレクトリ
• timeout (オプション): タイムアウト時間（ミリ秒）、デフォルトは600000（10分）

戻り値：

• terminalId: Codexを実行するターミナルのID
• reportPath: 修正レポートのパス（docs/codex-fix-TIMESTAMP.md）
• reportExists: レポートが正常に生成されたかどうか
• executionTime: 実行時間
• output: Codexのターミナル出力

ワークフロー：

1. AIアシスタントが詳細なバグ情報を収集する
2. このツールを呼び出し、詳細な説明を渡す
3. Codexが問題を分析し、コードを修正する
4. Codexがdocs/ディレクトリに詳細なレポートを生成する
5. AIアシスタントがレポートを読み取り、ユーザーに報告する

レポートの内容：

• 問題の説明
• 変更されたファイルのリスト
• 各ファイルの具体的な変更（変更前/変更後の比較）
• 変更の理由の説明
• テストの提案
• 注意事項

使用例：

ユーザー：ログイン機能にバグがあり、ユーザー名の検証が常に失敗します。

AIアシスタント：
1. [関連するファイルを確認し、問題を理解する]
2. [fix_bug_with_codexを呼び出す]
   {
     "description": "ログイン機能のユーザー名検証にバグがあり、具体的な症状は以下の通りです。
     1. 問題の現象：ユーザーが 'user_name' を入力すると拒否されます。
     2. 期待される動作：アンダースコアを含むユーザー名を受け入れるべきです。
     3. 問題の位置：src/auth/login.ts の45行目
     4. 関連するコード：const usernameRegex = /^[a-zA-Z0-9]{3,20}$/
     5. 根本原因：正規表現がアンダースコアを許可していません。
     ..."
   }
3. [Codexの完了を待つ]
4. [レポートを読む] view("docs/codex-fix-2025-10-18T00-35-12.md")
5. [ユーザーに修正結果を報告する]

前提条件：

• Codex CLIがインストールされていること：npm install -g @openai/codex-cli
• Codexの認証が設定されていること
• プロジェクトにdocs/ディレクトリが存在すること

ベストプラクティス：

• できるだけ詳細なバグの説明を提供してください（説明が詳細であるほど、修正の質が高くなります）。
• 呼び出す前に関連するファイルを確認し、問題を理解してください。
• 修正後は必ずテストを実行して検証してください。
• 生成されたレポートを確認して、具体的な変更内容を把握してください。
• バージョン管理を使用して、ロールバックを容易にしてください。

🌐 Web管理インターフェース

機能特性

• 📊 ターミナルリスト：すべてのターミナルの状態、PID、Shell、作業ディレクトリなどの情報を表示します。
• 🖥️ リアルタイムターミナル：xterm.jsを使用してターミナルの出力をレンダリングし、ANSIカラーをサポートします。
• ⚡ リアルタイム更新：WebSocketを使用して、ターミナルの出力がリアルタイムに表示されます。
• ⌨️ インタラクティブ操作：ブラウザ内で直接コマンドを送信できます。
• 🎨 VS Codeスタイル：ダークテーマで、シンプルで美しいデザインです。
• 🔄 自動ポート割り当て：複数のインスタンスをサポートし、自動的にポートの衝突を回避します。

クイックスタート

Claudeまたは他のMCPクライアントで以下のように入力します。

ターミナル管理インターフェースを開いてください

または、テストスクリプトを直接実行します。

npm run test:webui

詳細な使用方法はWeb UIの使用ガイドを参照してください。

🔌 REST API（オプション）

HTTPインターフェースが必要な場合は、RESTバージョンを起動できます。

npx persistent-terminal-mcp-rest

サーバーはデフォルトで3001ポートをリスニングします（設定可能）。エンドポイントはMCPツールと1対1で対応しています。

エンドポイント	メソッド	説明
/api/terminals	POST	ターミナルを作成する
/api/terminals	GET	すべてのターミナルをリストする
/api/terminals/:id	GET	ターミナルの詳細を取得する
/api/terminals/:id	DELETE	ターミナルを終了する
/api/terminals/:id/input	POST	コマンドを送信する
/api/terminals/:id/output	GET	出力を読み取る
/api/terminals/:id/stats	GET	統計情報を取得する

📁 プロジェクト構造

persistent-terminal-mcp/
├── src/                    # TypeScriptソースコード
│   ├── index.ts           # MCPサーバーのエントリーポイント
│   ├── mcp-server.ts      # MCPサーバーの実装
│   ├── terminal-manager.ts # ターミナルマネージャー
│   ├── output-buffer.ts   # 出力バッファ
│   ├── web-ui-manager.ts  # Web UIマネージャー
│   ├── web-ui-server.ts   # Web UIサーバー
│   ├── rest-server.ts     # REST APIサーバー
│   ├── types.ts           # 型定義
│   ├── __tests__/         # 単体テスト
│   └── examples/          # サンプルスクリプト
├── dist/                   # コンパイルされたJavaScript
├── public/                 # Web UIの静的ファイル
├── docs/                   # ドキュメント
│   ├── guides/            # 使用ガイド
│   ├── reference/         # 技術リファレンス
│   ├── clients/           # クライアントの設定
│   └── zh/                # 中国語ドキュメント
├── tests/                  # テストスイート
│   └── integration/       # 統合テスト
└── scripts/                # 補助スクリプト

📚 ドキュメントナビゲーション

クイックアクセス

• 📖 完全なドキュメントインデックス
• 🚨 修正ドキュメントインデックス
• 🧪 統合テストの説明
• 🌐 Web UIの使用ガイド

カテゴリ別

• 使用ガイド：使用説明 | トラブルシューティング | MCPの設定
• 技術リファレンス：技術詳細 | ツールの要約
• 修正ドキュメント：Stdioの修正 | Cursorの修正 | ターミナルの修正
• クライアントの設定：Claude Desktop/Code

🔍 重要な注意事項

Stdioのクリーン性

このMCPサーバーはMCPプロトコルに厳密に準拠しており、stdoutにはJSON-RPCメッセージのみが含まれ、すべてのログはstderrに出力されます。これにより、Cursorなどの厳格なクライアントとの完全な互換性が保証されます。詳細はStdioの修正ドキュメントを参照してください。

Cursorの互換性

Cursorおよび他の厳密なJSON-RPC通信を要求するMCPクライアントと完全に互換性があります。迅速な設定方法はクイック修正ガイドを参照してください。

ターミナルの対話性

vim、npm createなどの対話型アプリケーションをサポートし、ANSIエスケープシーケンスを正しく処理します。詳細はターミナルの修正ドキュメントを参照してください。

出力の安定性

wait_for_outputツールを使用して、コマンドを実行した後に完全な出力を取得し、不完全なデータの読み取りを避けてください。

🧪 テスト

テストの実行

npm test                     # すべての単体テストを実行する
npm run test:integration     # すべての統合テストを実行する
npm run test:all            # すべてのテストを実行する

統合テスト

npm run test:integration:stdio      # Stdioのクリーン性のテスト
npm run test:integration:cursor     # Cursorのシナリオテスト
npm run test:integration:terminal   # ターミナル機能のテスト

🤝 コントリビューションガイド

IssueやPRの投稿を歓迎します！詳細な手順とコード規約はCONTRIBUTING.mdを参照してください。

コントリビューションの方法

1. このリポジトリをForkする
2. 機能ブランチを作成する (git checkout -b feature/AmazingFeature)
3. 変更をコミットする (git commit -m 'Add some AmazingFeature')
4. ブランチにプッシュする (git push origin feature/AmazingFeature)
5. Pull Requestを作成する

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。

🙏 謝辞

• node-pty - 強力なPTYライブラリ
• Model Context Protocol - MCPプロトコルの仕様
• xterm.js - 優れたターミナルエミュレータ

📞 サポート

• 📖 ドキュメントを参照する
• 🐛 Issueを投稿する
• 💬 ディスカッションに参加する

---

最終更新: 2025-10-22 バージョン: 1.0.2