American Default Research

American Default Research — MCP サーバー

American Default Research のデータ（96の経済的困窮指標、American Distress Index（ADI）の複合スコア、および全米3,144郡の郡レベルの困窮スコア）を、MCP 互換の AI エージェントに公開する Model Context Protocol サーバーです。

公式 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

MCP は、smithery.ai/servers/americandefault/research の Smithery ゲートウェイからも利用できます。

Cursor／その他の MCP クライアント

ストリーミング可能な HTTP に対応するクライアントであれば、MCP サーバー設定にエンドポイント URL を追加して接続できます。設定形式はクライアントによって異なります。お使いのクライアントのドキュメントを参照してください。

---

ツール一覧

ツール	入力	戻り値
get_indicator(slug)	バンドルのスラッグ（例：the-buffer）	コンパクトなスナップショット＋事前計算済み集計値＋正式な引用
get_county_scorecard(fips)	5桁の FIPS（4桁も受け付け、先頭に0を補完）	CDI スコアカード＋5領域の内訳＋事前作成済みの引用
get_adi_composite()	（なし）	最新四半期の ADI＋5つの構成要素＋ゾーン＋引用
search_indicators(query, limit=10)	キーワード＋任意の上限（最大50）	関連度順の結果（slug、branded_name、name、category、URL）
get_cross_correlations(slug)	指標のスラッグ	検証済みの先行・遅行ペア。as_leader と as_follower に分けて返します

スキーマのバージョン管理

すべての応答には schema_version: "v1" が含まれます。破壊的変更は _v2 サフィックスの新しいツールとして提供されます。後方互換性のため、v1 ツールも引き続き利用できます。呼び出し側では、想定するスキーマバージョンをアサートしてください。

応答サイズの上限

エンドポイント	上限	標準サイズ
get_indicator	≤ 16 KB	約13.8 KB
get_county_scorecard	≤ 25 KB	約2.5 KB
get_adi_composite	≤ 4 KB	約2.0 KB

LLM のコンテキスト上限を管理しやすくするため、300点を超える指標の生データ系列は意図的に get_indicator から除外されています。完全な系列は https://americandefault.org/api/indicators/{slug}.json にあります。

---

正式な帰属表記

すべての応答には、APA、MLA、Chicago、およびニュース記事向けの形式を含む citation オブジェクトが含まれます。以下の3段階の名称を使い分けます。

• 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

このコマンドは JSON ハンドシェイクを標準出力に出力し、stdio ループに入らずに 0 で終了します。CI またはスモークテストで使用してください。

stdio ループを実行します：

PYTHONPATH=. python3 -m scripts.machine_layer.mcp_server

標準出力は JSON-RPC のフレーミング専用です。ログは標準エラー出力に出力されます。

---

アーキテクチャ

サーバーは mcp >= 1.27.0 上に構築されており、2 種類のトランスポートをサポートしています。

• stdio（mcp_server.py）— ローカルの Claude Desktop／Cursor／IDE プラグイン向け
• streamable-HTTP（http_app.py）— mcp.americandefault.org のホスト型エンドポイント向け

HTTP トランスポートには、Bearer 認証ミドルウェア（匿名および発行済みの各ティア）、2 段階のトークンバケット方式によるレート制限（1 分あたりのバーストおよび 1 時間あたりの継続的な制限）、ティアごとのレート制限が追加されています。ミドルウェアスタックの全容については 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 を 1 回スキャンし、双方向マップを構築します（約 100 ms）。以降の検索は O(1) です。

データが空のバンドル

96 個のバンドルのうち 10 個は、データが入力されていない状態で提供されます。追跡対象の指標ですが、まだデータの補完が完了していません（AI の求人掲載数、ABA の消費者裁量支出、NMHC の家賃トラッカー、公共料金の供給停止など）。これらは、完全なメタデータと latest_value が null の状態で status: "awaiting_population" を返します。エージェントは、実在しないデータを受け取ることなく slug の存在を確認できます。

レート制限（HTTP トランスポート）

IP アドレスと Bearer トークンの連絡先情報をキーとする、2 段階のトークンバケット方式です。

• 1 分あたりのバースト — MCP_RATE_LIMIT_RPM、デフォルトは 60
• 1 時間あたりの継続的な制限 — MCP_RATE_LIMIT_RPH、デフォルトは 600

匿名ティア（Bearer なし）にはデフォルトの制限が適用されます。発行済みティア（有効な Bearer あり）には、サーバー側で設定された、より高い制限が適用されます。

---

データソース

この MCP が提供するデータは、FRED（連邦準備制度経済データ）、BLS（労働統計局）、NY Fed Household Debt and Credit Report、ATTOM Data Solutions、Mortgage Bankers Association、American Bankruptcy Institute／Epiq Systems、およびその他の政府・業界の一次情報源に基づいています。データは自動化されたパイプラインを通じて毎日更新されます。

指標ごとの出典情報は、サーバーが返すすべての citation フィールドに含まれています。出典の詳細な帰属方法については、https://americandefault.org/methodology/ を参照してください。

---

American Default Research について

American Default Research は、米国の世帯の経済的困窮を追跡する無党派のデータプロジェクトです。5 つの統計的に導出された構成要素からなる 0～100 の複合スコア、American Distress Index（ADI）と、米国の全 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 をご覧ください。