前言¶
在 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 会话的常驻桥接，而是专注于目录治理、健康检查与授权判定。
