MCP-Local 本機檔案唯讀工具

MCP-Local 是 Windows 上的本機檔案唯讀 MCP 服務，在使用者明確授權的資料夾或磁碟範圍內，提供 UTF-8 文字與程式碼的列舉、搜尋及讀取能力。支援本機 STDIO，也可透過已設定的遠端通道連線。

服務版本：2026.09.17.3 · MCP 工具契約：4 · 設定版本：5 · 唯讀工具：11 個

主要功能

• 最多八個互不包含的具名共享根目錄；可明確授權整個磁碟，程式設定、備份與金鑰目錄仍固定排除。

• 目錄探索、檔名定位、專案入口摘要、批次內容搜尋與多區段讀取。

• Windows GUI、系統匣、登入自動連線及 DPAPI 金鑰保存。

• 關閉／極致節能雙模式，預設關閉，可即時切換並保存偏好。

MCP 工具不提供來源檔案寫入、刪除或指令執行能力。

Related MCP server: File Context MCP Server

快速開始

環境需求：Windows、Python 3.10+。既有驗證環境為 Python 3.10.11、MCP 1.30.0；相依套件版本見 requirements-lock.txt。

在專案根目錄執行：

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-lock.txt
.\.venv\Scripts\python.exe -B verify_isolated.py

啟動本機 STDIO 服務：

.\.venv\Scripts\python.exe local_files_mcp.py --root .\shared

此命令僅分享專案內的 shared，不會自動套用 GUI 設定。STDIO 供支援 MCP 的用戶端啟動與連接；手動執行時可用 Ctrl+C 停止。

GUI 與遠端連線

1. 準備經驗證的官方 tunnel-client.exe，以及具備通道使用權限的金鑰。供應商二進位檔不包含在 Git 原始碼內。

2. 雙擊 開啟連線設定.vbs，選取共享資料夾，填入自己的通道識別碼與金鑰，再按「儲存設定」。

3. 按「啟動連線」，或於完成設定後執行 .\start-local-files-tunnel.ps1。

範例通道識別碼不能直接用於正式連線。修改共享資料夾後，使用「儲存並重連」套用；更新工具後，需在 MCP 用戶端重新整理工具清單。

可勾選登入後啟動到系統匣並自動連線。左鍵系統匣圖示開啟設定，右鍵可啟停連線、切換電源模式或退出。

唯讀工具

省略 root_id 時只使用預設根，不會搜尋全部共享根。完整輸入結構與唯讀標記見 tool-contract.json。

建議先用 workspace_info 確認範圍；已知專案用 project_context，探索目錄用 list_directory，找檔名用 find_files。內容搜尋盡量指定較小目錄，多個已知檔案用 read_files，同檔多段用 read_file_ranges。

限制與安全邊界

• 單檔預設上限 2 MiB，可調至 64 MiB；單次讀取視窗最多 400 行、24,000 字元。

• find_files 最多 10 個查詢，每詞最多 50 筆，合計最多 200 筆與 100 KiB；達上限即停止，不保證完整清冊。

• 列舉與搜尋均有掃描及輸出預算。has_more 代表快照仍有下一頁；scan_truncated 代表掃描未完成，需縮小範圍。

• 讀取與內容搜尋保留整檔 UTF-8、NUL 與容量驗證；多區段讀取只開檔一次，仍驗證到檔尾。不解析 PDF、Office、圖片或壓縮檔。

• 拒絕工具輸入中的絕對路徑、向上跳脫、點號名稱、Hidden 項目、符號連結、重新解析點與多重硬連結。

• 整碟授權仍套用排除規則；程式狀態目錄禁止列舉與讀取。檔名排除不能辨識所有內容機密，應只授權願意交給連線用戶端的範圍。

• MCP 中繼資料不揭露主機根目錄絕對路徑；金鑰不放入命令列參數。檔案內容本身可能含路徑或敏感資訊。

• 內容視為不受信任資料。路徑防護不是作業系統沙箱，不抵禦不受信任本機程序持續替換共享路徑；不要以系統管理員身分執行服務。

電源模式

GUI 與系統匣可即時切換「關閉」或「極致節能」，不需重連；按「儲存設定」保留下次啟動偏好。極致節能使用 EcoQoS、臨時電源方案與 CPU 效能限制，可能增加工具回應時間；連線存活期間會提出防止系統睡眠的要求。

Windows 11 支援時會套用「最佳電源效率」，不強制開啟 Windows 節能器。正常退出或異常結束由還原流程處理；使用者中途改選其他方案或模式時保留其選擇，還原失敗需查看日誌。實機功耗與長時間遠端穩定性仍需另行驗收，詳見 低功耗模式工程設計。

驗證與文件

verify_isolated.py 執行隔離語法、相依套件及回歸檢查，並寫出測試報告。一般電源測試使用 mock；真實系統電源測試需另外明確授權。本次 README 更新不代表重新完成程式或遠端驗收。

遠端驗收須在實際 MCP 用戶端重新整理並確認 11 個工具、比對契約，以及實際列目錄、讀檔與搜尋。本機測試成功不能代替遠端驗收。

• 完整繁體中文說明：容量、游標、多根設定、遷移及錯誤處理。

• 介面使用說明：GUI、系統匣與連線操作。

• 性能優化交付報告：性能工具、測試方法與既有實測。

授權

本專案採用 Apache License 2.0。