ZapSign (unofficial)

zapsign-mcp

一个用于 ZapSign API 的 MCP 服务，旨在让你能够与 AI Agent 协作，而无需将签署者的个人数据交给它：

• 48 个工具：涵盖 ZapSign 公共 Postman 集合中的所有请求，以及文档中新增的请求（文档、签署者、模板、webhook、用户、套餐、背景调查、合作伙伴账户）。
• 读取操作可直接运行，写入操作每次都会询问。 更改内容的工具带有 Claude Code 的 anthropic/requiresUserInteraction 标记，因此无论处于哪种权限模式，Claude Code 都会在每次调用前询问。其他客户端只会看到读取操作。
• 生产环境为只读。 prod 服务完全不提供写入工具；sandbox 则提供全部工具。
• 模型看到的是经过筛选的答复副本。 姓名、邮箱、证件号码、州和日期会保留；CPF、CNPJ、RFC、CURP、出生日期、照片、签署链接、IP 地址、位置、电话字段、表单答案和背景调查结果会被隐藏。
• 完整答复由你保存在本地日志中；Agent 只会获得日志条目的 ID，不会知道日志的位置。
• 无需依赖项。 单个 Node 文件通过 stdio 使用 MCP；无需构建或安装任何内容。

本项目与 ZapSign 无关。ZapSign 自行发布了 MCP 服务：ZapSign/api-mcp。

要求

• Node.js 22 或更高版本。
• 你所使用的每个环境都需要一个 ZapSign API 令牌：sandbox、production 或两者都有 （ZapSign：Settings → Integration → ZapSign API）。

安装

任选一种方式：

• 从 npm 安装（推荐）。无需手动下载：Claude Code 会通过 npx -y [email protected] <environment> 启动服务，首次运行时获取该确切版本，之后则重复使用。 版本号会固定，这是有意为之：只有在你更改版本号后，才会运行新版本。 npm 上从 1.0.1 起的每个版本都由 GitHub Actions 根据此 仓库构建，且只有在维护者通过 2FA 批准后才会发布。

• 从源代码安装。 克隆仓库并使用 Node 启动服务；使用 git pull 更新。

  git clone https://github.com/BlancasJ/zapsign-mcp.git ~/zapsign-mcp
  

  然后，在下面的命令中，将 npx -y [email protected] sandbox 替换为 node ~/zapsign-mcp/bin/zapsign-mcp.js sandbox。

设置

1. 提供令牌

每个环境只读取自己的变量 ZAPSIGN_SANDBOX_TOKEN 或 ZAPSIGN_PROD_TOKEN，绝不会读取另一个环境的变量。 工具被调用时才会读取令牌，而不是在服务启动时读取。

在 macOS 上，你可以将令牌保存在钥匙串中，而不是配置文件里。未设置变量时，服务会从钥匙串读取令牌：

security add-generic-password -s zapsign-mcp-sandbox -a "$USER" -w   # asks for the sandbox token
security add-generic-password -s zapsign-mcp-prod -a "$USER" -w      # asks for the production token

2. 将其添加到 Claude Code

每个环境配置一个服务，名称分别为 zapsign-sandbox 和 zapsign-prod（下面的权限规则会用到这些名称）：

# With the token in the Keychain (macOS)
claude mcp add --scope user zapsign-sandbox -- npx -y [email protected] sandbox
claude mcp add --scope user zapsign-prod -- npx -y [email protected] prod

# With the token in a variable (any system). Claude Code keeps it in ~/.claude.json.
claude mcp add --scope user zapsign-sandbox -e ZAPSIGN_SANDBOX_TOKEN=your-token -- npx -y [email protected] sandbox

写入操作会通过 Claude Code 认可的标记进行询问（其 MCP 文档中的 “Require approval for a specific tool”）。在 dontAsk 模式下，系统不会询问，而是直接拒绝写入操作。

3. 添加权限规则和沙盒

将 examples/claude-settings.json 合并到 ~/.claude/settings.json：

• permissions.allow：读取操作（get_*、list_*）无需询问即可执行。
• permissions.ask：每个会更改内容的动词（create_*、add_*、update_*、delete_*……）都会询问。 工具上的标记已经会让 Claude Code 询问；这些规则是第二层保护。
• permissions.deny：Agent 的文件工具不得读取日志文件夹，WebFetch 不得访问 ZapSign 的 API。
• sandbox：启用 Claude Code 的 Bash 沙盒。任何 shell 命令，以及它启动的任何程序（包括 Python 或 Node 脚本），都无法读取日志文件夹或访问 ZapSign 的 API，即使你手头有令牌也不行。autoAllowBashIfSandboxed: false 会让 Claude Code 继续像之前一样在执行命令前询问；如果没有它，启用沙盒后，每条沙盒命令都会无需询问地运行。

保留 deny 规则和 sandbox 块：否则，Agent 可以打开未经筛选的回答，或绕过此服务调用 ZapSign。如果设置了 XDG_STATE_HOME，请将两处的日志路径都改为 $XDG_STATE_HOME/zapsign-mcp。

沙盒还会限制其他所有命令的操作：默认情况下，只能在工作文件夹和临时文件夹中写入；首次访问某个主机时，每个会话都会询问一次。使用 sandbox.filesystem.allowWrite 和 sandbox.network.allowedDomains 扩大权限；deniedDomains 的优先级仍高于它们。

工具

读取（可自由运行）：

工具	请求
get_document	GET /api/v1/docs/{doc_token}/
list_documents	GET /api/v1/docs/
get_document_audit_trail	GET /api/v1/docs/signer-log/{doc_token}
get_signer	GET /api/v1/signers/{signer_token}/
get_signer_validations	GET /api/v1/signer-verification-details/{signer_token}/
list_templates	GET /api/v1/templates/
get_template	GET /api/v1/templates/{template_token}/
get_plan	GET /api/v1/info-plan/
list_users	GET /api/v1/users/
get_partner_plans_csv	GET /api/v1/info-plan/partners-csv/
get_background_check	GET /api/v1/checks/{check_id}/
get_background_check_details	GET /api/v1/checks/{check_id}/details/

写入（仅限沙盒，每次调用都会先询问）：

工具	请求
create_document	POST /api/v1/docs/
create_document_async	POST /api/v1/docs/async/
create_document_from_template	POST /api/v1/models/create-doc/
create_document_from_template_async	POST /api/v1/models/create-doc/async/
add_extra_document	POST /api/v1/docs/{doc_token}/upload-extra-doc/
add_extra_document_from_template	POST /api/v1/models/{doc_token}/upload-extra-doc/
place_signatures	POST /api/v1/docs/{doc_token}/place-signatures/
reorder_envelope_documents	PUT /api/v1/docs/{doc_token}/document-display-order/
resend_notifications	POST /api/v1/docs/{doc_token}/resend-notifications-bulk/
update_document	PUT /api/v1/docs/{doc_token}/
reprocess_document	POST /api/v1/docs/{doc_token}/reprocess-doc/
delete_document	DELETE /api/v1/docs/{doc_token}/
delete_signer_groups	DELETE /api/v1/signature-group/{doc_token}/
reject_document	POST /api/v1/refuse/
reject_document_by_user	POST /api/v1/refuse/by-user/
validate_pdf_signature	POST /api/v1/validate-pdf-signature/（上传本地 PDF）
sign_in_batch	POST /api/v1/sign/
add_timestamp	POST /api/v1/timestamp/
add_timestamp_keeping_signature	POST /api/v1/timestamp/no-signature
add_signer	POST /api/v1/docs/{doc_token}/add-signer/
update_signer	POST /api/v1/signers/{signer_token}/
delete_signer	DELETE /api/v1/signer/{signer_token}/remove/
reset_signer_validation_attempts	PUT /api/v1/reset-auth-attempts/{signer_token}/
create_template	POST /api/v1/templates/create
update_template	PUT /api/v1/templates/{template_token}/
update_template_form	POST /api/v1/templates/update-form/
delete_template	DELETE /api/v1/templates/{template_token}/
create_webhook	POST /api/v1/user/company/webhook/
delete_webhook	DELETE /api/v1/user/company/webhook/delete/
create_webhook_header	POST /api/v1/user/company/webhook/header/
delete_webhook_header	DELETE /api/v1/user/company/webhook/header/delete/
create_user	POST /api/v1/users/create-user
delete_user	DELETE /api/v1/users/{user_email}/
create_background_check	POST /api/v1/checks/
create_partner_account	POST /api/v1/partner/company/
update_partner_payment_status	POST /api/v1/partner/update-payment-status/

写入操作会将请求中的 JSON 作为 body，并原样发送给 ZapSign，因此 ZapSign 的文档 中的所有选项均可使用。路径中的令牌和邮箱会先经过检查，因此无法将请求指向其他位置。

模型能看到什么

lib/response-filter.js 决定了哪些内容可见。它列出了可以显示的键；其他任何键都会保留名称，并显示为 [hidden]，因此 ZapSign 后续添加的字段会被隐藏，直到有人将其列出。

• 显示：令牌、状态、事件日期、设置、计数、姓名、电子邮件、身份证件号码。
• 隐藏：CPF、CNPJ、RFC、CURP 及类似 ID（也包括写在文本中的情况，无论是否带标点）、出生日期、照片和签名图片、签署链接和文件链接（只显示主机）、IP 地址和位置、电话字段（显示末尾 4 位数字）、表单答案、背景调查结果、webhook 标头值。
• 错误也会经过同样的过滤。

已知缺口：签署者令牌会显示，而它足以构造签署链接。写在自由文本中的电话号码、坐标或出生日期不会被屏蔽。

日志

每次调用都会完整保存，包括其参数和 ZapSign 的完整答复，存放在 $XDG_STATE_HOME/zapsign-mcp/（默认路径为 ~/.local/state/zapsign-mcp/）下的 sandbox/ 和 prod/ 中：

• 每次调用占一行 JSON，每天一个文件，保留 30 天；
• 文件夹权限为 0700，文件权限为 0600；
• webhooks.jsonl 会保留每个已创建 webhook 的 ID，且永不清理：ZapSign 没有列出 webhook 的请求，而 ID 是删除 webhook 的唯一方式。

Agent 收到的答复会给出日志条目的 ID，而不是文件夹路径。Read 拒绝规则会阻止 Claude Code 的文件工具访问日志；该规则也适用于 Claude Code 在 Bash 中识别的文件命令（cat、head、tail）；沙盒的 denyRead 则会阻止 shell 命令启动的所有程序访问日志。

限制

只有当 Agent 通过此服务操作时，过滤器和只读生产服务才有效。使用示例设置时，shell 命令既无法读取日志，也无法访问 ZapSign API（已在 macOS 上验证），WebFetch 也无法访问 API。但它们无法阻止：

• 读取令牌。 Keychain 中的令牌可以通过 security find-generic-password 读取，即使在沙盒中也可以：它请求的是系统服务，而不是文件。通过 -e 提供的令牌会存放在 ~/.claude.json 中。Agent 可以看到令牌，但无法通过 shell 命令或 WebFetch 使用它访问 ZapSign。
• 获准脱离沙盒运行的命令。 命令在沙盒内失败时，Claude 可以请求在沙盒外运行该命令（“Bash command (unsandboxed)”）；如果你批准，该命令就会在不受这些限制的情况下运行。 "allowUnsandboxedCommands": false 会禁用此选项。
• **在沙盒外运行的代码，**例如 MCP 服务和钩子。你允许 Agent 修改这些文件后，它就能改变它们的行为。

其他客户端

此服务通过 stdio 使用纯 MCP 协议，可与任何客户端配合使用。只有 Claude Code 会遵循 requiresUserInteraction 标记，因此其他客户端只会获得读取操作；即使它们调用写入操作，也会被拒绝。

生产环境写入

prod 有意设为只读。若要在生产环境中写入，请从 bin/zapsign-mcp.js 中的 ENVIRONMENTS 移除 readOnly: true。

开发

npm test

测试不会访问 ZapSign 或 Keychain。tests/zapsign-collection.json 列出了服务必须提供工具的所有请求：Postman 集合中的请求，以及只有文档中列出的请求。

发布

1. 在拉取请求中，将 package.json、server.json（两处）和 README 中 npx 命令里的版本号更新为新版本。只有这些版本号全部一致时，测试才会通过。
2. 合并后，发布一个 GitHub 版本，其标签为 v 加上版本号，例如 v1.0.1。
3. publish 工作流会检查标签与版本号是否一致、运行测试，并通过 npm 的可信发布（无需令牌）将该版本提交到 npm 进行暂存。
4. 使用双重身份验证，在 npmjs.com 上批准暂存的版本。只有批准后，该版本才会正式发布，工作流也会将其列入 MCP Registry。工作流会等待一小时以供批准；之后，请批准该版本并重新运行其 mcp-registry 作业。

许可证

MIT