tfbash-mcp

Agent システム向けの基本 MCP ツール群です。このプロジェクトは、さまざまな Agent に対して、コマンド実行、ファイルの読み書きと検索など、安定しており、組み合わせ可能で、認知的負荷の低い汎用能力を提供することを目指しています。具体的な能力については、成熟した実装の再利用を優先し、既存のソリューションが中核となる制約を満たせない場合にのみ、適合または自社開発を検討します。

現在のステータス：Python プロジェクトのスケルトンと要件/アーキテクチャ RFC。リポジトリから空の stdio MCP Server を起動することはできますが、 RFC で定義されている Shell ツールはまだ提供されていません。

なぜこのプロジェクトを作るのか

Agent は、プレーンテキストでの推論だけに留まらず、実際のワークスペースを操作したり、ローカルプログラムを呼び出したりする必要が頻繁にあります。プログラマーは Shell を主要な作業インターフェースとして使用します。一方、プロダクト、オペレーション、リサーチなどの一般的な職種でも、Shell を介してスクリプトの呼び出し、ファイル変換、データのバッチ処理、環境の診断を行います。

既存の MCP ツールは、能力範囲と実行モデルが大きく異なります。ワンショットコマンドのみをサポートするもの、PTY や常駐デーモンに依存するもの、承認機能やサンドボックスを内蔵するもの、堅牢な長時間コマンド・増分出力・管理されたプロセスクリーンアップを欠くものなどがあります。tfbash-mcp は、まず実シナリオと検証可能な能力契約を定義し、その上で直接採用、ラッピングによる適合、あるいは自社開発を決定します。

Related MCP server: MCP Terminal Tool Server

設計原則

• シナリオ優先、選定は後：特定の言語・フレームワーク・既存プロジェクトへの習熟度から要件を逆算しない。

• 再利用優先：選定の順序は Adopt → Wrap → Build。再利用は、重要な動作を満たすことを前提とする。

• 小さく直交：基本ツールは明確な境界を保ち、Agent のオーケストレーション、ビジネスワークフロー、UI をツール層に押し込まない。

• 明示的な状態：長時間タスク、永続 Shell、出力カーソル、終了ステータス、リソースのライフサイクルはすべて観測可能であること。cwd/env の保持が必要な Shell は、明示的に作成し、アドレス指定しなければならない。

• プロトコルは実装言語から独立：ツール契約は Python、pexpect、Computer、クライアントの内部概念を公開しない。V1 では Python + pexpect と stdio トランスポートを使用する。

• デプロイ環境を信頼：第一段階では approval、sandbox、コマンドポリシー、ディレクトリ境界を内蔵しない。

• リソースの制御：メモリ、ディスク、セッション、プロセス、一時ファイルには明確な上限・所有権・クリーンアップルールが必要。

第一段階：Bash ツール

第一段階は、Unix 環境（Linux、macOS）向けの独立した汎用 Bash MCP Server に焦点を当てます。対象は以下を同時にカバーします：

• プログラマーによるビルド、テスト、コード検索、サービス起動、ログ観察；

• 一般的な職種がインストール済み CLI やスクリプトを介して行うファイル処理、データ変換、環境診断；

• それぞれが cwd、環境、アクティベート状態を保持する、複数のアドレス指定可能な永続 Command Shell。各コマンドに対して正確な終了ステータスを返す；

• pexpect PTY の stdout/stderr を combined output として返し、実行ごとに有界な増分出力を維持する；

• 短いコマンドは shell_exec で一度に返す。長いコマンドが yield_ms を超えた場合は running を返し、元の Shell で実行を継続する；

• 長いコマンドは shell_read で出力を増分読み取りし、shell_write で stdin に書き込み、shell_signal で中断または終了する；

• 永続 Command Shell は、作成・実行・増分読み取り・書き込み・シグナル・列挙・クローズをサポートし、独立したバックグラウンド Job と Terminal のツールグループは公開しない；

• Shell と Execution は MCP サービスプロセスに帰属し、ツール呼び出しをまたいで保持されるが、サービス再起動をまたいだ復旧は保証しない；

• 1 つの tfrobot-client Computer は、SDK が管理する 1 つの MCP プロセスに対応し、クライアントは有効化スイッチと実行状態のみを保持する。

第一段階の永続 Shell では PTY を使用しますが、コマンド指向のテキストストリームのみを提供し、フルスクリーン TUI の画面モデル、生のターミナル Session、resize は提供しません。今後、xterm.js、REPL、フルスクリーン TUI の明確な統合先が現れた場合は、同じ Shell リソースモデル上に Terminal mode を追加します。また、コマンド承認、プロセスサンドボックス、サービス再起動をまたいだ復旧、MCP Tasks との強結合は含みません。

関連ドキュメント：

• 汎用 Bash MCP Server の要件とアーキテクチャ説明：独立した MCP 境界、ツール契約、ide4ai の再利用範囲、SDK/クライアントの責務、受け入れ基準を定義します。

計画中の基本機能

現在のロードマップは探索の順序を示すものであり、自社開発を決定したことを意味するものではありません：

1. 永続 Shell と長時間コマンド Execution；

2. ファイルの読み取り、書き込み、パッチ形式での変更；

3. ファイルの発見とテキスト検索；

4. 実際の Agent ワークフローに基づいて追加される、その他の小型基本ツール。

各機能は、まず独立した要件と候補調査をまとめ、Adopt・Wrap・Build のいずれかの判断根拠を記録する必要があります。機能ごとに採用元が異なっても構いません。ただし、Agent に公開されるエラーモデル、ライフサイクル、結果構造は一貫している必要があります。

リポジトリ構成

.
├── .github/workflows/tests.yml  # Python 3.10–3.12 CI
├── pyproject.toml               # 包元数据、依赖与工具配置
├── src/tfbash_mcp/              # MCP Server 包与入口
├── tests/                       # 自动化测试
├── README.md
├── docs/
│   └── bash-tool-requirements.md
└── reference/
    ├── ide4ai/                   # pexpect 持久 Shell 基线
    ├── codex/                    # 进程生命周期参考
    ├── pi/                       # Agent Shell 参考
    └── deepseek-harness/         # Agent Runtime 参考

reference/ はローカル調査用のチェックアウトディレクトリで、規模が大きく複数のサードパーティ Git リポジトリを含むため、 tfbash-mcp のバージョン管理や配布パッケージには含めません。

ローカル開発

このプロジェクトは Python 3.10–3.12 をサポートし、環境管理には uv を使用します：

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest --cov

現在の stdio Server スケルトンを起動します：

uv run tfbash-mcp

このプロセスは現在 Shell ツールを登録せず、パッケージ・エントリポイント・MCP stdio のライフサイクルを検証するためだけに使用します。

意思決定への参加

要件ドキュメントは現在、V1 の複数 Shell + Execution ツールモデルと Python/pexpect 実装ベースラインを確定していますが、まだ実装待ち・受け入れ待ちの RFC です。開発に入る前に、少なくとも以下が必要です：

1. ドキュメント内の必須条件と未決事項を整合させる；

2. 選定した pexpect ベースラインに対して最小限の実現可能性実験を実施する；

3. ide4ai のコード抽出について、ライセンス保持方法、適合コスト、長期メンテナンス範囲、撤退戦略を確認する；

4. 実験結果と最終実装の乖離を RFC に反映してから、コーディングと受け入れに進む。