pty-mcp-server

pty-mcp-server

---

⚠️ 注意

AI に無制限の制御権を与えないでください。
監視なしでの使用や誤用は、意図しない結果を招く可能性があります。
すべての AI システムは、厳格な人間の監督と制御の下に置く必要があります。
十分な認識を持ち、自己責任で適切に使用してください。

---

📢 お知らせ

サーバーをアップグレードする際は、pty-mcp-server.yaml が常に最新バージョンであることを確認してください。古い設定ファイルを使用すると、互換性の問題や実行エラーが発生する可能性があります。

---

📘 概要

pty-mcp-server は、AI エージェントが PTY（疑似端末）セッションや、エージェント向けのプロセス、ファイルシステム、ソケット、シリアルインターフェースを動的に制御できるようにする、Haskell 製の MCP（Model Context Protocol）サーバーです。ターミナル経由および直接 I/O インターフェースを通じて、実際のシステム環境とやり取りできます。

このサーバーは 標準入出力（stdio） のみで通信するため、MCP クライアントと簡単かつ安全に統合できます。このインターフェースを通じて、AI エージェントはコマンドの実行、外部エンドポイントとのデータ交換、システム状態の取得、設定の適用を、人間の監督の下で行えます。

---

🎯 目的

• AI エージェントに TTY ベースおよび直接 I/O による制御機能を提供します
• CLI ツールを使用した 設定、検査、操作の自動化を可能にします
• システム開発、診断、リモート操作のための AI 主導のワークフローを支援します
• 静的スクリプトや API では到達できない システムへのアクセスと操作を AI エージェントに可能にします
• 対話型または状態を保持するターミナルワークフローが必要な Infrastructure as Code（IaC） のシナリオをサポートします
• 異種環境やレガシーシステム間の システム統合を支援します
• 人間のようなターミナル操作を必要とするツールを実行することで、DevOps、IaC、統合パイプラインを支援する AI エージェントを実現します

---

🔧 使用例

• PTY 環境が必要な CLI ツールの動的な実行
  （例：シリアル接続や SSH ベースのターミナルを介した組み込みシステム）
• REPL の自動化：GHCi やその他の CLI ベースの対話型インタープリターを操作します
• Haskell アプリケーションやシェルベースのワークフローの 対話型デバッグ
• スクリプト化または対話型の bash セッションによる システム診断
• SSH を使用した リモートサーバーの管理
• エージェント向け MCP ツールを通じた プロセス、ソケット、シリアル、ファイルシステムの直接操作
• 非対話型スクリプトでは CLI の動作を再現できない場合の システムの実地操作
• ネットワーク機器とのやり取り：コンソール経由でルーター、スイッチ、機器を設定します
• AI 支援による IaC ワークフロー：プロンプト、状態の調整、リアルタイム入力を伴う Terraform、Ansible、シェルベースのデプロイスクリプトを実行します
• 複数の環境や CLI ツールにまたがる AI 主導のシステム統合テスト
• GUI/API が利用できず、ターミナル操作のみがサポートされる レガシーシステムの自動化

---

ユーザーガイド（使い方とセットアップ）

機能

pty-mcp-server は、強力で柔軟な自動化を実現するため、以下の組み込みツールを提供します。

利用可能なツール

• agent-proc-run
  指定されたコマンドとオプションで外部プロセスを起動します。プロセスの標準入力／標準出力は接続され、以降の agent-proc-read および agent-proc-write 操作で使用できます。一度に実行できるプロセスは 1 つだけです。

• agent-proc-read
  実行中のプロセスの標準出力から、指定されたバイト数までを読み取ります。利用可能なデータをすぐに返します（ノンブロッキング）。データがない場合は空文字列を返します。

• agent-proc-write
  指定された文字列を実行中のプロセスの標準入力に書き込みます。

• agent-proc-terminate
  現在実行中のプロセスを強制終了します。内部状態をリセットし、再度 agent-proc-run を呼び出せるようにします。

• agent-socket-open 後続の agent-socket-read、agent-socket-write、agent-socket-read-byte、agent-socket-write-byte 操作で使用するソケット接続を開きます。Unix ドメインソケットの場合は file を、TCP ソケットの場合は host と port を指定します。

• agent-socket-close アクティブなエージェントソケット接続を閉じます。

• agent-socket-read アクティブなエージェントソケット接続から指定したバイト数まで読み取り、データを UTF-8 文字列として返します。タイムアウトまでにデータがない場合は空の文字列を返します。

• agent-socket-read-byte アクティブなエージェントソケット接続から指定したバイト数まで読み取り、データを大文字の 16 進数文字列として返します。

• agent-socket-write 指定した UTF-8 文字列をアクティブなエージェントソケット接続に書き込みます。

• agent-socket-write-byte 指定した 16 進数文字列をデコードし、得られたバイト列をアクティブなエージェントソケット接続に書き込みます。

• agent-server-listen 指定した host と port にバインドし、受信 TCP 接続のリッスンを開始して、バックグラウンドの accept スレッドを起動します。リスナーの準備が整うとすぐに返ります。同時にアクティブにできるリスナーは 1 つだけです。

• agent-server-close アクティブな受け入れ済み接続があれば、それを閉じます。アクティブな接続がない場合は、リスナーも閉じます。接続とリスナーの両方を閉じるには、2 回呼び出してください。

• agent-server-status isListening と isConnected のブール値フィールドを含む JSON オブジェクトとして、現在のサーバーの状態を返します。

• agent-server-events 前回の呼び出し以降に蓄積されたサーバー側のイベント（例：ClientConnected、BytesReceived、ClientDisconnected）をすべてキューから取り出して返します。保留中のイベントがない場合は空の配列を返します。

• agent-server-read アクティブな受け入れ済み接続からデータを読み取り、UTF-8 文字列として返します。タイムアウトまでにデータがない場合は空の文字列を返します。

• agent-server-read-byte アクティブな受け入れ済み接続からデータを読み取り、大文字の 16 進数文字列として返します。

• agent-server-write 指定した UTF-8 文字列をアクティブな受け入れ済み接続に書き込みます。注：\r\n は文字としてそのまま送信されます。正しい CRLF を送信するには agent-server-write-byte を使用してください。

• agent-server-write-byte 指定した 16 進数文字列をデコードし、得られたバイト列をアクティブな受け入れ済み接続に書き込みます。16 進数文字列にスペースや改行を含めることはできません。

• agent-serial-open 後続の agent-serial-read、agent-serial-write、agent-serial-read-byte、agent-serial-write-byte 操作で使用するシリアルポート接続を開きます。同時にアクティブにできるポートは 1 つだけです。

• agent-serial-close アクティブなシリアルポート接続を閉じます。

• agent-serial-read アクティブなシリアルポートから指定したバイト数まで読み取り、データを UTF-8 文字列として返します。タイムアウトまでにデータがない場合は空の文字列を返します。

• agent-serial-read-byte アクティブなシリアルポートから指定したバイト数まで読み取り、データを大文字の 16 進数文字列として返します（例：FF0A1B41）。

• agent-serial-write 指定した UTF-8 文字列をアクティブなシリアルポートに書き込みます。

• agent-serial-write-byte 指定した 16 進数文字列をデコードし、得られたバイト列をアクティブなシリアルポートに書き込みます。大文字と小文字のどちらの 16 進数も使用できます（例：FF0A1BFF または 000a1bff）。

• pms-list-dir
  指定したパスにあるディレクトリの内容を一覧表示します。

• pms-make-dir
  指定したパスにディレクトリを作成します。存在しない親ディレクトリも作成されます。

• pms-read-file
  指定したパスにあるファイルの内容を読み取ります。必要に応じて startLine/endLine（1 始まり、両端を含む）を指定し、行の一部の範囲だけを読み取れます。

• pms-write-file
  指定したパスにあるファイルに内容を書き込みます。

• pms-file-info
  ファイルの基本的なメタデータ（総行数とバイトサイズ）を返します。ファイルの規模を把握するため、pms-read-file を使う前に使用してください。また、行数を pms-read-file の部分読み取りと組み合わせて、必要以上に読み込まないようにします。

• pms-grep-file
  POSIX 拡張正規表現に一致する行をファイル内で検索します。一致したオブジェクトの JSON 配列を返します。各オブジェクトには、'line'（1 から始まる行番号）、'text'（一致した行の全内容）、'cols'（その行でパターンが一致した位置を示す、1 から始まる列オフセットの配列）が含まれます。一致する行がない場合は、空の配列を返します。返された行番号を pms-read-file の部分読み取りと組み合わせて使用すると、前後のコンテキストを効率的に取得できます。

• pms-replace-file
  ファイル内の文字列をリテラル置換します。各置換は順番に適用され、その時点で見つかった oldText のすべての出現箇所が newText に置き換えられます。正規表現による置換ではありません。

• pms-patch-file
  指定されたパスのファイルに unified diff 形式のパッチを適用します。パッチは unified diff 形式（例：@@ -1,3 +1,3 @@）である必要があります。成功すると、パッチを適用したファイルのパスを返します。失敗すると、HunkMismatch などのエラーメッセージを返します。注：複数のハンクを使用する場合、各ハンクの行番号（- 側と + 側の両方）には、それ以前のすべてのハンクによる累積行数の差分（追加数から削除数を引いた値）を反映する必要があります。

• socket-open
  指定したホストとポートへのソケット接続を開始します。（非推奨：同等の機能をよりエージェント向けのインターフェースで提供する agent-socket-open と重複しています。）

• socket-close
  このツールは、'socket-open' ツールを使って確立したアクティブなソケット接続を閉じます。（非推奨：同等の機能をよりエージェント向けのインターフェースで提供する agent-socket-close と重複しています。）

• socket-read
  ソケットから指定したバイト数を読み取ります。'size' パラメーターは読み取るバイト数を示します。（非推奨：同等の機能をよりエージェント向けのインターフェースで提供する agent-socket-read-byte と重複しています。）

• socket-write
  一連のバイトをソケットに書き込みます。（非推奨：同等の機能をよりエージェント向けのインターフェースで提供する agent-socket-write-byte と重複しています。）

• socket-message
  このツールは、アクティブなソケット接続を介してメッセージを送信します。（非推奨：同等の機能をよりエージェント向けのインターフェースで提供する agent-socket-write と重複しています。）

• socket-telnet
  TCP ソケットを介して通信する、シンプルな Telnet 風ツールです。指定したホストとポートに接続してデータを送受信し、通信ストリームから Telnet の IAC（Interpret As Command）シーケンスを取り除きます。注：これは簡易的な Telnet 実装であり、Telnet プロトコルのすべての機能をサポートするわけではありません。（非推奨：同等の機能をよりエージェント向けのインターフェースで提供する agent-socket-open、agent-socket-read-byte、agent-socket-write-byte と重複しています。）

• serial-open
  指定したデバイスのシリアルポート接続を、指定したボーレートで開きます。コンソール経由でオンプレミスのハードウェアやネットワーク機器にアクセスする際によく使用されます。（非推奨：同等の機能をよりエージェント向けのインターフェースで提供する agent-serial-open と重複しています。）

• serial-close
  このツールは、'serial-open' ツールを使って確立したアクティブなシリアル接続を閉じます。（非推奨：同等の機能をよりエージェント向けのインターフェースで提供する agent-serial-close と重複しています。）

• serial-read
  シリアルポートから指定したバイト数を読み取ります。'size' パラメーターは読み取るバイト数を示します。（非推奨：同等の機能をよりエージェント向けのインターフェースで提供する agent-serial-read-byte と重複しています。）

• serial-write
  一連のバイト列をシリアル接続に書き込みます。（非推奨：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-serial-write-byte に置き換えられています。）

• serial-message
  指定した文字列をアクティブなシリアル接続に送信し、リモート側から認識可能なプロンプトが返されるまで待機します。プロンプトを検出すると、その前に受信したすべての出力を取得して返します。（非推奨：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-serial-write と agent-serial-read に置き換えられています。）

• pty-bash
  pty-bash は、疑似端末（PTY）で bash シェルを起動するツールです。LLM（MCP クライアント）が対話型端末（PTY）で実際の Linux シェルを操作できるようにします。これにより、AI は人間が操作する場合と同じようにシステムコマンドを実行し、情報を収集し、プロンプトや TUI ベースのツールに対応できます。そのため、Linux ベースの動的な自動化や診断に効果的です。（注：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-proc-run に置き換えられています。）

• pty-ssh
  指定した引数で疑似端末に SSH セッションを確立し、リモートシステムとの対話を可能にします。（注：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-proc-run に置き換えられています。）

• pty-telnet
  疑似端末（PTY）セッション内で telnet コマンドを起動します。これにより、リモート Telnet サーバーと対話し、人間のユーザーと同じように「login:」や「Password:」などのプロンプトに AI が応答できます。多くの Telnet サーバーでは、端末が実際の TTY デバイスのように動作する必要がありますが、PTY 環境によってこれが実現されます。（注：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-proc-run に置き換えられています。）

• pty-cabal
  指定したプロジェクトディレクトリ、メインソースファイル、引数を使って、疑似端末で cabal repl セッションを起動します。（注：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-proc-run に置き換えられています。）

• pty-stack
  指定したプロジェクトディレクトリ、メインソースファイル、引数を使って、疑似端末で stack repl セッションを起動します。（注：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-proc-run に置き換えられています。）

• pty-ghci
  指定したプロジェクトディレクトリ、メインソースファイル、引数を使って、疑似端末で GHCi セッションを起動します。（注：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-proc-run に置き換えられています。）

• pty-connect
  オプションの引数を指定して疑似端末（pty）経由でコマンドを実行し、外部のツールやサービスと対話します。（注：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-proc-run に置き換えられています。）

• pty-message
  pms-messages は、実行中の PTY セッションに構造化された指示やコマンドを送信するツールです。端末への直接入力を抽象化し、LLM（MCP クライアント）が制御されたプログラム可能な方法で PTY プロセスと対話できるようにします。（注：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-proc-write に置き換えられています。）

• pty-terminate
  アクティブな疑似端末（PTY）接続を強制終了します。（注：このツールは、よりエージェント向けのインターフェースで同等の機能を提供する agent-proc-terminate に置き換えられています。）

• proc-cmd
proc-cmd ツールは、Windows コマンドプロンプト（cmd.exe）をサブプロセスとして起動します。AI が標準の Windows シェル環境と対話できるようにし、使い慣れたターミナルインターフェースでバッチコマンドの実行、ファイル操作、システム設定のタスクを行えます。（注：このツールは agent-proc-run と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• proc-ps
proc-ps は Windows PowerShell（powershell.exe）をサブプロセスとして起動します。AI が PowerShell コマンド、スクリプト、システム管理タスクを実行できる、対話型のコマンドライン環境を提供します。シェルは、開いたまま次の入力を受け付けられるよう、既定のオプションで起動します。（注：このツールは agent-proc-run と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• proc-ssh
proc-ssh は、runProcess を使用して SSH クライアント（ssh）をサブプロセスとして起動します。AI が Secure Shell プロトコル経由で他のシステムにリモート接続できるようにします。このツールは、リモートコマンドの実行、リモートシェルへのアクセス、SSH 経由のサービスのトンネリングに使用できます。必須の arguments フィールドで、接続先のユーザー、ホスト、および SSH オプション（例：-p、-i、-L）を指定できます。（注：このツールは agent-proc-run と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• proc-telnet
  PuTTY の plink 実行ファイルを内部で使用して Telnet セッションを実行するツールです。winpty のような外部の疑似端末エミュレーターを必要とせず、Windows で対話型の Telnet 接続を行えます。ユーザーが指定した Telnet コマンドの引数は、セッションを確立するために plink に直接渡されます。（注：plink.exe がシステムの PATH から利用できる必要があります。）（注：このツールは agent-proc-run と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• proc-plink
  コマンドラインの SSH および Telnet クライアントである plink を介して、対話型のコンソールアプリケーションを起動する Windows ツールです。外部の PTY エミュレーターを必要とせず、SSH または Telnet セッションを直接実行するのに適しています。（注：plink.exe がシステムの PATH から利用できる必要があります。）（注：このツールは agent-proc-run と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• proc-spawn
  指定した引数を使って外部プロセスを起動し、標準入力と標準出力を介した対話的な通信を可能にします。PTY ベースの実行とは異なり、疑似端末を割り当てずに runProcess 関数を使ってプロセスと直接通信します。TUI を使わず、標準入力／標準出力ベースで対話するプログラムに適しています。（注：このツールは agent-proc-run と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• proc-message
runProcess で起動したサブプロセスに、構造化されたテキスト形式の指示またはコマンドを送信します。標準入力を介してプロセスと対話するためのプログラム可能なインターフェースを提供します。（注：このツールは agent-proc-write と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• proc-read
  アクティブな PTY セッションから、ブロックせずに利用可能な出力を読み取ります。データがない場合は、空の文字列を返します。（注：このツールは agent-proc-read と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• proc-write
  アクティブな PTY セッションに入力データを書き込み、完了を待たずに直ちに戻ります。（注：このツールは agent-proc-write と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• proc-terminate
runProcess を介して作成された実行中のプロセスを強制終了します。（注：このツールは agent-proc-terminate と重複しており、同等の機能をよりエージェントに適したインターフェースで提供します。）

• スクリプト可能な CLI 統合
pty-mcp-server は、tools-list.json で定義された登録済みツールに関連付けられたシェルスクリプトの実行をサポートします。各ツールは名前で登録する必要があり、設定済みの tools/ ディレクトリに対応するシェルスクリプト（.sh）が存在する必要があります。

  この設計では、予測可能なスクリプトの仕組みを通じてツールインターフェースを公開し、AI 主導のワークフローをサポートします。AI は名前でツールの呼び出しを指示でき、サーバーが実行とやり取りを透過的に管理します。
  新しいツールを追加するには：

  1. tools/ ディレクトリに your-tool.sh という名前のシェルスクリプトを作成します。
  2. "your-tool" という名前と適切なメタデータを指定して、tools-list.json にエントリーを追加します。
  3. サーバーを再コンパイルしたり変更したりする必要はありません。ツールは名前によって動的に解決されます。

  ツール定義（tools-list.json）と実装（tools/your-tool.sh）を分離することで、明確な疎結合を実現し、拡張性を高めます。

注：
pty- で始まるコマンドは Windows ではサポートされていません。これらのツールは POSIX 形式の疑似端末（PTY）に依存しており、Windows 環境ではネイティブに利用できません。

Podman または Docker での実行

Podman または Docker のいずれかを使用して、pty-mcp-server をビルドして実行できます。

注： Docker コンテナ内で pty-mcp-server を実行する場合、pty 接続を確立すると、コンテナ環境内で操作することになります。サーバーとやり取りする際は、この点を考慮してください。

1. イメージをビルドする

リポジトリをクローンし、docker ディレクトリに移動します：

$ git clone https://github.com/phoityne/pty-mcp-server.git
$ cd pty-mcp-server/docker
$ podman build . -t pty-mcp-server-image
$

参照：build.sh

2. コンテナを実行する

コンテナ内でサーバーを実行します：

$ podman run --rm -i \
--name pty-mcp-server-container \
-v /path/to/dir:/path/to/dir \
--hostname pms-docker-container \
pty-mcp-server-image \
-y /path/to/dir/config.yaml
$

参照：run.sh

以下は、VSCode 内で MCP サーバーを実行するための mcp.json の設定例です：

{
  "servers": {
    "pty-mcp-server": {
      "type": "stdio",
      "command": "/path/to/run.sh",
      "args": []
      /*
      "command": "podman",
      "args": [
        "run", "--rm", "-i",
        "--name", "pty-mcp-server-container",
        "-v", "/path/to/dir:/path/to/dir",
        "--hostname", "pms-docker-container",
        "pty-mcp-server-image",
        "-y", "/path/to/dir/config.yaml"
      ]
      */
    }
  }
}

バイナリのインストール

自分でビルドする場合は、以下の要件を満たしていることを確認してください：

• GHC >= 9.6

cabal を使用して pty-mcp-server をインストールできます：

$ cabal install pty-mcp-server

.dxt パッケージによるインストール

あらかじめパッケージ化された .dxt ファイルを使用してツールをセットアップすることもできます。
この方法は、Claude Code にすばやくインストールする場合や、展開して手動でセットアップする場合に適しています。

🛠️ .dxt パッケージの配布は現在 準備中です。
最新の状況とダウンロードリンクは、以下で確認できます：
https://github.com/phoityne/pms-dxt

バイナリの実行

pty-mcp-server アプリケーションはコマンドラインから実行します。

使用方法

$ pty-mcp-server -y config.yaml

サーバーはコマンドラインから直接起動できますが、通常は Visual Studio Code などの MCP クライアントを統合した開発ツールによって起動・管理されます。これらのツールはサーバーを利用し、PTY セッションを介した対話的かつ自動化されたコマンド実行を可能にします。

VSCode との統合：.vscode/mcp.json

Visual Studio Code 内での開発とサーバーの起動を効率化するため、このプロジェクトでは .vscode/mcp.json 設定ファイルをサポートしています。

このファイルでは、開発環境で pty-mcp-server をどのように起動するかを定義します。設定例：

{
  "servers": {
    "pty-mcp-server": {
      "type": "stdio",
      "command": "pty-mcp-server",
      "args": ["-y", "/path/to/your/config.yaml"]
    }
  }
}

config.yaml の設定（参照）

• logDir:
  ログファイルの保存先ディレクトリのパスです。標準出力／標準エラーのログと、スクリプトの実行ログが含まれます。

• logLevel:
  ログレベルを設定します。例として "Debug"、"Info"、"Error" があります。

• toolsDir:
  スクリプトファイル（ツール名をファイル名とするシェルスクリプト。例：ping.sh）を格納するディレクトリです。ここにツール名と一致するスクリプトが存在する場合、ツールの呼び出し時に実行されます。
  このディレクトリには、利用可能な公開ツールとそのメタデータを定義する tools-list.json ファイルも配置する必要があります。

• prompts:
  対話型コマンドのプロンプトを検出するためのプロンプト文字列のリストです。これにより、AI はコマンドが入力待ちの状態かどうかを識別できます。例として "ghci>"、"]$"、"password:" などがあります。

• allowedAgentCmds:
  agent-proc-run での使用が許可されるコマンドのホワイトリストです。このリストが空の場合（デフォルト）、すべてのコマンドが拒否されます。ここに明示的に記載されたコマンドのみ実行が許可されます。

---

デモ

pty-mcp-server を使用して AI がバイナリプロトコルの対話を処理

参照： socket-telnet-prompt

この動画では、socket-telnet-prompt.md で定義された MCP プロンプトを利用した Telnet ログインの流れを紹介します。socket-open、socket-read、socket-write、socket-message などのツールを使用して、AI が Telnet のネゴシエーションを行い、プロンプトに応答し、認証情報を送信します。バイナリ応答は解析され、人が読める形式で表示されます。

pty-mcp-server によるシリアル接続を介したネットワーク機器のバージョン確認

参照： serial-nw-setting-prompt

この動画では、pty-mcp-server によって、ネットワーク機器へのシリアル接続を介した AI 支援の自動化が可能になる様子を紹介します。

1. 機器の設定 ユーザーが通信ポートとボーレートを指定します。
   例： Windows では COM3、9600 baud。

2. ログイン操作 AI がユーザー名とパスワードの入力を求め、
   それらを使ってネットワーク機器にログインします。

3. 機器バージョンの取得 ログイン後、AI がコマンドを送信して、
   インストールされている OS またはファームウェアのバージョンを取得します。

4. 最新バージョンのオンライン確認 AI が公式ウェブサイトにアクセスして最新のバージョンを確認し、
   インストール済みのバージョンと比較します。

5. セッションの終了 確認が完了すると、AI がログアウトし、シリアル接続を適切に閉じます。

デモ：AI がゼロから Web アプリを作成して起動する様子

参照：Web サービス構築エージェントのプロンプト

1. [シーン 1：概要と MCP の設定]
   このデモでは、pty-mcp-server を使って、AI エージェントが Docker コンテナ内で Web サービスを構築し、実行する方法をご紹介します。
   まず、シェルスクリプトを使って MCP サーバーを起動するように mcp.json を設定します。
   このスクリプトは、PTY ベースの操作を行う Docker コンテナを起動します。

2. [シーン 2：Docker の起動設定]
   run.sh スクリプトでは、ボリュームのマウントやホスト名の設定を行い、ポート 8080 を公開します。
   これにより、コンテナからホストシステムに Web サービスを公開できます。

3. [シーン 3：MCP サーバーの起動]
   コンテナが起動し、その中で pty-mcp-server が実行されています。
   疑似端末を介して AI 主導のリクエストを処理する準備が整いました。

4. [シーン 4：AI エージェントの接続]
   チャットインターフェースを開き、Web サービス構築エージェント向けに設計されたプロンプトを送信します。
   AI は PTY を介してコンテナの Bash セッションに接続し、準備を開始します。

5. [シーン 5：初期設定コマンド]
   プロンプトに従い、AI は次の操作から始めます。

   • プロジェクトフォルダーを作成する
   • 作業ディレクトリに移動する

6. [シーン 6：AI が指示を受け取る準備を完了]
   環境の準備が整ったら、AI に「Hello, world」を表示する Web サービスを構築するよう指示します。
   ここから AI による自律的な構築プロセスが始まります。

7. [シーン 7：AI が Web サービスの設定コマンドを実行]
   AI が一連のターミナルコマンドを提案します。
   ユーザーとして、それらを 1 つずつ確認して承認します。
   手順は次のとおりです。

   • Python がインストールされているか確認する
   • Flask をインストールする
   • 「Hello, world」を表示するためのソースコード（app.py）を記述する
   • Flask サーバーを実行する
   • コンテナ内で curl http://localhost:8080 を使ってテストする

8. [シーン 8：コンテナ外からの確認]
   外部からアクセスできることを確認するため、ホストから ポート 8080 経由でサービスにアクセスします。予想どおり、応答は 「Hello, world」 です。

9. [シーン 9：実行履歴の確認]
   最後に、AI の操作を順を追って確認します。

   • Bash セッションを初期化し、作業ディレクトリを作成した
   • Python 環境を設定した
   • Flask ベースの app.py を生成した
   • Web サーバーを起動し、動作を検証した

10. [シーン 10：まとめ]
    これは、AI が PTY-MCP-Server と Docker を組み合わせることで、
    対話的に、インテリジェントに、そして再現可能な形で、実際の開発タスクを自動化できることを示しています。

デモ：Docker 実行とホストへの SSH アクセス

1. Docker を使用した MCP の設定
   これは mcp.json ファイルです。MCP サーバーの起動設定を定義します。この場合、pty-mcp-server はシェルスクリプト run.sh を使用して起動されます。このスクリプトは Podman を使用してコンテナーを起動します。
2. MCP サーバーの起動
   こちらが run.sh スクリプトです。正しいボリュームマウント、ホスト名、イメージタグを指定して、podman run を使用して Docker コンテナーを起動します。実行すると、コンテナー内で MCP サーバーが起動します。
3. ツール一覧
   次に、クライアントに公開するツールの一覧を tools-list.json で定義します。 pty-message、pty-ssh、hostname.sh という名前のシェルスクリプトの 3 つのツールが含まれています。
4. ツールスクリプトのディレクトリ
   config.yaml で、スクリプトディレクトリへのパスを定義します。 hostname.sh などのツールスクリプトはここに配置します
5. ホスト名スクリプト
   hostname.sh スクリプトは hostname コマンドを実行するだけです。 コンテナー内でツールとして実行されます。
6. チャットから hostname を実行
   では、チャットで hostname ツールを実行してみましょう。 現在のホスト（コンテナー）の名前が表示されます。
   想定どおり、出力は次のとおりです：pms-docker-container これにより、コマンドが Docker コンテナー内で実行されていることを確認できます。
7. pty-ssh を使用したホストへのアクセス
   次に、pty-ssh を使用してホスト OS との pty セッションを確立します。 Docker ホストに解決される host.docker.internal を使用して SSH 接続を試みます。
   ホストの識別情報を確認してパスワードを入力すると、ログインに成功します。
8. ホスト環境の確認
   ホストに接続したので、次を実行します：cat /etc/redhat-release
   これにより、現在 CentOS 9 のホスト OS 上にいることを確認できます。
   一方、Docker コンテナーでは AlmaLinux 9 が実行されています。

デモ：PTY 経由の対話型 Bash

1. mcp.json で bash-mcp-server を設定
   このファイルで、bash-mcp-server を MCP サーバーとして登録します。
   コマンドに pty-mcp-server を指定し、引数として設定ファイル config.yaml を渡します。
2. config.yaml の設定
   config.yaml ファイルでは、ログディレクトリ、ツール用ディレクトリ、プロンプト検出パターンを定義します。
   これらの設定により、AI が PTY 経由で Bash とやり取りするための環境が整います。
3. toolsDir に tools-list.json を配置
   toolsDir で指定したディレクトリに tools-list.json を配置する必要があります。
   このファイルでは、pty-bash や pty-message など、AI が利用できるツールを宣言します。
4. AI が Bash に接続し、コマンドを自律的に選択
   AI は疑似端末を介して Bash に接続し、
   状況に応じて実行するコマンドを決定します。
5. コマンド実行結果の確認
   getenforce コマンドの出力により、SELinux が Enforcing モードかどうかが分かります。
   この結果は端末またはログに表示されるため、ユーザーはシステムの状態を確認できます。

デモ：シェルスクリプトの実行

1. mcp.json の設定
   stdio モードで pty-mcp-server を起動し、引数として config.yaml を渡します。
2. config.yaml の概要
   ログディレクトリ、ツールディレクトリ、プロンプト文字列を指定します。
   toolsDir 内の tools-list.json で、公開するツールを定義します。
3. tools-list.json の役割
   利用可能なスクリプトツールを一覧表示します。ここでは script_add ツールのみを登録しています。
4. tools フォルダーの役割と命名規則
   MCP サーバー経由で呼び出す実行可能なシェルスクリプトを格納します。
   tools-list.json 内のツール名は、このフォルダー内のシェルスクリプトのファイル名と一致します。
5. VSCode GitHub Copilot から実行
   #script_add 2 3 コマンドで script_add.sh を実行し、加算を行います。
6. 結果の確認
   「5」が返され、処理が成功したことを示します。

デモ：cabal repl による Haskell のデバッグ

参照：haskell cabal debug prompt

1. 対象コードの概要
   MyLib.hs 内の関数を選択し、cabal repl と AI 駆動のデバッグインターフェースを使用して実行時の状態を調べます。
2. MCP サーバーの初期化
   AI とデバッグコマンド間の構造化されたやり取りを可能にするため、MCP サーバーを起動します。
3. デバッガーのプロンプトと環境の設定
   AI はプロンプトを受け取り、cabal repl を起動してモジュールを読み込み、実行時の調査に備えます。
4. デバッグの開始
   対象の関数を実行し、実行時の状態を観察できるよう、あらかじめ定義された地点で一時停止します。
5. 状態の調査と出力
   ロジックの検証や内部動作の観察に役立つよう、実行時の値と制御フローを表示します。
6. まとめ
   pty-msp-server との統合により、Haskell アプリケーションの実行時の状態を自動的に調査できます。

---

アーキテクチャガイド（ソフトウェアアーキテクチャと技術的詳細）

アーキテクチャ戦略

pty-mcp-server プロジェクトのアーキテクチャは、中規模から大規模のシステムを念頭に設計されています。特に、複数のチームや組織が関わる環境において、モジュール性、保守性、スケーラビリティを重視しています。

これらの目標を達成するため、システムは適切に分離された複数のパッケージで構成され、それぞれが特定の関心事やドメインを担当します。このパッケージ指向の設計には、いくつかの戦略的なメリットがあります。

パッケージ全体の構造は オニオンアーキテクチャの原則に従っており、ドメインモデルを中核に置くレイヤード設計を採用しています。さらに、各パッケージ内の内部モジュール構造もレイヤーアプローチに基づいており、純粋なデータ定義、ドメインサービス、インフラストラクチャの関心事を明確に分離しています。

依存性注入機構としての pty-mcp-server の役割

REPL との通信を管理するだけでなく、pty-mcp-server は単なる実行可能モジュールではなく、システム全体の依存性注入機構としても機能します。

• 依存先を含む、関連するすべての PMS パッケージを参照できます。
• これにより、複数のパッケージやモジュールにまたがるアプリケーションコンポーネントを、統一された方法で構築し、接続できます。
• 依存関係の解決を一元化することで、pty-mcp-server は横断的な依存関係を単一の場所で制御できるようにし、システムアーキテクチャの可視性と制御性を高めます。

その結果、パッケージ間およびモジュール間の依存関係を一元的に調整、管理できるようになり、システム全体のカプセル化、再利用性、テスト容易性が向上します。

依存関係

このパッケージは、以下のパッケージに依存しています。

• pms-ui-request
• pms-ui-response
• pms-ui-notification
• pms-infrastructure
• pms-infra-cmdrun
• pms-infra-procspawn
• pms-infra-agent-process
• pms-infra-agent-socket
• pms-infra-agent-server
• pms-infra-agent-serial
• pms-infra-serial
• pms-infra-socket
• pms-infra-watch
• pms-infra-filesystem
• pms-application-service
• pms-domain-service
• pms-domain-model

パッケージを分割する理由

• 明確なインターフェース定義
  各パッケージは、最小限かつ明確に定義された公開 API のみを公開します。これにより、モジュールの境界が明確になり、コンポーネント間で意図しない依存関係が生じるのを抑えます。

• チームとベンダーの所有権
  大規模なプロジェクトでは、異なるチームや外部ベンダーが特定のパッケージを所有できます。明確な分離によって責任範囲が定義され、組織の境界を越えた協調的な開発が可能になります。

• リポジトリとリリースの独立性
  パッケージを個別のリポジトリに分割し、それぞれ独立してバージョン管理できます。これにより、モジュール単位での開発と柔軟なリリースワークフローが可能になり、ビルド時間を短縮して統合を簡素化できます。

• 保守性と拡張性の向上
  関心事を分離することで、コード変更の影響を関連するモジュールに限定できます。これにより、リグレッションを最小限に抑え、安全で段階的な改善を継続しやすくなります。

想定されるユースケース

• 複数の開発者やチームが関わる中規模から大規模のエンタープライズシステム
• コンポーネントごとに独立した開発サイクルとリリースサイクルを持つモジュール型システム
• 長期的な保守性、拡張性、関心事の分離が求められるプロジェクト

このアーキテクチャでは、階層化されたモジュール型のアプローチを採用しています。ドメインモデル、ドメインサービス、アプリケーションロジック、インフラストラクチャに関する関心事をそれぞれ独自のパッケージにカプセル化することで、責任の分離を維持しながら、明確に構成できます。

デプロイ図

パッケージ構成

スレッド構成

背景

pty-mcp-server の階層型モジュールアーキテクチャは、Core Projection Architecture (CPA) の基礎となった元のケーススタディです。

---