cpsc-recalls-mcp-server

---

概述

CPSC saferproducts.gov 数据库中的消费品召回信息，涵盖玩具、电子产品、家具、家用电器、儿童用品、工具和服装。可按产品、品牌、零售商或危害搜索召回信息，获取特定召回编号的完整详情，或按日期范围获取近期召回列表。

工具

工具	描述
cpsc_search_recalls	按标题、产品名称、品牌、零售商、进口商、分销商、危害、补救措施或描述关键词搜索消费品召回信息，支持可选日期筛选和偏移分页
cpsc_get_recall	按召回编号获取单条召回的完整详情，包括危害、补救措施、产品、伤害、图片和 CPSC 官方页面
cpsc_get_recent	获取最新召回信息，按时间从新到旧排序，并限定在可配置的日期范围内

CPSC 的管辖范围仅限消费品——食品和药品（FDA）、机动车辆和轮胎（NHTSA）、船只（USCG）、农药（EPA）以及枪支（ATF）均不在此数据库中；每个响应都会附带管辖范围说明。

功能参考

cpsc_search_recalls _工具

• 至少提供一个筛选条件，多个条件以 AND 组合：9 个文本筛选项，每项最多 500 个字符（title_search 通常信号最强，另有 product_name、manufacturer、retailer、importer、distributor、description_search、remedy、hazard_search），以及两个日期范围（date_start/date_end 筛选发布日期，updated_start/updated_end 筛选 CPSC 最近一次发布日期）；limit（1–200，默认值为 20）和 offset 用于分页浏览 total_found
• 返回危害、补救方案及说明、产品、UPC、按角色分类的公司名称、图片、cpsc_url 和每条召回记录的 data_quality_notes；无匹配项时会返回空的成功结果，其中 effectiveQuery 会回显筛选条件，提示信息会指出应放宽的筛选条件。失败情况：missing_criteria、invalid_date_range、upstream_rejected（不可重试）、upstream_error（可重试）
• has_more 是分页信号；若页面因 64,000 字节的响应预算而被截断，会附带提示信息，告知可继续查询的 offset

---

cpsc_get_recall _工具

• 一个 recall_number：2002 年至今的记录使用 5 位数字（"25043"），1998–2001 年的记录使用 5 位数字加字母 a–d（"99003a"）
• 返回完整记录——可为空的 description（型号通常位于此处）、危害、补救方案及说明、所有产品变体、UPC、伤害情况叙述、按角色分类的公司名称、制造国家、图片、跨机构协调召回的 URL，以及 data_quality_notes
• 失败情况：not_found（通过 cpsc_search_recalls 或 cpsc_get_recent 查找编号）、upstream_rejected（不可重试）、upstream_error（可重试）

---

cpsc_get_recent _工具

• days 回溯窗口（1–365，默认值为 30），以今天为基准；limit（1–100，默认值为 20）和 offset 用于分页浏览 total_found。缩小 days 会舍弃最早的召回记录，而不是进行分页。较早的召回记录可通过 cpsc_search_recalls 的日期范围查询
• 每条召回记录返回精简信息——编号、日期、标题、危害、补救类型、产品名称、cpsc_url、data_quality_notes——供 cpsc_get_recall 获取完整信息；has_more 是分页信号，若时间窗口内无记录、offset 超出末尾或页面因响应预算而被截断，则会附带提示信息。失败情况：upstream_rejected（不可重试）、upstream_error（可重试）

功能

基于 @cyanheads/mcp-ts-core：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及结构化日志和可选的 OpenTelemetry 跟踪。

CPSC 专属功能：

• 完整对接 CPSC saferproducts.gov 公共召回 API，支持搜索、查看单项召回详情和获取最新召回列表
• 九种文本筛选条件均支持逐词匹配：任意顺序、不区分大小写，并针对结果中显示的纯文本进行匹配；匹配范围涵盖分页前的完整结果集，确保 total_found 和 has_more 保持准确；hazard_search（别名 hazard）涵盖危险描述、产品名称和补救说明
• 同时支持现代的 5 位数召回编号，以及带字母后缀的 1998–2001 年历史记录
• 在每个响应中说明管辖范围边界，在 Agent 错误归属前标记超出范围的食品、车辆和药品召回

便于 Agent 使用的输出：

• 每个响应都包含来源信息：source_note、cpsc_url 和 (CPSC source text) 引用块标签，用于区分转述的 CPSC 叙述内容和服务自身的说明
• 两种输出形式均提供纯文本：CPSC 在部分记录中保存的 HTML 标记和字符代码（&、<br>、多余的表格标签）会在匹配和输出前转换为纯文本；content[] 会转义 Markdown，确保 1HFVE05**K4000003 等型号和序列号中的每个字符都能保留；召回页面和联合召回会呈现为链接，产品图片会与说明文字一起内嵌显示；HTTP(S) 地址会在两种输出形式中保留 CPSC 提供的 URL 值，而其他协议的地址则以文本形式显示
• 分页标识字段：每个搜索或最新召回响应都包含 total_found、offset、has_more 和 truncated，便于 Agent 判断结果是否被截断并通过 offset 翻页；每种输出形式的单页内容都限制在 64,000 字节以内，如果页面因预算限制而提前结束，会提示下一个偏移量
• 每个响应都包含 data_quality_notes，说明上游记录中观察到的数据缺失（例如缺少危险描述或没有产品条目）；这些说明依据 CPSC 留空的字段生成，而非主观判断
• 每个响应都包含管辖范围说明（cpsc_jurisdiction），当产品超出 CPSC 管辖范围时，Agent 可据此将用户转介至正确的机构（FDA、NHTSA、USCG、EPA、ATF）

快速开始

公共托管实例

可使用公共实例：https://cpsc-recalls.caseyjhand.com/mcp，无需安装。该实例提供 Streamable HTTP；每种客户端的配置格式各不相同。

Claude Code：

claude mcp add --transport http cpsc-recalls-mcp-server https://cpsc-recalls.caseyjhand.com/mcp

Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "cpsc-recalls-mcp-server": {
      "type": "streamableHttp",
      "url": "https://cpsc-recalls.caseyjhand.com/mcp"
    }
  }
}

Cursor（mcp.json）：

{
  "mcpServers": {
    "cpsc-recalls-mcp-server": {
      "url": "https://cpsc-recalls.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "cpsc-recalls-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/cpsc-recalls-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 npx（无需安装 Bun）：

{
  "mcpServers": {
    "cpsc-recalls-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/cpsc-recalls-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "cpsc-recalls-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cpsc-recalls-mcp-server:latest"]
    }
  }
}

若要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置要求

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥 — CPSC 公共召回 API 可免费访问。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/cpsc-recalls-mcp-server.git

2. 进入目录：

cd cpsc-recalls-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if needed — no required API keys

配置

所有配置都会在启动时通过 Zod 架构进行验证。主要环境变量：

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_HOST	HTTP 服务主机	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径	/mcp
MCP_PUBLIC_URL	用于 TLS 终止反向代理部署的公共源	—
MCP_SESSION_MODE	会话处理方式：auto、stateful 或 stateless。服务在 src/index.ts 中声明为 stateless；设置此变量会覆盖该声明。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error）	info
LOGS_DIR	日志文件目录（仅限 Node.js）	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败工具调用的参数和结果，按键名进行脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）。自由格式值中的机密不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	启用 OpenTelemetry	false

无需配置服务专属 API 密钥。可查看 .env.example，了解所有可选覆盖项。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck  # Lint, format, typecheck, security
  bun run test      # Vitest test suite
  

Docker

docker build -t cpsc-recalls-mcp-server .
docker run --rm -p 3010:3010 cpsc-recalls-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/cpsc-recalls-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具并初始化 CPSC 服务
src/mcp-server/tools	工具定义（definitions/*.tool.ts）——搜索、获取召回信息、获取近期召回；此外还有 response-budget.ts，供两个列表工具共用的页面大小预算，以及 markdown-escape.ts，用于转义 content[] 中的 CPSC 文本
src/services/cpsc-recall	CPSC 召回服务 — API 客户端、类型，以及 normalize-text.ts，用于将 CPSC 的 HTML 标记和字符代码转换为纯文本

开发指南

开发指南和架构规则请参阅 CLAUDE.md / AGENTS.md。简要说明：

• 处理器抛出异常，框架捕获异常——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 在 src/index.ts 的 createApp() 数组中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。