supprecord
supprecord is a small local bridge to FormulaSignal's
hosted MCP server, which maintains a dated evidence
record for a defined, counted set of U.S. pre-workout
supplements: what each covered product declares now,
whether its formula has changed, and the evidence behind
each confirmed change.
The bridge keeps no record of its own. It serves the
upstream server's tool list locally, exactly as captured
from the live endpoint, and forwards each tool call
upstream, returning the result untouched. Reads dominate
the surface; the only writes are additions to and
removals from the caller's own watchlist.
Tools
record.search — answer one bounded natural-language
question from the record. Required: query (at most
300 characters).
products.resolve — resolve a brand, product name or
alias to one canonical covered product. Required:
identifier.
products.get — the current record for one product:
identity, serving configuration, declared ingredients,
captured price context and freshness. Required:
product_id.
products.history — the historical timeline for one
product, with each state classified by what it can
support. Required: product_id.
signals.explain — explain one approved signal: the
before state, the after state, the observation window
and the evidence. Required: signal_id.
signals.list — approved signals in release order,
newest first, for incremental polling. All filters are
optional: since, until, product_id, brand,
dimension, category, limit and cursor.
products.compare — compare two or three covered
products on consistent criteria. Required:
product_ids (2 to 3 ids).
products.serving_economics — captured commercial
facts and deterministic price arithmetic for one
product. Required: product_id.
ingredients.research — the dose range used in the
selected evidence set for named ingredients, with
citations and limitations. Optional: ingredient_ids
(up to 5) or product_id, not both.
ingredients.regulatory — regulatory records and
documented cautions for named ingredients. Optional:
ingredient_ids (up to 5) or product_id, not both.
signals.snapshot — a bounded summary of approved
signals and coverage state for a date window. Optional:
from, to, limit and cursor.
ledger.list — list the published Category Ledger
editions. Takes no arguments.
ledger.get — return one Category Ledger edition.
Required: edition_id.
watchlist.list — the watchlist of the account the
key is bound to, with each product's monitoring state.
Takes no arguments.
watchlist.add — add one covered product to the
bound account's watchlist. Required: product_id.
watchlist.remove — remove one product from the
bound account's watchlist. Required: product_id.
watchlist.receipt — the monitoring receipt for one
period. Optional: period (YYYY-MM).
record.version — the public record version,
methodology version, supported category, coverage
counts and source freshness. Takes no arguments.
Related MCP server: fooddb
Configuration
FORMULASIGNAL_MCP_URL (optional) — override the
upstream endpoint. Defaults to
https://formulasignal.com/mcp. (The override hook is
this rebuild's own labelled reconstruction.)
FORMULASIGNAL_API_KEY (optional) — when set, every
upstream request carries an
Authorization: Bearer <key> header. When it is not
set, no auth header is sent. (This forwarding is also
a labelled reconstruction; the original surface was
captured keyless.)
Forwarding mechanics
On the first tool call the client opens a streamable
HTTP session with the upstream: a JSON-RPC initialize
request (protocolVersion 2025-03-26, clientInfo name
supprecord), then a notifications/initialized
notification, then the tools/call request carrying
the caller's arguments unchanged. When the upstream
answers initialize with an Mcp-Session-Id header,
that value rides on every later request of the session,
which is reused for the life of the process. Replies
may arrive as plain JSON or as server-sent events;
both are read.
Successful upstream results pass through verbatim,
including any isError flag the upstream sets.
Failures — a JSON-RPC error, a non-2xx status, an
unreadable response, or a request that cannot be
completed — come back as an isError result whose
text starts with supprecord error: (this rendering
is this rebuild's own labelled reconstruction).
CLI
Each tool is also a subcommand taking one JSON argument
string (omit it for tools that take none). Tool names
contain dots and are used exactly as shown:
npx @reneturcios/supprecord record.search '{"query":"How much caffeine is in C4 Original?"}'
npx @reneturcios/supprecord products.resolve '{"identifier":"C4 Original"}'
npx @reneturcios/supprecord products.get '{"product_id":"example-id"}'
npx @reneturcios/supprecord signals.list '{"limit":10}'
npx @reneturcios/supprecord ledger.list
npx @reneturcios/supprecord --version
Exit codes: 0 on success, 1 on an isError
result, 2 on a usage error.
MCP server
npx -y @reneturcios/supprecord mcp
MCP client config:
{
"mcpServers": {
"supprecord": {
"command": "npx",
"args": ["-y", "@reneturcios/supprecord", "mcp"]
}
}
}
Docker
docker run -i ghcr.io/cloudcorprecords/supprecord
docker run --rm ghcr.io/cloudcorprecords/supprecord --version
The container's default command is mcp, so the first
form is a stdio MCP server; any other arguments reach
the CLI normally.
Development
npm install
npm run build
npm test
npm run dev
The test suite runs entirely against a stubbed
JSON-RPC upstream — no live network calls.
License
MIT — see LICENSE.
