American Default Research

MCP somente leitura para dados de dificuldades financeiras de domicílios nos EUA: 96 indicadores, o American Distress Index (ADI) e pontuações de dificuldades em nível de condado para todos os 3.144 condados dos EUA.

GitHubExperimente este MCPPatrocinado

Documentação

American Default Research — MCP Server

Um servidor Model Context Protocol que expõe dados da American Default Research — 96 indicadores de sofrimento econômico, o escore composto do American Distress Index (ADI) e escores de sofrimento em nível de condado em todos os 3.144 condados dos EUA — para agentes de IA compatíveis com MCP.

Namespace oficial do registro MCP: org.americandefault/research Endpoint hospedado: https://mcp.americandefault.org/mcp (HTTP streamable) Site: https://americandefault.org/press/mcp/

Use o MCP hospedado (recomendado)

Aponte qualquer cliente compatível com MCP para o endpoint streamable-HTTP hospedado. Sem instalação, sem arquivos de dados, sem manutenção — cada resposta é gerada com os mesmos dados que alimentam americandefault.org.

Claude Desktop

Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Reinicie o Claude Desktop. As 5 ferramentas aparecem sob o ícone de martelo.

Smithery

O MCP também está disponível via gateway Smithery em smithery.ai/servers/americandefault/research.

Cursor / outros clientes MCP

Qualquer cliente que fale streamable HTTP pode se conectar adicionando a URL do endpoint à configuração do servidor MCP. O formato exato da configuração varia por cliente — consulte a documentação do seu cliente.

Superfície de ferramentas

FerramentaEntradaRetorna
get_indicator(slug)slug do bundle (ex.: the-buffer)snapshot compacto + agregados pré-computados + citação canônica
get_county_scorecard(fips)FIPS de 5 dígitos (4 dígitos aceitos com zero à esquerda implícito)scorecard CDI + detalhamento de 5 domínios + citações pré-prontas
get_adi_composite()(nenhum)ADI do trimestre mais recente + 5 componentes + zona + citação
search_indicators(query, limit=10)palavra-chave + limite opcional (máx. 50)correspondências classificadas (slug, branded_name, name, category, URL)
get_cross_correlations(slug)slug do indicadorpares leading/lagging totalmente validados divididos em as_leader + as_follower

Versionamento de schema

Cada resposta carrega schema_version: "v1". Mudanças que quebram compatibilidade são lançadas como uma nova ferramenta com sufixo _v2 — as ferramentas v1 permanecem ativas para compatibilidade retroativa. Os chamadores devem verificar a versão do schema que esperam.

Orçamentos de tamanho de resposta

EndpointOrçamentoTípico
get_indicator≤ 16 KB~13.8 KB
get_county_scorecard≤ 25 KB~2.5 KB
get_adi_composite≤ 4 KB~2.0 KB

A série bruta de indicadores com 300+ pontos é omitida intencionalmente de get_indicator para manter os orçamentos de contexto do LLM gerenciáveis. A série completa está em https://americandefault.org/api/indicators/{slug}.json.

Atribuição canônica

Cada resposta inclui um objeto citation com formatos APA, MLA, Chicago e texto jornalístico. A nomenclatura em três níveis é aplicada:

  • American Default Research — nome institucional, usado em citações, listas de fontes, bibliografias
  • American Default — nome da marca, usado para URLs e referências casuais
  • American Distress Index (ADI) — nome do produto, usado apenas quando o escore composto é o assunto

Consulte https://americandefault.org/llms.txt § "Atribuição Canônica" para a especificação oficial.

Execute localmente (opcional)

A forma recomendada de usar este MCP é o endpoint hospedado acima. O caminho de instalação local é fornecido para transparência, auditoria e auto-hospedagem — mas o servidor local lê arquivos de dados de diretórios irmãos (data/ e site/src/data/) que não estão incluídos neste repositório. Para executar localmente de ponta a ponta, você precisa de uma das opções:

  1. Espelhe os arquivos de dados da API pública. Todos os dados de indicadores são publicados em https://americandefault.org/api/indicators/{slug}.json e os scorecards de condados em https://americandefault.org/api/counties/{fips}.json. Um pequeno script complementar (não incluído) pode buscar esses dados para um espelho local data/.
  2. Use este repositório apenas como referência de código. Leia o código-fonte, audite a implementação e aponte seu cliente para o endpoint hospedado.

Instalação:

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

Sonda (confirma que o servidor inicia e descobre ferramentas):

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

Isso emite um handshake JSON para stdout e sai com código 0 sem entrar no loop stdio. Use em CI ou como teste de fumaça.

Execute o loop stdio:

PYTHONPATH=. python3 -m scripts.machine_layer.mcp_server

O stdout é reservado para o enquadramento JSON-RPC. Os logs vão para o stderr.

Arquitetura

O servidor é construído sobre mcp >= 1.27.0 e suporta dois transportes:

  • stdio (mcp_server.py) — para Claude Desktop / Cursor / plugins de IDE locais
  • streamable-HTTP (http_app.py) — para o endpoint hospedado em mcp.americandefault.org

O transporte HTTP adiciona um middleware de autenticação bearer (camadas anônima e emitida), limitação de taxa com token bucket de dois níveis (rajada por minuto + sustentada por hora) e limites de taxa por camada. Consulte http_app.py para a pilha completa de middlewares.

Mapeamento slug ↔ indicator_id

Os JSONs de origem carregam tanto indicator_id (snake_case) quanto slug (kebab-case). 91 dos 96 indicadores têm slugs que NÃO se transformam mecanicamente a partir do id — indicadores com marca usam nomes de marketing como the-buffer (id: savings_rate), the-horizon (id: ai_capability), the-pinch (id: census_htops_difficulty).

O servidor constrói um mapa bidirecional na inicialização, escaneando cada JSON de origem uma vez (~100ms). As consultas são O(1) a partir daí.

Bundles com dados vazios

10 dos 96 bundles são fornecidos sem dados preenchidos — indicadores monitorados, mas ainda não retroalimentados (vagas de emprego em IA, gastos discricionários do consumidor ABA, rastreador de aluguel NMHC, cortes de serviços públicos, etc.). Eles retornam status: "awaiting_population" com metadados completos e um latest_value nulo. Os agentes podem descobrir que o slug existe sem receber dados fantasmas.

Limitação de taxa (transporte HTTP)

Token bucket de dois níveis com chave por IP e contato do token bearer:

  • Rajada por minuto — MCP_RATE_LIMIT_RPM, padrão 60
  • Sustentada por hora — MCP_RATE_LIMIT_RPH, padrão 600

A camada anônima (sem bearer) recebe o padrão. A camada emitida (bearer válido) recebe uma cota maior configurada no servidor.

Fontes de dados

Este MCP fornece dados originados de FRED (Federal Reserve Economic Data), BLS (Bureau of Labor Statistics), NY Fed Household Debt and Credit Report, ATTOM Data Solutions, Mortgage Bankers Association, American Bankruptcy Institute / Epiq Systems, e fontes primárias adicionais do governo e da indústria. Os dados são atualizados diariamente por meio de pipelines automatizados.

A atribuição de fonte por indicador está incluída em cada campo citation retornado pelo servidor. A metodologia completa de atribuição de fontes está em https://americandefault.org/methodology/.

Sobre a American Default Research

A American Default Research é um projeto de dados apartidário que acompanha o sofrimento financeiro das famílias dos EUA. Ela publica o American Distress Index (ADI) — um escore composto de 0 a 100 construído a partir de cinco componentes derivados estatisticamente — e o County Distress Index (CDI) para todos os 3.144 condados dos EUA.

Site: https://americandefault.org Imprensa: https://americandefault.org/press/mcp/ Metodologia: https://americandefault.org/methodology/

Licença

MIT — consulte LICENSE.

Os dados são de uso livre com atribuição conforme o bloco de atribuição canônica em https://americandefault.org/llms.txt.

Problemas e contribuições

Relatórios de bugs e solicitações de recursos são bem-vindos via GitHub Issues neste repositório. Pull requests são revisados contra os portões de correção do pipeline de dados — consulte https://americandefault.org/llms.txt para o padrão de precisão de dados.