@mindops/zapsign-mcp

将 ZapSign REST API 以 MCP 工具形式暴露出来的 Model Context Protocol 服务器。可将其接入任何支持 MCP 的主机（Claude Desktop、VS Code、Cursor 或你自己的 SDK 应用），让 LLM 驱动文档工作流：创建文档、管理签署人、填充 DOCX 模板、执行背景调查、管理 Webhook。

涵盖内容

工具按 ZapSign 资源分组。该集合与公开 REST API 一一对应；每个工具恰好封装一个端点。

• 文档 — 从 PDF URL / base64 / 模板创建、列表、详情、更新、删除、重新排序展示、放置签名、oneclick、附加文档、签署人活动日志

• 签署人 — 添加、更新、详情、删除、批量签署、拒签、按用户拒签、重置认证尝试、重新发送通知、验证详情、签署人分组

• 模板 — 从 DOCX 创建、更新表单字段、列表、详情、更新、删除

• 用户 — 创建、列表、删除、套餐信息

• Webhook — 创建、删除（事件负载是参考文档，不是 API 端点）

• 认证（JWT） — 获取令牌、刷新令牌（静态 API 令牌的替代方案）

• 背景调查 — 创建个人/公司调查、列表、详情

• 时间戳 — 为已签署的 PDF 或任意 PDF 加盖时间戳，且不改变签名

• 验证 — 验证已签署的 PDF

• 合作伙伴 — 合作伙伴公司管理、支付状态更新、套餐用量 CSV 报告

安装

发布到 registry 之后：

npm install -g @mindops/zapsign-mcp
# or run on demand with npx (no global install):
npx -y @mindops/zapsign-mcp

本地安装（发布前）

cd /path/to/zapsign-mcp
npm install
npm run build
npm link            # exposes `zapsign-mcp` on $PATH globally

首次发布

该包面向 npmjs.org 上的 @mindops scope，访问权限为 restricted。发布方式：

npm login                      # authenticate against registry.npmjs.org
npm publish --access restricted   # or just `npm publish` — restricted is the publishConfig default

如果 @mindops 组织在 npm 上尚不存在，请先在 https://www.npmjs.com/org/create 创建。

配置

创建 .env 文件（或在你的 MCP 主机配置中设置环境变量）：

ZAPSIGN_API_TOKEN=your-permanent-system-user-token
ZAPSIGN_ENV=production       # or 'sandbox' for the test environment

推荐使用系统用户永久令牌（ZapSign 面板中的 Configurações → API → Tokens）。绑定用户的令牌会过期并导致自动化中断。

从 MCP 主机使用

Claude Desktop / Claude Code

添加到你的 MCP 配置中（通常为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "zapsign": {
      "command": "npx",
      "args": ["-y", "@mindops/zapsign-mcp"],
      "env": {
        "ZAPSIGN_API_TOKEN": "...",
        "ZAPSIGN_ENV": "production"
      }
    }
  }
}

VS Code / Cursor

格式相同——将其放入设置中的 MCP servers 部分即可。

开发期间本地使用

npm install
npm run build
ZAPSIGN_API_TOKEN=... ZAPSIGN_ENV=sandbox node dist/index.js

该服务器使用 stdio 通信；可用任何 MCP 客户端连接以检查工具。

工具命名约定

• snake_case 命名与 ZapSign 的资源术语一致（create_document、add_signer、delete_template 等）

• 工具输入中的字段名保留 ZapSign API 的拼写（phone_country、phone_number、auth_mode、url_pdf...），以确保底层请求体与 API 期望完全一致。

• 路径参数以同名顶级字段出现（doc_token、signer_token、template_token）。

开发

npm install
npm run typecheck
npm run build

通过在 src/tools/<resource>.ts 中创建定义并重新运行 npm run build 来添加新端点。每个工具都是一个轻量封装：

registerTool(server, client, {
  name: 'create_document',
  description: 'Create a new document from a public PDF URL.',
  inputSchema: z.object({ /* fields */ }),
  handler: async (input, { client }) => client.post('/docs/', input),
});

该辅助函数负责处理错误信封格式化和 MCP 传输的 JSON 序列化。

版本管理

该包跟踪 ZapSign v1 API。ZapSign 在 /api/v1/ 之后对端点进行版本管理；如果/当 v2 发布时，此服务器将新增一个并行模块，而不是就地替换 v1。

许可证

专有（MindOps 内部使用）。再分发前请联系 MindOps。