ShelfSignal

io.github.CloudCorpRecords由 GitHub 账号 CloudCorpRecords 发布v0.3.1更新于 Nov 2, 2026

The open store index for AI agents: merchants list real stock, agents find local food and stores.

已验证STDIO仅桌面位置与生活商业与电商

概览

AI 生成的概览

ShelfSignal 是一个本地 MCP 服务器，接入由商家自行提交的本地店铺索引，让助手查找店铺和商品并评估库存可能性。

可以做什么
  • 按文本、城市、类别或类型搜索店铺，并按经纬度列出附近店铺，附距离和是否营业的信号
  • 跨已收录店铺查找特定食品或商品，每条结果都带有库存判定
  • 读取单个店铺的完整信息：营业时间、地址、履约方式，以及每件商品最近确认的库存状态
  • 评估某店铺当前有某件商品的可能性，返回 0-100 分数、等级和理由
  • 对店铺信息运行校验检查并返回凭据，含等级、分数和逐项证据；预览商家提交内容但不发布
  • 查看索引当前覆盖的城市和类别及店铺数量
适用场景
适合需要为用户推荐真实本地店铺或餐馆、在让人跑一趟之前确认某件商品是否可能有货，或在推荐前核实店铺信息可靠性的场景。也可用于预览商家提交内容及其校验凭据。
运行要求
以本地 stdio 进程运行，可通过 npx 使用 npm 包，或使用已发布的容器镜像；容器方式需要 Docker。未声明任何认证、环境变量或请求头。内置店铺为示例数据，并标记为 demo。
安装前请注意
库存结果是评分估算而非保证；服务器本身要求不得把 uncertain 或 unlikely 的判定当作有货呈现。店铺信息由商家提交，准确性取决于商家是否及时更新库存。submit_store 只做校验和预览，不收费也不发布，但 README 提到商家需一次性支付 100 美元上架费。demo 店铺为示例数据，不应作为真实店铺呈现。

安装

在 SourceWeft 中

  1. 打开 控制台中的 ShelfSignal，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

ShelfSignal

The open store index for AI agents.

Local merchants list what they actually sell. AI agents find real food and real products nearby, score how likely each item is actually in stock, and check a validation receipt before they send a human across town. Merchants pay one flat price to get listed. Nobody takes 30% of their food.

DoorDash and the delivery apps built a closed index: they own the customer, scrape or rent the menu, charge the merchant 15-30% per order, and still cannot tell you whether the kitchen has the thing you want. ShelfSignal is the opposite shape:

  • Merchant-owned listing. The store submits its own stuff, its own prices, its own stock. The listing belongs to the merchant, not the platform.
  • Built for agents, not ads. One MCP server any agent can query: find stores, find items, check stock, validate the listing. No sponsored placement, ever.
  • Stock is a scored signal, not a claim. Every item carries a last-confirmed date. The likelihood engine turns that evidence into a 0-100 score with printed reasons, so agents stop bluffing "they have it" and start saying "confirmed today, likely in stock."
  • Validation receipts. Every listing carries checks an agent can verify: complete profile, real prices, fresh inventory, declared fulfillment. Tier: VERIFIED, LISTED, STALE, or INCOMPLETE.
  • Flat money. $100 Starter Store, one time, listed and validated. No per-order commission. See docs/PRICING.md. Merchants can join by email: docs/EMAIL-INTAKE.md.

Quick start

bash
npm installnpm run buildnpm test
node dist/cli.js coveragenode dist/cli.js search "birria" --city "San Francisco"node dist/cli.js stock sf-mission-taqueria-demo "Birria tacos"node dist/cli.js nearby 37.7599 -122.4148 --radius 5node dist/cli.js ping sf-sunset-bakery-demo "Cardamom knot" innode dist/cli.js validate sf-mission-taqueria-demonode dist/cli.js doctornode dist/cli.js mcp        # run the MCP server (stdio)node dist/cli.js serve      # run the hosted registry API (http://0.0.0.0:8787)

Hosted registry API

A read-only HTTP API over the same registry, for agents and clients that do not speak MCP:

bash
curl localhost:8787/v1/stores?city=San%20Franciscocurl localhost:8787/v1/stores/sf-mission-taqueria-democurl "localhost:8787/v1/search?q=birria"

Only listings in the live state are served: listings still in the intake queue are excluded from list and search, and their detail route returns 404. Full reference: docs/API.md.

MCP tools

ToolWhat it does
search_storesFind stores by text, city, category, or type (with open-now signal)
find_nearbyStores near a lat/lng point, nearest first, with distance and open-now
search_itemsFind a food or product across stores, every hit carrying its stock verdict
get_storeFull listing: hours, address, fulfillment, items, stock
check_stockStock-likelihood verdict (score, band, reasons) for one item
validate_storeValidation receipt and tier for one listing
submit_storeValidate a merchant intake and preview its listing + receipt
list_coverageCities, categories, and store count in the index

For merchants

You run a store in the city. For $100 you get listed where the agents look:

  1. Fill the intake (10 minutes): who you are, where you are, your hours, and the stuff you sell with real prices. Template: examples/submission.example.json, field guide: docs/INTAKE.md.
  2. We validate it and your listing goes live with its first receipt.
  3. Update stock whenever it changes with one command or one message. Fresh listings rank as VERIFIED; stale ones decay honestly instead of lying to customers.

No commission. No tablet on your counter. No competing with your own listing.

How it works

  • The registry is the source of truth: registry/stores.json (v0.1, git-backed, every change reviewable).
  • The likelihood engine is deterministic: merchant-reported status, confirmation freshness, staple vs specialty. No model guesses.
  • The management layer is freshness: listings decay, validation re-runs on every read, and merchants see exactly what an agent sees. Roadmap in docs/MANAGEMENT.md.
  • Full design: docs/SPEC.md. Why this beats the delivery model: docs/VS-DOORDASH.md.

Bundled stores are sample data and are flagged demo: true in every response. Real merchants are never marked demo, and demo stores are never presented as real.

License

MIT

来源：README.md，提交 e472708

工具

8

search_stores

Find real local stores (restaurants, groceries, bakeries, bodegas, markets) in a city. Returns merchant-submitted listings, not scraped delivery-app menus.

输入参数citytypequerycategory

find_nearby

Find listed stores near a point (lat/lng), nearest first, each with distance in km and an open-now signal (null when the store has no structured hours: unknown, not a guess).

输入参数lat必填lng必填radius_km

search_items

Find a specific food or product across listed stores, e.g. 'birria tacos' or 'oat milk'. Every hit carries its stock verdict (score, band, reasons), best evidence first. Never present an 'uncertain' or 'unlikely' verdict to a human as available.

输入参数cityquery必填

get_store

Full listing for one store by registry id: hours, address, fulfillment, and every item with its last-confirmed stock status.

输入参数store_id必填

check_stock

Score how likely a store actually has an item right now. Returns a 0-100 score, a band (likely / probable / uncertain / unlikely), and the reasons. Never present an 'uncertain' or 'unlikely' verdict to a human as available.

输入参数item必填store_id必填

validate_store

Run the ShelfSignal validation checks on a listing and return its receipt: tier (VERIFIED / LISTED / STALE / INCOMPLETE), score, and every check with its evidence. Use this before recommending a store you have not used before.

输入参数store_id必填

submit_store

Validate a merchant submission (the $100 Starter Store intake) and preview exactly how it would appear in the registry, with its validation receipt. Does not charge anything and does not publish until the listing is merged into the registry.

输入参数submission必填

list_coverage

Which cities and categories the index currently covers, with store counts. Check coverage before promising a human you can search somewhere.

无需输入参数。

版本历史

2
  1. v0.3.1最新Oct 26, 2026
  2. v0.3.0Oct 26, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分