Serial Bridge

Serial Bridgeは、ローカルのOperatorとMCPエージェントの間で2つのシリアルコンソールを共有するHubです。OS固有ではありません。requirements.txt のPythonパッケージをインストールし、Python 3.10以降が動作する任意のホストで実行できます。Hubは serial_bridge/ パッケージ内にあります。python -m serial_bridge またはルートの app.py シムで起動します。

インストールと起動

Python 3.10以降を推奨します。

python -m pip install -r requirements.txt
python -m serial_bridge

以下のシェルスニペットはPowerShell（$env:NAME = "..."）を使用します。bashまたはzshでは、同じ名前を export NAME=... で設定してください。

Hubはリッスンを開始すると、ブラウザでコンソール http://127.0.0.1:8765/ を開きます。ルートの app.py シムも同様です。ブラウザタブを開かずに起動するには:

$env:SERIAL_BRIDGE_OPEN_UI = "off"
python -m serial_bridge

または --no-open-ui を渡します。環境が無効にしている場合は、--open-ui で強制的に開きます。SERIAL_BRIDGE_OPEN_UI が未設定の場合はデフォルトで開きます。0、false、no、off（大文字小文字を区別しない）のみが無効にします。

初回起動時に、Hubはポートバインディング設定ファイルの隣にある serial_bridge.token にアクセストークンを自動生成します（パスは SERIAL_BRIDGE_TOKEN_FILE で上書きできます）。シークレットファイルをコミットしないでください。

Hubホストで セットアップ（http://127.0.0.1:8765/setup）を開くと、Hub URLのコピー、アクセストークンの表示、ローテーション、Cursorの mcpServers スニペットの貼り付けができます。セットアップのシークレット（トークン平文、Rotate、シークレットを含むスニペット）は、ループバック（127.0.0.1 / ::1）でのみ表示されます。

あるいは、Hubを起動する前に SERIAL_BRIDGE_TOKEN を設定し、同じシークレットをMCPクライアントに渡します。この環境変数は、そのプロセスの間、シークレットファイルよりも優先されます。Rotateは依然としてファイルを書き換えますが、環境変数が未設定になるか、Hubが環境変数なしで再起動されるまで警告します。

MCP認証はループバックからでも必要です。トークンをソース管理、静的フロントエンドファイル、URL、ログに置かないでください。

Hubは 0.0.0.0:8765 で待ち受けるため、ローカルネットワークから到達可能です。適切なホストファイアウォールと強力なトークンを使用してください。リモートのエージェントはモードやポートバインディングを変更できません。

MCP

コピーペースト用のCursor設定は、Hubホストの セットアップ（/setup）を使用します。手動設定は次のとおりです:

エージェントのStreamable HTTP MCP接続を次のように設定します:

URL: http://<hub-host>:8765/mcp
Authorization: Bearer <SERIAL_BRIDGE_TOKEN>

/mcp を正確に使用してください。Web UIは / にあります。MCPサーバーは次を公開します:

• serial_status: 現在のモードと各ターゲットのポートバインディング、オープン状態、ビジーヒントを読み取ります。

• serial_exec: 1つのテキストコマンドを送信し、アイドルギャップ、任意のプロンプト一致、または60秒のタイムアウトまで出力をキャプチャします。

• serial_send: 出力を待たずにテキスト行またはRaw Payloadを送信します。

ステータスとExecを試すには:

1. ローカルでWeb UIを開き、ブリッジモードに切り替えます。

2. MCPクライアントを上記のURLにBearerヘッダー付きで接続します。

3. 引数なしで serial_status を呼び出し、mode が bridge であり、目的のターゲットが開いていることを確認します。

4. {"target":"linux","cmd":"uname -a"} または {"target":"rtos","cmd":"help"} を指定して serial_exec を呼び出します。

5. デバイスに安定したプロンプトがある場合は、任意で prompt を渡します。prompt_is_regex は、プロンプト値が正規表現の場合にのみ true に設定します。

Execは、シリアルデバイス名ではなく、ターゲット名 linux と rtos を受け入れます。キャプチャされた output と、timed_out、truncated、aborted フラグを返します。

Execの出力と live/*.log のトランスクリプトは、ANSIエスケープが除去されたプレーンテキストです。Web UIは代わりにエスケープを解釈し、デバイスの色を表示します。

ポートバインディング

ポートバインディングは、ターゲットをシリアルデバイスパスとボーレートに割り当てます。組み込みのデフォルトはWindowsスタイルです（linux は COM3、rtos は COM6、両方とも115200）。LinuxまたはmacOSでは、代わりに /dev/ttyUSB0 などのパスを設定します。

起動前に環境変数でデフォルトを上書きします:

$env:SERIAL_BRIDGE_LINUX_PORT = "COM8"
$env:SERIAL_BRIDGE_LINUX_BAUD = "57600"
$env:SERIAL_BRIDGE_RTOS_PORT = "COM9"
$env:SERIAL_BRIDGE_RTOS_BAUD = "115200"
python -m serial_bridge

同等のCLIフラグは、--linux-port、--linux-baud、--rtos-port、--rtos-baud です。SERIAL_BRIDGE_CONFIG または --config は、永続化されたJSONファイルを選択します。読み込み順序は、組み込みデフォルト、次に環境/CLI値、その後に永続化されたファイルです。保存されたWeb UIの値が優先されます。

ポートバインディングを編集できるのはオペレーターのみで、かつHubがポートを解放している CRTモード のときだけです。Web UIは、検出されたシリアルポートをターゲットごとのドロップダウンに一覧表示します。アダプターを接続した後は、スキャン を使用して再列挙します。Web UIで行った変更は再起動後も保持されます。

ライブディレクトリ

ライブディレクトリは、Hubがターゲットごとのブリッジセッションログと bridge_status.json を書き込む場所です。デフォルトはプロジェクトルートの隣の <app-dir>/live/ です（serial_bridge.json とルートの app.py シムと同じディレクトリ）。

起動前に次で上書きします:

$env:SERIAL_BRIDGE_LIVE_DIR = "D:\logs\serial-bridge"
python -m serial_bridge

または --live-dir を渡します。読み込み順序はポートバインディングと同じです。組み込みデフォルト、次に環境/CLI、その後に永続化された設定ファイルです。Web UIの保存が優先されます。

オペレーターが ブリッジモード に入るたびに、Hubは <TargetName>-YYYY-MM-DD-HHMMSS.log という名前の新しいログファイルを作成します（ローカル時刻、24時間制）。2回目のブリッジセッションでは新しいファイルが作成されます。古いログはそのまま残り、ライブディレクトリを変更したりターゲット名を変更したりしても移行されません。

ライブディレクトリを編集できるのは、Web UIのバインドパネルで CRTモード のときだけです（ポートバインディングと同じループバックのみの書き込みパス）。フッターには、設定済みのディレクトリと、割り当てられている場合の現在のセッションログファイル名が表示されます。

ブリッジモードとCRTモード

• ブリッジモード: Hubが設定されたシリアルポートを所有します。オペレーターとエージェントはコマンドを送信し、同じライブトランスクリプトを観察できます。

• CRTモード: HubはSecureCRTまたは他の排他シリアルクライアントのためにポートを解放します。オペレーターがブリッジモードに戻るまで、MCP ExecとSendは失敗します。

ブリッジモードに入る前にSecureCRTを切断してください。CRTモードへの切り替えは、実行中のExecを中止し、部分的な出力を返す可能性があります。

Raw Sendの警告

raw_hex を指定した serial_send は、テキスト行のフレーミングや自動改行なしで任意のバイトを書き込みます。これはコンソールの全機能です。制御バイトは起動を中断したり、プロセスを終了させたり、デバイスの状態を変更したり、セッションを応答不能にしたりする可能性があります。コマンドには serial_exec を使用し、Raw Payloadは正確なバイトシーケンスとデバイスへの影響を理解している場合にのみ使用してください。