ShelfSignal

io.github.CloudCorpRecordsPublished by GitHub account CloudCorpRecordsv0.3.1Updated Nov 2, 2026

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

VerifiedSTDIODesktop onlyLocation & LifestyleBusiness & Commerce

Overview

AI-generated overview

ShelfSignal is a local MCP server over an open index of merchant-submitted local store listings, letting an assistant find stores and items and score stock…

What you can do
  • Search and browse stores by text, city, category or type, and list stores near a latitude/longitude point with distance and an open-now signal
  • Find a specific food or product across listed stores, with each hit carrying a stock verdict
  • Read one store's full listing: hours, address, fulfillment and every item with its last-confirmed stock status
  • Score how likely a store has an item right now, returning a 0-100 score, a band and the reasons
  • Run validation checks on a listing and get a receipt with tier, score and per-check evidence; preview a merchant submission without publishing it
  • Check which cities and categories the index covers, with store counts
When to use it
Useful when an assistant needs to point someone to real local shops or restaurants, check whether a specific item is likely in stock before sending them across town, or vet a listing's reliability before recommending it. Also handy for previewing a merchant submission and its validation receipt.
Requirements
Runs as a local stdio process, either via npx from the npm package or via the published container image; Docker is needed for the container route. No authentication, environment variables or headers are declared. The bundled stores are sample data flagged as demo.
Before you install
Stock results are scored estimates, not guarantees; the server itself says uncertain or unlikely verdicts must not be presented as available. Listings are merchant-submitted, so accuracy depends on merchants keeping stock current. The submit_store tool only validates and previews a submission and does not charge or publish, but the README mentions a one-time $100 listing fee for merchants outside the tool. Demo stores are sample data and should not be presented as real.

Installation

In SourceWeft

  1. Open ShelfSignal in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit e472708

Tools

8

search_stores

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

Parameterscitytypequerycategory

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).

Parameterslatrequiredlngrequiredradius_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.

Parameterscityqueryrequired

get_store

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

Parametersstore_idrequired

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.

Parametersitemrequiredstore_idrequired

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.

Parametersstore_idrequired

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.

Parameterssubmissionrequired

list_coverage

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

Takes no parameters.

Version history

2
  1. v0.3.1LatestOct 26, 2026
  2. v0.3.0Oct 26, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts