文档

两种用法：把行情接给 Agent（MCP），或把数据集下载到本地用 DuckDB 查询。同一套价格口径。

MCP 快速开始

服务端是标准的 Streamable HTTP MCP，地址为 https://www.sincosone.com/mcp。任何支持 HTTP transport 的 MCP 客户端都可以直接连接。

{
  "mcpServers": {
    "auction-house": {
      "url": "https://www.sincosone.com/mcp",
      "headers": {
        "Authorization": "Bearer ah_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code 可以直接用命令行注册：

claude mcp add --transport http auction-house \
  https://www.sincosone.com/mcp \
  --header "Authorization: Bearer ah_live_xxxxxxxxxxxxxxxx"

连接后先调用 list_realms 获取合法的 realm 键，再用 search_items 把中文物品名换成 item_variant_sk，最后查询价格或历史。不要自己拼 realm 字符串。

认证与配额

• 请求头：Authorization: Bearer ah_live_...。Key 只存 SHA-256，服务端无法找回明文。
• 响应头：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（Unix 秒）。
• 超额返回 429 + Retry-After，响应体是 JSON-RPC error。
• 用量按 Key 持久化；重启服务不会重置额度。
• 日志只记录 key_id、工具、耗时、状态，不记录查询内容中的任何个人信息。

工具参考

一次典型调用链

realms  = list_realms()
item    = search_items(query="魔纹布").data.items[0].item_variant_sk
price   = get_price(item=item, realm=realms.data.realms[0].realm)
history = get_history(item=item, realm=..., days=7)

返回契约

所有工具返回同一层信封，业务数据放在 data：

{
  "ok": true,
  "as_of": "2026-10-23T08:15:09+08:00",
  "as_of_precision": "hour",
  "sample_size": 2912,
  "confidence": "high",
  "confidence_reason": "2912 件在售, 0.8h old, p95/median=...",
  "provenance": {
    "sources": 1,
    "trust": "operator-verified",
    "data_version": "20261023T004856Z-cbdd85c1",
    "artifact": "immutable-serving-parquet"
  },
  "data": {
    "realm": "CAMWOWCN1Realm1PvE Horde",
    "server_name": "PvE",
    "faction": "Horde",
    "item": { "item_variant_sk": "...", "item_id": "2589", "item_name": "亚麻布" },
    "snapshot": "2026102308",
    "price": {
      "unit": "copper",
      "unit_price_median": 79.0,
      "unit_price_p25": 78.0,
      "unit_price_p75": 349.0,
      "unit_price_p95": 391.4,
      "unit_price_max": 410.0,
      "listing_buyout_total": 1960.0
    },
    "listed_quantity": 2912
  },
  "warnings": []
}

• sample_size 是在售件数，不是挂单条数；旧引擎一条挂单可能是一组同价商品。
• confidence 由样本量、数据年龄、p95/median 与 max/median 共同决定。样本小于 5 件时不会返回 high。
• as_of 是这根日线覆盖的最后一次扫描时间；snapshot 是它所属的小时键。
• warnings 出现时，Agent 应把结论降级，而不是静默忽略。
• provenance.trust 首发是 operator-verified（单来源）。跨源校验、verified 是 11/6 之后的能力，接口不会假装已经有。

错误码

客户端配置

接口是 Streamable HTTP（无状态），不是 stdio。客户端必须支持 HTTP transport；不支持 HTTP 的旧客户端需要一个本地桥接器。

• Cursor：Settings → MCP → Add，选择 HTTP/URL，填入上面的地址与 Authorization 头。
• Claude Code：使用上面的 claude mcp add --transport http 命令。
• 自建 Agent：使用官方 mcp Python/TypeScript SDK 的 Streamable HTTP client。

DuckDB 数据集

MCP 适合点查与 Agent；批量分析请下载 DuckDB 数据集。单文件、七张数据表，不需要任何服务端账号：

curl -LO https://www.sincosone.com/downloads/forever-beta.duckdb
duckdb forever-beta.duckdb -c "SHOW TABLES"
duckdb forever-beta.duckdb -c "SELECT count(*) FROM listings"

表：listings（挂单明细）、daily_prices（日线）、 latest_prices、market_overview、items、 item_variants、realms；dataset_meta 记录 数据集版本、DuckDB 版本与各表行数。Parquet 版本仍然提供，适合直接接入现有数据湖。

Pro 的 90 天日线制品会按 flavour 与 scope_hash 发布，每个目录带 manifest.json 与 SHA-256；下游先下载到临时目录、校验、再原子切换，失败不会影响旧版本。

可用性与更新

• 目标可用性：月度 99.5%，不含维护窗口；单机部署，无多副本。
• 数据刷新：运营者每天扫描 1–2 次；list_realms 的 stale 超过 24 小时会置为 true。
• 发布：新版本以原子指针切换；MCP 重启或 POST /internal/reload 后加载新版本。
• 回滚：旧版本保留，切换指针即可；解析/发布失败不会覆盖上一版。
• 状态：/status.json（数据版本与计数）、/healthz、/readyz。