WorkspaceGuard MCP

WorkspaceGuard MCP は、ローカルで動作するクロスプラットフォームの MCP サーバーで、ChatGPT または MCP クライアントが指定されたワークスペース上で操作できるようにします。このプロジェクトは FileMCP の調査後に新規構築され、有用なセキュリティ原則を維持しつつ、最初のバージョンではまだ不要な部分を削減しています。

何に使うのか？

• ファイル単位または行単位での一覧表示・読み取り、ファイル名検索・内容検索。

• アトミック方式でのファイル書き込み。dry_run と expected_sha256 をサポートし、より新しい変更の上書きを防止。

• 「削除」は .workspaceguard/trash への移動で行い、手動で復元可能。

• シェルを有効にせずに Git の status、log、diff を読み取り。

• オプションで program + args によるターミナル実行。シェルを介した文字列連結は行わず、allowlist 内の実行可能ファイルのみ許可。

• stdio またはトークン付き 127.0.0.1 上の MCP Streamable HTTP で利用可能。

• ファイル内容やコマンドの全パラメータを保存しない監査 JSONL を記録。

Related MCP server: Kastor

主な改善点

ワークスペースの選択、モードの選択、コマンド allowlist の選択、サーバーの起動/停止、アプリ内での MCP テスト、Secure MCP Tunnel への接続ができる Electron デスクトップインターフェースを備えています。FileMCP の方針に従い、アプリはセッションごとに新しいループバックトークンを生成し、サーバーを 127.0.0.1 に維持し、tunnel-client のライフサイクルを管理し、Runtime API キーを OS の暗号化メカニズム（macOS では利用可能な場合 Keychain）で保存します。tunnel-client バイナリは引き続きユーザーが OpenAI からダウンロードします。プロジェクトはそのバイナリを同梱しません。ローカルランタイムとトンネルは Codex や OpenAI のモデル/API を呼び出しません。開発者モードアプリ経由で ChatGPT Web とともにアプリを使用するため、Codex のクォータは消費しません。会話は引き続き使用中の ChatGPT プランの制限に従います。

要件

• Node.js 20 以上（Node.js 24 でテスト済み）。

• git_* ツールを使用する場合は Git。

• ChatGPT の場合: カスタム MCP アプリをサポートするワークスペース、Secure MCP Tunnel、適切なトンネル権限を持つ runtime API キー。OpenAI Secure MCP Tunnel を参照。

ステップごとの実行

ステップ 1 — 依存関係のインストール

cd "/Users/danhpham/Documents/ChatGPT/MCP"
npm install

API キーを .env に入れたり、Git にコミットしたりしないでください。

ステップ 2 — プロジェクト全体のテスト

npm run verify

このコマンドは、typecheck、ユニット/統合テスト、本番ビルド、MCP stdio 経由のセマンティックスモークテストを実行します。

ステップ 3 — デスクトップインターフェースの実行（最も簡単な方法）

npm run desktop

WorkspaceGuard ウィンドウで:

1. フォルダを選択… を押し、テスト用のワークスペースを選択します。

2. 初回使用時は読み取り専用のままにします。

3. MCP を起動を押します。ステータスが実行中に変わると、HTTP サーバーは 127.0.0.1:<ポート> で準備完了です。

4. 終了したら停止を押します。アプリを閉じるとサーバーとトンネルの両方が停止します。

インターフェースは HTTP トークンを表示または保存しません。トークンは起動のたびにメインプロセスで新しく生成されます。

インターフェース内での MCP 全体のテスト

サーバーが実行中を表示したら、MCP テストを実行を押します。これは Electron メインプロセス内の実際の MCP クライアントであり、インターフェースを介した偽のテストではありません。

• 読み取り専用の場合、アプリは MCP HTTP ハンドシェイク、ツール探索、workspace_info、list_files をテストします。

• 読み取りと書き込みの場合、アプリはさらに write_file → read_file → trash_path をテストします。ランダムな名前のテストファイルが .workspaceguard/trash に移動されるため、確認のチェックを入れる必要があります。

• コマンド実行の場合、allowlist で node のチェックを維持し、アプリが node --version による run_command をさらにテストできるようにします。

最後の 2 つのモードには別のテスト用ディレクトリを選択してください。各ステップの結果はインターフェースのテストセクションにすぐに表示されます。

ステップ 4 — ターミナルでコアをビルド（オプション）

npm run build

本番エントリポイントは次のとおりです:

/Users/danhpham/Documents/ChatGPT/MCP/dist/index.js

ステップ 5 — ターミナルでワークスペースとモードを選択（オプション）

小さなテスト用ディレクトリから始めることをお勧めします:

mkdir -p /tmp/workspaceguard-demo
printf 'Xin chào MCP\n' > /tmp/workspaceguard-demo/hello.txt

3 つのモード:

• read-only: ファイル読み取りと Git 読み取りのツールのみ。これがデフォルトです。

• workspace-write: write_file と trash_path を追加。

• command: 書き込み権限と run_command を追加。

注意: サーバーは 3 つのモードすべてで内部監査を .workspaceguard/audit.jsonl に書き込み続けます。「読み取り専用」は公開ツールを説明するものであり、サーバープロセス自体のファイルシステムサンドボックスではありません。

ステップ 6A — stdio 経由での実行（推奨）

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode read-only

ターミナルは MCP クライアントが stdin 経由でリクエストを送信するのを待ちます。これは正しい動作であり、フリーズではありません。

ステップ 6B — 書き込み権限の有効化

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode workspace-write

trash_path はデフォルトで dry_run=true です。呼び出し元が dry_run=false を送信した場合のみ、パスはゴミ箱に移動されます。

ステップ 6C — ターミナルコマンドの自動実行を許可

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode command \
  --allow-command git,node,npm,npx

ツール入力の例:

{
  "program": "npm",
  "args": ["test"],
  "cwd": "",
  "timeout_seconds": 120
}

run_command はシェルを使用しませんが、OS サンドボックスではありません。node、npm、Python、または許可された実行可能ファイルは、ワークスペース外の読み取り/書き込み、ネットワークの使用、現在のアカウントの権限での他のプロセスの実行が可能です。コマンドモードは信頼できるワークスペースとワークフローでのみ使用してください。

ステップ 7 — Secure MCP Tunnel インターフェースで ChatGPT を接続

OpenAI Platform で、Secure MCP Tunnel と、トンネルを使用する権限を持つ runtime API キーを作成します。OS に適した tunnel-client をダウンロードします。Runtime API キーを Codex に送信したり、.env、ソース、Git に書き込んだりしないでください。

アプリで、MCP が実行中を表示した後:

1. tunnel_... 形式のトンネル ID を貼り付けます。

2. Runtime API キーを貼り付けます。次回は空のままにして、暗号化して保存されたキーを使用できます。

3. バイナリが PATH にある場合は tunnel-client を入力するか、ファイルを選択… を押してダウンロードしたバイナリを選択します。

4. デフォルトのプロファイルを維持し、トンネルに接続を押し、「ChatGPT の準備ができました」という通知を待ちます。

5. 緑色の「ChatGPT の準備ができました」という行がローカル部分の接続を確認します。ChatGPT Web を開くを押します。このアプリは Codex を開いたり呼び出したりしません。

6. ChatGPT のみを切断する場合はトンネルを切断を押します。トンネルと MCP サーバーの両方を停止するには停止を押します。

アプリは tunnel-client init --sample sample_mcp_remote_no_auth → doctor --explain → run の一連のコマンドと同等の処理を実行し、MCP エンドポイントは http://127.0.0.1:<ポート>/mcp、ローカルヘルスエンドポイント、トークンヘッダーは環境変数で渡されます。トンネルプロファイルはワークスペースではなく、アプリの専用データに保存されます。

ChatGPT Web で、ワークスペースのポリシーに従って Developer Mode/カスタム MCP アプリを有効にし、新しいアプリを作成し、トンネル接続を選択し、作成したトンネルを選択し、ツールをスキャンを実行してから、書き込みツールを有効にする前に workspace_info、list_files、read_file を試してください。トンネルオプションが表示されない場合は、ワークスペースに読み取り権限とトンネル使用権限が付与されているか確認してください。

ステップ 8 — HTTP ループバック（オプション）

export WORKSPACE_MCP_TOKEN="$(openssl rand -hex 32)"

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport http \
  --mode read-only \
  --port 7331

ヘルスチェック:

curl --fail http://127.0.0.1:7331/healthz

MCP リクエストは次のヘッダーを送信する必要があります:

X-Workspace-MCP-Token: <WORKSPACE_MCP_TOKEN>

HTTP サーバーは 127.0.0.1 のみにバインドし、Host、Origin、トークン、基本的なフレーミング、ボディサイズ制限をチェックします。特定の HTTP ニーズがない場合は stdio を使用してください。

利用可能なツール

常に利用可能

• workspace_info

• list_files

• read_file

• read_file_range

• search_filenames

• search_content

• git_status

• git_log

• git_diff

モード workspace-write または command

• write_file

• trash_path

モード command のみ

• run_command

ゴミ箱に入れたファイルの復元

ツールは trashPath を返します。ローカルコマンドで復元します。例:

mv "/tmp/workspaceguard-demo/.workspaceguard/trash/<id>/remove-me.txt" \
  "/tmp/workspaceguard-demo/remove-me.txt"

WorkspaceGuard は、意図しないデータ削除を避けるため、このバージョンではゴミ箱を自動的にクリーンアップしません。

構造

src/
├── config.ts                 # CLI/env và mode
├── security/path-policy.ts   # containment + sensitive-path policy
├── services/files.ts         # file/search/write/trash
├── services/git.ts           # Git read-only
├── services/process.ts       # process limits + tree cleanup
├── tools.ts                  # MCP schemas, annotations, audit
├── server.ts                 # stdio + HTTP loopback
├── desktop/                  # Electron main/preload + renderer an toàn
└── index.ts                  # CLI entry
tests/                        # unit, integration, MCP semantic smoke
docs/                         # phân tích source và lộ trình

追加ドキュメント

• 元の FileMCP プロジェクトの分析

• プロジェクト構築のステップとロードマップ

• セキュリティモデル

ライセンスと参考ソース

このプロジェクトは Apache License 2.0 を使用しています。FileMCP も Apache-2.0 を使用しています。参考設計のソースについては NOTICE を参照してください。tunnel-client バイナリは含まれていません。オペレーターは公式の OpenAI ソースから適切なバージョンをダウンロードします。