Cherry Studio 助手 MCP 默认模式变更从 auto 到 manual 的确定性工具解析【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 在 2026-08-03 的提交9c349245e8中调整了助手的 MCPModel Context Protocol默认交互模式新创建含种子数据生成的助手默认 MCP 模式从auto改为manual。本指南将说明该变更对使用 MCP 工具的用户与开发者产生的具体影响、如何在新助手中恢复 MCP 工具、三种模式的语义差异以及本次变更背后“消除三层默认值不一致、保证工具解析确定性”的实现原理与源码证据。变更摘要维度变更前变更后新助手默认 MCP 模式auto自动挂载全部活跃 MCP 服务器manual仅使用显式关联的 MCP 服务器新助手初始工具集自动获得所有活跃 MCP 服务器的工具无 MCP 工具直至手动关联服务器既有助手保留各自存储的模式不受影响保留各自存储的模式不受影响变更涉及三类对象新建助手、种子数据生成的助手如内置/预置助手以及未显式设置mcpMode的助手。对于已有助手其数据库中已存储的settings.mcpMode值继续生效行为不发生任何变化。对用户的实际影响在旧行为下新建一个助手即可“开箱即用”获得全部活跃 MCP 服务器提供的工具无需任何配置。新行为下新助手默认没有任何 MCP 工具依赖 MCP 工具的对话会缺少对应能力直到用户在助手设置中显式启用关联目标 MCP 服务器若希望恢复旧行为可将助手的 MCP 模式手动切换回auto。需要强调的是这不是删除或禁用 MCP 功能而是把“默认开放全部工具”的宽松策略收窄为“默认按需显式授权”属于安全性与确定性的默认值收紧。三种 MCP 模式的语义Cherry Studio 的助手通过settings.mcpMode字段控制 MCP 服务器解析范围该字段由 src/shared/data/types/assistant.ts 中的 Zod 枚举定义export const McpModeSchema z.enum([disabled, auto, manual])模式行为典型用途disabled完全不解析任何 MCP 服务器工具集为空不需要任何 MCP 能力的纯对话场景auto自动挂载所有活跃MCP 服务器isActive: true的工具需要全部服务器能力、希望零配置的场景manual仅挂载通过mcpServerIds显式关联的服务器需要精确控制每台助手可用工具集的场景本次新默认值默认值常量与“单一事实来源”关键的默认值常量定义在 src/shared/data/types/assistant.ts/** * Effective mcpMode when settings.mcpMode is unset. Single source of truth — * mains resolver, the renderer helper, and the composer MCP selector must all * agree, or the same assistant resolves different tool sets per layer * (runtime-test finding #6). manual only explicitly linked servers. */ export const DEFAULT_MCP_MODE: McpMode manual同时预计算好的默认设置对象 DEFAULT_ASSISTANT_SETTINGS 中mcpMode: DEFAULT_MCP_MODE新建助手写入数据库时即携带此默认值。这意味着“未显式设置mcpMode”与“显式设置为manual”在解析结果上是等价的只使用显式关联的服务器若一个都没关联解析结果为空工具集效果等同disabled。源码级解析链路模式如何决定工具集主进程侧的解析逻辑集中在 src/main/ai/tools/adapters/aiSdk/mcp/resolveAssistantMcpTools.ts核心是三个函数1. 获取生效模式export function getEffectiveMcpMode(assistant: Assistant): McpMode { return assistant.settings?.mcpMode ?? DEFAULT_MCP_MODE }渲染进程侧存在一个同名的薄封装 src/renderer/utils/mcpMode.ts同样回落到共享的DEFAULT_MCP_MODE确保主进程解析、渲染进程助手 UI、composer MCP 选择器三层读取到完全一致的默认值。2. 解析助手可用的服务器集合export function resolveServersForAssistant(assistant: Assistant, mode: McpMode): McpServer[] { const linkedIds mode auto ? null : new Set(assistant.mcpServerIds) // Manual mode with nothing linked can only resolve to an empty set — skip the query. if (linkedIds?.size 0) return [] const { items: activeServers } mcpServerService.list({ isActive: true }) return linkedIds ? activeServers.filter((server) linkedIds.has(server.id)) : activeServers }其解析规则非常直观autolinkedIds为null直接返回全部活跃服务器manual仅保留同时满足“活跃”且id在assistant.mcpServerIds中的服务器未关联任何服务器时直接短路返回空数组跳过数据库查询disabled在调用方resolveAssistantMcpToolIds即提前返回空数组不会触碰 MCP 服务。关联关系在数据库中通过assistant_mcp_server联结表持久化见 src/main/data/db/schemas/assistantRelations.ts以(assistantId, mcpServerId)为复合主键两侧级联删除保证关联与助手/服务器生命周期一致。3. 解析最终工具 ID 列表resolveAssistantMcpToolIds是聊天请求热路径上的核心入口先取助手实体再按模式解析服务器随后对每台服务器先预热工具缓存再列出工具最终返回所有工具的 ID 数组。相关代码见 resolveAssistantMcpTools.ts。本次变更的根因三层默认值不一致文档“Notes for release manager”一节揭示了变更动机主进程 / 共享层 / 渲染进程三层此前对“未设置时的回退模式”各持己见分别是manual/disabled、auto、disabled导致同一台助手在不同代码路径下解析出不同的工具集——这是运行期测试发现的 #6 号问题源码注释中明确引用runtime-test finding #6。统一为manual后无论请求从哪条路径进入未显式设置mcpMode的助手都以“仅显式关联服务器”为唯一答案工具解析结果变得确定性与可复现消除了“同一助手、不同轮次、不同工具”的歧义。同提交附带修复冷缓存预热Cold Catalog Warm-up本次提交还修复了一个隐蔽问题冷启动的 MCP 目录catalog在解析前未被预热此前会静默解析为空工具集导致同一助手在不同轮次出现工具集漂移。修复后resolveAssistantMcpToolIds在listTools纯缓存读取之前先调用McpCatalogService.warmToolsCache(serverId)强制刷新冷缓存。关键设计点见 resolveAssistantMcpTools.ts预热超时上限WARM_TOOLS_TIMEOUT_MS 10_00010 秒够一台健康服务器完成冷启动刷新connect listTools又保证不可达服务器其连接超时下限为 3 分钟MCP_CONNECT_TIMEOUT_FLOOR_MS不会拖住启动后的第一条聊天消息超时后降级而非阻塞底层刷新不会被中止仍在后台单飞single-flight完成后续请求即可读到已填充的缓存当前请求降级为缓存内已有的工具集可能为空并记录warn日志已填充的缓存立即返回缓存热时warmToolsCache同步返回不引入额外延迟。行为对照什么场景会感知到变化使用场景变更前变更后新建助手直接开始 MCP 对话自动获得全部活跃 MCP 工具无 MCP 工具需手动关联种子/预置助手首次使用自动获得全部活跃 MCP 工具无 MCP 工具需手动关联已有助手已存mcpMode按存储模式解析不变仍按存储模式解析已有助手且从未设置mcpMode按层各自回退可能为auto统一回退manual仅显式关联服务器手动将新助手切回auto—恢复自动挂载全部活跃服务器用户应如何操作对每个需要使用 MCP 工具的新助手二选一显式关联推荐精确控制进入助手设置在 MCP 服务器列表中启用关联所需服务器。此时模式保持manual工具集精确等于所关联服务器提供的工具恢复旧行为快捷将助手的 MCP 模式切换为auto即可自动挂载全部活跃服务器。两种方式均即时生效且不影响其他助手——mcpMode与关联关系都是按助手粒度存储的。测试验证仓库为该变更提供了完整的单元测试支撑见 src/main/ai/tools/adapters/aiSdk/mcp/tests/resolveAssistantMcpTools.test.ts关键用例包括预热时序断言warmToolsCache先于listTools被调用冷目录不会静默产生空工具集对应“修复前返回[]”的回归场景预热超时上限使用假定时器推进 10 秒验证挂起的预热不会阻塞解析、降级到当前缓存并发出Timed out warming MCP tools cache警告默认模式未设置mcpMode的助手无论是否关联服务器生效模式均为manual未关联服务器时不触碰缓存直接返回[]显式disabled不触碰目录直接返回空显式auto即使mcpServerIds为空也解析出全部活跃服务器的工具。此外defaultAssistantSeeder.test.ts 验证了种子数据助手以DEFAULT_ASSISTANT_SETTINGS含manual默认值创建确保预置助手同样遵循新默认。给开发者的迁移提示若你的代码在settings.mcpMode缺失时自行回退到auto请改为从共享常量DEFAULT_MCP_MODE读取或直接复用getEffectiveMcpMode主进程侧见 resolveAssistantMcpTools.ts渲染进程侧见 mcpMode.ts避免再次出现多层默认值分叉涉及 MCP 工具解析的新代码路径务必遵循“先warmToolsCache再listTools”的顺序并留意 10 秒预热上限的存在相关类型与默认值均可在 src/shared/data/types/assistant.ts 中追溯这是一处共享层的“单一事实来源”修改默认值时应同步评估主进程解析器、渲染进程 helper 与 composer MCP 选择器三处消费方。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考