Sequesign

@sequesign/mcp

一个适用于 Sequesign 的 Model Context Protocol 服务——让兼容 MCP 的 Agent 为其委托工作生成可通过密码学验证的收据，并可离线验证。

它是基于 @sequesign/sdk 的轻量级本地 stdio 封装。Agent 的签名密钥不会离开本机：在 direct 模式下，SDK 会在本地为每个操作签名，托管见证方只会对哈希进行联合签名。

工具

工具	功能
sequesign_start_session	开启记录会话（一个签名操作链）。返回 sessionId（收据 ID），供其他工具使用。传入 policyContext 对象可将收据绑定到策略（达到 L3_POLICY_BOUND）。可选的 mode（direct/managed）可针对每个会话覆盖服务默认模式。
sequesign_record_action	向操作链追加签名操作。evidence 会经过哈希处理并签名。返回 actionId。
sequesign_record_approval	为已记录的操作附加本地签名的审批（例如，由人工或 Agent 审核者签字确认）。
sequesign_record_counterparty_attestation	为已记录的操作附加交易对手签署的确认（例如，供应商确认金额）。SDK 会根据经证明的操作推导内容绑定。
sequesign_approve_receipt	为已封存的收据附加独立见证的审批（延后处理的卫星项）。供审核者——人工或另一个 Agent——事后签字确认。审批者必须与记录操作的 Agent 不同。
sequesign_countersign_receipt	为已封存的收据附加独立见证的交易对手确认（延后处理的卫星项），并绑定到特定操作。
sequesign_finalize	封存并见证收据，然后运行 SDK 自带的验证。关闭会话。
sequesign_verify	离线验证已封存的收据。支持三种模式：对本地包进行完整性自检（默认）；传入见证方发布的密钥进行第三方 external 验证；或传入 receiptUrl，验证代理存储的收据（包含已注册身份的权威副本），并自动获取已发布的见证方信息和注册锚点。

为每个会话选择模式

服务默认模式由 SEQUESIGN_MODE 指定，但 sequesign_start_session 接受 mode 参数（direct 或 managed），因此同一个运行中的服务无需修改配置即可同时支持两种模式。mode: "managed" 会话仍需要托管密钥（SEQUESIGN_API_KEY + SEQUESIGN_AGENT_PRIVATE_KEY）；缺少密钥时，调用会立即失败。

验证存储的（注册身份）收据

在 managed 模式下，代理会将已注册的 agent_identity_attestation 写入存储的收据，而非本地信封，因此本地验证会显示 self_asserted。将 finalize 返回的 receipt_url 作为 receiptUrl 传给 sequesign_verify：它会获取存储的收据（使用 SEQUESIGN_API_KEY），将其与本地包进行验证，并自动获取已发布的见证方信息和注册锚点，因此结果会显示 external 信任以及registered 身份。

多方 / 延迟证明（封存后）

sequesign_approve_receipt 和 sequesign_countersign_receipt 用于证明一份已定稿的回执，且不会对其进行修改。每个工具都会生成一个独立的附属签名，通过哈希绑定到已封存的回执，在各自生成时单独进行见证，并写入软件包的 attestations.jsonl 旁路文件；验证器会将有效的附属签名合并到与回执内签名相同的批准方 / 交易对方环节中。它们接收已封存的 packageDirectory（而非活动会话），因此另一方——即使是在另一台机器上的不同模型，只要拥有该软件包——也可以稍后批准或会签。这是多方工作流的基础：一个 Agent 记录并封存工作，第二方批准，第三方确认——一份回执上有三个独立的带时间戳签名。

绑定到已注册（存储的）回执。 默认情况下，附属签名绑定到本地的 receipt.json。在托管模式下，代理存储的副本带有已注册的 agent_identity_attestation（哈希不同），因此请将 receipt_url 作为 receiptUrl 传给 approve_receipt / countersign_receipt：工具会获取存储的回执（经过身份验证，且来源在允许列表中），并将附属签名绑定到该回执。之后运行 sequesign_verify --receiptUrl，即可在同一份回执上看到已注册身份以及合并后的批准方 / 交易对方环节。将附属签名的 mode 设置为与回执封存时相同的模式。

收敛说明（跨平台）。 代理不会存储附属签名——封存后的附属签名会追加到本地软件包的 attestations.jsonl 中。因此，要让使用不同机器 / 平台的各方收敛到同一份可验证回执，.sequesign 软件包必须在各方之间传递（由编排器移动软件包，各方依次追加自己的附属签名）。支持服务器端存储附属签名的独立提交功能，未来将由代理提供。

背书（已验证的各方）

如果不传入密钥，sequesign_record_approval 和 sequesign_record_counterparty_attestation 会生成一个临时密钥，因此该环节会被验证为 present_unverified。若要使环节成为 present_verified（已背书），请先在平台上注册该方的密钥，然后传入已注册的私钥 PEM 和返回的 identityProofRef。提供平台发布的注册密钥后，sequesign_verify 会将该环节标记为 present_verified。

配置

所有配置均通过环境变量完成：

变量	默认值	说明
SEQUESIGN_MODE	direct	默认传输方式：direct（本地密钥，由独立见证方共同签名）或 managed（代理）。可通过 mode 工具参数按会话覆盖。
SEQUESIGN_WITNESS_URL	https://witness.sequesign.com	直接模式下的见证方。
SEQUESIGN_BROKER_URL	https://broker.sequesign.com	托管模式下的代理。
SEQUESIGN_DASHBOARD_API_URL	https://dashboard-api.sequesign.com	receiptUrl 验证路径中已发布注册密钥的来源。
SEQUESIGN_RECEIPT_LIBRARY_URL	https://library.sequesign.com	回执存储源。获取 receiptUrl 时，API 密钥仅会转发给此源或代理源；任何其他来源都会在发送密钥前被拒绝（防密钥外泄）。
SEQUESIGN_API_KEY	—	托管模式下必需（写入类密钥）。在直接模式下也会传给见证方——托管见证方会对签名 POST 进行身份验证，因此直接模式也需要此密钥，除非将 SEQUESIGN_WITNESS_URL 指向允许未验证签名的见证方。
SEQUESIGN_TIER	hosted	托管层级：hosted、hash-only 或 ephemeral。
SEQUESIGN_AGENT_PRIVATE_KEY	—	Agent 密钥的 Ed25519 PKCS#8 PEM。直接模式下，如果未设置，则每个会话都会生成一个新的临时密钥（身份读取结果为 self_asserted）。托管模式下必需——必须是已注册到你的 API 密钥的密钥（代理会拒绝其他 Agent 密钥）。
SEQUESIGN_PACKAGE_DIR	<tmpdir>/sequesign-mcp	回执包的写入位置。

会话在进程运行期间保存在内存中。sessionId 不会在服务重启或执行 sequesign_finalize 后保留。

安装

作为 Claude Desktop Extension（.mcpb）安装——推荐

一键安装：从 GitHub releases 下载 sequesign.mcpb，然后用 Claude Desktop 打开（设置 → 扩展 → 从文件安装）。Desktop 会根据清单中的 user_config 显示设置表单；请填写：

字段	说明
模式	direct（默认）或 managed。
API 密钥	你的写入类密钥。managed 模式下必需；在 direct 模式下用于验证托管见证方。存储在操作系统密钥链中。
Agent 私钥（PEM）	Ed25519 PKCS#8 PEM。managed 模式下必需（必须与已注册到你的 API 密钥的密钥匹配）；在 direct 模式下留空则每个会话都会生成临时密钥。存储在操作系统密钥链中。
回执包目录	密封包的写入位置。留空 → 使用临时目录。

机密信息会存入操作系统密钥链（绝不会写入清单），可选字段留空时会采用默认值。该软件包独立完整——无需设置 npm/node 项目。API 密钥和 Agent 密钥从何处获取？ 请参阅下文的 获取密钥。

从源代码构建 .mcpb：

npm run build:mcpb -w @sequesign/mcp
# → packages/sequesign-mcp/sequesign.mcpb (+ the staged mcpb-dist/ directory)

构建过程会使用 esbuild 将服务及其所有依赖打包到单个文件中，并将协议注册表/架构/配置文件复制到其旁边，然后通过 @anthropic-ai/mcpb 打包并验证。将生成的 .mcpb（及其打印出的 SHA-256）附加到 GitHub release。

发布到 npm 和官方 MCP 注册表的流程已自动化——请参阅 PUBLISHING.md。

通过 npm 安装

对于非 Desktop MCP 客户端（或者你希望自行管理配置），请从 npm 安装并通过环境变量配置——参阅下文的用法。

获取密钥（以及你将获得的身份）

这两个机密信息——你的API 密钥和Agent 私钥——来自 Sequesign 控制面板中的 Create-API-key 流程。你在托管模式下使用的密钥必须是注册到你的 API 密钥的密钥。

托管模式 — 已注册身份

在控制面板中创建 API 密钥（Settings → API keys → Create key）。 注册默认关闭，因此你必须主动启用：

1. 启用 "Register this key with an agent public key"（创建对话框中的复选框，默认未勾选；不启用的话，你只会获得普通 API 密钥，不会获得私钥 PEM，这不足以用于托管模式）。
2. 选择 "Generate keypair (recommended)"。随后，控制面板会在你的浏览器中生成 Ed25519 密钥对（私钥不会传到我们的服务器），将公钥注册到你的账户（平台会签署一条与其指纹绑定的注册记录），并且只显示一次私钥 PEM — 请立即下载。
3. 复制 API 密钥和该私钥 PEM。

将两者粘贴到设置表单中（或设置 SEQUESIGN_API_KEY 和 SEQUESIGN_AGENT_PRIVATE_KEY）。在不同安装和设备上重复使用它们 — 无需每次都创建新密钥。

使用自己的密钥（高级）。 你也可以选择 "Bring your own public key (advanced)"，并粘贴自己生成的密钥的公钥 PEM（例如在 HSM 中生成的密钥）。私钥由你持有；平台会记录公钥部分。在托管模式下完全受支持。

Broker 只接受与你的 API 密钥关联注册的 Agent 密钥 — 无论该密钥是由控制面板生成，还是由你自行提供。未注册的密钥（在本地生成且从未注册）会被拒绝（agent_public_key_not_registered）。规则是：该密钥必须登记在你的 API 密钥名下，而且这种绑定会在创建 API 密钥时完成。

验证 Broker 存储的收据后，会显示已注册的 Agent 身份（参见下方 receiptUrl 验证路径）。

直接模式 — 自我声明身份

直接模式不需要账户，也不需要注册。Agent 密钥只能证明连续性（这些收据由同一签名者生成），而非平台背书的身份。有两种选择：

• 将密钥留空 → 服务器会为每个会话生成一个新的临时密钥。适用于快速、一次性、匿名但可验证的收据；每张收据都有不同的 self_asserted 密钥。
• 粘贴固定 PEM → 在不同会话中重复使用同一稳定身份。任何 Ed25519 PKCS#8 PEM 都可使用（例如控制面板可以为你生成的密钥，或使用 openssl genpkey -algorithm ed25519 生成的密钥）。除非该密钥是注册到你的 SEQUESIGN_API_KEY 的密钥，否则它会保持为 self_asserted：在这种情况下，witness（会对同一密钥进行身份验证）会确认两者匹配，收据便会验证为已注册身份 — 既是直接签名，也是已注册身份。（witness 也会拒绝使用未注册到你的 API 密钥的密钥进行签名，因此 API 密钥不能用未注册的密钥生成收据。）

用法

将其作为 stdio 服务添加到 MCP 客户端（例如 Claude Desktop）：

{
  "mcpServers": {
    "sequesign": {
      "command": "npx",
      "args": ["-y", "@sequesign/mcp"],
      "env": {
        "SEQUESIGN_MODE": "direct"
      }
    }
  }
}

或直接运行：

npm install -g @sequesign/mcp
sequesign-mcp

示例提示词

配置好服务器后，可将这些内容提交给任何支持 MCP 的 Agent（如 Claude Desktop）。这些示例采用了实际提问时的表达方式，Agent 会自行选择工具。

1. 记录并封存一项工作，然后验证。

使用 Sequesign，为由 [email protected] 委派的任务 q3-refund-review 开启会话，记录操作 refund_approved，证据为 { "invoice": "INV-2231", "amount_usd": 480, "reason": "duplicate charge" }， 然后完成收据并验证。告诉我软件包目录，以及验证是否通过。

依次使用 start_session → record_action → finalize → verify（本地完整性自检）。

2. 多方参与：一名 Agent 记录，另外两方事后证明。

<packageDirectory> 处的收据已经封存。让 Sequesign 以 [email protected]（人工审核者）的身份为其附加一项批准，然后以 vendor-globex 的身份，为 refund_approved 操作附加一项用途为 refund_amount_confirmation 的交易对方确认。接着验证软件包，并向我展示批准和交易对方证明。

使用 approve_receipt 和 countersign_receipt（绑定到已完成收据的延后附属证明），然后使用 verify。任何另一方——即便是在另一台设备上拥有该软件包的不同模型——也能执行这些操作。

3. 验证经纪方存储的注册身份副本（托管模式）。

我已完成一份托管模式收据；其 receipt_url 为 <receipt_url>，本地软件包位于 <packageDirectory>。使用 Sequesign 根据我的软件包验证已存储的收据，并告诉我它是否显示外部信任和已注册的 Agent 身份。

使用 receiptUrl 执行 verify——获取权威存储的信封（其中包含已注册的 agent_identity_attestation），自动获取已发布的见证和注册锚点，并报告 external 信任和 registered 身份。

示例流程

1. sequesign_start_session → { taskId, delegatorId, policyContext } → 返回 sessionId。
2. sequesign_record_action → { sessionId, actionType, evidence } → 返回 actionId。
3. （可选）sequesign_record_counterparty_attestation → { sessionId, counterpartyId, attestedActionId, attestationPurpose }。
4. （可选）sequesign_record_approval → { sessionId, approverId, approvedActionType, approvalContext }。
5. sequesign_finalize → { sessionId } → 返回软件包目录和验证摘要。
6. sequesign_verify → { packageDirectory } → 随时离线重新验证。

许可证

Apache-2.0