American Default Research

MCP de solo lectura para datos de dificultades financieras de hogares estadounidenses: 96 indicadores, el American Distress Index (ADI) y puntuaciones de dificultades a nivel de condado para los 3,144 condados de EE. UU.

GitHubPrueba este MCPPatrocinado

Documentación

American Default Research — Servidor MCP

Un servidor de Model Context Protocol que expone datos de American Default Research — 96 indicadores de dificultad económica, la puntuación compuesta del American Distress Index (ADI) y puntuaciones de dificultad a nivel de condado en los 3.144 condados de EE. UU. — a agentes de IA compatibles con MCP.

Espacio de nombres del registro oficial de MCP: org.americandefault/research Endpoint alojado: https://mcp.americandefault.org/mcp (streamable HTTP) Sitio web: https://americandefault.org/press/mcp/

Usar el MCP alojado (recomendado)

Apunta cualquier cliente compatible con MCP al endpoint streamable-HTTP alojado. Sin instalación, sin archivos de datos, sin mantenimiento: cada respuesta se genera con los mismos datos que impulsan americandefault.org.

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Reinicia Claude Desktop. Las 5 herramientas aparecen bajo el icono del martillo.

Smithery

El MCP también está disponible a través de la pasarela de Smithery en smithery.ai/servers/americandefault/research.

Cursor / otros clientes MCP

Cualquier cliente que hable streamable HTTP puede conectarse añadiendo la URL del endpoint a su configuración de servidor MCP. El formato exacto de configuración varía según el cliente: consulta la documentación de tu cliente.

Superficie de herramientas

Herramienta	Entrada	Devuelve
`get_indicator(slug)`	slug de bundle (p. ej. `the-buffer`)	instantánea compacta + agregados precalculados + cita canónica
`get_county_scorecard(fips)`	FIPS de 5 dígitos (se aceptan 4 dígitos con cero inicial implícito)	tarjeta de puntuación CDI + desglose de 5 dominios + citas predefinidas
`get_adi_composite()`	(ninguna)	ADI del último trimestre + 5 componentes + zona + cita
`search_indicators(query, limit=10)`	palabra clave + límite opcional (máx. 50)	coincidencias clasificadas (slug, branded_name, name, category, URL)
`get_cross_correlations(slug)`	slug de indicador	pares adelantados/rezagados totalmente validados divididos en `as_leader` + `as_follower`

Versionado de esquema

Cada respuesta incluye schema_version: "v1". Los cambios disruptivos se publican como una nueva herramienta con un sufijo _v2: las herramientas v1 permanecen activas para compatibilidad hacia atrás. Los llamadores deben verificar la versión de esquema que esperan.

Presupuestos de tamaño de respuesta

Endpoint	Presupuesto	Típico
`get_indicator`	≤ 16 KB	~13,8 KB
`get_county_scorecard`	≤ 25 KB	~2,5 KB
`get_adi_composite`	≤ 4 KB	~2,0 KB

La serie de indicadores sin procesar de más de 300 puntos se omite intencionalmente de get_indicator para mantener manejables los presupuestos de contexto de LLM. La serie completa está en https://americandefault.org/api/indicators/{slug}.json.

Atribución canónica

Cada respuesta incluye un objeto citation con formatos APA, MLA, Chicago y de copia de prensa. Se aplica una nomenclatura de tres niveles:

American Default Research — nombre institucional, utilizado en citas, listas de fuentes y bibliografías
American Default — nombre de marca, utilizado para URLs y referencias informales
American Distress Index (ADI) — nombre de producto, utilizado solo cuando la puntuación compuesta es el tema

Consulta https://americandefault.org/llms.txt § "Atribución canónica" para la especificación autoritativa.

Ejecutar localmente (opcional)

La forma recomendada de usar este MCP es el endpoint alojado anterior. La ruta de instalación local se proporciona por transparencia, auditoría y autoalojamiento, pero el servidor local lee archivos de datos de directorios hermanos (data/ y site/src/data/) que no están incluidos en este repositorio. Para ejecutar localmente de extremo a extremo necesitas una de estas opciones:

Replicar los archivos de datos desde la API pública. Todos los datos de indicadores se publican en https://americandefault.org/api/indicators/{slug}.json y las tarjetas de puntuación de condados en https://americandefault.org/api/counties/{fips}.json. Un pequeño script complementario (no incluido) puede descargarlos a un espejo local data/.
Usar este repositorio solo como referencia de código. Lee el código fuente, audita la implementación y luego apunta tu cliente al endpoint alojado.

Instalación:

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

Prueba (confirma que el servidor arranca y descubre herramientas):

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

Esto emite un handshake JSON a stdout y sale con código 0 sin entrar en el bucle stdio. Úsalo en CI o como prueba de humo.

Ejecutar el bucle stdio:

PYTHONPATH=. python3 -m scripts.machine_layer.mcp_server

Stdout está reservado para el encuadre JSON-RPC. Los registros van a stderr.

Arquitectura

El servidor está construido sobre mcp >= 1.27.0 y admite dos transportes:

stdio (mcp_server.py) — para plugins locales de Claude Desktop / Cursor / IDE
streamable-HTTP (http_app.py) — para el endpoint alojado en mcp.americandefault.org

El transporte HTTP añade un middleware de autenticación bearer (niveles anónimo y emitido), limitación de tasa de dos niveles con token bucket (ráfaga por minuto + sostenida por hora) y límites de tasa por nivel. Consulta http_app.py para la pila completa de middleware.

Mapeo slug ↔ indicator_id

Los JSON de origen incluyen tanto indicator_id (snake_case) como slug (kebab-case). 91 de 96 indicadores tienen slugs que NO se transforman mecánicamente desde su id: los indicadores de marca usan nombres de marketing como the-buffer (id: savings_rate), the-horizon (id: ai_capability), the-pinch (id: census_htops_difficulty).

El servidor construye un mapa bidireccional en el arranque escaneando cada JSON de origen una vez (~100 ms). Las búsquedas son O(1) a partir de entonces.

Bundles con datos vacíos

10 de 96 bundles se distribuyen sin datos poblados: indicadores registrados pero aún no rellenados con datos históricos (ofertas de empleo de IA, gasto discrecional del consumidor de ABA, rastreador de alquileres de NMHC, cortes de servicios públicos, etc.). Estos devuelven status: "awaiting_population" con metadatos completos y un latest_value nulo. Los agentes pueden descubrir que el slug existe sin recibir datos fantasma.

Limitación de tasa (transporte HTTP)

Token bucket de dos niveles con clave por IP y contacto de token bearer:

Ráfaga por minuto — MCP_RATE_LIMIT_RPM, predeterminado 60
Sostenida por hora — MCP_RATE_LIMIT_RPH, predeterminado 600

El nivel anónimo (sin bearer) recibe el valor predeterminado. El nivel emitido (bearer válido) recibe una asignación mayor configurada en el servidor.

Fuentes de datos

Este MCP sirve datos procedentes 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, y fuentes gubernamentales y de la industria adicionales. Los datos se actualizan diariamente mediante canalizaciones automatizadas.

La atribución de fuentes por indicador se incluye en cada campo citation devuelto por el servidor. La metodología completa de atribución de fuentes está en https://americandefault.org/methodology/.

Acerca de American Default Research

American Default Research es un proyecto de datos no partidista que rastrea la dificultad financiera de los hogares estadounidenses. Publica el American Distress Index (ADI), una puntuación compuesta de 0 a 100 construida a partir de cinco componentes derivados estadísticamente, y el County Distress Index (CDI) para los 3.144 condados de EE. UU.

Sitio web: https://americandefault.org Prensa: https://americandefault.org/press/mcp/ Metodología: https://americandefault.org/methodology/

Licencia

MIT — consulta LICENSE.

Los datos son de uso libre con atribución según el bloque de atribución canónica en https://americandefault.org/llms.txt.

Problemas y contribuciones

Se aceptan informes de errores y solicitudes de funciones a través de GitHub Issues en este repositorio. Las pull requests se revisan contra las compuertas de corrección de la canalización de datos: consulta https://americandefault.org/llms.txt para el estándar de precisión de datos.