SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI开发平台agreements-api-sdk

agreements-api-sdk

agreements-api-sdk（Shodai Agreements SDK + MCP）是 CNSLabs 提供的客户端库与 MCP 工具集，用于定义、验证、部署和运行机器可读的协议（agreements）。它把协议定义转化为可校验的协作工作流，包含可读条款、参与方、有效输入、状态、状态转换与历史记录，可供人、产品和 AI 智能体共同检查与使用。仓库支持 TypeScript SDK、MCP 智能体/工具接入，以及基于 SDK 构建的 Shodai 参考应用。托管 MCP 端点位于 https://shodai.network/mcp，采用 Streamable HTTP，要求环境参数，支持环境范围 API 密钥作为后备，且不托管私钥。主要包含 @shodai-network/agreements-api-client、@shodai-network/agreements-mcp-server、agreements-api-playground、shodai-reference-app、oauth-connect-cli 等包。

访问官网

工具介绍

用途

Shodai Agreements SDK + MCP 将协议定义转变为机器可读、可验证的协调工作流，适用于人、产品和 AI 智能体。协议本身携带可读条款，以及参与方、有效输入、状态、状态转换和历史记录。

该仓库面向三类使用者：使用 TypeScript SDK 的开发者、使用 MCP 的智能体或工具，以及基于 SDK 构建的 Shodai 参考应用。

主要能力

  • 共享的协议状态，人类、应用和智能体均可检查。
  • 依据编写的状态、输入、签发者和转换，得到确定性的下一步动作。
  • 在签名前进行验证与部署预检。
  • 支持 EIP-712 签名授权，用于部署和参与方输入。
  • 提供状态与输入历史，用于凭据和监控。
  • 减少重复的合约编排、索引以及参与方工作流管道搭建。

使用方式

托管 MCP 端点

将 Shodai 配置为远程 Streamable HTTP MCP 服务器：

  • 在支持 OAuth 的客户端发起连接，然后完成 Shodai 浏览器登录与授权同意。托管端点声明测试网授权服务器，因此此 OAuth 连接使用 environment: "testnet"。
  • 不支持 OAuth 的客户端可发送 Authorization: Bearer cns_pk_...。API 密钥仅在创建它的环境中有效；生产密钥可使用 environment: "production"。托管 MCP 从不接收私钥；写入工具使用外部签名的 EIP-712 permit 或类型化数据准备。
  • 普通浏览器 GET 请求 /mcp 可能返回 405，因为该端点期望 MCP 协议请求。docs.shodai.network 上的 MCP 界面仅用于文档和搜索；https://shodai.network/mcp 是协议执行端点。

MCP 快速上手：docs.shodai.network/sdks/quickstart-with-mcp MCP 包文档：packages/agreements-mcp-server/README.md 执行服务器卡片：shodai.network/.well-known/mcp/server-card.json MCP 目录：shodai.network/.well-known/mcp/catalog.json

安装 TypeScript SDK

大多数 TypeScript 使用者应安装已发布的 npm 包，而非此 monorepo：

npm install @shodai-network/agreements-api-client

如需用于部署和输入提交的内置 permit 签名辅助工具，请添加 viem：

npm install viem

使用具名 Shodai 环境创建客户端：

SDK 用法与 API 生命周期文档位于 packages/agreements-api-client/README.md。构造函数选项、方法、签名辅助、诊断和导出，请参见 TypeScript 客户端参考。

本地运行 MCP

为本地 stdio 客户端使用已发布的 MCP 包：

本地 stdio 模式使用 AGREEMENTS_API_ENVIRONMENT；托管 MCP 使用 environment 工具参数。自托管、环境变量、工具、资源、提示和 Inspector 用法请参见 packages/agreements-mcp-server/README.md。

协议生命周期

如需按引导完成验证、部署、签名输入提交、状态读取和输入历史，请使用端到端工作流。

Agreements API 环境

SDK 优先使用具名环境而非原始主机：

内置映射：

  • testnet -> https://test-api.shodai.network
  • production -> https://api.shodai.network

API 密钥按环境区分。测试网密钥配 testnet，生产密钥配 production。

客户端仍支持 baseUrl 作为高级覆盖，用于本地代理、内部网关或非标准部署。它仍会自动添加 /v0/*。

本地开发

默认 dev 命令启动 Shodai 参考应用。其后端默认为 http://localhost:4199，前端默认为 http://localhost:5184/agreements/。

停止参考应用 dev 栈：

所需本地环境文件请参见 apps/shodai-reference-app/README.md。

显式运行 API playground：

playground 默认 http://localhost:5176。若该端口已被占用，可在另一端口启动 playground：

对于本地浏览器开发，playground 以环境优先并默认 testnet。使用应用内环境选择器在托管 testnet 与生产 API 目标之间切换。

可选的包级验证命令：

完整环境配置请参见 apps/agreements-api-playground/README.md。

限制

  • 托管 MCP 不持有私钥。
  • 支持托管 MCP 浏览器 OAuth 和直接 API 委托 OAuth 连接路径；x402 支付不是当前设置路径。
  • Shodai 协议不声称具有法律终局性或完全自主执行能力。
  • 未经授权的签名输入，Shodai 不会移动价值。

开源项目说明

  • API 客户端消费者文档：packages/agreements-api-client/README.md
  • API 客户端维护者说明：packages/agreements-api-client/DEVELOPMENT.md
  • MCP 服务器文档：packages/agreements-mcp-server/README.md
  • Playground 文档：apps/agreements-api-playground/README.md
  • 根许可证：Apache-2.0
  • MCP 包许可证：MIT

同类工具

查看分类