The Spice Melange Trading Desk: DeepBook market data connector

香料香精交易台：DeepBook 市场数据连接器

面向 AI Agent 的 DeepBook v3 只读市场数据。（软件包、服务 ID 和端点沿用名称 plumbline。）

香料香精交易台（DeepBook 市场数据连接器，软件包 plumbline-mcp）是一个面向 Sui DeepBook v3 市场数据的免费、只读 Model Context Protocol 服务。它为 Agent 提供交易池、中间价和价差、订单簿深度、交易量、实时链上手续费、近期交易和 OHLCV 蜡烛图。

• 无需 API 密钥、钱包、签名或交易。 每个工具都标注为 readOnlyHint: true。
• 输出精简。 提供紧凑 JSON，序列采用列／行数组，并进行合理的舍入处理。
• 快速且友好。 使用内存 TTL 缓存（订单簿为 2 秒，元数据最长为 10 分钟）、请求去重和 8 秒超时。

免责声明：仅供教育和信息参考。本内容不构成财务、投资、法律或税务建议。 数据来自公开的第三方来源（Mysten Labs DeepBook 索引器和 Sui GraphQL）。数据可能延迟、不完整或有误，按“原样”提供，不附带任何保证。本内容不建议买入、卖出或持有任何资产。

快速开始

npx -y plumbline-mcp

该服务通过 stdio 运行，需要 Node.js 18.17 或更高版本。无需配置。

Claude Code

claude mcp add plumbline -- npx -y plumbline-mcp

Claude Desktop、Cursor、Windsurf、VS Code 或任何 stdio 客户端

将以下内容添加到客户端的 MCP 配置中（claude_desktop_config.json、~/.cursor/mcp.json 等）：

{
  "mcpServers": {
    "plumbline": {
      "command": "npx",
      "args": ["-y", "plumbline-mcp"]
    }
  }
}

Smithery

npx -y @smithery/cli@latest mcp add nazarenechalice/plumbline --client claude   # or cursor, claude-code, vscode, windsurf, ...

你也可以打开 Smithery 列表页。如需一键安装到 Claude Desktop，请在那里下载 .mcpb 软件包。

托管端点（远程，无需安装）

托管实例运行于 https://plumbline-mcp.fly.dev/mcp（可流式传输的 HTTP、无状态、返回 JSON；健康检查路径为 /health，服务卡片路径为 /.well-known/mcp/server-card.json）。

claude mcp add --transport http plumbline https://plumbline-mcp.fly.dev/mcp

任何支持远程 MCP URL 的客户端（Cursor、VS Code、Claude Desktop 连接器、Windsurf）：

{
  "mcpServers": {
    "plumbline": { "type": "http", "url": "https://plumbline-mcp.fly.dev/mcp" }
  }
}

托管端点为每个客户端每天（UTC）提供 100 次免费工具调用，之后每次调用收费 0.002 USDC，需在 Sui 主网上以 USDC 预付，每次充值约 0.01 USDC。get_indexer_status 始终免费。免费调用次数用完后，工具会返回 x402 风格的支付必需结果，其中包含确切金额和私有 payment_token；详见 docs/PAYMENTS.md。npm/stdio 软件包始终免费且没有调用限制。

流式 HTTP（可自托管）

npx -y plumbline-mcp --http --port 8081        # POST http://127.0.0.1:8081/mcp, GET /health
HOST=0.0.0.0 PORT=8081 npx -y plumbline-mcp --http

HTTP 模式为无状态模式，返回 JSON。它还会在 /.well-known/mcp/server-card.json 提供静态服务卡片，并将每个客户端的请求速率限制为每分钟 120 次。对外开放前，请将其置于 TLS 后方。托管说明见 deploy/DEPLOY.md。

向你的 Agent 提问

• “DeepBook 上 SUI_USDC 当前的价差是多少？”
• “SUI_USDC 中间价 1% 范围内有多少流动性？”
• “显示 DEEP_USDC 过去一天的 1h 蜡烛图。”
• “过去 24 小时内，哪些 DeepBook 交易池的交易量最大？”
• “SUI_USDC 当前的吃单和挂单手续费是多少？”

该服务还附带提示词（market_snapshot、compare_pools、liquidity_check）和资源（plumbline://guide、plumbline://disclaimer）。

工具

工具	返回内容	关键输入
list_pools	所有 DeepBook 池：基础资产/报价资产、最小变动价位、最小交易单位、最小数量、启用标志	asset?（例如 SUI）、include_ids?
get_mid_price	最优买价/卖价、中间价、价差（绝对值和基点）、最新价格	pool
get_order_book	每侧前 N 档，以及中间价 ±X% 范围内的基础资产数量和报价资产名义价值	pool、levels（1-100）、within_pct（例如 [0.5,1,2]）
get_volume	24 小时基础资产/报价资产交易量、最高价/最低价、涨跌幅、成交量加权平均价；或按交易量排列的顶级池；或自定义滚动时间窗口	pool?、window_hours（1-720）、top
get_pool_params	吃单方/挂单方手续费（百分比和基点）、所需 DEEP 质押、最小变动价位/最小交易单位/最小数量、白名单/稳定币标志、金库余额（实时链上数据）	pool
get_recent_trades	最新成交：时间、吃单方方向、价格、基础资产和报价资产数量、买入/卖出统计	pool、limit（1-200）、start_time?、end_time?（Unix 秒）、include_tx?
get_ohlcv	K 线，按从早到晚排列；交易量以基础资产计	pool、interval（1m,5m,15m,30m,1h,4h,1d,1w）、limit（1-500）、start_time?、end_time?
get_indexer_status	数据源健康状况和新鲜度	无
get_bm_fills	某个 BalanceManager 作为挂单方（或吃单方）的成交：时间、其方向、价格、数量、手续费和手续费代币、交易	pool、balance_manager_id、role?、limit、hours
get_swing_range	1 小时/4 小时/24 小时区间、已实现波动率、状态（CALM < 2%、ELEVATED 2-4%、HIGH_VOL > 4% 4 小时区间）以及建议档位数 3/4/5	pool
get_pool_stats	N 小时内的记分卡式统计：交易笔数、吃单方买入/卖出比例、交易量、成交量加权平均价、平均交易额、区间、价差	pool、hours（1-72）
estimate_fees	以输入代币支付的成交手续费（费率 x 1.25）与以 DEEP 支付的手续费（基础费率），基于实时链上费率	pool、qty、price?、role

池名称使用 BASE_QUOTE 格式（例如 SUI_USDC）。输入不区分大小写，sui/usdc 或 SUI-USDC 也可用。未知池会返回清晰的错误并提供建议；例如，USDC_SUI 会建议使用 SUI_USDC。

示例输出（实时数据，2026 年 10 月 9 日）

get_mid_price 使用 {"pool":"SUI_USDC"}：

{"pool":"SUI_USDC","quote":"USDC","best_bid":1.0708,"best_ask":1.07106,"mid":1.07093,"spread":0.00026,"spread_bps":2.428,"last_price":1.0708,"as_of":"2026-10-09T08:38:03.997Z"}

get_order_book 的一个深度区间（当天较早时的快照）：

{"pct":1,"bid_base":204536.4,"bid_quote":216152.61,"ask_base":105721.5,"ask_quote":113063.72,"bid_levels":26,"ask_levels":27}

get_pool_params 使用 {"pool":"SUI_USDC"}（从链上 Pool 对象实时读取；内容已精简）：

{"pool":"SUI_USDC","source":"sui-onchain","taker_fee":{"pct":0.02,"bps":2},"maker_fee":{"pct":0,"bps":0},"stake_required_deep":100000,"tick":0.00001,"lot":0.1,"min_size":1}

get_ohlcv 使用 {"pool":"SUI_USDC","interval":"1h","limit":2}：

{"pool":"SUI_USDC","interval":"1h","count":2,"cols":["open_time","open","high","low","close","volume_SUI"],"candles":[["2026-10-09T07:00:00Z",1.0658,1.07579,1.06268,1.07543,66001],["2026-10-09T08:00:00Z",1.07529,1.07817,1.06721,1.0708,26347.5]]}

配置（均为可选）

环境变量	默认值
PLUMBLINE_INDEXER_URL	https://deepbook-indexer.mainnet.mystenlabs.com
PLUMBLINE_GRAPHQL_URL	https://graphql.mainnet.sui.io/graphql
PLUMBLINE_TIMEOUT_MS	8000
PORT / HOST（HTTP 模式）	8081 / 127.0.0.1

对比

Plumbline 只读取数据。面向 DeepBook 的交易 MCP 会构建交易，有时还会持有密钥。覆盖范围更广的 Sui 分析 MCP 会涉及许多协议。Plumbline 则深入提供 DeepBook 市场数据：中间价附近的深度区间、实时链上手续费、OHLCV 和池名称建议。你可以放心将它交给任意 Agent，不会有资金风险。

数据来源：订单簿、交易、交易量和 K 线来自公开的 DeepBook 索引器。手续费和池参数通过 Sui GraphQL 从实时 Pool 对象获取。

可选：按次付费（默认关闭）

stdio 包始终免费。托管端点会对调用计量（每天免费 100 次，之后每次调用收费 0.002 USDC）。自托管 HTTP 服务的运营者也可以选择对调用计量，例如每天免费 100 次，之后每次调用收费 0.002 USDC，以 Sui 上的 USDC 支付。除非设置 PLUMBLINE_PAYMENTS=1，否则不会启用计量。该服务仅接收请求，绝不会持有密钥。完整的设计和安全模型请参阅 docs/PAYMENTS.md。

从源代码构建

git clone https://github.com/SajanMelcher/plumbline-mcp.git
cd plumbline-mcp
npm install && npm run build
node dist/index.js            # stdio; add --http for HTTP

开发

npm test            # live tests against the public indexer (SUI_USDC); needs network
npm run smoke       # spawns the server over stdio and calls every tool via the MCP client
npm run smoke:http  # same over streamable HTTP
npm run inspector   # MCP Inspector UI
npm run payments:testnet  # Sui testnet end-to-end with a throwaway payer (needs testnet SUI + USDC)
npm run pack:mcpb   # MCPB bundle at build/plumbline.mcpb, validated with mcpb + a Smithery payload check (publishes nothing)

备注和限制

• 公共索引器每侧最多提供约 100 个价格档位。如果深度区间超出此范围，响应会标记为 truncated: true，且该值为下限。
• list_pools 的参数来自索引器元数据。get_pool_params 读取链上实时的 Pool 对象，因此当治理更改刻度或费用时，它提供的数据具有权威性。
• 费用采用 DeepBook 定点值（1e9 倍率），并转换为百分比和基点。
• 不提供保证金、余额管理器或特定钱包的端点。

独立性和名称

Plumbline 的名称源自铅垂线，这是一种用于测量深度和垂直度的加重绳线。其他候选名称包括 Sounding 和 Tidemark。Plumbline 是一个独立的社区项目，与 Mysten Labs、Sui Foundation 或 DeepBook 均无关联。

许可证

MIT。请参阅 LICENSE。

商店和服务台工具（v0.3.3）

另外四个工具让 Agent 无需人工结账即可查找、购买和加入。这些工具免费（不计量）。

工具	功能
list_templates	模板、以 Sui USDC 计价的价格、许可证和购买流程（来自 thespicemelange.org/store/catalog.json）
create_template_order	创建商店订单，并返回收款方、确切金额和私有订单令牌。不会扣款。每个客户端每小时可创建少量订单。
check_template_order	提供付款摘要时：验证链上付款并返回下载链接。不提供时：返回订单状态。
get_desk_rhythm	服务台的每周节奏，并使用固定的发布密钥验证 ed25519 签名。若验证失败，调用也会失败。仅供参考。

你使用自己的钱包付款。连接器不会持有密钥或资金。你的订单令牌只会通过请求头发送到 https://thespicemelange.org（固定），且绝不会被存储。所有销售均为最终交易，不提供退款。这不是财务建议。

商店工具的安全细节：

• **固定商店：**这些工具只会与 https://thespicemelange.org 通信。预览商店需要同时设置 PLUMBLINE_STORE_URL 和 PLUMBLINE_ALLOW_PREVIEW_STORE=1，且仅用于测试。
• 收款方检查：create_template_order 会读取经过签名的 templates/versions.json，并使用固定的发布密钥进行验证。若订单的收款方与其中发布的收款方或连接器自身固定的收款方不一致，则会拒绝订单。在收款方发布之前，响应会显示 payeeVerified: false：请向你的负责人展示完整地址，并在付款前获得明确同意。

**订单限制（托管版）。**每个客户端（IPv4 地址或 IPv6 /48 网段）每小时最多可创建 3 个新订单，同时最多可有 2 个未付款订单处于待处理状态。整个服务每小时最多处理 60 个订单，同时最多可有 15 个未付款订单处于待处理状态。这些计数器存储在内存中，服务器重启时会重置。商店也会执行自身的每小时限制，并将其持久保存在 KV 中：托管连接器会发送一个商店密钥和经过哈希处理的客户端 ID（绝不发送 IP），因此商店会分别限制每个转发的客户端，而不是将连接器共享的 IP 视为单个客户端。未付款订单会在商店 30 分钟的付款时限后过期。