Shodai Agreements

@shodai-network/agreements-mcp-server

面向 Agreements API 的 Model Context Protocol 服务。将 Shodai 配置为远程 Streamable HTTP MCP 服务后，便可通过 MCP 工具调用完整的协议生命周期——编写、验证、预检、部署和提交输入。

该服务仅通过 @shodai-network/agreements-api-client 调用公开的 /v0 API，不包含业务逻辑，也不存储凭据：每次工具调用都会将调用方的 API 密钥或 OAuth 访问令牌转发到 Agreements API 网关，由网关负责身份验证、权限控制和用量计量。

托管端点

无状态 Streamable HTTP：仅支持 POST，返回 JSON，不使用服务端会话。使用以下托管配置约定：

Configure Shodai as a remote Streamable HTTP MCP server.

URL:
https://shodai.network/mcp

Auth:
Start the connection and complete Shodai browser sign-in and consent.

Tool environment:
testnet

Use this value as the environment argument on API-calling tools.

规范的托管端点会公布 Shodai 的测试网授权服务器。支持 OAuth 的 MCP 客户端会按照 RFC 9728 执行受保护资源发现，打开浏览器进行授权，并使用获得的访问令牌重新连接。此 OAuth 连接请使用 environment: "testnet"。

设置 OAUTH_AUTHORIZATION_SERVERS 后，服务会：

• 在 /.well-known/oauth-protected-resource（以及 .../mcp）提供 RFC 9728 受保护资源元数据
• 使用 WWW-Authenticate（resource_metadata=...）质询未经身份验证的 POST /mcp
• 除 API 密钥外，也接受 OAuth 访问令牌（Authorization: Bearer <jwt>）

仍支持使用 API 密钥作为回退方式和生产环境凭据。发送 Authorization: Bearer cns_pk_...，并确保密钥与工具的 environment 匹配：测试网密钥使用 testnet，生产环境密钥使用 production。

首次连接配置、工具访问和类型化数据准备请参阅：MCP 快速入门。

在本地运行（stdio）

{
  "mcpServers": {
    "shodai-agreements": {
      "command": "npx",
      "args": ["-y", "@shodai-network/agreements-mcp-server"],
      "env": {
        "AGREEMENTS_API_KEY": "YOUR_API_KEY",
        "AGREEMENTS_API_ENVIRONMENT": "testnet"
      }
    }
  }
}

Stdio 环境变量：

变量	用途
AGREEMENTS_API_KEY（或 API_KEY）	工具调用所用的 API 密钥。除非已配置 OAuth 客户端凭据，否则此项必填。
OAUTH_CLIENT_ID / OAUTH_CLIENT_PRIVATE_JWK	面向 Agent 身份的 OAuth 客户端凭据身份验证；服务会自行签发并刷新 Bearer 令牌。可替代 AGREEMENTS_API_KEY（若两者都已设置，则优先使用后者）。
OAUTH_ISSUER_URL（或 OAUTH_TOKEN_URL）	用于令牌端点发现的授权服务器发行者，或明确指定的令牌端点。使用 OAuth 客户端凭据时必填。
OAUTH_SCOPE	可选，以空格分隔要在签发令牌时请求的权限范围。
AGREEMENTS_API_ENVIRONMENT	testnet（默认值）或 production。
AGREEMENTS_API_BASE_URL	明确覆盖网关源地址。优先级高于环境设置。
AGREEMENTS_SIGNER_PRIVATE_KEY	可选的本地许可签名密钥，用于写入工具（仅限开发/测试网）。
INFURA_PROJECT_ID	Infura 项目 ID，用于为内置的 Linea、Sepolia 和 Base 协议链推导 RPC URL。
AGREEMENTS_RPC_URL、AGREEMENTS_RPC_URL_<chainId>	可选的 RPC 覆盖项，用于准备或签署许可。

工具

大多数工具通过 TypeScript 客户端调用公共 /v0 API，并携带 MCP 行为注解（readOnlyHint、destructiveHint）。少数工具会执行多项操作，以确保签名和部署安全。

在托管端点上，以下每个调用 API 的工具都需要 environment: "testnet" | "production"。本地 stdio 模式则使用 AGREEMENTS_API_ENVIRONMENT 指定的固定环境。

工具	封装的 API	权限范围
list_agreements	GET /v0/agreements	agreements.read
get_agreement	GET /v0/agreements/{id}	agreements.read
get_agreement_document	GET /v0/agreements/documents/{documentId}	agreements.read
get_agreement_state	GET /v0/agreements/{id}/state	agreements.read
get_input_history	GET /v0/agreements/{id}/inputs	agreements.read
validate_agreement	POST /v0/agreements/validate-template	agreements.write
preflight_deployment	POST /v0/agreements/validate	agreements.write
deploy_agreement	POST /v0/agreements/validate，然后调用 POST /v0/agreements/deploy-with-permit	agreements.write
submit_input	POST /v0/agreements/{id}/input	agreements.write
prepare_deployment_typed_data	POST /v0/agreements/validate，然后本地构造 EIP-712 载荷并读取链上 nonce	agreements.write
prepare_input_typed_data	GET /v0/agreements/{id}，然后本地构造 EIP-712 载荷并读取链上 nonce	agreements.write

可通过 resources/list 发现资源：

资源	URI
simple-example-agreement	agreements://examples/simple-agreement.json
complex-example-agreement	agreements://examples/complex-agreement.json
authoring-guide	agreements://docs/author-agreement-json.md
docs-index	agreements://docs/index.md

提示词：author_agreement（业务描述 → 协议 JSON）。

签名托管模式

部署和提交输入需要 EIP-712 授权签名。支持以下三种模式：

1. 预签名授权 — Agent 或宿主应用持有钱包，在外部签名，然后将 signer/deadline/signature 传递给 deploy_agreement 或 submit_input。
2. 准备类型化数据，在外部签名 — 调用 prepare_deployment_typed_data / prepare_input_typed_data 获取准确的 EIP-712 载荷，使用任何支持 EIP-712 的签名器签名，然后调用写入工具。对于部署，将返回的 normalizedInitValues、normalizedParticipants 和 normalizedObservers 连同签名一起传回 deploy_agreement。
3. 本地环境签名器（仅限 stdio） — 设置 AGREEMENTS_SIGNER_PRIVATE_KEY，写入工具即可在本地签名。适用于开发和 testnet 流程；托管端点绝不会使用服务器端密钥签名。

最简托管流程：读取 simple-example-agreement，调用 validate_agreement、preflight_deployment，再调用 prepare_deployment_typed_data，并传入 environment/agreement/chainId/signerAddress 及预期的部署上下文；在外部签名后，调用 deploy_agreement，并传入相同的 environment、displayName、匹配的 docUri、规范化后的部署字段及授权签名字段。对于输入，调用 prepare_input_typed_data 并传入 environment/agreementId/inputId/values/signerAddress，在外部签名后使用相同的 environment 调用 submit_input，然后重新读取状态和输入历史。

托管 MCP 只接收已签名的授权字段，绝不会接收私钥。使用私钥环境变量签名仅适用于本地 stdio 开发和 testnet 自动化。

自托管

npm install @shodai-network/agreements-mcp-server
agreements-mcp-server-http   # Streamable HTTP on PORT (default 3905), endpoint /mcp

HTTP 环境变量：PORT、HOST、MCP_PATH、PUBLIC_MCP_URL、AGREEMENTS_API_TESTNET_BASE_URL、AGREEMENTS_API_PRODUCTION_BASE_URL，以及用于单源测试的可选本地 AGREEMENTS_API_BASE_URL。如果发现元数据应公布与请求主机不同的规范公共端点，请设置 PUBLIC_MCP_URL。

已包含用于容器部署的 Dockerfile。GET /healthz 用作健康检查端点。

开发

pnpm install
pnpm --filter @shodai-network/agreements-mcp-server build
pnpm --filter @shodai-network/agreements-mcp-server test

使用 MCP Inspector 进行交互式验证：

npx -y @modelcontextprotocol/inspector@latest --cli http://localhost:3905/mcp \
  --transport http --method tools/list --header "Authorization: Bearer $SHODAI_API_KEY"

固定使用 @latest：较旧版本的 Inspector 不支持对 URL 目标使用 --transport/--header。

许可证

MIT — 请参阅 LICENSE。请注意，此软件包单独采用 MIT 许可；此仓库中的其他软件包采用 Apache-2.0 许可。