Household Recall Watch

Recall Radar — 一个 MCP 服务和语音前端，用于回答“我家里有没有东西被召回？”

一个可自托管的 Model Context Protocol 服务，让语音助手能够根据政府公开的召回数据回答家庭安全问题：

• 美国消费品召回（CPSC）和家用医疗器械召回（FDA）；
• 美国食品召回（FDA）；
• 美国药品召回（FDA）和欧盟药品短缺信息（欧洲药品管理局）；
• 欧盟危险产品警报（EU Safety Gate，前称 RAPEX）；
• 以及助手会主动检查的家庭关注清单：“从夏天以来，我拥有的东西有没有被召回？”

每条回答都包含一条简短的 spoken 语音回复，以及结构化详情，其中列出每个条目的来源 URL 和日期。运行该服务不需要 API 密钥、账户或大模型。

本项目为 Amazon Developer Hackathon 的 Alexa+ 专项开发。符合 MCP 规范 2025-11-25，使用 Streamable HTTP，无状态，基于 @modelcontextprotocol/sdk 1.30.1。

这是由真实 MCP 服务支持的模拟智能显示屏体验；尚未连接 Alexa+ 设备。请参阅评审运行指南、验证记录和使用摩擦记录。

**不构成医疗或安全建议。**召回和短缺数据可能不完整或有所延迟。请务必查看相关通知，并在采取行动前咨询药剂师、医生或制造商。切勿擅自停用处方药。

运行（一个命令）

需要 Node 20 或更高版本。一个进程同时在 /mcp 提供 MCP 服务，在 / 提供语音界面，并在 POST /api/ask 提供 Agent：

npm ci && npm start
# recall-radar MCP server: http://127.0.0.1:3000/mcp (health: /healthz, ...)
# Recall Radar voice UI:   http://127.0.0.1:3000/  (agent: POST /api/ask, model: Scripted mode, no LLM)

体验路径。

1. **无需密钥，脚本模式。**运行 npm start，打开 http://127.0.0.1:3000/。徽标显示 脚本模式， 无大模型：使用固定的短语到工具映射代替模型，但 MCP 调用和召回数据都是真实且实时的。试试建议标签，或通过 URL 操作： http://127.0.0.1:3000/?q=Watch%20my%20crib%20mattress&q=Has%20anything%20in%20my%20house%20been%20recalled%3F
2. **使用模型。**在仓库外设置 OPENAI_API_KEY，然后运行 npm start。徽标会显示所选模型（默认值为 gpt-6-luna）。此路径已于 2026-10-02 使用该模型实际运行；未测试其他模型（EVIDENCE.md）。

也可以使用 Docker：

docker build -t recall-radar-mcp . && docker run --rm -p 3000:3000 recall-radar-mcp
docker run --rm -p 3000:3000 -e OPENAI_API_KEY recall-radar-mcp   # with a model

环境变量	默认值	含义
PORT	3000	HTTP 端口
HOST	127.0.0.1（在 Docker 中为 0.0.0.0）	绑定地址
WATCHLIST_PATH	./data/watchlist.json	家庭关注列表的存储位置；CPSC 最近一次成功响应会保存为其旁边的 cpsc-cache.json
ALLOWED_ORIGINS	（无）	除 localhost 外允许的其他浏览器 Origin（以逗号分隔，* 表示任意来源）
MODEL_PROVIDER	如果设置了 OPENAI_API_KEY，则为 openai；否则为 scripted	openai、ollama 或 scripted
OPENAI_API_KEY	（无）	OpenAI 密钥；绝不会记录日志或发送到浏览器
OPENAI_MODEL	gpt-6-luna	任意支持函数调用的 Chat Completions 模型
OPENAI_REASONING_EFFORT	none	作为 reasoning_effort 发送；没有 none 时，GPT-6 模型会拒绝 Chat Completions 中的函数工具。对于不接受此字段的模型，请设置为 omit
OPENAI_BASE_URL	https://api.openai.com/v1	用于兼容 OpenAI 的网关
OLLAMA_URL / OLLAMA_MODEL	http://127.0.0.1:11434 / llama3.1	Ollama 的 OpenAI 兼容端点（/v1/chat/completions）
MCP_URL	此进程自身的 /mcp	将 Agent 指向另一个 Recall Radar MCP 服务

端点：POST /mcp（MCP Streamable HTTP，无状态：没有会话 ID，不提供 GET 流）、GET /healthz、 GET /（界面）、POST /api/ask（{"q": "...", "history": [...]}）、GET /api/config、GET /api/watchlist。 另附 stdio 入口：npm run start:stdio。

stdio 入口已在 MCP Registry 中列出，名称为 io.github.MGrin/household-recall-watch（server.json）。其软件包是附加到 GitHub 发布版本的 MCPB 捆绑包；npm run pack:mcpb 会重新构建该捆绑包，并打印 server.json 必须包含的 SHA-256。该捆绑包会将关注列表保存在 ~/.recall-radar/watchlist.json。发布流程见 .github/workflows/publish-mcp.yml：对于 v* 标签（或 gh workflow run publish-mcp.yml --ref vX.Y.Z），该流程会先根据 server.json 检查发布捆绑包，然后使用 GitHub OIDC 发布。请在工作流运行前将捆绑包附加到 GitHub 发布版本。

如果你的机器只能通过 HTTP 代理访问互联网，Node 内置的 fetch 会忽略 HTTPS_PROXY，除非你设置 NODE_USE_ENV_PROXY=1（Node 24+）。这也适用于 OpenAI 调用。

语音前端（模拟智能显示屏）

本项目允许打造“在 Web 应用中模拟 Alexa+ 体验”；这是我们的实现，名为 Recall Radar，不使用任何第三方商标。

• 按住说话：按住麦克风按钮（或空格键）并说话；它使用浏览器的 Web Speech API（SpeechRecognition）。如果浏览器不支持该 API，麦克风会被禁用，文本框可完成相同操作。 麦克风功能仍需在真实设备上检查。
• 语音回复通过 speechSynthesis 实现，并带有静音切换开关；底部边缘的灯条会显示正在聆听、思考和说话的状态。扬声器输出仍需在真实设备上检查。
• 工具调用轨迹：Agent 调用的每个 MCP 工具都会显示一个标签，其中包含参数和延迟，让查看者知道答案来自 MCP 服务。
• 回忆卡片：来源、日期、标题、危害、解决方法、匹配的关注清单项目，以及官方通知链接。
• 家庭关注清单面板（通过 + 按钮或语音添加，通过 × 移除；两种操作都会经由 Agent 执行），以及对话记录。
• ?q=... 会在加载时提问；重复该参数（?q=a&q=b）可进行脚本化演示，还可添加 mute=1 以静音录制。

Agent（src/agent/）

agent.ts 是一个真实的 MCP 客户端（SDK Client + StreamableHTTPClientTransport）：每个问题都会连接到 /mcp，列出工具，将它们映射为模型的函数格式并运行工具调用循环，最多 6 个模型步骤。工具结果会以工具的 structuredContent 形式返回给模型。 ModelAdapter（types.ts）只有一个方法：输入消息和工具，输出文本或工具调用。

适配器	状态
openai（openai.ts）	使用 OpenAI Chat Completions 的工具功能，通过普通 fetch 调用，不使用 SDK。已使用录制形态的响应进行单元测试，包括 3 步工具调用循环。2026-10-02 使用 gpt-6-luna 对接实时 API 运行（EVIDENCE.md）。
ollama	同一个类，指向 Ollama 的 OpenAI 兼容端点。未经测试：构建机器上未安装 Ollama。
scripted（scripted.ts）	确定性实现：几种说法会映射到一次工具调用，回复则是工具自己的 spoken 句子（仅第一项）。供测试和无密钥演示使用。

系统提示词（prompt.ts）要求回答以语音为先（两到三句话：危害、官方解决方法、现在该怎么做），要求所有说法均以工具结果为依据，并禁止提供超出官方解决方法文本范围的医疗建议。

试用

MCP Inspector（无需 LLM 密钥）：

npx @modelcontextprotocol/inspector

在 Inspector 界面中选择传输方式 Streamable HTTP，URL 填写 http://127.0.0.1:3000/mcp，然后点击 Connect， 再选择 Tools → List Tools 并调用任意工具。

在终端中使用捆绑的 SDK 客户端：

npm run call                                                   # list tools
npm run call -- search_product_recalls '{"query":"stroller","limit":3}'
npm run call -- watchlist_add '{"name":"crib mattress","kind":"product"}'
npm run call -- check_my_household '{}'

工具

共有 8 个工具。search_eu_product_recalls 于 v0.2.0 添加，在演示视频录制完成后；视频中展示和提到了 7 个工具。

tool	可解答的问题	来源
search_product_recalls	“我的婴儿推车／空间加热器／婴儿床被召回了吗？”	CPSC、openFDA device
search_food_recalls	“花生酱有召回吗？”“有李斯特菌相关的召回吗？”	openFDA food
search_medicine_alerts	“我的胰岛素被召回或短缺了吗？”（region：us、eu、all）	openFDA drug、EMA shortages
watchlist_add	“留意一下我的 Graco 婴儿推车。”（kind：product、food、medicine、any）	本地文件
watchlist_list	“我在关注什么？”	本地文件
watchlist_remove	“停止关注这辆婴儿推车。”	本地文件
search_eu_product_recalls (v0.2.0)	“我的 USB 充电器在欧盟被召回了吗？”可按产品、品牌、型号或条形码查询（默认：最近 28 天，最多查询最新的 12 份周报）	EU Safety Gate
check_my_household	“我家里有任何东西被召回了吗？”（默认：最近 180 天）	CPSC、openFDA、EMA，按物品种类筛选（不含 Safety Gate）

每个工具都声明了 zod 输入架构和 outputSchema；结果以 structuredContent（由 SDK 验证）和文本形式返回。每条召回记录都会规范化为：

{ source, id, title, hazard, remedy, date /* YYYY-MM-DD */, products[], url, summary /* one spoken sentence */ }

如果某个上游服务不可用，其他服务仍会返回结果，并在结果中列出警告；如果某个问题对应的所有数据源都不可用，工具会返回清晰的 MCP 工具错误（isError: true）。

CPSC 的 API 曾连续数天对某些 URL 正常响应、对另一些 URL 返回 503，且各 URL 的表现始终一致（观察时间为 2026-10-02 至 10-04）。因此，读取 CPSC 数据时会先尝试时间窗口对应的 URL，然后尝试不带产品筛选条件的同一时间窗口，接着最多尝试 3 个更早的起始日期（当月 1 日、上个月 1 日，以及故障期间曾正常响应的几个日期），并在此处将结果筛选为所请求的时间窗口：20 秒内最多发起 6 次请求。如果答案来自较早的 URL，结果会在 notes 中注明，并列出该 URL。每个正常的 CPSC 响应也会保存在监视列表旁边（cpsc-cache.json，最近 8 个 URL，每个都附有抓取时间）。如果所有实时尝试都失败，则返回最新保存副本中位于该时间窗口内的记录；每条摘要末尾都会注明“来自于 抓取的 CPSC 数据保存副本；当前无法连接 CPSC”，并在警告中列出抓取时间；如果没有保存副本，则会报告 CPSC 不可用。不会编造其他信息。

每个上游请求的超时时间为 10 秒（Safety Gate 为 20 秒）。EMA 文件会在内存中缓存 1 小时，因为 EMA 会限制重复下载。Safety Gate 每周五发布一份周报，每份约 200-300 KB，服务响应耗时 3-6 秒（截至 2026-10-02）：搜索最多读取 12 份周报，每次并发读取 4 份；索引缓存 1 小时，每份已发布的周报则在进程生命周期内缓存。首次搜索 4 周数据约耗时 5 秒；再次搜索则直接从缓存返回。如果时间窗口内包含的周报超过 12 份，答案中的 since 会是实际读取的最早一份周报。

数据来源与条款

来源	端点	条款
美国消费品安全委员会	saferproducts.gov/RestWebServices/Recall	美国政府作品，属于公有领域
openFDA 执法报告（食品、药品、器械）	api.fda.gov/{food,drug,device}/enforcement.json	根据 open.fda.gov/license，属于公有领域 / CC0；openFDA 自身免责声明：请勿将其用于医疗护理决策。无需密钥的使用受速率限制（条款）。
欧洲药品管理局，药品短缺目录	ema.europa.eu/en/documents/report/shortages-output-json-report_en.json	允许再利用，但须注明 EMA 为来源（法律声明）；每条 EMA 数据都附有其 EMA URL
欧盟委员会，欧盟 Safety Gate 每周报告	ec.europa.eu/safety-gate-alerts/api/download/weeklyReport/{list,detail}/xml/…	允许再利用，前提是不歪曲警报含义，并按欧盟委员会的原文注明来源（免责声明，“警报再利用”，当前修订版日期为 2026-06-11）。每个答复都会在 attribution 字段和正文中附上该句；每条数据都会链接到其官方警报

openFDA 没有单条召回的网页，因此 FDA 数据项的 url 是能够返回该条召回的 openFDA API 查询（search=recall_number:"…"）。

Safety Gate 归属声明，原文如下："Alerts from the Rapid Alert System for dangerous non-food products, published free of charge on the Safety Gate website (https://ec.europa.eu/safety-gate-alerts) © European Union, 2005 – 2026". 欧盟委员会还指出，警报中提到的品牌可能是经营者未经所有者许可使用的。

改编自既有代码

src/sources/ema.ts 改编自我们自己的早期代码，来自 ema-medicines-watch Apify Actor（作者相同）：EMA 的 dd/mm/yyyy 日期解析器、{meta, data[]} 结构检查，以及截断文件保护机制。 src/sources/safetygate.ts 改编自 eu-recall-watchlist Apify Actor（作者相同）：Safety Gate XML 解析器设置、CDATA 处理、连写的 measures 字段，以及逐字保留的归属声明。除此之外，本项目所有内容均专为此条目编写。

开发

npm run build        # tsc -> dist/
npm test             # vitest, against recorded fixtures in test/fixtures (no network)
LIVE=1 npm test      # also runs test/live.test.ts against the real APIs

test/agent.test.ts 使用脚本适配器通过 HTTP 对真实 MCP 服务运行 Agent 循环（上游服务由 fixtures 模拟），并测试 /api/* 路由和静态 UI。test/openai.test.ts 单独测试 OpenAI 适配器对接模拟的 Chat Completions 端点，以及在多步 Agent 循环中的运行。

端到端测试会启动 HTTP 服务，通过 StreamableHTTPClientTransport 使用 SDK Client 建立连接，检查是否协商了协议 2025-11-25，列出工具并逐一调用，同时将上游 fetch 请求路由至 fixtures。

许可证

MIT，© 2026 Nikita Grishin Limited。详见 LICENSE。摩擦记录：FRICTION.md。