MCP 扩展管理

MCP 扩展管理

学习目标

读完本章后，你将能够：

• 理解 ExtensionManager 的核心职责与 6 种扩展类型的适用场景
• 掌握 Goose 的工具命名空间策略：前缀规则与一等扩展的例外
• 设计版本驱动的缓存失效机制，避免无效的工具列表查询
• 理解 MCP Client 的双向通信能力（list_roots、create_message、create_elicitation）
• 分析 Docker 容器执行与恶意软件检查在安全架构中的角色

前置知识

• [[mcp/01-overview]] — MCP 协议的核心概念、传输层与客户端/服务器架构
• [[mcp/02-multi-server-mcp]] — MCP 多服务器管理：工具发现与 OAuth 集成

---

项目实践

ExtensionManager 核心架构

Goose 的 ExtensionManager 管理一个 HashMap<String, Extension> 映射，每个 Extension 对应一个 MCP 服务器连接：

6 种扩展类型详解

类型	传输方式	说明	典型场景
Stdio	子进程 stdin/stdout	最常见的本地 MCP 扩展	文件系统、Shell、记忆服务
StreamableHttp	HTTP POST + SSE	远程 MCP 服务，支持 OAuth	云端 API、远程数据库
Builtin	进程内直接调用	打包在 goose-mcp 中的内嵌服务器	Developer 扩展（文件读写 + Shell）
Platform	进程内直接调用	一等扩展，享有 unprefixed 工具名	扩展管理工具、定时任务
InlinePython	进程内 Python 解释器	内嵌 Python 脚本执行	数据处理、计算任务
Frontend	UI 侧执行	由前端（Desktop/CLI）执行	浏览器操作、桌面自动化

Stdio 扩展启动流程：

启动 Stdio 扩展:
    1. 恶意软件检查（见下文安全部分）
    2. 配置子进程（工作目录、环境变量、命令参数）
    3. 启动子进程，连接 stdin/stdout
    4. MCP initialize 握手，交换能力声明
    5. 拉取工具列表，写入缓存
    6. 如果配置了 OAuth，处理认证流程

工具命名空间策略

多个 MCP 服务器可能提供同名工具。Goose 使用以下命名策略：

普通扩展：extension_name__tool_name    (如 developer__shell)
一等扩展：tool_name                    (如 shell、read_file)

前缀规则的实现：

get_tool_name(extension_name, tool_name, is_first_class):
    if is_first_class:
        return tool_name          // 无前缀
    else:
        return f"{extension_name}__{tool_name}"  // 带前缀

为什么大多数工具需要前缀？

• 多个扩展可能提供同名工具（如多个扩展都有 read_file）
• 前缀确保工具名唯一，LLM 可以明确指定调用哪个扩展的工具
• 模型的工具调用需要精确的字符串匹配，歧义会导致调用失败

一等扩展为什么无前缀？

Developer 扩展（goose-mcp 中的 Developer MCP Server）是 Goose 的核心能力，提供最常用的文件读写和 Shell 操作。用户期望直接使用 shell、read_file、write_file 等自然名称。将其设为”一等”避免了前缀带来的认知负担，也减少了模型 prompt 中的 Token 消耗。

版本驱动的缓存失效

ExtensionManager 缓存工具列表，避免每次 Turn 都调用 tools/list：

缓存键：(extension_name, tools_version_hash)

失效条件：
    1. 扩展重新连接（transport 重建）
    2. 收到 tools/list_changed 通知
    3. 手动刷新（用户通过 /extensions reload）

缓存工作流程：

与通用策略的关系：这实现了 [[mcp/01-overview]] 中提到的”版本标识”策略，用哈希而非版本号来判断变更，避免了服务器需要维护版本号的负担。

Docker 容器执行

扩展可以在 Docker 容器内运行：

extension:
  cmd: "docker exec my-container mcp-server"
  type: "stdio"

安全意义：将 MCP 服务器的执行环境隔离到容器中，避免直接访问宿主机文件系统。这对于不可信或实验性扩展特别重要。

实现方式：

• 通过 Container 抽象层封装容器操作
• 容器配置（容器名、工作目录、环境变量）通过 ExtensionConfig 传入
• 容器内的 MCP 服务器通过 Stdio 传输与 Goose 通信
• 容器销毁时自动清理连接

恶意软件检查

Stdio 扩展在启动前进行恶意软件检查（extension_malware_check 模块）：

malware_check(extension_config):
    1. 检查命令路径是否为已知的合法位置
       拒绝在 /tmp、/var/tmp 等临时目录执行未知二进制文件

    2. 检查命令是否在系统目录中
       拒绝在 /usr/bin、/sbin 等系统目录执行非标准二进制文件

    3. 验证扩展配置的签名或来源
       如果配置了签名验证，检查扩展二进制文件的签名

    4. 记录审计日志
       所有检查通过/失败都写入日志，便于事后审计

设计原则：恶意软件检查是”快速失败”机制——在扩展启动前拦截可疑配置，而非运行后检测异常行为。这避免了恶意扩展在检测到异常前已经造成的损害。

MCP Client 双向通信

Goose 的 MCP Client 不仅消费工具，还支持双向交互：

三种双向交互能力：

能力	说明	触发场景
list_roots	向 MCP 服务器暴露工作目录	服务器需要知道可访问的文件根目录
create_message	MCP 服务器需要 LLM 采样时，Goose 将请求委托给自己的 Provider	服务器内部的智能决策（如资源路由）
create_elicitation	MCP 服务器需要用户交互时，通过 ActionRequiredManager 路由到前端	服务器需要用户提供输入或确认

Session 上下文注入：每个 MCP 请求附带 Extensions._meta，携带 session_id 和 working_dir，使得 MCP 服务器可以感知当前会话和工作环境。

---

问题与规避

扩展启动失败

问题：某个 MCP 扩展配置错误或依赖缺失，导致启动失败。

规避策略：

• 独立启动：每个扩展独立启动，失败不影响其他扩展
• 错误隔离：启动失败的扩展标记为不可用，工具列表中不展示其工具
• 延迟加载：支持按需启动扩展，减少启动时间和依赖问题
• 健康检查：定期检查已连接扩展的响应，失败时标记为不可用并尝试重连

工具列表过时

问题：MCP 服务器动态添加或移除工具，客户端工具列表 stale。

规避策略：

• list_changed 通知：服务器主动推送变更，客户端立即失效缓存
• 哈希校验：每次拉取工具列表后计算哈希，与缓存对比决定是否更新
• 手动刷新：用户可通过命令手动刷新所有扩展的工具列表
• 版本驱动：缓存键包含版本哈希，哈希不同自动失效

OAuth 认证流程中断

问题：StreamableHttp 扩展需要 OAuth 认证，授权流程可能被用户中断或超时。

规避策略：

• OAuth Flow 管理器：统一的 OAuth 流程管理，支持浏览器回调和本地临时服务器
• Token 持久化：刷新后的 token 立即写回磁盘，避免进程重启后失效
• Auth Elicitation：在 pending 授权时暂停工具调用，避免超时
• Credential Store：通过 GooseCredentialStore 统一管理所有扩展的凭据

---

设计取舍

前缀工具名 vs 无前缀

维度	全部无前缀	全部前缀	Goose 方案（混合）
用户体验	最好（自然名称）	差（认知负担）	核心工具无前缀
工具冲突	高（同名冲突）	无	非核心工具前缀隔离
Token 消耗	低	高	大部分工具无前缀节省 Token
扩展性	差（最多一个扩展）	好	支持无限扩展

Goose 的选择：混合策略。Developer 扩展作为一等扩展无前缀，其他扩展一律前缀。这平衡了用户体验和扩展性：最常用的工具名称简短自然，而长尾扩展通过前缀隔离避免冲突。

缓存工具列表 vs 每次查询

维度	缓存	每次查询
延迟	低（内存读取）	高（网络/IPC 往返）
一致性	可能过时	始终最新
资源消耗	低	高
适用场景	工具列表稳定的扩展	动态工具列表的扩展

Goose 的选择：默认缓存 + 版本驱动的失效机制。大多数 MCP 服务器的工具列表在运行期间不变，缓存可以显著减少每次 Turn 的延迟。当工具列表确实变化时（服务器推送 list_changed 通知或重连），缓存自动失效并重新拉取。

Stdio vs StreamableHttp

维度	Stdio	StreamableHttp
延迟	低（本地 IPC）	高（网络往返）
部署	需本地安装	即开即用
安全	依赖 OS 进程隔离	依赖 TLS + OAuth
可扩展性	受限于本地资源	可水平扩展
适用场景	开发工具、文件系统操作	API 服务、远程数据库

Goose 的选择：同时支持两种传输。开发工具使用 Stdio（如 Developer 扩展），远程服务使用 StreamableHttp（如云端 MCP 服务器）。用户可以根据需求选择最合适的传输方式。

---

参考来源

• [[mcp/01-overview]] — MCP 协议与生态集成
• [[mcp/02-multi-server-mcp]] — MCP 多服务器管理
• Goose 源码：crates/goose/src/agents/extension_manager.rs（ExtensionManager 实现）
• Goose 源码：crates/goose/src/agents/extension_malware_check.rs（恶意软件检查）
• Goose 源码：crates/goose/src/agents/mcp_client.rs（MCP Client 双向通信）
• Goose 源码：crates/goose/src/agents/container.rs（Docker 容器执行）
• Goose 源码：crates/goose/src/agents/tool_execution.rs（工具执行）
• Goose 源码：crates/goose/src/agents/extension/（扩展类型定义）