Versum

Versum Agent Assistant

AI Agent 可以查找本地商家、查看商品、查询库存和价格，并发起真实订单或预约。

为什么

本地商家几乎无法被 AI Agent 发现。菜单、价目表和预约页面都是为人设计的；Agent 无法给店铺打电话，许多商家甚至没有 Agent 能使用的网站。Versum 会读取各商家发布的信息，将其整理成每家商户一张卡片，附上可用于下单、预约或咨询的真实链接，并将卡片提供给任何 MCP 客户端。

60 秒快速入门

两个 MCP 入口，均使用可流式传输的 HTTP——无需密钥、账号或付费：

入口
https://versum.suverse.io/mcp/catalog	免费商家目录：仅包含下方 15 个工具（推荐）
https://versum.suverse.io/mcp	面向没有密钥的客户端提供相同的 15 个工具（使用 Versum 节点密钥时，此入口用于计算）

Claude — Customize → Connectors → Add custom connector → URL https://versum.suverse.io/mcp/catalog → Add。 无需登录。

ChatGPT（支持 Developer mode 的套餐）——在连接器设置中开启 Developer mode，然后使用 MCP URL https://versum.suverse.io/mcp/catalog 创建一个连接器，无需身份验证。不同版本的 ChatGPT 菜单名称可能有所不同。

Cursor（~/.cursor/mcp.json）或任何接受 JSON 服务列表的客户端：

{
  "mcpServers": {
    "versum": { "type": "http", "url": "https://versum.suverse.io/mcp/catalog" }
  }
}

已通过官方 MCP TypeScript SDK 客户端验证，且配置项与此完全一致：列出 15 个工具，并成功收到实时调用的响应。

发送一个请求——调用 search_catalog，参数为 {"query": "a dozen red roses delivered", "location": "Miami, FL", "limit": 3}——即可获得实时结果（2026-11-02），以下截取第一家商户：

{
  "found": 12,
  "returned": 3,
  "businesses": [
    {
      "id": "f2f197e1-7e39-4794-9e3c-54a77a75ef24",
      "name": "More Than Flowers",
      "trade": "Florist",
      "miles_away": 2.1,
      "offerings": [
        {
          "id": "e9a2aebb-cd9e-4627-8d8d-84d866a26bee",
          "title": "Three Dozen Roses - Hot Pink",
          "price": 135,
          "availability": "in_stock",
          "link": "https://morethanflowersmiami.com/miami-more-than-flowers/three-dozen-roses-hot-pink.html?ref=versum"
        }
      ],
      "can": ["check_delivery", "contact", "order"],
      "links": {
        "order": "https://morethanflowersmiami.com/miami-more-than-flowers/mayflower-wrapped-bouquet.html?ref=versum",
        "contact": "tel:+17865876195"
      }
    }
  ]
}

自行读取任何商家的网站

reader/ 是 Versum 自带的开源读取器：目录使用的同款读取器，可在你的机器上读取任何网站——包括商品及价格、下单、预约或咨询入口、营业时间和联系方式，并为每个值附上读取来源文字。不使用 Google、代理或浏览器；遵守 robots.txt；仅在使用你自己的 ANTHROPIC_API_KEY 时调用模型（使用 --no-model 可将其关闭）。

cd reader && npm install && npm run build
node dist/cli.cjs read https://example-business.com --pretty

共享缓存免费且默认启用（使用 --no-share 或 VERSUM_SHARE=0 可将其关闭）：发送和保留的数据说明见 reader/README.md 和隐私政策。

如何搜索（供 Agent 使用）

服务会在指令中向每个客户端发送这些规则；简要版如下：

1. 将用户的请求转换为业务类型和地点。 «我的车被锁在车外了，地点是 Tampa» → locksmith， Tampa。«我的空调吹出热风，邮编是 33618» → hvac，33618。你不需要了解目录内部使用的细分类别键： list_niches 和 search_catalog 可以匹配日常用语。
2. 选择工具： 知道名称 → find_business；知道类型 → list_cards；不知道，或需要查找特定商品（«素食披萨»、«刹车片»）→ search_catalog。
3. 没有地点，就不要猜。 如果请求中没有城市或邮编，请询问用户。目录会返回 location_needed，而不是替你选择地点。
4. 搜索结果只是候选项。 查看名片：列出了什么、是否提供上门服务（at_customer：已确认 / 已确认不提供 / 未知）、服务范围以及营业场所。
5. 区分不同事实： 营业时间不代表有空；商品价格不等于最终总价；“附近”不代表“服务该区域”；没有数据不等于“没有”。
6. 通过正确渠道进行下一步： 查看菜单或目录，预订用 book，获取总价用 quote_order，联系店主用 request_to_owner（仅限已接入渠道的情况）；否则请拨打电话。
7. 未经用户许可，不得代其采取任何行动——不得代为提交请求、预订、下单或付款。

每条结果都会说明匹配原因（match.basis：已确认的商品、商家自己的描述、类别标签，或仅类别）。当目录无法判断一条原始短语对应哪类商家时，会说明这一点并推荐相近类型，而不是返回相似但不相关的结果。

工具

工具	功能	主要参数
list_niches	查询目录在某个地点附近收录的行业及其数量	location、radius_miles、niche
list_cards	按固定顺序列出某个行业在某个地点附近的所有商家（在线行业无需地点）	niche、location（本地行业必填）、query、needed_by、max_price、deliver_to、page
find_business	按名称查找商家	name（必填）、location
search_catalog	行业未知时按含义查找匹配项	query（必填）、location、fulfillment、max_price、only_local
get_card	查看单个商家的完整信息：销售内容、可办理事项以及联系渠道	id
get_business	get_card 的同义工具	id
get_offering	完整查看单项商品或服务，并立即再次核实价格	id
get_product	get_offering 的同义工具	id
quote_order	查询订单配送至某个地址的价格——向商家自己的购物车询价，不会下单	offering_id、deliver_to（必填）、quantity、options
check_availability	查询商家自己的系统：当前是否有库存、哪些时段有空	business_id、offering_id（必填）、from、to
place_order	在商家自己的系统中下单；买家在平台的结账页面付款	business_id、lines（必填）、customer
book_slot	在商家自己的日历（Square Appointments）中预约时段	business_id、offering_id、start_at、customer（必填）
order_status	查询通过此渠道下的订单或预约的状态	order_id
request_to_owner	向商家经过验证的所有者发送请求（Telegram、电子邮件或 WhatsApp）——在所有者确认前不算预约	business_id、what、customer、idempotency_key（必填）、date、time、quantity、branch、note
request_status	查询请求状态：送达情况（sent · link_given · expired · failed）以及所有者的答复（declined · other_time · available = 有空但未预约 · confirmed = 已预约）	request_id

check_availability、place_order 和 book_slot 适用于所有者已连接 Shopify 或 Square 的商家 （卡片显示 live_data，并有一个 connected 渠道）。Shopify：place_order 会返回商家自己的结账链接，其中包含购物车里的商品；买家在 Shopify 上填写信息并付款。对于其他所有商家，卡片上的渠道会链接到其自己的下单和预约页面。

request_to_owner 适用于所有者已认领卡片并连接联系渠道的商家；对于其他商家，它会返回 no_channel，并附上卡片上的其他渠道。使用相同的 idempotency_key 重试绝不会重复发送请求。

示例：quote_order —— Flowers of Miami，12 朵玫瑰

{"offering_id": "a05bbf1c-32c0-4a56-9038-310b0c35b852", "deliver_to": "1000 Brickell Ave, Miami, FL 33131"} — 「12 朵红玫瑰与满天星迷你花束」，截至 2026-11-02 的实时报价，来自商家自己的购物车：

商家购物车提供的选项	运费	总计
本地配送（商家优先选择）	$20.00	$80.25
本地自取	$0.00	$58.85

商品 $55.00；总价包含商家针对该地址计算的税费。placed: false —— 未下单；仅发送了配送地址（未发送姓名、电子邮件或电话号码），之后购物车会话已清空。返回的 delivery_date 为 unknown：商家未通过购物车提供配送日期。

在线业务

目录收录各类业务，不仅限于本地业务：软件和应用、API 和 MCP 服务、网店、开源工具、内容网站和市场平台。每张卡片都会说明业务类型是 本地、在线 还是 两者兼有（既有线下业务又在线销售的本地业务；本地业务即使有自己的应用，也仍归为本地业务），并说明原因。

• 在线卡片没有地点。它会显示「在线服务」、服务内容、面向对象、定价和套餐、免费试用或套餐、平台、集成 / API / 文档、支持方式和公司信息——每项都取自该业务自己的页面，并附上引文。
• list_niches 会在 online_niches 下列出在线细分领域。
• 使用在线细分领域调用 list_cards 时，会忽略地点；不指定地点并提出在线业务请求（软件、应用、API……）时，search_catalog 会返回在线业务——绝不会返回 location_needed。
• get_card 会添加一个 online 区块，列出每项事实及其来源页面。

仅收录真实业务

有些「本地业务」其实是获客网站：同一家公司用几个虚构名称兜售电话服务。Versum 会检查并排除这类业务：

• 多个不同网站上的价目表相同，并且其电话号码属于同一号段；
• 网站上没有受监管行业所需的执照号码；
• 没有列出所有者、创立年份或公司名称；
• 这些网站使用相同的模板和文本。

已确认的获客卡片绝不会出现在目录中——不会出现在 search_catalog、list_cards 或 find_business 中，也不会出现在站点地图中；其页面会返回 410。看起来可疑但尚未确认的卡片，会先由人工审核，再决定是否隐藏。每周都会进行检查。

发布标准

Versum 还会发布关于部分本地业务的独立页面（versum.suverse.io/offers/…）：内容仅取自该业务自己的公开页面，在上线当天重新核查，并标明其独立性（「该业务未要求发布，也未为此付费，且不是 Versum 的客户或合作伙伴」），同时提供更正或删除页面的方式。每个页面在发布前都要通过 18 项检查。规则公开可见： 我们的发布标准。

限制

MCP 入口，无密钥	目前没有单次调用限制——请缓存读取的内容
使用 Versum 节点密钥的 MCP	密钥的限制，通过 x-ratelimit-limit / -remaining / -reset 返回
业主网站：实时卡片生成	每个地址没有每日上限；每个地址每小时 60 次请求
免费检查	每个网站每天 3 次，每个地址每天 20 次

名片

get_card 每家商户返回一张名片。完整架构根据各种类型商户的实时名片推断得出，见 schema/card.schema.json。主要部分：

• identity — id、name、address、location、phone、email、website、hours / hours_folded、page_url

• offerings — 销售的商品或服务：每项包含 id、title、price、currency、availability、link

• actions（入口）— order、book、reserve、request_quote、contact、check_delivery；每项都带有真实的 url（或 tel: / mailto:），如果通过平台操作，也会注明 provider

• fulfillment — 配送、自提及其他履约方式，包括已知和未知的信息

• reach — Agent 与商户打交道的方式，用一个词表示：

  reach	含义
  online_platform	订单或预订通过平台处理（商店、订购系统或预订系统）
  own_cart	商户自有网站接受订单
  form_only	只有申请表单，不支持在线订购
  phone_only	电话是唯一入口
  no_site	商户没有网站
  not_read	无法读取该网站

• status — unverified：信息读取自商户自己的公开页面；商户所有者尚未确认。所有者认领并确认名片的商户会显示 owner_verified。截至 2026-11-08，尚无商户所有者验证过名片：唯一经过验证的名片属于 Versum 自己的测试商户，它们不会出现在名录中。

透明度评级

每张名片都带有公开的 Versum Transparency 评级：买家在联系商户之前，根据商户自行发布的信息，能够了解到多少情况。它不是对服务质量的评级： 没有星级、没有评论、没有「最佳」称号，Versum 也绝不会在任何页面上按此评级排列商户。

项目（本地商户）	计入条件
已公布价格	商户自己的页面上至少有一项以文本形式公布的价格
已显示执照	仅适用于需要州执照的行业（暖通空调、管道、电气、屋顶施工、牙医……）
营业时间	显示在网站、Google 商家资料中，或由经过验证的所有者设置
服务区域 / 地址	服务区域（上门服务的行业），或街道地址（顾客到店的场所）
电话或预订 / 联系链接	可点击拨打的电话号码，或预订、联系链接
过去 30 天内读取过网站	Versum 在 30 天内读取过该网站

在线商户根据各自类别（软件、API、商店、开源、内容、市场）的专属清单进行评级，清单来自免费检查所用的同一配置。评级不含「适合谁」这一项：由 Agent 判断某家商户是否适合；如果商户在自己的网站上说明了目标受众，get_card 会在 stated 中附上该信息及其来源，但不会据此评分。等级：每项都符合为 A；除一项外都符合为 B；符合一半或以上为 C；符合不足一半为 D。 每个 ✓ 都会链接到找到该信息的页面，并标注读取日期。评定方法： versum.suverse.io/transparency。

对于 Agent：get_card → transparency {grade, have, of, items with source and read_at, or how_to_add}； list_cards 和 find_business → 每张名片的 transparency {grade, have, of, items: {key: true|false}}。你可以按此排序或筛选；列表顺序不使用此评级。在名片页面的 JSON-LD 中，它是普通的 additionalProperty （PropertyValue，propertyID: versum-transparency），而非 Review 或 AggregateRating。

分类法

每张名片都属于一个或多个细分领域（行业），包括一个 key、人们常用的称呼（also_called）以及商户销售的商品或服务类别（tags）。taxonomy/niches.json 列出了截至 2026-11-02 的 128 个细分领域，数据读取自 list_niches；实时目录截至 2026-11-03 有 130 个。

覆盖范围

货架上的名片	34,716（实时数量：上方徽章，或 /api/public/stats）
细分领域	136
城镇和街区	87

截至 2026-11-08（20:36 UTC）。新区域的扫描已暂停；现有名片会保留并重新读取。

入口和价格（2026-11-08，34,716 张名片中）
有在线下单入口	2,773
有在线预约入口	5,188
至少有一项价格	5,211

目前覆盖最密集的地区是 Tampa、St. Petersburg 和 Tampa Bay 东部郊区。有些地方的数据仍然稀少或为空——例如 Pinellas 北部（Clearwater、Dunedin、Palm Harbor）——佛罗里达州的其他城市目前名片也少得多。在这类地方附近搜索结果为空，通常意味着该区域尚未扫描，而不是那里没有这类商家。

面向商家

• 免费检查：「AI 了解您的业务多少」——访问 versum.suverse.io，输入 您的网站，即可根据公开公式获得 100 分制评分（评分方式）： AI 助手是否会提及您（每个细分领域和城市的三个买家问题，每周通过带网页搜索功能的 Claude 提问——报告会注明引擎和日期）；买家关注的哪些信息已出现在您的网站上；搜索和 AI 机器人是否能读取网站；您与 15 英里范围内同一细分领域的商家相比表现如何；以及应优先修复什么。每个 ✓ 都链接到发现相关信息的页面。完整报告还会列出所有来源，并提供可直接使用的 LocalBusiness JSON-LD 代码块和 llms.txt，内容仅基于您自己的信息。在线业务会按类型（软件、API / MCP、在线商店、开源、内容、市场）采用专属公式；问题不包含城市，而是根据商家自身描述和受众生成（例如，向市场询问在哪里买卖，而不是使用哪种软件），并提供 SoftwareApplication / Organization 代码。如果您输入的网址是应用或登录区域（app.…、dashboard.…、/login），系统也会读取同一商家的公开网站，并在报告中注明读取了哪些页面。报告仅供私人查看（不会被索引，也不会出现在站点地图中）；目前检查免费且没有每日次数限制。检查不包含 Google Maps、评价和排名。
• 认领您的名片：访问 versum.suverse.io，找到您的商家并确认归您所有（通过已在名片或网站上列出的联系方式接收验证码，或使用 Shopify / Square），然后编辑名片内容并发布。每张名片都有公开页面，例如 versum.suverse.io/b/flowers-of-miami-miami。
• Telegram 机器人「Versum for Business」（@VersumBusinessBot）：客户和 Agent 的请求会发送到这里，您可以通过按钮确认、拒绝或回复。
• 连接 Shopify 或 Square：在商家页面进行连接后，名片会显示商店的实时商品、价格和库存情况，Agent 也可以在商家自己的系统中下单，以及通过 Square 预约时段。
• 拓展业务（在商家页面的 /grow 页面以及机器人中的 /grow）：查看名片的下一步操作，以及开始推广——根据发布标准制作的独立页面，只有通过全部 18 项检查后才会发布，并标记为应商家要求发布。测试期间免费；仅向已验证其业务的商家开放。
• 即将推出：Shopify App Store 上架。

业主 API 和业主自己的站点（2026-11-09）

业主所做的一切——无论是在网页上、Versum 应用中（iPhone/Android，敬请期待），还是通过助手——都使用同一个 JSON API：https://versum.suverse.io/api/owner/v1（OpenAPI）。 通过电子邮件验证码登录（获取短期有效的访问令牌和刷新令牌）。登录仅用于验证联系方式：只有通过商家自行公开的联系方式（其网站或 Google 商家信息）、其自有网站上的文件或标签，或由他人审核文件来验证认领，才能管理商家；或者该商家是由业主添加的。

• **添加没有网站的商家：**用业主自己的话填写名称和描述 → 检查重复项（高度匹配时显示「认领此商家」，相似名称仅作为建议）→ 选择细分领域 → 填写该细分领域的字段 → 发布，并标记为「来自业主」。
• **网站较弱：**控制面板会显示透明度评级和需要补充的具体内容；「改进我自己的网站」会提供 JSON-LD、llms.txt，以及可直接使用的缺失内容文本，还可以在业主的 WordPress 上创建草稿页面。
• 业主自己的 Versum 站点（versum.suverse.io/s/<name>）：只有在业主启用后才会显示；仅展示业主批准的数据；外观只能通过设置调整（带对比度检查的颜色、字体、布局、版块），不能添加自定义代码。

Agent 仍通过 MCP 读取相同的卡片；本文不会改变下方的工具。

工作原理

1. 扫描会列出某个区域内某个行业的商家。
2. 分析器会读取每家商户自己的站点：菜单、价目表、商店目录、预约和下单页面。
3. 收录的所有信息都会附上其来源页面和原文；不会凭空编造。
4. 每家商户都会在目录中占据一张卡片，并提供真实入口。
5. Agent 通过 MCP 入口查询；业主可以认领、更正并连接自己的卡片。

flowchart LR
  A[Scan an area] --> B[Read the business website]
  B --> C[Card: offerings, prices, doors]
  C --> D[MCP door for agents]
  C --> E["/b/ page + owner site"]
  E -->|owner claims, edits, connects Shopify / Square| C

收录平台

• Official MCP Registry — io.suverse.versum/catalog（较早的条目 io.github.sudzikcoin/versum-agent-assistant 已标记为弃用，并指向该条目）
• mcptry（第二个条目）
• Glama
• mcpub.dev
• wellknown.network
• ToolSDK MCP Registry

路线图

已完成：

• 带共享缓存的开放读取器：reader/。
• 仅用于目录的 MCP 入口 /mcp/catalog（15 个工具，无需密钥）。
• 业主认领、Shopify 和 Square 连接，以及通过 Telegram 向业主发送请求。
• 线索生成筛选器。
• 独立推广页面和公开的发布标准。
• 为业主提供免费的「AI 对你的业务了解多少」检查。

接下来：

• 发布 npm 包 @suverselabs/versum-mcp（stdio、提供工具的类型化函数）；源代码位于 npm/。
• WhatsApp 点击聊天入口。
• 扫描更多区域（目前暂停）。

许可证和联系方式

本仓库中的模式、分类体系、文档和开放读取器（reader/）采用 MIT 许可证；托管目录的服务代码为闭源。 隐私政策 · 服务条款 · 发布标准 · 评分方式（SuVerse LLC）。 联系方式：[email protected]。Versum 的计算端是 versum-node。