supprecord

supprecord

supprecord 是 FormulaSignal 托管 MCP 服务的轻量本地桥接程序。该服务维护着一份带日期的证据记录，覆盖范围为数量明确的美国运动前补剂：每款已覆盖产品当前标示的内容、其配方是否发生变化，以及每项已确认变化背后的证据。

该桥接程序不保留自己的记录。它会在本地提供上游服务的工具列表，内容与从实时端点捕获的内容完全一致；并将每次工具调用转发至上游，原样返回结果。其功能以读取为主；唯一的写入操作是向调用方自己的关注列表中添加或移除条目。

工具

• record.search — 根据记录回答一个范围明确的自然语言问题。必填：query（最多 300 个字符）。
• products.resolve — 将品牌、产品名称或别名解析为一款规范的已覆盖产品。必填：identifier。
• products.get — 单款产品的当前记录：身份信息、每份配置、标示成分、采集到的价格信息及新鲜度。必填：product_id。
• products.history — 单款产品的历史时间线，并按可支持的内容对各状态进行分类。必填：product_id。
• signals.explain — 解释一项已批准信号：变更前状态、变更后状态、观察时间窗口及证据。必填：signal_id。
• signals.list — 按发布顺序列出已批准信号，最新的在前，供增量轮询使用。所有筛选条件均为可选：since、until、product_id、brand、dimension、category、limit 和 cursor。
• products.compare — 按统一标准比较两款或三款已覆盖产品。必填：product_ids（2 到 3 个 ID）。
• products.serving_economics — 单款产品采集到的商业信息及确定性价格计算。必填：product_id。
• ingredients.research — 所选证据集对指定成分采用的剂量范围，附带引文和限制。可选：ingredient_ids（最多 5 个）或 product_id，不可同时提供。
• ingredients.regulatory — 指定成分的法规记录及有文档记录的注意事项。可选：ingredient_ids（最多 5 个）或 product_id，不可同时提供。
• signals.snapshot — 指定日期窗口内已批准信号及覆盖状态的摘要，范围明确。可选：from、to、limit 和 cursor。
• ledger.list — 列出已发布的 Category Ledger 版本。不接受参数。
• ledger.get — 返回一个 Category Ledger 版本。必填：edition_id。
• watchlist.list — 列出密钥绑定账户的关注列表，以及每款产品的监控状态。不接受参数。
• watchlist.add — 将一款已覆盖产品添加到绑定账户的关注列表。必填：product_id。
• watchlist.remove — 从绑定账户的关注列表中移除一款产品。必填：product_id。
• watchlist.receipt — 某一时期的监控回执。可选：period（YYYY-MM）。
• record.version — 公开记录版本、方法论版本、支持的类别、覆盖数量及来源新鲜度。不接受参数。

配置

• FORMULASIGNAL_MCP_URL（可选）— 覆盖上游端点。默认值为 https://formulasignal.com/mcp。（此覆盖钩子是本次重建自行标注的还原内容。）
• FORMULASIGNAL_API_KEY（可选）— 设置后，每个上游请求都会携带 Authorization: Bearer <key> 标头。未设置时，不会发送身份验证标头。（此转发功能同样是自行标注的还原内容；原始接口是在无密钥情况下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26，clientInfo name supprecord），然后发送 notifications/initialized 通知，接着发送携带调用方原样参数的 tools/call 请求。当上游在 initialize 响应中返回 Mcp-Session-Id 标头时， 该值会随会话后续的每个请求一同发送，并在进程的整个生命周期内复用。 响应可能以纯 JSON 或服务器发送事件的形式到达； 两种形式都会被读取。

成功的上游结果会原样传递， 包括上游设置的任何 isError 标志。 失败——JSON-RPC 错误、非 2xx 状态、无法读取的响应， 或无法完成的请求——会以 isError 结果返回，其 文本以 supprecord error: 开头（此呈现方式是本次重建中自行添加的标注）。

CLI

每个工具也是一个子命令，接收一个 JSON 参数 字符串（无需参数的工具可省略）。工具名称包含点号， 并按所示名称原样使用：

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

退出代码：成功时为 0，返回 isError 结果时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/supprecord mcp

MCP 客户端配置：

{
  "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

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数会正常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全通过存根 JSON-RPC 上游运行，不会发起实时网络调用。

许可证

MIT——参见 LICENSE。