safe-workspace-mcp

最小限かつセキュリティ重視の MCP サーバーで、1つのローカルワークスペースへの構造化された読み書きアクセスを提供し、ローカル Git チェックポイントとロールバックを内蔵しています。

チャットモデル（例: MCP 対応の ChatGPT）が1つのプロジェクトフォルダ内のファイルを安全に編集し、それ以外には触れないように設計されています。

Windows ポータブル クイックスタート（Python / Git / Node 不要）

1. リリース から Windows リリース ZIP をダウンロードして解凍します。

2. ワークスペースディレクトリ（サーバーが触れてよい唯一のフォルダ）を準備します。

3. OpenAI の Secure MCP Tunnel ID（ここで作成）と Runtime API Key（ここで作成）を取得します。

4. 解凍したフォルダ内で次を実行します:

.\Start-SafeWorkspaceMCP.ps1 -Workspace "D:\ChatGPT_Workspace\demo" -TunnelId "tunnel_..."

5. プロンプトが表示されたら Runtime API Key を入力します（非表示入力、保存されません）。

6. ターミナルは開いたままにします。Ctrl+C ですべて停止します。

7. ChatGPT の Developer Mode から既存トンネルに接続します — これは自分で行うアカウント側の手順です。

ランチャーは初回実行時に公式の OpenAI トンネルクライアント（固定 v0.0.11、SHA-256 検証済み）をダウンロードし、%LOCALAPPDATA%\SafeWorkspaceMCP\ 配下にキャッシュします。管理者権限は不要で、PATH やレジストリも変更しません。詳細は ZIP 内の README-PORTABLE.md\ を参照してください。

正確な説明: Python/Git/Node のインストールを必要としないポータブルなローカル展開で、ランチャーがテスト済みの OpenAI トンネルクライアントを自動的にブートストラップします。 「ゼロ構成」ではありません。ワークスペース、トンネル ID、ランタイムキー、ChatGPT のアカウント側セットアップは自分で用意します。

Related MCP server: git-mcp-server

概要

• 1プロセス = 1構成 = 1つの固定ワークスペース（起動時に選択され、実行時には不変）

• 原子的な複数ファイルトランザクションを備えた構造化テキストファイル CRUD

• 楽観的並行性: 既存ファイルの変更には常にその現在の sha256 が必要

• 管理されたローカル Git 履歴（Dulwich 経由、git.exe は使用しない）: 変更前後のチェックポイント、差分、履歴、復元

• stdio MCP サーバー、合計9ツール

非目標（明確に非対応）

シェルなし、ターミナルなし、サブプロセスなし、コード実行なし、コンパイラ/テストランナー/パッケージマネージャーなし、任意の HTTP やネットワークツールなし、リモート Git なし、ワークスペース切り替えなし、バイナリ/画像編集なし、OS サンドボックスを主張しない。

以下に列挙されていない機能は、このサーバーにはありません。

アーキテクチャ

ChatGPT / any MCP client
        │
OpenAI Secure MCP Tunnel (account-side, outbound-only)
        │
tunnel-client.exe            <- external deployment layer (official OpenAI binary,
        │                       pinned + SHA-256 verified by the launcher)
        │ MCP over stdio (child process)
        ▼
Safe Workspace MCP           <- this project (9 tools, no network, no exec)
        │
   fixed single workspace
        │
   ┌────┴─────────────┐
   │                   │
structured file CRUD   managed local Git checkpoints

• Web 検索や URL 取得はチャットホスト自身が行います。このサーバーは設計上、ネットワーク機能を持ちません。

• トンネルクライアントは外部のデプロイコンポーネントであり、このサーバーの一部ではありません。サーバープロセス自体はソケットを開かず、ランチャーの唯一のネットワークアクティビティは、固定されチェックサム検証された公式トンネルクライアントのダウンロードのみです。

9つのツール

apply_changes の操作はすべて最初に検証されます（パス、ハッシュ、ポリシー、プランの競合）。何かが失敗した場合、何も適用されません。実行途中で失敗した場合はすべてロールバックされます。

インストール

サポートされている2つの方法:

• エンドユーザー（Windows）: ポータブルリリース ZIP をダウンロード — Python/Git/Node は不要（上記クイックスタート参照）。

• 開発者 / Linux: Python 3.12+ でのソースチェックアウト:

git clone https://github.com/Xs-trek/safe-workspace-mcp.git
cd safe-workspace-mcp
py -3.12 -m venv .venv
.venv\Scripts\pip install -e .

ランタイム依存関係: mcp==2.0.0（公式 SDK）、dulwich==1.2.6、Python 標準ライブラリのみ。その他はありません。ポータブルリリースのエンドユーザー前提条件は以下のみです: Windows 10/11、PowerShell、トンネル用のインターネット、ワークスペースフォルダ、トンネル ID + Runtime API Key、そしてご自身の ChatGPT アカウント設定。

設定

TOML ファイル。起動時に一度だけ読み込まれ、その後は不変です。実行時に構成、ワークスペースルート、または任意の制限を変更できるツール（およびコードパス）はありません。

[workspace]
root = "D:/ChatGPT_Workspace/demo"
max_file_bytes = 2097152        # largest file the server will write/track
max_read_bytes = 1048576        # largest read returned / searched per file
max_transaction_bytes = 10485760
max_search_results = 200
excluded = ["node_modules", "build", "dist", ".venv"]  # plus built-ins

[paths]
reject_reparse_points = true    # symlinks/junctions/mounts: always recommended
reject_hardlinks = true
require_same_filesystem = true

[write]
allow_create_file = true
allow_modify_file = true
allow_delete_file = true
allow_move = true
allow_create_directory = true
allow_delete_empty_directory = true
require_expected_hash = true

[git]
mode = "managed"                # only mode in v0.1.0
author_name = "Safe Workspace MCP"
author_email = "safe-workspace-mcp@local"

[search]
include_hidden = false

[server]
transport = "stdio"             # only transport in v0.1.0

最小構成 / 既存ソース / 大規模ソースの各バリアントは examples/ を参照してください。

管理対象ワークスペース

空またはプレーンなソースディレクトリ（.git なし）での初回起動時に、サーバーは:

1. ディレクトリをスキャンし（通常のテキストファイルのみ追跡）、

2. <root>/.git に管理対象リポジトリを初期化し、

3. initial snapshot チェックポイントを作成します。

ワークスペースに既に .git が含まれている場合、起動は EXISTING_GIT_REPOSITORY_NOT_SUPPORTED で失敗します。既存リポジトリ、ワークツリー、サブモジュール、リモートの採用は v0.1.0 の対象外です。

編集可能 ⇒ 復元可能: MCP が変更または削除できるすべての通常ファイルは管理対象リポジトリで追跡されるため、常にチェックポイントから復元できます。除外されたディレクトリ（node_modules、ビルド成果物、virtualenv など）はすべてのツールから見えません — 読み取り不可、書き込み不可、検索不可、チェックポイント対象外です。

実行

.venv\Scripts\safe-workspace-mcp path\to\config.toml

サーバーは stdio 上で MCP を話し、ログを stderr に出力します。ワークスペースルートが存在しないか安全でない場合、起動を拒否します。

複数プロジェクト

1つのプロセスは正確に1つのワークスペースを提供します。複数の構成で複数のプロセスを実行します:

safe-workspace-mcp project-a.toml
safe-workspace-mcp project-b.toml

既存ソースのインポート

workspace.root を .git のない既存ソースディレクトリに指定します。初期スナップショットが現在の状態をベースラインとしてコミットし、以後そのディレクトリは管理対象になります。大きな生成ディレクトリは excluded に追加してください。

ポータブル利用シナリオ（Windows）

• 新しい PC での初回実行: ZIP を解凍し、ワークスペースを作成/選択し、ランチャーを実行し、トンネル資格情報を提供します。ランチャーは固定されたトンネルクライアントを自動的にダウンロードして検証します。

• 2回目以降の実行: 同じランチャーを使用し、キャッシュされたトンネルクライアントが再利用されます — 再ダウンロードも再インストールもありません。

• プロジェクトの切り替え: 同じリリースで、異なる -Workspace パスを使用します。各 MCP プロセスは依然として正確に1つの固定ワークスペースを提供します（実行時切り替えなし）。

• オフラインインストール（上級者向け）: 公式の tunnel-client-<version>-windows-<arch>.zip を自分で事前ダウンロードし、公式の SHA256SUMS.txt に対して検証し、展開した公式の tunnel-client.exe を -TunnelClientPath に指定します。これは上級者向けのオペレーターオーバーライドです。ランチャーの固定 SHA-256 保証をスキップします（存在確認と --version は引き続きチェックされます）。通常の使用では不要です。

MCP Inspector を使ったテスト

npx @modelcontextprotocol/inspector .venv\Scripts\safe-workspace-mcp -- args/config.toml

（または MCP SDK CLI の mcp dev。）tools/list が正確に9つのツールを表示すること、読み取り専用の注釈が正しいことを確認し、使い捨てワークスペースに対して read → search → apply_changes → git_diff/git_history/git_restore を最初に実行してください。

ChatGPT Desktop / ChatGPT Web への接続

ChatGPT は OpenAI の Secure MCP Tunnel（Developer Mode / コネクタ）を通じてローカル MCP サーバーに到達します。このプロジェクトは stdio サーバーとオペレーターが実行するランチャーのみです — トンネルトランスポート、OAuth、資格情報の保存は含まれておらず、ChatGPT/Codex 構成を読み書きすることもありません。

推奨フロー:

1. 使い捨てワークスペースでローカルテストスイート全体に合格する（上記参照）。

2. OpenAI Platform で Secure MCP Tunnel を作成し、そのトンネル ID を使ってポータブルランチャーを実行します（または tunnel-client run を自分で実行）。

3. ChatGPT で、ランチャーのターミナルが起動している間に、既存トンネルを開発者/アプリコネクタとして接続します。

4. 最初に専用のテストワークスペースを使用し、その後構成を実際のプロジェクトに切り替えます。

ChatGPT は常に UI で手動設定してください。

セキュリティ概要

• ワークスペース閉じ込め — ワークスペース相対パスのみ許可。トラバーサル、絶対/ドライブ/UNC パス、予約済みデバイス名、ADS コロン、末尾のドット/スペース名はすべて拒否。封じ込めはファイルシステムを考慮した（realpath ベース）ものであり、文字列プレフィックスではありません。

• リンク — 既存パスの任意のコンポーネントにある再解析ポイント（シンボリックリンク、ジャンクション、マウント、不明なタグ）⇒ 拒否。ハードリンクされた通常ファイル（st_nlink > 1）⇒ 拒否。

• 内部分離 — .git はすべてのファイルツールからアクセス不可です。管理対象 Git ストアのみが触れます。

• 原子的書き込み — 一時ファイルを同じディレクトリに作成 → fsync → 検証 → os.replace。書き込みが失敗しても元のファイルが切り詰められることはありません。

• 楽観的並行性 — 古い expected_sha256 ⇒ HASH_MISMATCH。ユーザーの新しいファイルが上書きされることはありません。

• 実行なし / ネットワークなし — 本番コードにはサブプロセス/ソケットの使用がありません（テストで AST により全モジュールのインポートと呼び出しをスキャンして強制）。dulwich の無条件フック実行パスはインポート時に無効化され、仕込まれたフックファイルで回帰テストされています。管理対象リポジトリにフック、フィルター、リモートが追加されることはありません。

• リソース制限 — ファイル/読み取り/トランザクションの最大バイト数と検索結果数を設定。制限に達するとフェイルクローズします。

• プロンプトインジェクション — 解決はされておらず、封じ込めのみ: 誤誘導されたモデルが実行できるのは、1つのフォルダ内での構造化されたチェックポイント付きファイル編集のみで、常にロールバック可能です。

完全な分析と残存リスクについては SECURITY.md と THREAT_MODEL.md を参照してください。

既知の制限事項（v0.1.0）

• テキスト（UTF-8）ファイルのみ。バイナリファイルは拒否されます。

• Windows が主要なセキュリティ対象です。Linux はサポートされ、CI でテストされています。

• ハッシュチェック以外の複数クライアント同時調整はありません（ライターは1つで実行してください）。

• チェックポイント履歴は無制限に増加します（v0.1.0 では gc なし）。

• 復元はファイルレベルです。除外されたディレクトリは復元によって変更されません。

セキュリティ報告

公開 issue ではなく、非公開のセキュリティアドバイザリ（GitHub の "Report a vulnerability"）を開いてください。

ライセンス

Apache-2.0 — LICENSE を参照してください。