Project Files Read-only MCP

ローカル・マルチルート・読み取り専用のファイルシステム MCP サービスです。MCP クライアントに対して明示的に登録されたプロジェクトディレクトリのみを公開し、限定されたディレクトリ閲覧、ファイル名検索、テキスト読み取り、および DOCX・PDF・XLSX のコンテンツ抽出機能を提供します。

このサービスは、書き込み・編集・コピー・移動・削除・コマンド実行ツールを登録しません。ChatGPT など MCP 対応クライアントに、少数のローカルプロジェクトファイルを安全に読み取らせたい場合に適しています。ユーザーディレクトリやディスク全体を公開することを避けられます。

これは独立したコミュニティプロジェクトであり、OpenAI の公式製品ではありません。また、OpenAI がその安全性や互換性を保証するものではありません。

プロジェクトのアドレスは github.com/13030109506/project-files-readonly-mcp です。

機能

このサービスは固定で 9 つの読み取り専用ツールを公開します。

すべてのツールは読み取り専用かつ非破壊的とマークされています。統合テストでは、ツールリストに書き込み・削除・移動・コピー・コマンド実行機能が含まれていないことも確認します。

Related MCP server: Local File Management MCP Server

セキュリティ境界

• roots.json に登録された絶対パスのみを受け付けます。

• 語彙パスと realpath の結果の両方で二重の境界チェックを行います。

• 相対パス、UNC パス、デバイスパス、Windows ADS、シンボリックリンク、ジャンクションによる脱出を拒否します。

• デフォルトで .git、.env、資格情報ファイル、秘密鍵、仮想環境、依存関係ディレクトリをブロックします。

• テキスト・ディレクトリ・検索・ドキュメントの応答にはサイズと数の上限があります。

• DOCX・XLSX は解析前に、ZIP パス、エントリ数、展開サイズ、圧縮率、暗号化、マクロ、ActiveX、埋め込みオブジェクトをチェックします。

• バイナリドキュメントは独立した Worker で解析され、時間とメモリの制限が設定されます。

• XLSX の数式は実行されず、外部リンクにはアクセスしません。

より完全な境界の説明は セキュリティモデル を参照してください。これらの保護は MCP の呼び出し面を縮小しますが、Windows アカウントの権限やホストのセキュリティに代わるものではありません。信頼できるコンピュータと MCP クライアント上でのみ本サービスを実行してください。

環境要件

• Windows 10 または Windows 11

• Node.js 22.13–22.x または Node.js 24+

• npm

• オプションの OpenAI tunnel-client。ChatGPT Secure MCP Tunnel に接続する場合のみ必要です。

クイックスタート

プロジェクトをクローンします。

git clone https://github.com/13030109506/project-files-readonly-mcp.git
Set-Location .\project-files-readonly-mcp

依存関係をインストールします。

npm ci

ローカル設定を作成します。roots.json は .gitignore に含まれており、Git にはコミットされません。

Copy-Item .\roots.example.json .\roots.json
notepad .\roots.json

サンプルパスを、許可したい具体的なプロジェクトディレクトリに変更してください。ディスク全体、ユーザーディレクトリ、Desktop、Documents は設定しないでください。

{
  "roots": [
    {
      "name": "my-project",
      "path": "C:\\Projects\\my-project"
    }
  ]
}

テストを実行します。

npm test

ローカルで起動します。

npm start

このサービスは STDIO を使用するため、通常は MCP クライアントまたは Tunnel プロセスによって起動されます。直接実行した場合、対話型プロンプトが表示されないのは正常です。

環境変数を使用して別の設定ファイルを使うこともできます。

$env:MCP_PROJECT_ROOTS_CONFIG = 'D:\Config\project-files-roots.json'
npm start

プロジェクトルートディレクトリの追加

まず MCP サービスを停止してから、以下のコマンドを実行してください。

.\add-project-root.ps1 -Path 'D:\Projects\another-project' -Name 'another-project'
npm test

スクリプトはディスク全体、ユーザーディレクトリ、Desktop、Documents を拒否します。設定を変更した後は MCP または Tunnel を再起動する必要があります。実行中のサービスはルートディレクトリをホットリロードしません。

ChatGPT Secure MCP Tunnel への接続

まず OpenAI Platform Tunnel 設定ページから公式の tunnel-client をダウンロードしてください。本プロジェクトは以下の順序でプログラムを検索します。

1. 環境変数 TUNNEL_CLIENT_PATH

2. プロジェクト内の tunnel-client\tunnel-client.exe

3. システムの PATH

4. %USERPROFILE%\Tools\OpenAI\tunnel-client 配下のローカルバージョンディレクトリ

Tunnel を作成したら、ローカルプロファイルを生成します。

.\configure-tunnel.ps1 -TunnelId 'tunnel_your_id'

スクリプトはデフォルトでローカルヘルスチェックポートを 127.0.0.1:8081 に設定し、プロファイルに env:CONTROL_PLANE_API_KEY 参照を保存します。API Key 自体は保存しません。

フォアグラウンドでの起動方法は以下のとおりです。Runtime API Key は非表示入力で現在のプロセス環境に入り、Tunnel が終了するとクリアされます。

.\start-tunnel.ps1

OpenAI Secure MCP Tunnel の作成、権限、ChatGPT への接続手順は公式ドキュメントに従ってください。

Windows ログイン後の非表示起動

長期間使用する場合は、現在の Windows ユーザーのタスクスケジューラタスクをインストールできます。

.\install-tunnel-autostart.ps1

インストーラーは現在のユーザーの DPAPI で暗号化した Runtime API Key のみを保存し、平文をタスクパラメータ、プロジェクトファイル、ログには書き込みません。タスクスケジューラタスクは非表示の VBS ラッパーを介して起動し、最初に doctor を実行してから Tunnel を起動し、healthz と readyz をチェックします。

状態とログの場所は以下のとおりです。

Get-ScheduledTask -TaskName 'OpenAI Project Files Read Only Tunnel'
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/healthz
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/readyz

%LOCALAPPDATA%\OpenAI\ProjectFilesReadOnly\tunnel-client.log

タスクと暗号化キーファイルを削除します。

.\remove-tunnel-autostart.ps1

完全な説明は Windows Tunnel 運用ガイド を参照してください。

ファイルサポート

ドキュメントの内容は常に信頼できない入力として扱われます。MCP クライアントはファイル内のテキストをシステム命令として扱うべきではありません。

テスト

npm test

テストは以下の範囲をカバーします。

• ルートディレクトリ内の読み取りとルートディレクトリ外の拒否

• 機密ファイルの拒否

• 相対パスの拒否

• シンボリックリンクと Windows ジャンクションの境界

• 読み取り専用ツールの一覧と annotations

• CSV、DOCX、PDF、XLSX の読み取り

• アクティブな Office コンテンツと異常な ZIP の拒否

• ドキュメント形式、ページング、ワークシート、応答上限

プロジェクト構造

server.mjs                 MCP 工具注册与文本读取
path-guard.mjs             路径、白名单和敏感文件边界
document-reader.mjs        安全读取与 Worker 调度
document-worker.mjs        DOCX、PDF、XLSX 内容提取
archive-guard.mjs          Office 压缩包检查
roots.example.json         可提交的配置示例
*-test.mjs                 安全、文档和集成测试
*.ps1 / *.vbs / *.cmd      Windows Tunnel 与计划任务脚本

責任ある開示

パス脱出、未承認の読み取り、機密情報の漏洩、ドキュメント解析の問題を発見した場合は、実際の機密ファイルを含む再現資料を公開しないでください。対応方法は SECURITY.md を参照してください。

ライセンス

このプロジェクトは MIT License を使用しています。