American Default Research

American Default Research — MCP 服务

一个 Model Context Protocol 服务，用于向兼容 MCP 的 AI Agent 提供 American Default Research 数据，包括 96 项经济困境指标、American Distress Index（ADI）综合评分，以及覆盖美国全部 3,144 个县的县级困境评分。

官方 MCP Registry 命名空间： org.americandefault/research 托管端点： https://mcp.americandefault.org/mcp（可流式传输的 HTTP） 网站： https://americandefault.org/press/mcp/

---

使用托管 MCP（推荐）

将任意兼容 MCP 的客户端指向托管的可流式传输 HTTP 端点。无需安装、无需数据文件、无需维护——每条响应都基于为 americandefault.org 提供支持的同一份数据生成。

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "american-default-research": {
      "url": "https://mcp.americandefault.org/mcp",
      "transport": "streamable-http"
    }
  }
}

重启 Claude Desktop。5 个工具将显示在锤子图标下。

Smithery

也可通过 Smithery 网关使用 MCP，地址为 smithery.ai/servers/americandefault/research。

Cursor / 其他 MCP 客户端

任何支持可流式传输 HTTP 的客户端，都可以通过将端点 URL 添加到其 MCP 服务配置中进行连接。具体配置格式因客户端而异，请参阅相应客户端的文档。

---

工具概览

工具	输入	返回内容
get_indicator(slug)	bundle slug（例如 the-buffer）	精简快照 + 预先计算的汇总数据 + 规范引用
get_county_scorecard(fips)	5 位 FIPS（也接受 4 位数，自动补前导零）	CDI 记分卡 + 5 个领域的细分数据 + 预先生成的引用
get_adi_composite()	（无）	最新季度 ADI + 5 个组成部分 + 区域 + 引用
search_indicators(query, limit=10)	关键词 + 可选的 limit（上限为 50）	按相关性排序的匹配项（slug、branded_name、name、category、URL）
get_cross_correlations(slug)	指标 slug	经过完整验证的领先／滞后配对，分为 as_leader + as_follower

Schema 版本控制

每条响应都包含 schema_version: "v1"。破坏性变更将通过名称带 _v2 后缀的新工具发布；v1 工具将继续提供服务，以保持向后兼容。调用方应验证其预期的 schema 版本。

响应大小预算

端点	预算	典型值
get_indicator	≤ 16 KB	~13.8 KB
get_county_scorecard	≤ 25 KB	~2.5 KB
get_adi_composite	≤ 4 KB	~2.0 KB

为控制大模型上下文预算，get_indicator 会有意省略包含 300 多个数据点的原始指标序列。完整序列位于 https://americandefault.org/api/indicators/{slug}.json。

---

规范署名

每条响应都包含一个 citation 对象，提供 APA、MLA、Chicago 和新闻稿形式。严格执行三级命名规范：

• American Default Research — 机构名称，用于引用、来源列表和参考书目
• American Default — 品牌名称，用于 URL 和非正式提及
• American Distress Index (ADI) — 产品名称，仅在综合评分为主题时使用

权威规范请参阅 https://americandefault.org/llms.txt §“规范署名”。

---

本地运行（可选）

推荐的使用方式是通过上方托管端点使用此 MCP。提供本地安装方式是为了提高透明度、便于审计和自托管，但本地服务会从同级目录（data/ 和 site/src/data/）读取数据文件，而这些目录未包含在此仓库中。若要在本地端到端运行，你需要：

1. 从公共 API 镜像数据文件。 所有指标数据均发布在 https://americandefault.org/api/indicators/{slug}.json，县级评分卡则发布在 https://americandefault.org/api/counties/{fips}.json。有一个小型配套脚本（未随包提供）可以将这些文件抓取到本地 data/ 镜像目录。
2. 仅将此仓库用作代码参考。 阅读源代码并审计实现，然后让客户端连接到托管端点。

安装：

python3 -m venv venv
./venv/bin/pip install -r requirements.txt

探测（确认服务已启动并发现工具）：

PYTHONPATH=. python3 -m scripts.machine_layer.mcp_server --probe

此命令会向 stdout 输出 JSON 握手信息，并以状态码 0 退出，不会进入 stdio 循环。可在 CI 中使用，也可用作冒烟测试。

运行 stdio 循环：

PYTHONPATH=. python3 -m scripts.machine_layer.mcp_server

Stdout 专用于 JSON-RPC 帧。日志会写入 stderr。

---

架构

此服务基于 mcp >= 1.27.0 构建，支持两种传输方式：

• stdio（mcp_server.py）——用于本地 Claude Desktop / Cursor / IDE 插件
• streamable-HTTP（http_app.py）——用于 mcp.americandefault.org 上的托管端点

HTTP 传输方式添加了 bearer 身份验证中间件（匿名与已签发令牌层级）、两级令牌桶速率限制（每分钟突发限制 + 每小时持续限制）以及按层级设置的速率限制。完整的中间件栈请参阅 http_app.py。

slug ↔ indicator_id 映射

源 JSON 文件同时包含 indicator_id（snake_case）和 slug（kebab-case）。96 个指标中有 91 个的 slug 无法通过其 id 进行机械转换——品牌指标会使用营销名称，例如 the-buffer（id：savings_rate）、the-horizon（id：ai_capability）、the-pinch（id：census_htops_difficulty）。

服务会在启动时扫描每个源 JSON 一次，构建双向映射表（约 100ms）。此后查找操作的复杂度为 O(1)。

空数据包

96 个数据包中有 10 个尚未填充数据——这些指标已纳入跟踪，但尚未回填数据（AI 招聘信息、ABA 消费非必需品、NMHC 租金跟踪、公共事业断供等）。这些数据包会返回 status: "awaiting_population"，其中包含完整元数据，且 latest_value 为 null。Agent 可以发现这些 slug 的存在，而不会收到虚构数据。

速率限制（HTTP 传输）

两级令牌桶通过 IP 和 bearer 令牌联系人进行键控：

• 每分钟突发限制 — MCP_RATE_LIMIT_RPM，默认值为 60
• 每小时持续限制 — MCP_RATE_LIMIT_RPH，默认值为 600

匿名层级（无 bearer 令牌）采用默认限制。已签发层级（有效 bearer 令牌）可获得由服务端配置的更高限额。

---

数据来源

此 MCP 提供的数据来源包括 FRED（Federal Reserve Economic Data）、BLS（Bureau of Labor Statistics）、纽约联储家庭债务与信贷报告、ATTOM Data Solutions、Mortgage Bankers Association、American Bankruptcy Institute / Epiq Systems，以及其他政府和行业一手来源。数据通过自动化管道每日更新。

服务返回的每个 citation 字段都包含对应指标的数据来源说明。完整的数据来源说明方法见 https://americandefault.org/methodology/。

---

关于 American Default Research

American Default Research 是一个无党派数据项目，跟踪美国住户的财务困境情况。该项目发布 American Distress Index（ADI）——由五个通过统计方法得出的组成部分构建而成的 0-100 综合评分——以及涵盖美国全部 3,144 个县的 County Distress Index（CDI）。

网站：https://americandefault.org 新闻：https://americandefault.org/press/mcp/ 方法论：https://americandefault.org/methodology/

---

许可证

MIT — 详见 LICENSE。

数据可免费使用，但须按照 https://americandefault.org/llms.txt 中的标准署名区块注明出处。

---

问题与贡献

欢迎通过此仓库的 GitHub Issues 提交错误报告和功能请求。拉取请求将依据数据管道的正确性门槛进行审查 — 数据准确性标准请参阅 https://americandefault.org/llms.txt。