klsv-saysigned

面向 AI 智能体的电子签名：注册、创建信封、签署与验证，符合 ESIGN Act 与 UETA。

## 概述（中文）

面向 AI 智能体的电子签名：注册、创建信封、签署与验证，符合 ESIGN Act 与 UETA。

## 技能正文

# SaySigned — AI 智能体电子签名技能

> **面向 AI 智能体的电子签名。** 符合 ESIGN Act 与 UETA 第 14 条，具有法律约束力。
> 两种交付模式：**API**（智能体对智能体）与 **Email**（智能体对人）。注册、签署合同、验证——均通过 REST 或同意 UI。

**发布方：** SaySigned, Inc.
**主页：** [https://www.saysigned.com](https://www.saysigned.com)
**文档：** [https://www.saysigned.com/docs](https://www.saysigned.com/docs)
**基础 URL：** `https://api.saysigned.com`
**MCP 端点：** `https://mcp.saysigned.com`
**TLS 要求：** 所有端点强制 HTTPS。连接前验证 `*.saysigned.com` 证书。

**认证：** 在 `X-API-Key` 头中传递 API 密钥。密钥以 `ss_live_` 开头。公开端点（register、verify、templates）无需认证。

## MCP 服务器（AI 智能体推荐）

直接连接远程 MCP 端点——无需本地安装，无需手工构造 HTTP 请求。

> **认证说明：** MCP 客户端发送 `Authorization: Bearer <api_key>`。MCP 服务器提取密钥并内部转发为 `X-API-Key`。直接 REST 调用请使用 `X-API-Key` 头。

### 设置

> **需要人工批准。** 步骤 1、4、5 会修改 MCP 客户端配置。写入配置文件或重启 MCP 客户端前，始终向用户展示即将更改的内容并请求确认。切勿静默修改配置。

**步骤 1.** 向用户展示以下 MCP 配置并在添加前请求确认：

```json
{
  "mcpServers": {
    "saysigned": {
      "type": "streamable-http",
      "url": "https://mcp.saysigned.com"
    }
  }
}
```

用户确认后添加到 MCP 配置。尚无需 API 密钥——公开工具立即可用。

**步骤 2.** 重启 MCP 客户端以加载新服务器。

**步骤 3.** 调用 `saysigned_register` 工具（无需认证），传入智能体 `name` 与 `email`。响应含 `api_key`——**立即保存，仅显示一次且无法再次获取。** 密钥以 `ss_live_` 开头。

**步骤 4.** 向用户展示带认证头的更新配置并在写入前请求确认：

```json
{
  "mcpServers": {
    "saysigned": {
      "type": "streamable-http",
      "url": "https://mcp.saysigned.com",
      "headers": {
        "Authorization": "Bearer ss_live_PASTE_YOUR_ACTUAL_KEY_HERE"
      }
    }
  }
}
```

**步骤 5.** 用户确认后重启 MCP 客户端以加载认证头。所有需认证工具现已可用。

> **配置变更需人工参与。** 用户必须确认后才能 (1) 添加或修改 MCP 配置项、(2) 在配置文件中存储 API 密钥、(3) 重启 MCP 客户端。注册、创建信封、签署与验证可自主处理——这些是不修改智能体配置的正常 API 操作。

### 已有密钥？

若已有 API 密钥（以 `ss_live_` 开头），跳至步骤 4——向用户展示带 `headers` 的配置，获取确认并重启。

### MCP 工作流（签署流程）

1. **Prepare the contract** — two options:
   - **Use a template:** call `saysigned_list_templates` → `saysigned_get_template` to discover required variables, then pass `template_id` + `variables` in the contract field.
   - **Bring your own text:** pass your own contract content in the `clauses` array. Each clause has `id`, `title`, and `body`. You can put an entire document into a single clause or split it into sections. **Use this when you have your own NDA, agreement, or any custom document.**
2. **Create envelope** — `saysigned_create_envelope` with `title`, `contract`, and `recipients` array.
3. **Send envelope** — `saysigned_send_envelope` with the envelope_id. Response includes each recipient's `id` and `access_token`. **Save these — they are needed for signing.**
4. **Sign** — For API recipients: `saysigned_sign` for each recipient, passing their `envelope_id`, `recipient_id`, `access_token`, and `signature_data` (at minimum `full_name`). For email recipients: the human reviews and gives consent at `doc.saysigned.com` — no action needed from the agent.
5. **Verify** — `saysigned_verify` with the envelope_id. No auth needed.

### AI 智能体关键注意事项

- **You don't have to use a template.** If you have your own contract text (an NDA, agreement, policy — any document), pass it directly via `clauses`. Templates are a convenience, not a requirement.
- **Always call `saysigned_get_template` before creating an envelope with a template.** The required variables differ per template and the API will reject unknown or missing variables.
- **`saysigned_send_envelope` returns access tokens.** You must capture and use these tokens for signing. They are 128-character hex strings.
- **Signing does not use your API key.** The `saysigned_sign` and `saysigned_decline` tools authenticate via the `access_token` parameter, not the API key header.
- **The envelope auto-completes** when the last recipient signs. You don't need to call a separate "complete" endpoint.
- **Auth header is forwarded automatically.** Authenticated tools (`create_envelope`, `send_envelope`, `get_envelope`, `get_profile`, etc.) use the API key from your MCP client's `Authorization` header. Public tools (`register`, `verify`, `list_templates`, `get_template`) work without it.
- **`delivery_method: "email"` sends a signing link to a real human.** The human reviews the contract at `doc.saysigned.com` and gives consent via browser. Email recipients do NOT get an `access_token` in the send response — they authenticate via a URL token in their email link. Use `delivery_method: "api"` (default) for agent-to-agent signing.
- **Poll or use webhooks for email recipients.** Since humans sign asynchronously, use `saysigned_get_envelope` to poll for status changes or configure a `webhook_url` to receive `recipient.viewed` and `recipient.signed` events.

### 全部 14 个 MCP 工具

| 工具 | 认证 | 说明 |
|------|------|-------------|
| `saysigned_register` | None | 注册智能体，获取 API 密钥 |
| `saysigned_create_envelope` | API key | 创建草稿信封 |
| `saysigned_send_envelope` | API key | 发送待签署，获取访问令牌 |
| `saysigned_get_envelope` | API key | 获取信封详情与状态 |
| `saysigned_void_envelope` | API key | 取消已发送（未完成）信封 |
| `saysigned_sign` | Access token | 作为收件人签署 |
| `saysigned_decline` | Access token | 拒绝签署 |
| `saysigned_verify` | None | 验证密码学完整性 |
| `saysigned_get_audit_trail` | API key | 获取哈希链审计追踪 |
| `saysigned_list_templates` | None | 列出可用合同模板 |
| `saysigned_get_template` | None | 获取模板详情与必填变量 |
| `saysigned_billing_setup` | API key | 升级到付费计划 |
| `saysigned_get_usage` | API key | 当前计费周期用量 |
| `saysigned_get_profile` | API key | 智能体档案与计划信息 |

---

## 完整端到端示例

完整工作流：注册、创建 NDA、发送、双方签署、验证。所示响应均来自真实生产 API。

### 步骤 1 — 注册（无需认证）

```bash
curl -s -X POST https://api.saysigned.com/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My AI Agent", "email": "agent@example.com"}'
```

```json
{
  "agent_id": "7773b4af-44d1-44fc-8db7-05d9bc95b541",
  "api_key": "ss_live_203bff0e53ba167462aa2cdcbd8e189e2909d37cf76c31da675cb1dba7dc0026",
  "plan": "free",
  "free_envelopes_remaining": 5
}
```

**保存 `api_key`——仅显示一次且无法再次获取。**

### 步骤 2 — 创建信封

在 `X-API-Key` 头中使用步骤 1 的 `api_key`。标准合同用 `template_id` 或通过 `clauses` 提供自定义条款。

```bash
curl -s -X POST https://api.saysigned.com/envelopes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ss_live_203bff0e53ba167462aa2cdcbd8e189e2909d37cf76c31da675cb1dba7dc0026" \
  -d '{
    "title": "Mutual NDA — Acme & Beta",
    "contract": {
      "template_id": "nda_mutual_v1",
      "variables": {
        "disclosing_party_name": "Acme Corp",
        "receiving_party_name": "Beta Inc",
        "effective_date": "2026-02-09",
        "purpose": "Evaluating a potential partnership",
        "governing_law_state": "California"
      }
    },
    "recipients": [
      {"name": "Alice", "email": "alice@acme.com", "role": "signer"},
      {"name": "Bob", "email": "bob@beta.com", "role": "signer"}
    ]
  }'
```

```json
{
  "id": "2c272d15-cd4b-4c0d-96c0-bd7438b66699",
  "status": "draft",
  "title": "Mutual NDA — Acme & Beta",
  "recipients": [
    {"id": "62f73ba5-05a0-4223-8f55-e880047a7b3e", "name": "Alice", "status": "pending"},
    {"id": "cc0aeb32-eb9d-420d-ab93-1d42400f85b9", "name": "Bob", "status": "pending"}
  ]
}
```

**保存信封 `id` 与各收件人 `id`。**

### 步骤 3 — 发送信封

消耗 1 个信封配额（免费层）或报告 1 次计量事件（付费计划）。收件人获得 `access_token`——签署时用于认证。

```bash
curl -s -X POST https://api.saysigned.com/envelopes/2c272d15-cd4b-4c0d-96c0-bd7438b66699/send \
  -H "X-API-Key: ss_live_203bff0e53ba167462aa2cdcbd8e189e2909d37cf76c31da675cb1dba7dc0026"
```

```json
{
  "id": "2c272d15-cd4b-4c0d-96c0-bd7438b66699",
  "status": "sent",
  "recipients": [
    {"id": "62f73ba5-05a0-4223-8f55-e880047a7b3e", "name": "Alice", "status": "sent", "access_token": "600b9b4297b2921396a1db138a80801c7dfb5101..."},
    {"id": "cc0aeb32-eb9d-420d-ab93-1d42400f85b9", "name": "Bob", "status": "sent", "access_token": "952340a770b96740e2696c306ad490b28556952e..."}
  ]
}
```

**保存各收件人 `access_token` 并分发给对应签署人。**

### 步骤 4 — 收件人签署

各收件人通过 `X-Access-Token` 头（推荐）或 `?access_token=` 查询参数使用其 `access_token` 签署。无需 API 密钥——令牌即认证。

```bash
# Alice 签署
curl -s -X POST "https://api.saysigned.com/envelopes/2c272