goose/source-notesupstream ↗
goose · version 1.45.0 · Rust 1.94.1

第 5 章：MCP 与工具系统——从配置到可执行能力

5.1 是什么：Extension 是能力容器

goose 把外部能力抽象为 extension，而不是把每个工具直接塞进 Agent。ExtensionConfig 支持 stdio、streamable HTTP、builtin、platform、frontend、inline Python 等类型；ExtensionManager 负责连接、初始化、发现 tools/resources/prompts、缓存工具清单以及 dispatch。

flowchart LR
  Config[ExtensionConfig] --> Manager[ExtensionManager]
  Manager --> Stdio[Tokio child process]
  Manager --> HTTP[Streamable HTTP / UDS]
  Manager --> Builtin[bundled goose-mcp]
  Manager --> Platform[goose process 内的平台扩展]
  Manager --> Frontend[由桌面端执行的 frontend tool]
  Stdio --> Client[McpClientTrait]
  HTTP --> Client
  Builtin --> Client
  Client --> Tools[Tool / Resource / Prompt catalog]
  Tools --> Agent[Agent prompt + tool call]

5.2 源码怎么做：四步管道

连接

ExtensionManager::add_extension 根据配置选择 transport：子进程 stdio、streamable HTTP 或 Unix socket。它会合并环境变量、解析命令路径、设置 timeout，并在需要时走 OAuth。外部 extension 的敏感 env key 由 keyring/config 系统补齐，且 Envs 明确拒绝 PATH、LD_PRELOAD、PYTHONPATH、NODE_OPTIONS、TEMP 等容易被用于劫持或持久化的变量。

发现

初始化后通过 MCP client 发现 tools、resources、prompts。工具会被加上 extension owner metadata，并按 extension__tool 命名空间展平；对 provider 把双下划线变成点号、functions. 前缀等兼容情况，manager 还有名称恢复逻辑。

缓存

tools_cache 与 tools_cache_version 避免每次 turn 都重复列出工具。新增/删除/更新 extension 会使缓存失效。不同 session 可以再叠加 available_tools 过滤，因此“服务端提供了什么”和“当前 Agent 暴露什么”是两层概念。

dispatch

dispatch_tool_call 先解析 owner，再把 ToolCallContext 传递下去。上下文包括 session id、working dir、tool request id 和通知 emitter。返回值不是单一 future，而是 ToolCallResult：最终 result 之外，还能携带 notification stream 和 action-required stream。

5.3 MCP App 与资源

goose 不只把 MCP 当 RPC。ResourceItem 把 extension resource 展平为带 URI、时间、priority、token_count 的可排序输入；MCP App attachment 则允许 tool 的 UI resource 被前端挂载。goose-mcp 还包含 autovisualiser、computercontroller、memory、tutorial 等内置 server，实现“产品内置能力”和“外部 MCP”使用同一协议。

5.4 为什么这样做：能力发现与安全审查可以独立演进

如果工具直接由 Agent 持有，新增 transport、OAuth、资源读取或前端代理都会污染 loop。现在 Agent 只关心工具描述和调用结果；ExtensionManager 负责连接生命周期与协议细节；ToolInspectionManager 在 dispatch 前做安全判断。这个边界还允许桌面端以 frontend extension 提供本地 UI 能力，而不要求 Agent 进程真的执行它。

5.5 从配置到调用的最小路径

config.yaml / UI
  → ExtensionConfig
  → add_extension
  → MCP initialize + list_tools
  → prefix/name + cache
  → Provider::stream(tools)
  → ToolRequest
  → inspect + permission
  → dispatch_tool_call
  → ToolResponse + notifications

源码定位