前言¶
在 DeepSeek Harness (DSH) 的插件化架構下，管理外部 MCP (Model Context Protocol) 連接器往往面臨權限邊界不清、配置導入靜默失敗、連接狀態不可見等問題。dsh-mcp-registry 插件旨在解決這些痛點，通過一個受治理的註冊表來統一管理 stdio 和 streamable-http 類型的 MCP 連接器。它借鑑了 dsh-mcp-connector 和 openhanako 的設計理念，提供了一套從配置導入到運行時授權的完整治理流程。
核心功能¶
註冊表與持久化
插件負責登記 stdio / streamable-http MCP 連接器，並將配置持久化到 ~/.dsh/mcp-registry/registry.json。寫入過程採用原子操作、寫後回讀以及滾動快照機制（快照數量 ≤20），確保配置的可靠性與可回溯性。
四級 fail-closed 授權
授權邏輯採用多層防禦策略，遵循 fail-closed 原則：
1. 全局開關：控制註冊表的整體可用性。
2. 連接器級模式：通過 permissionMode 控制（缺省爲 review-all）。
3. 工具級授權：通過 grant 命令顯式放行特定工具。
4. 服務器聲明證據：依賴服務器端的聲明（僅內存，重啓失效）。
其中 destructiveHint 作爲硬否決項，會覆蓋任何授權。
Fail-loud 導入
插件會對導入的 mcpServers JSON 進行嚴格校驗，拒絕以下情況並報錯：
* args 字段是字符串而非數組。
* command 帶空格但未正確處理 args。
* 包含 __proto__ 等潛在危險的鍵名。
這與某些實現靜默丟參數的 bug 形成反向驗收。
全邊界脫敏
在註冊表的輸出邊界，所有涉及工具、命令、導出、HTTP 狀態的原始信息都會被投影（如保留 origin / 命令基名）。敏感信息如 token 與環境變量的明文值不會出現在註冊表數據中。
誠實橋接
Agent 調用 mcp_bridge_call 時，review 模式會返回結構化的 needs_review 狀態，包含 grant 指引，但不會執行工具，也不會僞裝批准。
原生工具懶加載
這是一個可選功能，旨在減少常駐 prompt 的 token 消耗。開啓後，非核心原生工具（如 shell、文件、搜索）的完整 schema 會被摺疊。Agent 需先通過 tool_discover 查看摺疊後的目錄，再通過 tool_activate 按需展開。支持兩檔模式（lazyEagerIndex，缺省 true）：Eager 模式下列表直接攤開，Non-eager 模式下需先 discover 再 activate。
安裝與啓用¶
安裝該插件需要修改 DSH 的 profile 配置。
方法一：Profile Patch
在 profile 中插入插件 ID：
profile patch
- insert: [{id: dsh-mcp-registry, name: "dsh-mcp-registry"}]
方法二：直接使用補丁文件
使用倉庫提供的 cordis.patch.yml 文件進行安裝。
典型用法¶
插件提供了一套 CLI 命令用於註冊表的管理。
導入連接器
導入配置文件，默認全部 disabled 並標記爲 UNCONFIRMED：
mcp-reg import D:\configs\mcp.json
查看與管理
mcp-reg list # 查看註冊表
mcp-reg probe <id> # 執行一次 MCP initialize 握手
mcp-reg confirm <id> # 確認並啓用連接器
授權控制
mcp-reg mode <id> allowlist # 設置爲允許列表模式
mcp-reg grant <id> <tool> # 顯式放行特定工具
mcp-reg call <id> <tool> '{"k":"v"}' # 人工調用（視同批准）
適用場景與注意¶
版本要求
插件對宿主 DSH 的版本有嚴格要求：
* DSH 0.2.0 線：使用 latest 版本（對應 DSH 0.3.4）。
* DSH 0.1.7 線：需安裝 dsh-mcp-registry@dsh-0.1.7（對應 npm 0.3.3）。
* 0.1.6 及以下：不再支持，安裝會被 engines.dsh 拒絕。
權限與運行環境
插件以當前 DSH 進程的權限運行。建議在安裝前檢查源碼與許可證（MIT）。
結語¶
dsh-mcp-registry 通過提供受治理的註冊表、嚴格的授權模型和透明的診斷機制，爲 DSH 中的 MCP 連接器管理提供了一個堅實的底層設施。它不承擔 MCP 會話的常駐橋接，而是專注於目錄治理、健康檢查與授權判定。
