say-ur-intent

Sui MCP

Sui MCP 是一层以本地为先、供 AI 客户端使用的 Sui 审核与证据层。

它会将受支持的 Sui 操作转换为内部审核卡片，供你检查已验证的交易事实和 PTB 图，然后在自己的钱包中请求批准。后端会构建或验证相关材料，绑定审核过的账户和摘要，并使用 WalletConnect 发起仅签名请求。在向 Sui 主网提交一次之前，后端会验证钱包返回的字节和签名。

AI 和卡片都不会接收可执行的交易字节或签名。审核或钱包连接都不代表持续有效的交易权限。只有明确的用户操作和对该笔交易的钱包批准，才能授权此请求。如果回复丢失，系统会读取已知摘要来确认结果，不会再次发起签名或提交请求。请求失败和结果未知，与独立观察到的链上成功／失败是两回事。

账户、收据和图表卡片会独立于签名提供只读证据。连接、断开连接、审核和设置也可在 MCP 宿主内使用。设置提供本地数据控制，以及明确的连接服务恢复选项。易于阅读的审核内容并不保证安全，也不保证能完整解读每笔交易的所有细节；你仍可检查原始 PTB 结构和地址。

用户可以提出日常问题：

• “我的资产足以支付一笔 1000 美元的款项吗？”
• “我的美元计价资产合计有多少？”
• “差额是多少？”

安装

使用 npm 安装一次，然后在每个 AI 应用中注册该命令。你需要 Node.js 22 或更高版本，其中包含 npm。常规安装流程不需要 Git 检出、构建、自定义安装文件夹、数据库服务器、Sui API 密钥或端点设置。

用过较早版本？请先按照更新现有 Sui MCP 安装操作。新安装可继续执行以下步骤。

本指南介绍 0.8.2。请先确认该版本已发布，然后安装此确切版本：

npm view @zktx.io/[email protected] version
npm install -g @zktx.io/[email protected]

第一条命令必须返回 0.8.2。如果该版本不可用，请按照版本可用性说明操作；不要省略版本号并假设旧版本与本指南相符。贡献者可以使用可选的开发者检出。

在应用中注册已安装的命令。以下是 Claude Desktop 的完整默认配置；Cursor 的示例见设置指南：

{
  "mcpServers": {
    "sui-mcp": {
      "command": "sui-mcp"
    }
  }
}

Codex 则在 ~/.codex/config.toml 中使用 TOML：

[mcp_servers.sui-mcp]
command = "sui-mcp"

添加这些条目时，请保留现有设置和其他服务。选择适用于你应用的指南，了解文件位置、注册方式和启动确认步骤：

• Codex Desktop / CLI
• Claude Desktop
• Claude Code
• Cursor

应用加载注册信息后，请提问：“使用 Sui MCP 显示其包名称、服务名称、版本和网络。” 预期结果为 @zktx.io/sui-mcp、sui-mcp、0.8.2 和 mainnet。然后提问：“使用 Sui MCP 列出 Sui 主网上可用的 DeepBook 池。” 首次读取无需钱包或交易。首次使用教程介绍了预期结果、可选卡片和钱包连接。如果应用找不到 sui-mcp，请查看找不到命令。

同时使用多个应用

Codex、Claude Desktop 和其他本地 MCP 应用可以在同一台计算机上，由同一个 OS 用户同时使用同一安装。在每个应用中注册 sui-mcp。使用默认设置时，它们会共享本地后端、设置、记录和一个当前钱包连接；无需为每个应用单独配对钱包。在一个应用中更改该连接会影响其他应用，但已完成的卡片会保留原始结果。

所有应用都必须使用相同的软件包版本和配置。更新前，必须停止所有正在使用的 Sui MCP 连接，然后重启共享后端。有关共享和更新条件，请参阅使用多个应用。交互式钱包、Review 和 Settings 工作流需要支持 MCP Apps 卡片；普通读取不需要此支持。

软件包标识和本地数据

npm 软件包是 @zktx.io/sui-mcp，其代码仓库是 zktx-mcp/sui-mcp。更改客户端注册信息前，请确认所需版本可用。

请使用完整的带作用域软件包名称：不带作用域的 sui-mcp 软件包属于另一个项目。 请使用 sui-mcp 作为默认 MCP 注册名称。客户端自定义的注册别名只是本地标签，并非服务标识或授权信息。本项目处于预发布阶段：本地数据格式可能会变化，且不提供迁移功能。兼容的更新会保留当前数据目录。不兼容的数据库和备份会被拒绝，不会进行转换或自动删除。如果启动时报告数据库格式不匹配，请按照恢复说明操作。你可以保留旧文件并使用新的空数据目录，也可以明确选择丢弃旧的本地数据和设置，并使用默认设置重新开始。不会发现或导入来自其他软件包的数据。有关安装和重启共享服务的说明，请参阅设置指南。

两层产品范围

• **已实现：**通过与协议无关的适配器，实现 Sui 主网读取证据、不可签名的外部提案审查，以及绑定账户的 DeepBook 兑换审查。账户、收据、图表、连接、断开连接、审查和设置卡片使用相同的 SQLite 状态和范围限定的权限模型。后端会在收到明确的用户请求前，验证已存储的材料、所有权、报价／策略来源、人类可读事实、模拟结果和 PTB 证据。WalletConnect 仅在后端与钱包之间传递字节；普通 MCP 响应仅公开事实、请求状态和观察到的执行结果。设置负责管理端点和读取地址控件、本地备份／导入／重置，以及显式的连接服务恢复。设置操作需要用户在指定范围内确认；普通 MCP 调用只能创建卡片或读取设置。
• **安全边界：**不托管私钥、不由 MCP 或 AI 自主执行、不将不透明的外部交易字节转发给钱包，也不保证锚定价值。当前产品不会悄悄为用户选择结算代币或交易路线。不提供法币提现、损益、税务或成本基础支持。

DeepBook 通过共享的协议适配器合约，提供当前范围内的 Sui 兑换、价格和订单簿证据。钱包和 Sui 余额读取描述的是持有的资产，并不代表产品的全部功能。

Sui MCP 不托管资金、不持有私钥，也不会代表用户自主交易。 根据当前设计，它不会对交易场所进行排名、选择交易路线、推荐最优价格，也不会悄悄为用户选择结算代币。

绑定账户的交易构建、签名请求和链上观察均在本地后端完成。审查卡片会显示证据和当前允许的操作。公开审查 JSON、面向模型的卡片数据和备份绝不包含交易字节、签名、SDK 密钥或签名权限。重新打开卡片时只会读取其存储状态，不会重放金融请求。

当前版本的流程如下：

The user states an intent in natural language.
Sui MCP resolves the supported Sui mainnet evidence surface.
The AI answers only from returned evidence and boundaries.
Supported swap transaction material build is an account-bound review step, not
part of the natural-language intent evidence answer.

当前版本为受支持的 Sui 主网读取操作实现了意图证据。它还可以根据结构化的外部支付或 Sui 操作提案，创建只读、不可签名的本地审查会话。导入外部提案时，不会信任外部交易材料，也不会发送任何内容供钱包签名。

如需设置说明，请参阅 docs/MCP_SETUP.md。 如需 MCP API 参考，请参阅 docs/MCP_TOOLS.md。 如需 AI 客户端答复指南，请参阅 docs/AGENT_BEHAVIOR.md。 如需维护人员和开发者手动使用的实用工具，请参阅 docs/UTILITY_INDEX.md。

关于以美元计价的覆盖范围、余额总额和资金缺口答复的用户问题处理流程，见 docs/AGENT_BEHAVIOR.md。这些答复的响应字段见 docs/MCP_TOOLS.md。

当前支持的功能

当前版本可作为本地 stdio MCP 服务运行，并提供 Sui 主网 DeFi 证据：

• 带已验证显示单位的钱包余额；
• 币种余额分类；
• 根据固定的 DeepBook SDK 注册表元数据生成的美元计价结算资产组；
• 意图证据及响应摘要，用于回答自然语言提出的美元计价支付覆盖、余额总额和缺口问题；
• DeepBook 池、代币、中间价、订单簿上下文、原始报价、显示金额报价和账户资产；
• 用户请求的 Sui 交易摘要查询、账户活动扫描、仅针对已知钱包持久化的已发送函数活动扫描，以及已存储的规范化活动摘要；
• 只读外部提案审查会话，展示拟议操作、资产流向、接收方或目标、新鲜度、缺失证据、用户选择、不受支持的声明以及不可签名原因；
• 本地 Sui MCP 审查证据和审查会话状态读取；
• 绑定账户的 DeepBook 审查，包含已验证材料、摘要、所有权、策略、易读事实、模拟和 PTB 可视化，随后通过后端进行明确的卡片选择和钱包审批；
• 分别记录的请求状态与链上成功／失败状态，可在审查卡片中查看，也可通过常规读取获取；
• 用于查看服务器读取的任意交易摘要事实的收据卡片，独立于签名。

还包括：

• 绑定到 127.0.0.1 的本地审查服务；
• 用于存储链限定地址历史和审查证据的本地 SQLite 数据库；
• MCP 输出检查，可拒绝响应中包含禁止的可执行、签名、令牌、种子和密钥材料字段名称的内容。

屏幕

钱包连接。 一次 WalletConnect 连接会为每条已批准的链提供一个固定地址。设置可选择下次连接使用的网络，默认选择 Sui。钱包可能只返回部分地址。目前支持 Sui、Ethereum 和 Solana 主网地址；金融操作仍仅限 Sui。对于在一次连接中返回多个地址的链，该链不可用；没有账户选择器。更改钱包、地址或网络范围需要先断开连接，然后重新连接。连接和断开连接是用途各异的独立卡片。经过身份验证的查看确认后，连接操作会启动一次配对；断开连接操作则要求对指定目标进行一次确认。已结束的卡片会显示固定的、不含地址的结果，且不接受后续操作。当前地址可通过只读连接状态查看。连接不等于交易审批。

审查与结果。 审查卡片会为其固定的 Sui 账户和连接准备并更新已验证条件。断开连接并重新连接不会更改现有审查的目标。更换连接需要创建新的审查。用户检查交易图、金额和费用，然后选择“请求钱包审批”，并在钱包中批准。准备失败时提供明确的重试操作。收据和已完成的审查会显示已执行的交易图、观察到的资产变动以及网络净费用。详情会补充相同的信息。缺失的交易图或收据数据会标记为不可用。

DeepBook USDC 图表。 ui_open_chart 会打开一个内部 MCP Apps 卡片，显示所选 USDC 池的官方 DeepBookV3 Indexer K 线和交易量。保存的结果会显示所选交易对、时间间隔、UTC 时段和数据源时间。有限结果和空结果会明确标示。

当前限制

尚未实现

目前尚未实现外部提案执行。除内部 Account 和 Chart 卡片、内嵌审核回执及内部 Receipt 卡片之外的其他本地分析视图也尚未实现。对于通过计划工厂注册表处理的账户绑定 DeepBook 兑换审核，已实现交易材料审核、由用户控制的后端 WalletConnect 请求、签名验证、单次提交和独立回执监测。

外部提案接入仅支持只读本地审核会话。它接受结构化提案事实，在存储前拒绝禁止的可执行或签名字段、已识别的 Sui 私钥字符串、有效的英文 BIP39 助记词、明显的敏感标记及可疑的原始类密钥载荷，并记录该审核不可签名的原因。

被阻止的审核缺少该会话所需的证据。只有完整的 TransactionReviewData 才能将人类可读的事实和模拟结果绑定到确切的审核摘要。这是签名前的证据，不代表授权，也不保证执行。后端会在提交前检查返回的字节和所选账户的签名。请参阅适配器契约。

法币提现、损益、税务和成本基础支持不属于当前版本的范围。

永久安全与正确性边界

以下是产品边界，常规功能开发不得放宽：

• Sui MCP 不托管资金、不持有私钥，也不会自主交易。
• 它不会将 USDC、USDT 或任何以 USD 计价的结算资产视为法币 USD、银行提现金额或 USDC/USD 挂钩保证。
• 它不会将仅供报价的兑换候选项转化为支付覆盖、缺口证据、资金准备就绪、支付执行准备就绪或签名准备就绪。

按当前设计不在范围内

根据当前版本的设计，以下产品行为不在范围内：

• 它不会暗中为用户选择 USDC、USDT 或其他结算代币。它可以报告受支持的结算资产组，且仅在用户明确选择结算代币时才会使用该代币。
• 它不会对交易场所进行排名、选择路线或推荐最佳价格。

报价响应限制

read_quote_deepbook_action 和 read_quote_deepbook_display_amount 等报价工具仅返回限定范围的报价事实和原始报价证据。

其语义将报价输出标记为价格证据，而非支付覆盖或缺口证据。覆盖和缺口的答复来自 read_preview_intent_evidence.responseSummary。

仅凭报价响应，无法支持以下结论：

• 无法提供支付覆盖；
• 无法提供缺口贡献；
• 无法提供依赖路线的支付支持；
• 无法提供最终 min-out 值；
• 无法提供路线推荐；
• 无法提供交易场所比较；
• 无法提供有效价格相关声明；
• 无法提供价格影响计算；
• 无法提供报价与中间价之间的滑点；
• 无法提供法币提现估算；
• 无法进行外部市场查询；
• 无法采用 USDC/USD 挂钩假设；
• 无法提供损益；
• 无法提供成本基础；
• 无法提供可执行的签名数据。

仅限主网的产品界面

产品文档、注册表、AI 响应、UX 文案和可签名操作均仅限主网。

不受支持的协议实验不属于产品功能，也不会列入软件包文档、MCP 资源、注册表支持列表、UX 文案或可签名操作列表。

MCP 工具

权威的 MCP API 参考文档位于 docs/MCP_TOOLS.md。

服务还会提供 read_get_server_status。它会在运行时返回软件包版本、证据策略版本、implementedToolsCount 和已实现的工具列表。

DeepBook 池价格上下文通过 read_get_deepbook_mid_price 提供。有关响应字段和不支持的结论，请参阅 docs/MCP_TOOLS.md。

工具名称采用 domain_verb_object 格式。名称用于标识操作；其权限由架构、卡片可见性和权限检查定义。action_start_review 会返回一个 reviewSessionId 和一张内部 card；它不会请求签名、提交交易或返回可执行的交易字节。

文档地图

该服务仅将仓库文档的一个子集作为 MCP 资源公开。

当前面向运行时的 MCP 资源包括：

• 本 README；
• docs/MCP_SETUP.md；
• docs/MCP_TOOLS.md；
• docs/WALLET_CONNECTION.md；
• docs/AGENT_BEHAVIOR.md；
• protocols/deepbook-v3.md；
• protocols/deepbook-margin.md。

协议资源仅供参考。当前支持情况由 read_get_server_status、read_list_supported_protocols、具体工具的架构及具体工具的响应声明，而非仅由协议 Markdown 文档声明。

仅用于开发或发布审核的文档可以规定贡献者规则和检查项。

在将 AI 客户端的回答行为视为产品行为之前，必须先将其反映到面向运行时的指令、资源、提示词、架构或返回的证据字段中。

• README.md：面向公众的入口文档：产品用途、当前发布范围、设置流程和文档地图。
• docs/MCP_SETUP.md：设置指南：安装、MCP 客户端连接、首次使用流程、设置和故障排除。
• docs/MCP_TOOLS.md：API 参考：工具契约、响应字段、状态、后续操作字段和输出边界。
• docs/AGENT_BEHAVIOR.md：回答手册：用户问题处理流程、工具选择和回答措辞边界。
• docs/WALLET_CONNECTION.md：钱包连接参考：当前读取上下文、私有 SDK 的归属，以及经用户批准的交易请求。
• protocols/deepbook-v3.md：仅供参考的协议文档；当前支持情况请以 MCP 工具响应和 read_list_supported_protocols 为准。
• protocols/deepbook-margin.md：仅供参考的协议文档；此版本未公开保证金 MCP 读取工具或可签名操作。
• docs/TRANSACTION_ACTIVITY_LOG.md：交易活动证据、存储、扫描和摘要边界。
• docs/UTILITY_INDEX.md：供维护者和开发者手动使用的工具。除非明确指定为 MCP 工具，否则工具条目并非 MCP 工具；源代码检出中的脚本也不是已打包的产品命令。
• docs/LOCAL_DB_ARCHITECTURE.md：面向维护者的本地 SQLite 存储边界。
• docs/SDK_API.md：固定版本的 SDK API 说明和源码验证边界。
• docs/SIGNABLE_ADAPTER_CONTRACT.md：钱包审核适配器和 PTB 可视化契约。该文档定义签名前的审核证据和承诺边界；钱包签名需要用户点击卡片操作并在钱包中批准；字节数据仅由后端处理。

贡献者参考资料位于源代码仓库中，不属于已安装的 MCP 资源或产品命令：

• AGENTS.md：根仓库开发契约和不可妥协的产品边界。
• docs/AGENT_DEVELOPMENT_POLICY.md：贡献者开发与审核政策。
• docs/FRONTEND_POLICY.md：卡片前端实现政策。
• docs/golden-scenarios/INTENT_EVIDENCE_MATRIX.md 和 docs/golden-scenarios/BEHAVIOR_MATRIX.md：发布审核场景；当前工具响应定义了受支持的证据。

合约名称注册表

Review 卡片中的 PTB 可视化可以显示人类可读的标签来替代原始地址，也可以切换回原始地址。标签仅用于身份显示，并不代表安全性、可信度、路由质量或签名就绪状态，且只有已注册的地址会被替换为标签。

以下两个固定且基于上下文的注册表驱动此功能： src/core/action/contractNameRegistry.ts

• 包，仅在 <address>:: 路径位置替换为标签：通过 Move Registry（MVR）名称 @deepbook/core 标记 DeepBook swap 包，以及通过 Move 别名（std、sui、sui_system）标记 Sui framework 包；
• 知名 Sui 系统对象，仅在独立对象 ID 的形式下替换为标签：Clock、SuiSystemState、Random、DenyList、CoinRegistry，以及基于地址的余额 AccumulatorRoot。

如果你维护的 Sui DeFi 协议拥有已注册的 MVR 名称，并希望其包在审核图中显示该名称，请发起拉取请求，将主网包地址和 MVR 名称添加到包注册表。所有未注册地址均保留原始形式。