MCP File Tools

Scripthold — ローカルワークスペース向けのセキュアな MCP サーバー

Web上のコードをローカルで扱い、安全に復元できます。

Scriptholdは、Web、デスクトップ、CLIのエージェントに、明示的に許可されたローカルワークスペースへの制御されたアクセスを提供するModel Context Protocol（MCP）サーバーです。レガシーなテキストエンコーディング、決定論的なファイル変更、ソースコード内の移動、バックアップ、およびstdioまたは認証済みStreamable HTTPを介した、オプションの永続的なローカル実行を安全に処理します。

AIクライアントにはНастройкиと表示されます。????やÍàñòðîéêèではありません。

こちらから始めましょう： クイックスタート · ツールを探す · すべてのドキュメント · セキュリティポリシー。

Scripthold が提供するもの

Scripthold 4.x は、36 個のツールと 3 つのガイド付きプロンプトを提供します。最新の公開バージョンについては、GitHub Releasesをご覧ください。3.x からアップグレードするクライアントは、統合された確認ツールについて4.0 移行ガイドに従ってください。4.0.1 では、source_symbols outline のレスポンスはデフォルトでコンパクトなツリーになります。以前の files フィールドと symbols フィールドを維持するには、presentation: "detailed" を渡してください。

• 168 種類の登録済みテキストエンコーディングに対応し、コンテンツベースの検出、UTF-32 LE/BE のサポート、慎重な曖昧性処理を備えています。
• 100 種類の有効なソースインテリジェンスプロバイダーにより、対象を限定した宣言のナビゲーション、構造検索、選択したプロジェクトの関連情報、検証済みコンテキストの組み立てを実現します。
• セキュアなワークスペース境界により、正規ルートへの包含、Windows の再解析ポイント／ジャンクションへの対応、決定論的な走査、パスの存在確認を実現します。
• 承認に基づく変更では、プレビュー／適用機能、正確なフィンガープリント、競合チェック、ステージング済み書き込み、部分的な状態の正確な報告を利用できます。
• 任意の永続バックアップでは、履歴、比較、監査、復元、明示的なガベージコレクション、ピン留め、ID を指定した削除を利用できます。
• 永続性のある非同期タスクでは、冪等性、永続状態、制限付きログ、復旧、ロック、キャンセルに対応します。
• 長時間実行される読み取り専用呼び出しの信頼性は、任意の遅延操作ストレージと、保持結果を取得するための制限付き機能によって確保されます。
• 認証付き Streamable HTTPは、ループバックをデフォルトとし、ベアラー認証、Host／Origin 検証、リソース制限、ループバック以外に公開する場合の明示的な TLS／プロキシ要件を備えています。

Scripthold は、Dimitar Grigorov が作成した元の mcp-file-tools プロジェクトから派生しており、GPL-3.0 の系譜を引き継いでいます。プロジェクトの方針をご覧ください。

クイックスタート

公開済みバイナリを選ぶか、ソースからビルドしてから、共有するディレクトリのみにアクセスを許可するよう MCP クライアントを設定してください。HTTP とコンテナを使ったデプロイには、以下の追加設定が必要です。

公開リリースを使用する

最新リリースからプラットフォーム用のアセットをダウンロードし、checksums.txt と照合して検証してください。リリースには、通常の GoReleaser アセット用に、署名付きの Sigstore ビルド来歴バンドルも添付されています。

ソースからビルドする

git clone https://github.com/zoster81/scripthold.git
cd scripthold
go test ./...
go build -o scripthold ./cmd/scripthold

モジュールパスは github.com/zoster81/scripthold です。

ローカル stdio クライアント

許可する各ディレクトリを起動時の引数として渡します。

{
  "mcpServers": {
    "scripthold": {
      "type": "stdio",
      "command": "C:\\Tools\\scripthold_windows_amd64.exe",
      "args": ["D:\\Projects"]
    }
  }
}

起動時のルートが正式な設定となります。ルート機能に対応した stdio クライアントは、ディレクトリ引数なしでプロセスを起動した場合に限り、動的なルートを指定できます。

検証済みセルフアップデート

対応するスタンドアロンインストールでは、セルフアップデートを有効にできます。scripthold update --adopt を実行する前に、同じバイナリを使用している他の Scripthold プロセスを停止してください。Adoption では、実行ファイルをダウンロードまたは置き換えることなく、ローカル状態を準備します。

Adoption 後、scripthold update を実行して、利用可能なリリースを検証し、処理を開始します。完了を確認するには scripthold update status を使用してください。scripthold update recover は、ステータスで復旧が提示された場合にのみ実行してください。これらの操作には、それぞれ異なる安全要件と検証要件があります。

対応するインストール方法、正確なコマンド、障害時の対応、復旧ルールについては、検証済みセルフアップデートガイドをご覧ください。

Streamable HTTP

HTTP では、ベアラートークンの取得元を必ず 1 つだけ設定する必要があります。ループバックでの最小限の PowerShell 起動例は次のとおりです。

$tokenPath = Join-Path $env:TEMP "scripthold.token"
$bytes = New-Object byte[] 32
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
try { $rng.GetBytes($bytes) } finally { $rng.Dispose() }
[System.IO.File]::WriteAllText($tokenPath, [Convert]::ToBase64String($bytes), [System.Text.UTF8Encoding]::new($false))

$env:MCP_HTTP_TOKEN_FILE = $tokenPath
$env:MCP_HTTP_ADDR = "127.0.0.1:8765"
.\scripthold_windows_amd64.exe --transport=streamable-http D:\Projects

MCP エンドポイントは http://127.0.0.1:8765/mcp です。/healthz と /readyz は、稼働状態と準備状態を公開します。すべての MCP リクエストで、トークンを Authorization: Bearer <token> として送信してください。

HTTP セキュリティを読まずに、HTTP をループバック以外に公開しないでください。ループバック以外で使用するには、明示的なオプトインと、TLS または信頼できるプロキシ境界が必要です。

OpenAI Secure MCP Tunnel

サニタイズ済みの PowerShell サンプルは examples/ にあります。

• start-local-stdio.ps1
• start-local-http.ps1
• start-openai-tunnel-stdio-plus-local-http.ps1
• start-openai-tunnel-http-plus-local-stdio.ps1

プレースホルダーを置き換える前に、サンプルをチェックアウト先の外部にコピーしてください。Runtime API キー、Tunnel ID、ベアラートークン、非公開の状態パスは、絶対にコミットしないでください。

コンテナー

docker build --build-arg VERSION=dev -t scripthold:dev .

docker run --rm -i \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --mount type=bind,source=/absolute/project,target=/data \
  scripthold:dev --transport=stdio /data

イメージは、非特権の UID/GID 10001 で実行されます。

ツールグループ

TOOLS.md は、スキーマ、パラメーター、例、制限事項、エラー動作を詳しく説明した公開リファレンスです。以下の表は、4.x のカタログ（36 個のツール）について説明しています。3.3.6 からアップグレードするクライアントは、以前の 8 つの apply コマンドを confirm_verified_operation に移行する必要があります。

領域	主なツール
テキスト／ファイル	read_text_file、read_multiple_files、write_whole_file、edit_file、grep_text_files
確認	confirm_verified_operation — 準備済みのあらゆる操作を 1 回限りで承認
複数ファイルの変更	patch_package、filesystem_package
ディレクトリ／状態	list_directory、tree、search_files、get_file_info、fingerprint_paths、verify_state
エンコーディング	detect_encoding、convert_encoding、detect_line_endings、change_line_endings、manage_bom、list_encodings
バックアップ	backup_store、backup_delete
ソースコードインテリジェンス	source_symbols、source_query
Markdown インテリジェンス	markdown_read、markdown_workspace、markdown_create、markdown_edit
永続的な作業	task_run、task_list、task_get、task_logs、task_cancel、deferred_operation
サービス	list_allowed_directories、check_for_updates

ソースコードインテリジェンス

ソースコードインテリジェンスを使うと、コードを実行したり外部のコンパイラー、パーサー、言語サーバーを必要としたりせずに、エージェントがソースコードをナビゲートできます。source_symbols を使って、digest presentation: "compact" でプロジェクトファイルをマッピングし、デフォルトのツリー構造のファイル概要を参照します（以前の概要 JSON 構造を使う場合は presentation: "detailed" を指定してください）。また、選択したシンボルを調べることもできます。構造検索、サポート対象のプロジェクト関係、依存関係グラフ、検証済みのコンテキストには source_query を使用してください。構造シンボルで表現されない任意のテキストやコードの動作を探す場合は、grep_text_files を使用してください。

サポートされていない関係や曖昧な関係は、推測せずに拒否されます。Markdown ファイルには専用のドキュメントツールがあります。利用可能なソースプロバイダーと分析範囲については、生成された言語機能のマトリックスを確認してください。

Markdown ドキュメント

Markdown ファイルには、Source Intelligence プロバイダーではなく専用のツールを使用します。markdown_read でドキュメントを読み込むか、読み取り専用の markdown_workspace ツールでファイル間のリンクや関係を調べます。

ドキュメントを変更するには、markdown_edit（新しいファイルの場合は markdown_create）でプレビューを作成して提案内容を確認し、previewId を confirm_verified_operation に渡します。安全でない変更、競合する変更、または古くなった変更は、黙って書き換えられるのではなく拒否されます。

使用例と正確な操作形式については、Markdown ツールリファレンスを参照してください。Markdown の仕様、サポートされるエンコーディング、Marksplice との連携境界については、Markdown Intelligenceを参照してください。

安全性モデル

• ファイルアクセスは、正規パスの検証後に明示的に許可されたルートに限定されます。
• シンボリックリンク、ジャンクション、再解析ポイント、エイリアス、および存在しないパスを経由したアクセスは、すべて拒否されます。
• エンコーディングの検出には、ファイル名や拡張子ではなく、バイト列とデコードされた内容の証拠を使用します。
• 変更はコミット前にステージングして再検証されます。最初は存在しない宛先には、上書きしないセマンティクスが適用されます。
• プレビュー／適用ワークフローでは、承認された操作を一度限りのケイパビリティに紐付けるため、適用時に変更パラメーターを変更できません。
• 複数ファイルの変更では、トランザクションによるロールバックを保証しません。該当する場合、失敗時にはコミット済み／未変更／不明の状態が報告されます。
• オプションのバックアップストアは、公開ルートの外側にある、別個に保護された権限領域です。
• task_run の実行はデフォルトで無効です。シェルとスクリプトの実行には明示的な許可が必要です。HTTP には追加の HTTP 実行オプトインが必要です。
• HTTP は認証が必要で、デフォルトではループバックにのみバインドされます。

現在のアーキテクチャ上の境界については、アーキテクチャにまとめています。

主な設定

ほとんどのインストールでは、環境変数の一部を設定するだけで十分です。

変数	目的	デフォルト
MCP_TRANSPORT	stdio または streamable-http	stdio
MCP_DEFAULT_ENCODING	新しいテキストファイルのエンコーディング	utf-8
MCP_HTTP_ADDR	HTTP のリッスンアドレス	127.0.0.1:8765
MCP_HTTP_TOKEN_FILE / MCP_HTTP_TOKEN	相互排他的なベアラートークンの設定元	未設定
MCP_HTTP_ALLOW_NON_LOOPBACK	ほかのセキュリティ要件を満たす場合に、ループバック以外へのバインドを許可	無効
MCP_BACKUP_STORE_DIR	永続バックアップストアを有効化	未設定
MCP_BACKUP_DEFAULT_POLICY	対象となる承認紐付き変更に対するデフォルトの永続バックアップポリシー	disabled
MCP_TASK_STORE_DIR	タスクの永続化を有効化	未設定
MCP_DEFERRED_STORE_DIR	対象となる長時間実行の読み取り専用呼び出しに対する永続的な所有権管理を有効化	未設定
MCP_ENABLE_RUN_SCRIPT	task_run kind=script を許可	無効
MCP_ENABLE_SHELL	task_run kind=shell を許可	無効
MCP_ENABLE_EXECUTION	両方のタスク種別を許可	無効
MCP_HTTP_ENABLE_EXECUTION	HTTP 実行に対する追加のゲート	無効

詳細な制限やサブシステム固有のオプションは、各機能の説明に記載されています。TOOLS.md、永続タスク、HTTP セキュリティを参照してください。

ドキュメント

クライアントの設定、ツールの選択、デプロイのセキュリティ確保、プロジェクトへの貢献など、タスク別の手順を探すにはドキュメントガイドを使用してください。

• サーバーの使用: ツールリファレンス、HTTP セキュリティ、永続タスク。
• プロジェクトの理解と変更: アーキテクチャ、貢献ガイド、ロードマップ。
• リリース履歴: 変更履歴。バージョン固有の手順は移行ガイドに記載されています。

開発

必要な Go のバージョンは go.mod で宣言されています。

go mod verify
go test ./...
golangci-lint run ./...
go build -o scripthold ./cmd/scripthold

変更を提案する前に、CONTRIBUTING.mdを参照してください。

ライセンス

GPL-3.0 — LICENSEを参照してください。