MCP ToolHub

MCP ToolHub は、ワークスペースに制限されたファイルシステム操作、読み取り専用の Git 検査、構造化されたコマンド実行、および監査証跡を公開する、ローカルで stdio のみの Model Context Protocol サーバーです。ファイルシステムを変更する操作と、エージェントが選択したすべての外部シェルコマンドは、既存の帯域外の人間による承認モデルを使用します。

ToolHub は、HTTP、SSE、その他のネットワークリスナーを公開しません。

機能

• ワークスペースに制限されたファイル読み取り、ディレクトリ一覧、書き込み、パッチ

• 読み取り専用の Git ステータスおよび差分操作

• デフォルト拒否のリスク分類を備えた構造化シェルコマンド

• 原子的で、有効期限付き、一度きりの承認リクエスト

• 分離された信頼済み管理者 CLI。MCP 自己承認ツールなし

• 制限付きで機密情報が編集された JSON Lines 監査イベント

• Windows および POSIX のサポート

Related MCP server: enterprise-agent-lab

要件

• Python 3.12 以降 (CI は現在 3.12 と 3.13 を検証しています)

• stdio サーバーをサポートする MCP クライアント

• Git ツールおよび承認ゲート付き Git シェルリクエスト用の git

インストール

ソースチェックアウトから uv でインストールします:

uv tool install .

または、ホイールをビルドしてインストールします:

uv build
uv tool install dist/mcp_toolhub-0.1.0-py3-none-any.whl

インストールでは 2 つの実行可能ファイルが提供されます:

• mcp-toolhub — stdio MCP サーバー

• mcp-toolhub-admin — 信頼済みの人間による承認 CLI

ランタイム設定

ワークスペースルート

TOOLHUB_WORKSPACE_ROOT は、mcp-toolhub serve と管理 CLI に必要です。既存のディレクトリへの絶対パスを含む必要があります。ToolHub はパスを一度正規化し、プロセスの生存期間中固定します。

ToolHub は意図的に、カレントディレクトリ、ソースチェックアウト、インストールディレクトリをデフォルトにしません。

信頼済み状態ルート

TOOLHUB_STATE_ROOT はオプションで、workspace-binding.json、approvals.json、audit.jsonl を含むディレクトリを選択します。指定する場合は絶対パスである必要があります。このディレクトリは、最初の有効な使用時に、正確に 1 つの正規ワークスペースへ恒久的にバインドされます。別のワークスペースで再利用するとフェイルクローズします。

TOOLHUB_STATE_ROOT が設定されていない場合、ToolHub は platformdirs から得られる、プラットフォームに適したユーザーごとの状態ディレクトリをベースとして使用します。各正規ワークスペースは、workspaces/ の下に独立した名前空間を受け取ります。名前は、プラットフォーム正規化された正規ワークスペースパスから導出される決定論的 SHA-256 識別子です。この識別子により、ワークスペースパスがディレクトリ名に含まれることはありませんが、これは認証シークレットではなく名前空間の分離です。ワークスペースを移動または名前変更すると、通常は新しいデフォルト名前空間が作成されます。

状態ディレクトリは必要に応じて作成され、正規化され、ワークスペース設定とともに固定されます。状態ルートがワークスペース内にある場合、起動は失敗します。サーバーと管理 CLI は、この状態を共有するため、同じユーザーとして、同じワークスペースおよび状態構成で実行する必要があります。

POSIX の例

export TOOLHUB_WORKSPACE_ROOT=/home/alice/projects/example
export TOOLHUB_STATE_ROOT=/home/alice/.local/state/mcp-toolhub
mcp-toolhub serve

Windows PowerShell の例

$env:TOOLHUB_WORKSPACE_ROOT = "D:\work\example"
$env:TOOLHUB_STATE_ROOT = "$env:LOCALAPPDATA\mcp-toolhub"
mcp-toolhub serve

サーバーは、バナーや人間向けのログテキストを stdout に書き込みません。stdout は MCP プロトコルメッセージ専用に予約されています。想定される設定エラーは stderr に簡潔に報告され、非ゼロの終了ステータスで終了します。

コマンド

mcp-toolhub --version
mcp-toolhub serve
python -m mcp_toolhub serve

mcp-toolhub-admin --help
mcp-toolhub-admin list
mcp-toolhub-admin approve REQUEST_ID
mcp-toolhub-admin reject REQUEST_ID

管理コマンドは人間向けであり、通常の出力を stdout に書き込む場合があります。これは MCP トランスポートプロセスではありません。

MCP クライアント設定

正確な外側の設定キーはクライアントによって異なります。一般的な POSIX stdio エントリは次のとおりです:

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "/home/alice/projects/example",
        "TOOLHUB_STATE_ROOT": "/home/alice/.local/state/mcp-toolhub"
      }
    }
  }
}

Windows パスには JSON エスケープが必要です:

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "D:\\work\\example",
        "TOOLHUB_STATE_ROOT": "C:\\Users\\alice\\AppData\\Local\\mcp-toolhub"
      }
    }
  }
}

MCP クライアントがシェルの PATH を継承しない場合は、実行可能ファイルの絶対パスを使用してください。

ツール一覧

本番サーバーは、正確に次の 12 個の MCP ツールを公開します:

• toolhub.ping

• toolhub.audit_recent

• filesystem.list_directory

• filesystem.read_file

• filesystem.write_file

• filesystem.write_file_approved

• filesystem.apply_patch

• filesystem.apply_patch_approved

• git.status

• git.diff

• shell.run

• shell.run_approved

MCP の管理、承認、拒否ツールはありません。

人間による承認ワークフロー

1. MCP の変更リクエストまたは外部シェルリクエストが、保留中のリクエスト ID を返します。

2. 管理者は、サーバーと同じワークスペースおよび状態環境で mcp-toolhub-admin list を実行します。

3. 承認のために、管理者は mcp-toolhub-admin approve REQUEST_ID を実行します。

4. CLI は保護されたリクエストを表示し、オペレーターに APPROVE と正確に入力することを要求します。

5. MCP 呼び出し元は、リクエスト ID を指定して対応する _approved ツールを呼び出します。消費の成功は原子的かつ一度きりです。

シェルリクエストの場合、承認表示には、元のプログラム、正規化された解決済み実行可能ファイル、SHA-256、バイトサイズ、cwd、および個別に JSON エスケープされた引数値が含まれます。引数を曖昧なシェルコマンド文字列として表現することはありません。

セキュリティモデルと制限事項

構造化シェルコマンド

shell.run はデフォルト拒否のコマンドポリシーを使用します。LOW は、ToolHub の正確な組み込み機能、現在は実行中の Python バージョンの問い合わせに限定されます。LOW は PATH を検索せず、外部サブプロセスも作成しません。汎用 Git、シェルインタープリター、Windows バッチスクリプト、py ランチャー、および不明なプログラムが LOW になることはありません。

すべての外部シェルコマンドは MEDIUM または HIGH であり、帯域外の管理者承認が必要です。承認は、不変のプログラム、引数、cwd、タイムアウト、ワークスペース、およびプライマリ実行可能ファイルのスナップショットを捕捉します。承認済みシェルリクエストは、スナップショット検証の前に原子的に消費されます。その後のどのような失敗でも永久に消費されるため、再試行には新しい承認が必要です。

subprocess の起動直前に、ToolHub はプライマリ実行可能ファイルの正規パス、サイズ、SHA-256 を検証します。実行は shell=False でその絶対パスを使用します。これは、起動直前における検証済みのプライマリ実行可能ファイルの同一性であり、オペレーティングシステムが最終的にマッピングする正確なバイトの暗号学的保証ではありません。

ToolHub は以下を保証します:

• LOW は外部サブプロセスを作成しません。

• すべての外部シェル実行には MEDIUM または HIGH の承認が必要です。

• エージェントは、承認済みのプログラム、引数、cwd、タイムアウトを置き換えることはできません。

• 承認は原子的、有効期限付き、一度きりです。

• ワークスペースとプライマリ実行可能ファイルのスナップショットが必要であり、フェイルクローズします。

• プライマリ実行可能ファイルの正規の同一性とハッシュは、起動直前に再検証されます。

• ファイルシステムパスは、固定されたワークスペース境界内に留まります。

• 変更パスはシンボリックリンクのたどりを拒否し、該当する場合は expected_hash の並行性チェックを実施します。

ToolHub は以下を保証しません:

• 最後のチェックから実行までの狭い競合ウィンドウ中に、並行するローカルファイルシステム上の敵対者に対する正確なバイト同一性。

• DLL、インタープリター、ヘルパー、プラグイン、設定ファイル、環境によって選択された依存関係、または子孫プロセスの同一性。

• 承認された実行可能ファイルのバイトが無害であること、署名されていること、または信頼できる発行元からのものであること。

管理者の承認表示は、保護された正規パス、ハッシュ、サイズ、cwd、および正確な JSON エスケープ済み引数の境界を公開します。エージェントが読み取り可能な監査イベントは、外部実行可能ファイルのディレクトリを省略し、ベース名、ハッシュ、サイズ、スコープ、およびリクエスト ID の相関を保持します。

監査動作

監査イベントは、信頼済み状態ルートの下の audit.jsonl に追記されます。これらは制限付きメタデータを含み、認識可能なシークレット引数を編集し、生のプロセス出力ではなく stdout/stderr の文字数のみを保存します。監査書き込みの失敗は、ツール実行にとって致命的ではありません。

開発

ロックされたすべてのランタイムおよび開発依存関係をインストールします:

uv sync --all-groups

必要なチェックを実行します:

uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q src/mcp_toolhub
uv run pytest -q
uv build
git diff --check

意図的にフォーマットを適用するには:

uv run ruff format .

アーティファクトのスモークテスト

uv build の後、チェックアウト外の仮想環境でクロスプラットフォームのスモークドライバーを実行します。

POSIX:

uv run python scripts/artifact_smoke.py --dist-dir dist --venv /tmp/mcp-toolhub-wheel-env --repository .

Windows PowerShell:

uv run python scripts/artifact_smoke.py --dist-dir dist --venv "$env:TEMP\mcp-toolhub-wheel-env" --repository .

ドライバーはホイールの内容を検査し、分離環境にホイールのみをインストールし、コンソール/バージョンの動作を検証し、リポジトリ外から initialize、list_tools、ping、設定済みワークスペースアクセス、無効な設定、およびサーバー/管理者の共有状態テストを実行します。

トラブルシューティング

• TOOLHUB_WORKSPACE_ROOT is required: MCP クライアントの環境に、既存の絶対ワークスペースパスを追加してください。

• ワークスペースがディレクトリではありません: ディレクトリを作成するか、パスを修正してください。

• 状態ルートはワークスペース外にある必要があります: TOOLHUB_STATE_ROOT を、MCP ファイルシステムツールがアクセスできない信頼済みディレクトリに移動してください。

• 状態名前空間が別のワークスペースに属しています: 異なる明示的な TOOLHUB_STATE_ROOT を選択してください。バインドが黙って再割り当てされることはありません。

• クライアントが無効な stdio JSON を報告する: ラッパーおよび起動スクリプトがバナーやログを stdout に出力しないことを確認してください。

• 管理者がリクエストを表示できない: サーバーと管理者が、同じユーザーとして、同一のワークスペースおよび状態ルート設定で実行されていることを確認してください。

• 承認後に実行可能ファイルが変更された: 新しい承認をリクエストしてください。消費済みまたは無効化された承認が再生されることはありません。

本番 ToolHub は意図的に、HTTP、SSE、パブリックネットワーク、認証サーバー、コンテナオーケストレーション、またはクラウドホスティングのサーフェスを公開しません。