Zapier 工具接入 parolkar/dsh-zapier-mcp

dsh-zapier-mcp

把托管的 Zapier MCP 服务器接入 DeepSeek Harness——在设置里粘贴一个 token，Zapier 的工具就会成为每个会话里的智能体工具。

MIT · DSH 0.2.x · Node ≥ 22.19 · 无需构建步骤

为什么需要它

Zapier 托管的 MCP 服务器把已连接的应用都放在一个端点后面。要把这个端点接进 harness，通常得改配置文件、重启，还常常得把一个密钥留在 YAML 里。

这个插件两件事都不做。它给 DSH 配置档加一行，给 harness Web UI 加一个 Zapier MCP 页面，并把 token 存到该存的地方：配置档的凭据存储。保存时它会立刻重新连接，并告诉你结果。连接期间，它还会向模型说明 Zapier 的元工具接口怎么用，这样模型会去尝试你尚未启用的应用，而不是声称它不可用。

功能

- 托管 Zapier MCP——用你的 token 连接 https://mcp.zapier.com/api/v1/connect。没有本地 MCP 服务器，没有桥接进程。
- token 放在设置里，就在 Models 下方——一个专门的 Zapier MCP 页面，用来粘贴、重新检查和移除 token。
- 即时校验与工具刷新——保存后立刻重新连接；页面会显示 Connected — N tools available 和刷新后的工具名列表，或者显示 Token rejected 以及服务器返回的消息。
- 系统提示词里的 Zapier 知识——连接期间，插件会告诉模型：列出的工具只是脚手架，把 Zapier 的元工具名映射到它们可调用的 mcp__<serverName>__ 名称，并列出当前已启用的应用。见 系统提示词知识。
- 每个会话都生效，包括 DS Bot——这一行挂载在 harness 根上，所以工具不局限于单个会话。
- 高级端点覆盖——在 Settings → Zapier MCP → Advanced 里把插件指向另一个 MCP 端点（自托管或本地测试服务器）。
- 无需构建步骤——纯 ESM，没有转译器，没有打包器；npm test 不需要安装。
- 配置文件里没有 token——token 存在 harness 凭据存储的 credentialRef 下；配置里只带引用名。

要求

| 要求 | 版本 |
| DeepSeek Harness (DSH) | 0.2.x——基于 0.2.1-rc.2 构建并测试 |
| Node.js | >= 22.19 |
| 带托管 MCP 服务器的 Zapier 账号 | mcp.zapier.com |

插件依赖随附包 @deepseek-ai/dsh-mcp-client，版本固定为 0.2.1-rc.2，由它完成 MCP 连接和工具注册。harness 版本变化时，这个固定版本必须同步提升——见 兼容性。

安装

用 dsh plugin 把 bundle 安装到 DSH 配置档。这条命令会把剩余参数原样转发给配置档目录里的 pnpm，所以 add、remove、why 就是 pnpm 的动词：

Usage: dsh plugin [options] [args...]

manage a profile's plugins by forwarding the remaining arguments to pnpm in the
profile directory

Arguments:
args pnpm arguments, forwarded verbatim (add <pkg>, remove <pkg>,
why <pkg>, ...)

Options:
--profile <name> the profile whose plugins to manage (initialized on first
use)
-h, --help show this help

推荐：从 GitHub 安装

常规做法是用 GitHub spec，因为包的依赖会跟着一起装进来：

dsh plugin --profile web add https://github.com/parolkar/dsh-zapier-mcp

本地检出（开发）

本地路径是本地目录链接，不是打包好的副本：pnpm 就地记录这份检出，不会为它安装检出自身的依赖。bundle 会 import @deepseek-ai/dsh-mcp-client 和 @deepseek-ai/schemastery，所以在这两个依赖解析成功之前，单纯挂本地链接跑不起来。要么先安装检出的依赖：

cd /absolute/path/to/dsh-zapier-mcp
pnpm install
dsh plugin --profile web add /absolute/path/to/dsh-zapier-mcp

要么用 file: spec 安装，它会一并带上检出的依赖：

dsh plugin --profile web add file:/absolute/path/to/dsh-zapier-mcp

启用 bundle，然后重新加载

1. 按上面的方式安装包。
2. 在 harness 的 Plugins UI 里启用已安装的 bundle。启用后会应用 bundle 的 cordis.patch.yml，插入那一行 zapier-mcp —— 正是这一行挂载了插件的两半。
3. 重新加载浏览器标签页。 已经打开的页面不会加载新注册的 Settings 页面；刷新之后 Settings → Zapier MCP 才会出现。

把 web 换成你实际运行的配置档（dsh plugin --profile <name> ...）。
dsh plugin --help 显示同样的摘要；dsh --help 列出启动器参数，并确认 plugin 命令的形式。

获取 Zapier MCP token

1. 打开 mcp.zapier.com，创建一个 server，或打开已有的 server。
2. 选择你想让模型快速访问的工具（Zapier action）。之后可以再启用更多 —— 还没列出的工具从来不算缺失的能力（见 How Zapier MCP actually works）。
3. 复制 server 的 connect URL 或 token。URL 长这样：

https://mcp.zapier.com/api/v1/connect?token=<USER_ZAPIER_MCP_TOKEN>

4. 在 harness 里打开 Settings → Zapier MCP，把只有 token —— 也就是 token 查询参数的值，不是整个 URL —— 粘贴到 token 字段，然后选择 Save & verify。

使用

Settings 页面

Settings → Zapier MCP 就在 Models 正下方。它能让你：

- 粘贴 token，再点 Save & verify。保存会把 token 存进配置档的凭据存储，并立即重新连接。
- 查看验证结果。 成功时页面显示 Connected — N tools available，并列出刷新后的工具名（前 25 个；如果更多，页面会说明展示了多少个）。失败时显示 Token rejected，并附上服务端返回的消息——比如 token 无效会返回 Invalid OAuth token - please re-authenticate。页面还会显示上次检查的时间。
- Re-check。 强制发起一次新的连接尝试，刷新工具列表，不改动 token。
- Remove token。 需要再点一次确认，然后删除已存储的凭据；服务器随之断开连接。
- Advanced → MCP endpoint override。 可选，用于指定非默认的 MCP 端点 URL。留空则使用 https://mcp.zapier.com/api/v1/connect；页面会显示当前用的是哪个端点。自建端点或 本地测试服务器 就用这个字段。

页面只会知道 token 是否已配置，永远不会拿回 token 的值。

工具

连接成功后，从 Zapier 桥接过来的工具会以普通智能体工具的形式出现在模型面前，名字是：

mcp__zapier__<tool>

其中 zapier 是工具名命名空间，可通过 serverName 配置。由于这一行挂在 harness 根上，这些工具在每个会话和智能体里都可用，包括 DS Bot。

如果你在 Zapier 里改了启用的动作，去 Settings 页面点 Re-check 刷新列表；harness 不会自己轮询 Zapier。

Zapier MCP 到底怎么工作

这部分最容易让人意外，也是这个插件要注入一段系统提示词的原因。

工具列表只是脚手架，不是能力上限

Zapier 托管的 MCP 服务器从 tools/list 返回的是一组固定的约 16 个元工具，跟你连了哪些应用无关。它们是管道：发现 / 启用 / 禁用 / 检查、执行读 / 执行写、列出和管理连接、auto_provision、write_code_action、技能、反馈，以及配置 URL。连一个应用还是八十个，列表都一样。

真正的面——9,000+ 个应用——是虚拟的，在调用时才解析。某个工具不在，绝不代表某个应用不可用。 如果列表里没有 mcp__zapier__<some_app> 这个工具，那是正常的：模型本来就该通过元工具去发现并启用动作。

应用、连接、动作

三层，从最宽到最窄：

1. 应用 —— 集成（Gmail、Trello……），内部用 selected_api 值标识。
2. 连接 —— 该应用的一个已认证账号。一个应用可以有多个连接；其中恰好一个是默认连接。
3. 操作 — 针对某个应用的具体操作，按服务器逐个启用。

推荐的调用顺序

下面所有名称都省略了前缀；调用时要写成 mcp__zapier__<name>（如果你改过 serverName，则写成 mcp__<serverName>__<name>）：

1. mcp__zapier__inspect_zapier_actions — 查看当前已启用的内容。
2. 如果缺少你需要的操作：
- 用 mcp__zapier__discover_zapier_actions 找到它，然后
- 用 mcp__zapier__enable_zapier_action 把它打开。启用后可能返回一个 auth URL，用户必须打开它才能连接应用。
3. 再次调用 mcp__zapier__inspect_zapier_actions，这次带上 selected_api 和 tool_name，拿到该操作的确切参数。动态选项通过 enum_property / params 传入。
4. 读取用 mcp__zapier__execute_zapier_read_action，写入用 mcp__zapier__execute_zapier_write_action。

只有要覆盖某个应用的默认账号时，才需要 connection_id。
技能会缓存已解析好的多步流程，同一套步骤不必重新摸索。

系统提示词智能

连接存活期间，插件会注册一个有边界的系统提示词区块（zapier-mcp，紧跟在 MCP 服务器指令之后）。它包含四部分内容：

1. Zapier 裸元工具名到可调用名 mcp__<serverName>__ 的映射。
2. 一条提醒：工具列表只是脚手架，不是能力上限。
3. 当前已启用的应用及其操作数和连接数 — 例如 Enabled now: Gmail — 1 action, 2 accounts。只含应用名和计数：绝不含账号 id、账号标题或邮箱。
4. 一条规则：写入前先跟用户确认，因为 execute_zapier_write_action 会作用于真实的外部系统。

每次重新检查都会重建该区块，断开连接时它不存在（没有 token、token 被拒或连接中断，都不会添加上下文）。设 systemPrompt: false 可完全禁用它。另外，dsh-mcp-client 会原样注入 Zapier 自己的服务器指令；maxInstructionBytes 限制该区块的大小（见配置）。

配置

所有字段都是可选的，放在行配置里：

| 字段 | 默认值 | 含义 |
| serverName | zapier | 工具名命名空间。工具注册为 mcp__<serverName>__<tool>。 |
| endpoint | https://mcp.zapier.com/api/v1/connect | 托管的 Zapier MCP 端点，token 会附加到它后面。 |
| credentialRef | ZAPIER_MCP_TOKEN | 配置档凭据存储中保存 token 的键。 |
| toolCallTimeoutMs | 60000 | 单次工具调用的超时，单位毫秒（清单探测也用它）。 |
| maxInstructionBytes | 131072 | 首次连接尝试时 dsh-mcp-client 接受的服务器指令区块大小上限。 |
| instructionRetryBytes | 1048576 | 更大的上限，用于首次尝试仅因指令超出 maxInstructionBytes 而失败时的一次自动重试。 |
| systemPrompt | true | 插件是否贡献自己的 Zapier 系统提示词段落。设为 false 可退出。 |
| endpointOverride | ""（空） | 高级选项。备用或自托管的 MCP 端点。留空表示「使用 endpoint」。 |

这一行还带有运行时易变字段，由 Host 半边写入、由设置页读取：status、toolCount、toolNames、lastError、checkedAt、inventory 和 checkNonce。checkNonce 和 endpointOverride 是面向用户的触发器——改动它们（也就是设置页上「重新检查」和「高级」按钮做的事）会安排一次新的检查。这些字段你都不用手动设置。

要覆盖某个字段，从你的配置档补丁里指向已有的 zapier-mcp 行。补丁条目带 id 且不带 insert 时，会替换该行的字段；而 config 是整体替换，不做深度合并——所以你想保留的字段要全部列出来。省略的字段回退到上面的默认值。易变字段不要写：它们归 harness 设置服务所有，由它写回。

profile patch (e.g. your profile's cordis.patch.yml)
- id: zapier-mcp
name: 'dsh-zapier-mcp' # asserts the existing plugin name
config:
serverName: zapier
endpoint: https://mcp.zapier.com/api/v1/connect
credentialRef: ZAPIER_MCP_TOKEN
toolCallTimeoutMs: 120000
maxInstructionBytes: 131072
instructionRetryBytes: 1048576
systemPrompt: true
endpointOverride: '' # Advanced; set it from the Settings page instead

日常改动优先用设置页，而不是手改补丁：token、重新检查和端点覆盖在那里都有控件，并且会通过 harness 设置服务写入。

兼容性

补丁怎么组合由 harness 决定；MCP 相关的工作由 @deepseek-ai/dsh-mcp-client 包完成，本 bundle 把它精确锁定在 0.2.1-rc.2，以匹配 DSH 0.2.1-rc.2。如果你的 DSH 版本不同，症状通常是这一行挂载失败，或者工具始终注册不上。解决办法是把锁定版本提到你所用 DSH 发行版附带的 @deepseek-ai/dsh-mcp-client 版本。

工作原理

本 bundle 是一行，分两个半边：

- Host 半边——index.js，可测试的逻辑在 lib/host-logic.js，提示词文本在 lib/prompt.js。它每次连接尝试都从凭据服务解析 token（绝不缓存已轮换或已删除的 token），每次尝试都读取生效的端点（所以覆盖无需重载即可生效），挂载 @deepseek-ai/dsh-mcp-client，并在凭据变化或页面要求重新检查时重新连接。结果发布到上面的易变配置字段；系统提示词段落只是读取同一批事实。
- 浏览器半边——client.js。它注册名为 Zapier MCP 的 settings.section 页面，位置就在 模型，并与设置服务通信，保存、重新校验、删除 token，以及设置端点覆盖。

两部分都由 cordis.patch.yml 插入的同一行挂载。实现细节见仓库文件。

故障排查

| 现象 | 可能原因 | 修复 |
| 设置页显示 Token rejected，并附 Invalid OAuth token - please re-authenticate | token 无效、已过期，或来自已删除的 Zapier 服务器 | 从 mcp.zapier.com 复制新 token，重新保存。 |
| 连接返回 HTTP 401 | 同上——端点拒绝该凭证 | 在 Zapier 重新签发 token，再重新校验。 |
| 有效 token 被拒，提示类似 server instructions exceed maxInstructionBytes | Zapier 自己的指令块超过上限。插件已用 instructionRetryBytes（1048576）重试一次，仍然失败说明指令块比这还大。 | 调高 maxInstructionBytes / instructionRetryBytes。代价：这些指令会注入每个提示词，上限设得很大，每次请求都要多耗上下文。 |
| 页面一直显示 Re-check，始终不结束 | 从 harness 无法访问端点，或请求挂起 | 检查到 mcp.zapier.com 的网络/代理访问，然后重新校验。 |
| 在 Zapier 改了启用的动作后，工具列表看起来还是旧的 | 列表在连接时拉取，harness 不轮询 | 在设置页点 Re-check，刷新列表和提示词清单。 |
| 期望的工具不在列表里 | Zapier 的 tools/list 是固定的元工具集，动作是虚拟的 | 不是 bug——模型通过元工具发现并启用动作。见 How Zapier MCP actually works。 |
| 想指向别的 MCP 端点（自托管、测试） | — | Settings → Zapier MCP → Advanced → MCP endpoint override，然后保存端点。 |
| 离线或网络不稳 | 到 mcp.zapier.com 没有路由 | 恢复连接后重新校验；在此之前工具调用都会失败。 |
| DSH 升级后，行挂载失败或工具始终注册不上 | @deepseek-ai/dsh-mcp-client 的版本锁定与你的 DSH 版本不匹配 | 把锁定版本提到 DSH 发行版自带的版本，然后重启。 |
| 想彻底移除这个包 | — | 在设置页点 Remove token，再从配置档移除（dsh plugin --profile <name> remove dsh-zapier-mcp），并在插件界面里禁用它。 |

安全与隐私

- token 绝不会写入这个包，也不会写入配置档的配置文件。 它由 harness 凭证服务保存在 ~/.dsh/.credentials.yaml（文件权限 600），键为 credentialRef（默认 ZAPIER_MCP_TOKEN）。
- 设置页只知道 token 是否已配置，永远拿不到 token 的值。token 输入框是密码字段。
- 行配置和配置档的 Cordis 补丁里只存凭据的引用名，外加几个易变的运行时字段（status、toolCount、toolNames、lastError、checkedAt、inventory、checkNonce），这些字段由 harness 设置服务回写。
- 系统提示词段落只带应用名和数量，绝不带账号 id、账号标题或邮箱。
- token 只发往实际生效的 MCP 端点：配置里的 endpoint，或者你设了 endpointOverride 时的 endpointOverride。如果你把 override 指向自己无法控制的服务器，token 就会发到那里。
- 删除 token 会一并删掉已存的凭据；除此之外，这个 bundle 不会读取或缓存你 Zapier 账号的任何信息。

开发与测试

npm test

它实际执行的就是：

node --check index.js && node --check client.js && node --check lib/host-logic.js && node --check lib/prompt.js && node test/host.test.mjs && node test/prompt.test.mjs && node test/client.test.mjs

测试脚本不需要安装任何东西，这个包也没有构建步骤。index.js、client.js 和 lib/ 都是纯 ESM。

本地端到端检查

test/fake-mcp-server.mjs 是 Zapier 端点的替身，只实现够用的 MCP Streamable HTTP —— initialize、tools/list 和 tools/call —— 这样离线也能跑通成功路径：

node test/fake-mcp-server.mjs [--port 8765] [--reject]

- 默认端口是 8765。
- --reject 会按 Zapier 对无效 token 的应答方式回复每个请求（HTTP 401，Invalid OAuth token - please re-authenticate），用来跑失败路径。

它只是测试辅助文件，package.json 的发布文件列表里已排除。想拿它对接真实的 harness，先启动它，再把 Settings → Zapier MCP → Advanced → MCP endpoint override 设为 http://127.0.0.1:8765，然后保存端点。

开发环境搭建、代码风格和 PR 检查清单见 CONTRIBUTING.md。

许可证

MIT © 2026 parolkar.

与 Zapier 无关联，未获其认可或赞助。「Zapier」是其所有者的商标，此处仅用于说明本插件连接的对象。

更新日志

见 CHANGELOG.md。