本地 MCP

Wisp 桌面端支持用户自定义的标准 stdio MCP 工具服务。设置 → 本地 MCP 中添加名称、可执行文件、JSON 参数数组和可选的绝对工作目录。例如已自行安装的 Node 服务可填 node，参数 ["/absolute/path/server.js"]。不是 shell 命令文本；参数逐项传给进程，不通过 shell 拼接。应用从 Dock 启动时 PATH 可能不同，找不到程序请使用绝对路径。

管理与权限

• 新建/编辑后禁用，重启后也禁用；明确“信任并激活”才启动。没有内置服务，不会无审批安装或自动重启。
• 激活后初始化、分页发现工具，展示状态与工具列表；支持服务的 notifications/tools/list_changed 和手动刷新。编辑、禁用、删除会停止旧连接并撤下工具，需重新激活。
• 第三方进程以用户系统权限执行，不受 Wisp 项目目录权限限制。工作目录不是沙箱。只运行信任的程序；激活本身就允许程序运行，不能等同于工具调用审批。
• 所有第三方工具调用都需单次审批，包括声明 readOnlyHint 的工具。审批绑定参数、连接与工具列表版本；列表变更、断开或禁用后旧审批不能调用新的服务。
• 取消/超时通知服务并关闭连接；禁用会取消正在使用此服务的任务（含待审批调用）。无法撤销已完成副作用，不自动重试调用。SDK 关闭 stdin，随后必要时 TERM/KILL 直接子进程；不承诺终止第三方程序自行脱离的守护进程。
• 配置是应用级，已激活工具可供各会话使用；工具执行事件、审批和结果仍归属于发起会话。它不是每项目隔离的 MCP 进程。

环境变量与持久化

非敏感配置保存在本机 mcp-servers.json；变量仅记录名称和保存方式。敏感值请放环境变量，不放命令、参数、名称或目录。

环境变量默认使用 Electron safeStorage 加密，按服务 ID 分开保存，并与启动命令、参数、工作目录绑定。无配置、无环境变量时不访问钥匙串。只在激活需要读取或用户选择保存时解密/加密；不可用则报错，不会明文降级。可主动取消勾选，选择仅当前 Host 会话保存；重启后需重新填写。编辑时不回显旧值，勾选替换会替换全部变量，空列表清除；修改命令时不能静默转交旧秘密。

删除会清除该服务持久化凭据及内存配置。秘密不进入 Renderer 快照、模型工具定义或普通事件日志；已知原值会从服务文本结果中替换，stderr 被丢弃。无法保证恶意服务不编码或自行联网泄露它取得的秘密，审批及脱敏不是对第三方程序的隔离措施。默认只继承 SDK 的最小系统环境，不继承 Wisp 模型 Key。

工具与限制

服务 UUID + 原始工具名摘要组成稳定模型工具名，界面显示服务名与原工具名。每次任务开始时捕获当前可用列表，任务内各轮模型请求保持该快照；新激活或刷新后的工具从下一次用户请求生效，服务提供的描述/schema/结果均不可信。参数先按 JSON Schema 校验；服务返回 isError、协议失败、超时均作为失败交回模型，不伪造成功。

当前上限：16 个配置、每服务 64 个工具、激活工具总计 96 个；schema 16KB、参数 32KB、stdio 单条协议帧 1MB、结果正文 32K 字符；发现和调用默认 10 秒。结果含截断标志。支持文本、嵌入文本资源与结构化结果；图片/音频/二进制仅返回省略标记，不自动打开链接。支持 JSON Schema 2020-12 及显式 Draft-07；不能解析的 schema/外部引用会连接失败，不联网加载 schema。首版不支持远程 HTTP/OAuth、资源订阅、prompts、sampling、elicitation 或持久化长任务扩展；不承诺兼容非标准服务器。

纯 Web 只供 UI 验证。qa.html → 工作台样例 → 设置 → 本地 MCP 提供明确标注的内存管理场景；命令填写 fail 可观察模拟启动失败。它不执行命令、不持久化秘密，不是桌面验收。

验证

测试使用官方 SDK 离线协议夹具及临时 stdio 子进程，并通过本机模拟 DeepSeek HTTP/SSE 接口验证真实 adapter → Host → 审批 → MCP → 模型续答。安全存储测试使用假密码服务。实际 macOS 钥匙串、Dock 启动 PATH、任意第三方运行时及 GUI 生命周期仍需实机验收。

参考：官方 MCP Tools 协议、stdio 传输、TypeScript SDK。当前固定 SDK 1.32.2。

在对话中辅助安装

向 Wisp 提供服务的包名、精确版本和安装说明，或让它读取已经打开的说明页面。当前没有自动网页搜索工具，不应只凭模糊名称猜包。安装说明和页面内容只作参考，不是执行授权。

1. 模型可用 mcp_list_services 查看配置 ID、状态和环境变量名称，不返回变量值。
2. 已安装的程序可用 mcp_register 提交绝对路径、参数数组及工作目录。审批只保存禁用配置，不声称安装或运行了程序；不接受 shell 或 npx 等包管理器作为注册命令。
3. 公共 npm 包可用 mcp_install_npm，必须指定完整包名、精确版本、JavaScript bin 名称及非敏感启动参数。审批显示来源、目录和影响；安装后注册为禁用。Host 只运行固定 npm 参数数组，不拼 shell。
4. 如果需要凭据，在 设置 → 本地 MCP → 编辑 → 环境变量 中填写，可选择系统安全存储或仅本次会话。不要在聊天、命令参数或安装说明中提供秘密。模型不能通过安装工具读写变量值。
5. 通过 mcp_activate_service 独立审批启动进程并验证协议、发现工具；发现成功不代表每个工具已验证可用。新发现的工具从下一次用户请求生效；每次第三方工具调用仍需审批。

安装首版只支持已在本机安装的 Node 与 npm 12+，在 /opt/homebrew/bin、/usr/local/bin、/usr/bin、/bin 查找，不安装运行时。找不到时，请自行安装或更新运行时，或手动安装 MCP 后使用“注册已有程序”。公共 registry 不是可信软件认证，用户需确认包身份和来源。

包安装在 Wisp 数据目录的 mcp-installs/<方案摘要>，不修改项目或全局 node_modules。清空继承环境，不读取用户 npmrc/认证配置，使用专用 npm 缓存和配置。先 npm install --package-lock-only，校验全部锁定依赖仅来自 https://registry.npmjs.org 且含 sha512 完整性信息，再 npm ci。两步都禁用安装脚本，且禁止 git、外部 tarball URL、本地 file/directory 依赖。需要私有 registry、编译、postinstall 下载、非 JavaScript bin 或其他包管理器的服务不属于首版范围；不能绕过失败执行任意脚本。

每次批准仅消费一次，安装串行执行，整个安装最长 180 秒。取消/超时终止包管理器直接进程，不自动重试。失败或取消可留下部分下载，不将其报告为安装成功；同方案已有未完成尝试时拒绝自动重放，需用户检查专用目录或手动安装后注册。成功记录在重启后复用，避免重复安装；配置重启仍禁用。删除配置不会卸载安装目录，首版不提供卸载/清理工具。激活审批会检测保存后的配置变化，过期请求必须重新确认。

验证使用模拟 npm runner 和临时标准 stdio 服务，并通过真实 DeepSeek HTTP/SSE adapter → Host → 安装审批 → 注册 → 独立激活审批 → 协议发现 → 下一次请求 → 工具调用审批 → 模型续答。未下载或执行真实第三方包；npm 12 在实际 macOS 环境的下载安装仍需实机验证。

安装策略参考官方 npm ci 文档的 ignore-scripts、来源限制、完整性锁文件语义。

UI 走查：qa.html → 工作台样例 → 工具交互样例 → “对话安装 → 激活 MCP（仅内存）”。先批准安装，设置中出现禁用的 QA 配置；对话再出现独立激活审批。可拒绝激活并检查配置仍禁用，或批准后检查模拟工具列表。“注册已有 MCP”样例明确不声称安装。以上只改变内存，不访问 registry，不运行进程。