SignWell

SignWell MCP 服务

用于编排 SignWell 电子签名工作流的 Model Context Protocol 服务。

前提条件

• Node.js v18 或更高版本。
• 具有文档访问权限的 SignWell API 密钥（SIGNWELL_API_KEY 环境变量）。
• 可选覆盖项：
  • 非生产环境端点使用 SIGNWELL_API_BASE_URL。
  • 使用 SIGNWELL_API_TIMEOUT_MS 调整 HTTP 客户端超时时间（默认值为 90000 ms；在 setup 中使用 CLI 标志 --timeout 可跳过环境变量提示并写入此覆盖值）。

设置

交互式向导（推荐）

1. 如果尚未安装依赖项，请先安装：

   npm install
   

2. 打包 CLI，以便 MCP 客户端指向构建输出：

   npm run build
   

3. 运行向导并按照提示操作：

   node build/index.js setup
   

   • 将 SignWell 密钥存储在 Linux 上的 ~/.config/signwell-mcp/env、macOS 上的 ~/Library/Application Support/SignWell/MCP/env，或 Windows 上的 %APPDATA%/SignWell/MCP/env 中，并设置 0700/0600 权限。
   • 自动更新 Claude Desktop、Claude Code、Cursor 和 OpenCode 配置文件（每次写入前都会创建备份），无需手动查找各平台的路径。
   • 客户端目标：
     • Claude Code：~/.claude.json 中的 mcpServers.signwell
     • Claude Desktop：claude_desktop_config.json 中的 mcpServers.signwell
     • Cursor：~/.cursor/mcp.json 中的 mcpServers.signwell
     • OpenCode：~/.config/opencode/opencode.json 中的 mcp.signwell（Windows：%USERPROFILE%\.config\opencode\opencode.json）
   • 使用各客户端文档规定的 JSON 封装格式和 STDIO/本地服务结构，确保服务在客户端重启后可见。
   • 如果之前安装的 Claude Code 将过时的 ~/.claude/mcp.json servers.signwell 条目写入了文件，重新运行设置会备份该旧版文件，并在写入正确的 ~/.claude.json 配置后仅移除过时的 SignWell 条目。
   • 使用 --print（或 -p）可预览输出而不写入磁盘；使用 --yes --api-key=... 可进行非交互式运行（适用于 CI、开发容器等）。
   • 传入 --clients=claude-desktop,cursor 可指定向导要配置的 MCP 客户端；省略则表示“全部”。仅在需要非默认 HTTP 超时时使用 --timeout=<ms>。
   • 打包（npm run build）并发布软件包后，最终用户可通过 npx @signwell/mcp setup 调用同一向导。全局安装后，也可直接调用 signwell-mcp setup。

手动导出

更倾向于自行管理环境变量？运行服务前导出所需的值：

export SIGNWELL_API_KEY="your_api_key"
# export SIGNWELL_API_BASE_URL="https://www.signwell.com/api/v1"   # optional

安装（npm）

软件包发布到 npm（GitHub：Bidsketch/signwell-mcp）后：

• 无需全局安装即可运行设置向导：

  npx @signwell/mcp setup
  

• 如果希望使用持久的二进制文件，可全局安装：

  npm install -g @signwell/mcp
  signwell-mcp setup
  

配置完成后，通过 signwell-mcp 启动 MCP 服务（需要 Node.js v18+）。

signwell-mcp.mcpb 文件是独立的 Claude Desktop 扩展产物。它使用根目录下的 manifest.json，发布版本时应在运行 npm run build 后重新构建。

本地开发工作流

1. 安装依赖项：npm install

2. 打包 CLI 入口点（MCP 客户端配置所必需）：npm run build

3. 配置凭据：node build/index.js setup（或发布后运行 npx @signwell/mcp setup）

4. 在本地启动 MCP 服务：npm start（运行 node build/index.js）

5. 打开另一个终端，在提交前运行测试和代码检查工具：

   npm test
   npm run typecheck
   npm run lint
   

6. 使用 MCP inspector 或其他客户端时，将其指向 npm start（stdio）。

运行服务

• 开发入口（stdio 传输）：

  SIGNWELL_API_KEY="$SIGNWELL_API_KEY" npm start
  # or run directly:
  SIGNWELL_API_KEY="$SIGNWELL_API_KEY" node build/index.js
  

• CLI 辅助命令：

  • node build/index.js --help 会显示用法和环境变量要求。
  • node build/index.js --version 会显示当前构建版本。
  • 从源代码运行时，node build/index.js setup 会启动上文所述的设置向导。
  • 打包并发布后，npx @signwell/mcp setup 会运行设置向导，而 SIGNWELL_API_KEY=... npx @signwell/mcp 会通过打包后的二进制文件启动服务（全局安装后可直接调用 signwell-mcp ...）。

MCP Inspector

使用 MCP inspector 在本地测试工具：

npx @modelcontextprotocol/inspector node build/index.js

测试

按顺序运行质量检查：

npm test
npm run typecheck
npm run lint
npm run format

演示

MCP inspector 会话示例（ID 已脱敏）：

1. 创建草稿

   Tool: document_create
   Input: {
     "name": "Sales Agreement",
     "recipients": [{ "id": "1", "name": "Alice Example", "email": "[email protected]" }],
     "files": [{ "name": "agreement.pdf", "file_url": "https://files.example.com/agreement.pdf" }]
   }
   Output:
   {
     "ok": true,
     "type": "document_create",
     "message": "Document draft created.",
     "data": {
       "id": "doc_123",
       "status": "draft"
     }
   }
   

2. 发送草稿

   Tool: document_send_draft
   Input: { "document_id": "doc_123", "confirm_send": true }
   Output:
   {
     "ok": true,
     "type": "document_send_draft",
     "message": "Send request accepted.",
     "data": { "id": "doc_123", "status": "Sent" },
     "warnings": ["Status may update asynchronously. If this response still shows Draft, call document_get after a few seconds; do not send again. Recipient send_email is an embedded-signing setting, not an email-delivery receipt."]
   }
   

3. 检查状态

   Tool: document_get
   Input: { "document_id": "doc_123" }
   Output:
   {
     "ok": true,
     "type": "document_get",
     "message": "Fetched document status.",
     "data": {
       "id": "doc_123",
       "status": "completed",
       "recipients": [{ "email": "[email protected]", "status": "signed" }]
     }
   }
   

4. 已完成的 PDF

   Tool: document_completed_pdf
   Input: { "document_id": "doc_123" }
   Output:
   {
     "ok": true,
     "type": "document_completed_pdf",
     "data": {
       "pdf_url": "https://signwell-downloads.example.com/doc_123.pdf"
     }
   }
   

隐私政策

本节介绍 SignWell MCP Server 的数据处理实践。

数据收集

• MCP 服务本身不会收集、传输或存储任何个人数据或使用情况分析数据。
• 您的 SignWell API 密钥会以严格的文件权限（0600）存储在您机器上因平台而异的安全位置：
  • macOS： ~/Library/Application Support/SignWell/MCP/env
  • Linux： ~/.config/signwell-mcp/env
  • Windows： %APPDATA%/SignWell/MCP/env

使用与存储

• 通过 file_store 提供的文件会暂时存储在内存中，TTL 为 60 分钟，并会自动清除。
• 所有内存中的文件数据也会在服务重启时清除。
• 除设置期间创建的凭据文件外，不会持久存储任何数据。

与第三方共享

• MCP 服务不会与任何第三方共享数据。
• 所有 API 通信均在您的机器与 SignWell 的服务器之间直接进行（https://www.signwell.com/api/v1）。

遥测与分析

• 服务不会以任何形式收集、传输或存储使用情况分析数据或遥测数据。

数据保留

• 内存中的文件存储会在服务重启或 60 分钟 TTL 到期后清除。
• 除本地凭据配置文件外，不会保留任何持久数据。

联系方式

如有隐私相关疑问，请联系 [email protected]，或在 github.com/Bidsketch/signwell-mcp/issues 提交问题。

另请参阅托管的隐私政策：https://www.signwell.com/privacy/。

资源

• MCP 资源：document://{id} 和 template://{id} 会公开只读 JSON 快照，并复用与工具相同的规范化逻辑，因此检查器或其他 MCP 客户端可以快速浏览之前创建的内容。

附加文件与草稿安全

• document_create 和 template_create_document 始终设置 draft: true，确保您主动调用 document_send_draft 之前，不会发送任何电子邮件。
• 使用 files 数组提供文件，可选择 file_url（公开 URL，或您在 Claude Desktop 等 UI 中使用 @ 附加文件时 MCP 客户端提供的链接）、file_base64 或 resource_uri。提供 resource_uri 时，MCP 服务会自动调用 resources/read 获取附件字节，并将其转发到 SignWell 的 /api/v1/documents/ 端点。

文档更正与签署日期

• **收件人姓名：**在每个 document_create 收件人中传入 name。如果省略 name，系统会合并旧版字段 first_name 和 last_name。设置 test_mode: true 可创建不具约束力的测试文档，且不会产生 API 费用。
• 草稿设置：document_send_draft 接受 name、subject、message、expires_in 和 reminders 等可选更新，以及 confirm_send: true。未提供的设置会保留。它无法编辑收件人、文件或字段，也无法在不发送的情况下保存更改。
• **已发送文档的收件人：**调用 document_get 获取收件人 ID，然后调用 document_update_recipients，并传入 document_id、confirm_update: true 和 recipients: [{ "id": "<returned recipient ID>", "name": "Correct Name", "email": "[email protected]" }]。必须同时包含姓名和电子邮件地址，并保留未更改的值。对于已发送、已查看、待处理或退信的文档，只有尚未开始签署的收件人可以更改。非嵌入式收件人会收到新的通知邮件；嵌入式收件人则遵循其现有的 send_email 设置。
• **撤回文档：**使用 document_id 和 confirm_delete: true 调用 document_delete，即可删除文档并取消正在进行的签署。创建替代文档前，请先删除错误的请求，以免产生两个有效请求。
• **发送状态：**发送成功后会返回“Send request accepted”，并尝试刷新一次状态。如果刷新失败，已接受的发送仍视为成功。状态可能仍有延迟；请等待几秒后使用 document_get，不要重新发送。send_email 是嵌入式签署选项，不是投递回执。

若要自动填入并锁定签署日期，请将 text_tags: true 与以下现有的 SignWell 文本标签搭配使用：

{{signature:1:y}} {{autofill_date_signed:1:y}}
{{signature:2:y}} {{date:2:y::::::y}}

这两种日期格式都会锁定签署日期。对于应由签署人选择的日期，普通的 {{date:1:y}} 仍可编辑。文本标签解析是异步的：处理完成后，使用 document_get 检查字段。请参阅 SignWell 的文本标签选项、收件人更新以及更新和发送的限制。

可用脚本

脚本	用途
npm start	通过 stdio 执行 MCP 服务入口点（运行 npm run build 后）。
npm test	运行测试套件。
npm run typecheck	使用 tsc --noEmit 对项目进行类型检查。
npm run lint	使用 Biome 检查源代码和测试。
npm run format	使用 Biome 应用仓库格式规范。
npm run build	使用 esbuild 在 build/index.js 生成 ESM 包。

目录结构

.
├── src/                # MCP server source (entrypoint + domain modules)
│   └── setup/          # Interactive setup wizard for MCP client configuration
├── test/               # Test suites
├── build/              # Bundled output (ignored in releases)
├── biome.json          # Biome lint/format configuration
└── tsconfig.json       # TypeScript compiler configuration