signdocs

SignDocs Brasil — MCP 服务

一个用于 SignDocs Brasil 电子签名 API 的 Model Context Protocol 服务。它让支持 MCP 的 AI 客户端（Claude Desktop、Claude Code、Cursor、……）创建签署会话、管理多签署人的信封、上传／下载文档、验证签名并管理 Webhook——提供与官方 n8n、Zapier 和 Make.com 集成相同的操作目录。

它是基于官方 @signdocs-brasil/api SDK 的轻量适配器；OAuth2 令牌交换、缓存、重试和错误处理均由该 SDK 负责。

安装

npm install -g @signdocs-brasil/mcp-server   # or run on demand with npx

凭据

在 SignDocs 控制面板（app.signdocs.com.br → API）中创建 API 凭据，并将其设为环境变量：

变量	必填	默认值	备注
SIGNDOCS_CLIENT_ID	是	—	OAuth2 客户端 ID
SIGNDOCS_CLIENT_SECRET	是	—	OAuth2 客户端密钥
SIGNDOCS_ENVIRONMENT	否	hml	hml（预发布）或 production
SIGNDOCS_BASE_URL	否	自动推导	覆盖解析出的基础 URL
SIGNDOCS_SCOPES	否	完整集合	以空格分隔的 scope 覆盖值

请从 hml 开始。HML 数据会在约 7 天后过期，适合安全测试。 只有在准备创建具有法律约束力的真实签名时，才切换到 production。

连接 AI 客户端

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "signdocs": {
      "command": "npx",
      "args": ["-y", "@signdocs-brasil/mcp-server"],
      "env": {
        "SIGNDOCS_CLIENT_ID": "your_client_id",
        "SIGNDOCS_CLIENT_SECRET": "your_client_secret",
        "SIGNDOCS_ENVIRONMENT": "hml"
      }
    }
  }
}

Claude Code：

claude mcp add signdocs \
  -e SIGNDOCS_CLIENT_ID=your_client_id \
  -e SIGNDOCS_CLIENT_SECRET=your_client_secret \
  -e SIGNDOCS_ENVIRONMENT=hml \
  -- npx -y @signdocs-brasil/mcp-server

工具

工具	操作	安全性
create_signing_session	创建单签署人会话，返回 signingUrl	⚠️ 具有约束力 + 配额
get_signing_session_status	轮询会话状态	读取
get_signing_session	获取完整会话引导信息	读取
list_signing_sessions	按状态列出会话	读取
cancel_signing_session	取消会话	⚠️ 不可撤销
resend_signing_session_otp	重新发送 OTP	写入
create_envelope	创建多签署人信封	⚠️ 具有约束力 + 配额
get_envelope	获取信封详情	读取
add_session_to_envelope	添加签署人，返回 signingUrl	⚠️ 具有约束力 + 配额
get_envelope_combined_stamp	获取合并后的盖章 PDF URL	读取
upload_document	将 PDF 附加到交易	写入
download_document	获取预签名下载 URL	读取
list_transactions	搜索／列出交易	读取
get_transaction	获取交易详情	读取
cancel_transaction	取消交易	⚠️ 不可撤销
get_evidence	获取加密证据	读取
verify_evidence	验证公开证据	读取
verify_envelope	验证公开信封	读取
verify_document	检测 PDF 中的签名	⚠️ 仅限 PROD + 配额
register_webhook / list_webhooks / delete_webhook / test_webhook	Webhook 管理	混合

⚠️ 这些工具带有 destructiveHint 注解，并且在说明中包含警告，以便符合要求的客户端在调用前提示用户。 注解仅供提示——请检查客户端的自动批准设置。

尚未提供

@signdocs-brasil/api v1.6.1 尚不支持信任会话（/v1/trust-sessions）和 resend-invite；待 SDK 支持后将予以添加。 数字 ICP-Brasil A1 签名通过较底层的交易／advance 流程处理，而非托管会话配置文件。

资源

该服务提供模型可按需读取的上下文资源：

• signdocs://quickstart — 最简签署流程和安全说明
• signdocs://policy-profiles — 有效的 policyProfile 值和 CUSTOM 步骤
• signdocs://webhook-events — 所有可订阅的事件类型

远程 HTTP 传输（多租户）

相同的工具也通过 Streamable HTTP 提供服务，因此单个部署可以为多个 AI Agent／租户提供服务——每个租户在每个会话中都使用自己的 SignDocs 凭据进行身份验证（服务器中不会内置共享密钥）。

npm run start:http        # or: signdocs-mcp-http   (listens on PORT, default 3000)
# or containerized:
docker build -t signdocs-mcp . && docker run -p 3000:3000 signdocs-mcp

端点： POST /mcp（Streamable HTTP）。MCP initialize 请求需要身份验证，通过 Authorization 标头提供：

• Authorization: Bearer <token> — SignDocs OAuth2 访问令牌（来自 /oauth2/token），直接传递给 API。
• Authorization: Basic base64(clientId:clientSecret) — 服务器会为你执行 client_credentials 交换。
• X-SignDocs-Client-Id + X-SignDocs-Client-Secret — 相同的客户端凭据 分别通过两个普通标头传递（无需 base64），适用于无法转换值的仅支持标头的客户端。

使用 X-SignDocs-Environment: hml|production 按会话选择环境 （默认为服务器配置的默认环境）。

服务器的行为符合 OAuth 2.0 资源服务器：提供 GET /.well-known/oauth-protected-resource（RFC 9728，指向 SignDocs 授权服务器），并对未通过身份验证的 initialize 请求返回 401 + WWW-Authenticate。SignDocs API 仍是权威的令牌验证方。 GET /healthz 是无需身份验证的健康检查端点。

客户端配置示例（Bearer）：

{
  "mcpServers": {
    "signdocs-remote": {
      "type": "http",
      "url": "https://your-host.example/mcp",
      "headers": {
        "Authorization": "Bearer <signdocs_access_token>",
        "X-SignDocs-Environment": "hml"
      }
    }
  }
}

服务器环境变量： PORT、HOST、SIGNDOCS_ENVIRONMENT（默认环境）、 MCP_PUBLIC_URL（用于代理后的资源元数据）、MCP_CORS_ORIGIN、 MCP_DNS_REBINDING_PROTECTION=true + MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS （建议在生产环境中启用）。

会话保存在进程内存中，因此请运行单个实例或使用粘性路由。对于多实例／无服务器部署，请在前端使用粘性会话，或将会话映射替换为共享存储 + EventStore（以支持恢复）。计划中的生产部署方式是在现有的 external-api Lambda + API Gateway 上以 NestedStack 形式部署。

AWS Lambda

对于无服务器托管，@signdocs-brasil/mcp-server/lambda 会导出 createLambdaHandler——一个 API Gateway HTTP API v2 处理程序，可无状态运行 MCP 传输（每次调用启动一个服务器，不使用会话存储），并支持相同的 Bearer／Basic 身份验证。SignDocs 在 mcp-hml.signdocs.com.br / mcp.signdocs.com.br 上托管该服务。

import { createLambdaHandler } from '@signdocs-brasil/mcp-server/lambda';
export const handler = createLambdaHandler({ defaultEnvironment: 'hml' });

开发

npm install
npm run build      # tsc → dist/
npm test           # vitest (pure unit tests, no network)
npm run inspect    # build + launch MCP Inspector against the stdio server

路线图

• v0.1： 本地 stdio 服务器、完整工具目录、环境凭据。
• v0.2（此版本）： 远程 Streamable-HTTP 传输，支持按会话、 按租户进行身份验证（Bearer 直通或 Basic 客户端凭据），并支持 OAuth 资源服务器发现。两个传输共用工具层。
• 下一步： 将 HTTP 传输部署到 external-api（Lambda + API Gateway NestedStack）；可选的边缘 JWT 验证 + 共享存储会话，以支持水平扩展。