fdarecords

fdarecords

无需在 FDA 门户中费力查找记录。fdarecords 是一个小型 openFDA API 客户端，涵盖人们反复进行的两类查询：查找药品信息——标签文本、产品背后的 Drugs@FDA 申请，以及某个名称对应的申请编号；追溯医疗器械从提交编号到监管类别的信息。

七个工具负责完成这些工作。其中三个工具依赖原项目中的发现，值得提前了解：De Novo（DEN）编号记录在 510(k) 端点的 k_number 字段中，因为 openFDA 没有自己的 De Novo 端点；openFDA 中没有 HDE（H）编号，因此 H 编号查询会返回 null，不会假装能查到；验证链仍会为 H 编号报告 III 类，并明确标注这是监管推断，而非数据。

其中一个工具是研究辅助工具，不是权威答案： screen_for_rwe_signals 会扫描药品标签中的真实世界证据词汇，并返回找到的内容。它仍处于实验阶段，尚未经过验证——请将其命中结果视为等待人工审核的候选项，绝不要视为结论。

配置

• OPENFDA_API_KEY（可选）——openFDA API 密钥。设置后，密钥会作为 api_key 查询参数传递，并可提高速率限制。不设置也没有影响；所有工具都可在无需密钥的情况下使用。
• OPENFDA_BASE_URL（可选）——API 基础 URL。默认为 https://api.fda.gov。

结果约定

所有工具都遵循相同的规则，值得明确说明，因为这些规则决定了如何理解“未找到”：

• 查询没有匹配项时，返回 JSON 文本 null。这包括 HTTP 404 和返回空结果列表的 200 响应。
• 遇到暂时性故障——超时、连接错误、429、5xx——会进行两次带退避的重试。如果仍然失败，工具会抛出 openfda transient failure: ...。暂时性故障绝不会被报告为未找到，因此 null 始终表示“没有此记录”，而不是“无法查询”。
• 遇到其他被拒绝的请求（其他 4xx）时，会立即抛出 openfda request error: HTTP <status>。
• 参数错误会在发出任何请求前报错： <arg> must be a non-empty string，或 limit must be an integer between 1 and 100。

单条记录查询工具会将第一条匹配记录作为 JSON 返回。两个标签工具会原样返回上游响应正文。

工具

• search_drug_label — 搜索 SPL 标签文本中的 query。传入 section（例如 indications_and_usage 这样的 SPL 字段名），即可将搜索范围限制在该章节。可选参数 limit，默认值为 10。
• lookup_drugsfda_application — 查询 application_number 对应的 Drugs@FDA 记录（NDA、BLA 和 ANDA 编号均可）。
• resolve_drug_to_application — 根据品牌名或通用 name 查找相关申请编号，并以去重、排序后的字符串 JSON 数组返回。
• screen_for_rwe_signals — 进行上述实验性扫描。可选参数 query 可在固定信号集合中添加一个搜索词；可选参数 limit，默认值为 10。
• lookup_device_submission — 查询 submission_number 对应的器械记录。K 和 DEN 编号搜索 510(k) 端点；P 编号搜索 PMA 端点；H 编号返回 null（openFDA 中没有）；其他编号会因前缀无法识别而被拒绝。
• classify_device_product_code — 根据 product_code 查询器械类别和医疗专科。
• validate_device_application — 一次调用完成整条查询链：从 submission_number 经由产品代码，查到 device_class、medical_specialty 和 device_name，并通过 device_class_source 说明类别的来源。H 编号会直接返回带标签的推断结果；没有产品代码的记录会合并返回 "device_class": null。

端点来源

GET /drug/label.json 是 openFDA API 索引中固定的路径。其余路径遵循相应端点系列中记录的 相同模式，并标注为基于模式推导，而非固定路径：

• GET /drug/drugsfda.json — 基于模式推导
• GET /device/510k.json — 基于模式推导
• GET /device/pma.json — 基于模式推导
• GET /device/classification.json — 基于模式推导

有三种行为是为此客户端组合而成， 并在代码中作了相应标注：resolve_drug_to_application 如何合并其品牌名称和通用名称查询、信号词集合 screen_for_rwe_signals 搜索的内容，以及 validate_device_application 根据两条记录组合出的结构。

CLI

每个工具都是一个子命令，接受一个 JSON 参数字符串：

npx @reneturcios/fdarecords search_drug_label '{"query":"aspirin"}'
npx @reneturcios/fdarecords search_drug_label '{"query":"chest pain","section":"indications_and_usage","limit":25}'
npx @reneturcios/fdarecords lookup_drugsfda_application '{"application_number":"NDA021457"}'
npx @reneturcios/fdarecords resolve_drug_to_application '{"name":"Tylenol"}'
npx @reneturcios/fdarecords screen_for_rwe_signals '{"query":"diabetes"}'
npx @reneturcios/fdarecords lookup_device_submission '{"submission_number":"K123456"}'
npx @reneturcios/fdarecords classify_device_product_code '{"product_code":"ABC"}'
npx @reneturcios/fdarecords validate_device_application '{"submission_number":"H123456"}'
npx @reneturcios/fdarecords --version

输出为工具的结果文本（null、一条记录、 一个数组或上游响应正文）。退出代码：成功时为 0， 运行时出错（包括验证失败或上游失败）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/fdarecords mcp

MCP 客户端配置：

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

Docker

docker run -i ghcr.io/cloudcorprecords/fdarecords
docker run --rm ghcr.io/cloudcorprecords/fdarecords lookup_device_submission '{"submission_number":"DEN200001"}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

许可证

MIT — Copyright (c) 2026 Rene Turcios