Repository avatar
Search & Data Extraction
v0.1.0
active

shelfscout

io.github.CloudCorpRecords/shelfscout

Hobby price and stock checks, consumer recall search, card-grading guidance, settlements.

Documentation

shelfscout

Is that Pokémon box actually overpriced, has the sold-out LEGO set restocked anywhere, and has the stroller you are about to recommend been recalled? shelfscout is a local forwarding client for a hosted oracle service that answers exactly those kinds of questions about hobby products and consumer goods: it answers tools/list locally from the captured tool definitions and forwards every call to the service, returning the answers exactly as the service sends them back.

Every read here is about a product, never a person. The price check compares an asking price against current retail and returns a fair / high / scalped verdict — a read about a product's price, not a transaction; nothing is bought. The stock check returns recent restock matches with buy links, and links only: this client executes no purchase. The recall search runs over published CPSC, FDA and NHTSA recall registers. The settlements search surfaces published class-action settlements with their claim details; this client files no claim and submits nothing.

All 5 captured tools are built; there are no omissions.

The tools

  • check_scalper_price — Checks whether a hobby item's asking price is fair or scalped, comparing it against current retail across tracked specialty shops for the niche. Returns a verdict (fair / high / scalped), the retail price band, and where to buy at retail. niche (one of tcg, lego, funko, keebs, vinyl, aqua) and query are required; price is the optional asking price you are seeing.
  • check_recall — Searches active consumer product recalls (CPSC, FDA, NHTSA and more) by keyword. Returns matching recalls with agency, hazard, affected products, and remedy. query is required.
  • check_in_stock — Checks whether a hobby item has recently dropped or restocked across the specialty shops monitored for a niche. Returns recent in-stock matches (new and restock) with direct buy links. niche and query are required.
  • grade_card_centering — Card-centering guidance. The centering measurement itself runs client-side in the browser on the uploaded image and is not server-callable; this tool returns guidance plus a link to the live CardGrade tool where the analysis runs. image_url is optional, and the captured schema carries an empty required list, served verbatim.
  • find_settlements — Finds open class-action settlements you may be eligible to claim, often with no proof of purchase required. Returns settlements with payout, claim deadline, proof requirements, and the official claim URL. query is an optional filter; the captured schema carries an empty required list, served verbatim.

Install and run

As an MCP server via npm:

npx -y @reneturcios/shelfscout mcp

MCP client configuration:

{
  "mcpServers": {
    "shelfscout": {
      "command": "npx",
      "args": ["-y", "@reneturcios/shelfscout", "mcp"]
    }
  }
}

As a container:

docker run -i ghcr.io/cloudcorprecords/shelfscout
docker run --rm ghcr.io/cloudcorprecords/shelfscout check_recall '{"query":"stroller"}'

CLI

One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:

shelfscout check_scalper_price '{"niche":"tcg","query":"Pokemon 151 Booster Box","price":289}'
shelfscout check_recall '{"query":"infant formula"}'
shelfscout check_in_stock '{"niche":"lego","query":"Millennium Falcon"}'
shelfscout find_settlements '{"query":"data breach"}'
shelfscout --version

Exit codes: 0 when the forwarded call succeeds, 1 when the upstream result is an error, and 2 for usage problems such as an unknown subcommand or a malformed JSON argument.

Configuration

  • ORACLE_MCP_URL — Overrides the upstream endpoint. The default is the pinned hosted endpoint, https://oracle.dropwatchhq.com/mcp. (The override variable is a reconstruction added by this rebuild.)

The upstream registry record declares no headers, so no authentication header is ever sent; the tool surface was captured keyless.

Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with shelfscout error:.

How forwarding works

The first forwarded call opens a session: an initialize request (protocol version 2025-03-26), followed by a notifications/initialized notification, then the tools/call itself. If the service answers the initialize request with an Mcp-Session-Id header, that value is carried on every later request, and the open session is reused for the rest of the process. Replies are accepted either as plain JSON or as server-sent events. Successful results pass through verbatim, including any isError flag and any extra fields the service includes.

Development

npm install
npm run build   # tsc -> dist/ (dist/cli.js is the bin)
npm test        # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev     # run the CLI from source

The test suite checks the served tool list against the captured surface (all 5 tools, deep-equal, in order, with no titles invented and the two empty required arrays preserved exactly), exercises the session handshake and its reuse, verifies that no Authorization header is ever sent under any environment, and verifies that arguments go upstream untouched and results come back untouched.

License

MIT — see LICENSE. Copyright (c) 2026 Rene Turcios.

NPM
@reneturcios/shelfscout
Install Command
npm install @reneturcios/shelfscout
Runtime: npx
OCI
ghcr.io/cloudcorprecords/shelfscout:0.1.0
Install Command
docker pull ghcr.io/cloudcorprecords/shelfscout:0.1.0:undefined
Runtime: docker