内容
# 工具列表
> [!NOTE]
> **状态：原型。** 正在编写第一批连接器，以验证工件形状是否符合评估、安装和从各种代理程序中消费的要求。 **此处内容不视为稳定契约。** 1.0 之前（`0.x`）：破坏性更改作为小版本更新，功能和修复作为补丁更新。使用插入符号 (`^0.x.y`) 锁定版本，以免自动获取破坏性小版本更新。遵循 [Elastic License 2.0](./LICENSE) 许可协议。
一个不断增长的适用于 9k+ Zapier 集成应用的代理可调用工具目录。每个工具同时是一个 [agentskills.io](https://agentskills.io/specification) 兼容的技能工件和一个 [MCP `Tool`](https://modelcontextprotocol.io/specification/2025-06-18/schema#tool) 形状的 TypeScript 模块。组合形状是贡献： neither 标准单独定义它。
该目录旨在可在**任何地方**运行：
- 作为可在任何兼容客户端（Cursor、Claude Code、Codex、Copilot、VS Code、Gemini CLI、Goose、OpenCode 等）中安装的 agentskills.io 技能
- 作为 native MCP 工具，注册到任何 MCP 服务器的 `tools/list`
- 在 Zapier 界面（Sidekick、Zapier MCP 服务器、基于代码的 Zaps）内 — Zapier 是**简单**路径，但不是唯一路径
- 通过每个连接器的声明的 `connectionResolvers`，使用用户持有的凭证在 Zapier 之外
## 使用连接器
一个连接器是一个文件夹，多个界面 — 有四种方式可以访问它：
1. **安装为 agentskills.io 技能**，在兼容的 AI 客户端中 — Cursor、Claude Code、Codex、Copilot、Goose 等约 40 个。代理读取 `SKILL.md` 并直接执行连接器的脚本，或使用脚本和 `references/` 作为生成代码的配方。
2. **在您自己的 TypeScript / Node 代码中添加为依赖**。命名导入提供每个脚本的包装 `.run(input, opts)`；默认导入添加结构化对象 (`scripts`, `connectionResolvers`) 以进行直接进程内调用。传递身份验证为一个 `[<resolver>:]<value>` 字符串： `{ connection: "env:NOTION_TOKEN" }`（或 `{ connections: { <slot>: ... } }` 用于多槽脚本）。
3. **作为 CLI 调用** — `echo '{...}' | npx @zapier/notion-connector run <script>` 在 stdin/argv 上解析 JSON 并打印上游 API 响应。Cron、GitHub Actions、Terraform，任何 shell 调用。
4. **通过捆绑的 CLI 作为本地 MCP 服务器运行** — `npx @zapier/notion-connector mcp` 通过 stdio 将每个脚本公开为原生 MCP 工具，并将连接器的 `SKILL.md` + `references/*.md` 作为 MCP 资源，无需使用者代码。
每个连接器在其自己的 `README.md` 中记录其自己的脚本、身份验证模式和设置（例如 [`apps/notion/README.md`](apps/notion/README.md)）。
### 在您自己的代码中
```ts
import notion from "@zapier/notion-connector";
const result = await notion.scripts.search.run(
{ query: "Q4 planning" },
{ connection: "env:NOTION_TOKEN" },
);
// 或导入一个脚本的运行函数，当您已经知道名称时：
import { search } from "@zapier/notion-connector";
await search({ query: "Q4 planning" }, { connection: "env:NOTION_TOKEN" });
```
身份验证是一个 `[<resolver>:]<value>` 连接字符串，每个槽位 — `env:NOTION_TOKEN` 从 `process.env.NOTION_TOKEN` 读取令牌，`zapier:<connection-id>` 通过 Zapier 管理的身份验证路由，而裸值被第一个匹配的解析器认领。
### 本地运行工具
这就是方式 1 在后台执行的操作，以及 — 交换 `node <script>` 为 `npx @zapier/notion-connector run <script>` — 方式 3（CLI）从已发布的包执行的操作。每个脚本接受 stdin 或 `argv[1]` 上的 JSON，并从 `--connection [<resolver>:]<value>` 标志解析身份验证到连接器的解析器。连接值是一个**选择器**（环境变量名称或连接 ID），而不是秘密本身，因此可以安全地在 argv 上传递；`env:` 解析器仍然从命名的环境变量中读取实际令牌。推荐通过 Zapier 连接进行身份验证；直接模式是调用者不想要 Zapier 依赖的回退：
```bash
# 使用 Zapier — Zapier 连接 UUID，身份验证由 Zapier 处理（推荐）
# 使用 zapier-sdk list-connections notion 查找连接 UUID
echo '{"query":"foo"}' | node apps/notion/scripts/search.ts --connection zapier:<connection-id>
# 直接模式 — 您自己的第三方凭证（不需要 Zapier）；令牌保留在 env 中
echo '{"query":"foo"}' | NOTION_TOKEN=secret_xxx node apps/notion/scripts/search.ts --connection env:NOTION_TOKEN
# `<resolver>:` 前缀是可选的 — 裸值进入声称它的第一个解析器
# （UUID → `zapier`，设置的环境变量名称 → `env`）：
echo '{"query":"foo"}' | node apps/notion/scripts/search.ts --connection <connection-id>
# 从已发布的包中，`node <script>` 成为捆绑的 CLI（方式 3）—
# 相同的 stdin/argv + `--connection` 契约，无需检查：
echo '{"query":"foo"}' | npx @zapier/notion-connector run search --connection env:NOTION_TOKEN
# 运行 `--help` 以查看每个脚本的输入模式和可用解析器：
node apps/notion/scripts/search.ts --help
```
连接器的 `SKILL.md` 描述了两种模式之间的权衡（设置步骤，第三方凭证的位置，吊销方式）。
Node（22.18+）直接运行 TypeScript — 首先 `npm install` 连接器的依赖。Bun 也支持，并且在第一次运行自动安装依赖。
### 克隆源代码
您不需要克隆连接器的源代码即可使用它；上述已经解释了安装和使用连接器的各种选项。但是，如果您确实想要实际的源代码 — 读取脚本代码，浏览 `references/`，运行连接器的测试，或对其进行修改 — 请使用路径过滤器克隆，以便您只获取所需的 `apps/<slug>` 文件夹，而不是整个目录：
```bash
git clone --filter=blob:none --sparse https://github.com/zapier/connectors.git
cd connectors
git sparse-checkout set apps/notion apps/trello # 只需要您需要的连接器
```
每个 `apps/<slug>` 都是独立可安装的 — 不需要根 `npm install` 或工作区引导。只需 `cd apps/<slug> && npm install`。
MCP 市场