
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 oftcg,lego,funko,keebs,vinyl,aqua) andqueryare required;priceis 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.queryis 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.nicheandqueryare 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_urlis optional, and the captured schema carries an emptyrequiredlist, 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.queryis an optional filter; the captured schema carries an emptyrequiredlist, 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.
@reneturcios/shelfscoutnpm install @reneturcios/shelfscoutghcr.io/cloudcorprecords/shelfscout:0.1.0docker pull ghcr.io/cloudcorprecords/shelfscout:0.1.0:undefinedRelated Servers
io.github.CloudCorpRecords/abandoncheck
Judge whether a dependency is maintained, from factual signals: releases, commits, archival.
io.github.CloudCorpRecords/actionbridge
Zapier exposed actions as MCP tools via a generic action runner.
io.github.CloudCorpRecords/actionpin
GitHub Actions supply-chain hardener: audit workflows for unpinned actions and build a SHA pin plan.