enaho-mcp

Servidor MCP y CLI para los microdatos de la ENAHO (Encuesta Nacional de Hogares del INEI, Perú).

El portal de microdatos del INEI es una aplicación ASP con dropdowns en cascada y sin API. Bajar un módulo son cuatro clicks; bajar una encuesta completa a través de los años son cientos. Pero el problema grande no es mecánico: es saber qué pedir. Que el ingreso del hogar está en la Sumaria y no en el módulo de empleo, que las llaves de unión son conglome/vivienda/hogar, o que un promedio sin factor de expansión no representa a nadie.

Este servidor mete ese conocimiento en las herramientas, no en el prompt.

Qué hace bien

Reproduce las cifras oficiales. Validado contra el informe técnico de pobreza 2023 del INEI:

Nunca devuelve microdatos al contexto. Las herramientas devuelven metadatos, rutas en disco y agregados chicos. Cuando el parquet está listo, el análisis libre se hace con pandas sobre esa ruta.

Estadística correcta bajo diseño complejo. Linealización de Taylor con estimador de conglomerado último, IC logit para proporciones, mediana por Woodruff, chi-cuadrado corregido por Rao-Scott, prueba de diferencia entre dominios con su covarianza, y Gini/percentiles por bootstrap rescalado de Rao-Wu-Yue. Sin scipy ni samplics: ~700 líneas auditables y bajo test.

Genera el entregable. Informes en Word, Excel, PDF, Markdown y HTML construidos ejecutando las estimaciones, no copiando números.

Avisa de lo que suele salir mal en silencio. Filas perdidas en cada merge, estratos con un solo conglomerado, coeficientes de variación por encima del umbral de publicación del INEI, y variables que cambian de significado entre olas.

Related MCP server: emovi-mcp

Instalación

git clone <este-repo> && cd enaho-mcp
uv sync
uv run enaho doctor      # comprueba catálogo, índice, cache y dependencias

Registro en Claude Code (scope user para tenerlo en todos los proyectos):

claude mcp add --scope user --transport stdio enaho \
  -- uv run --directory /ruta/absoluta/enaho-mcp python -m enaho_mcp.interfaces.mcp.servidor

Verificación: claude mcp list, y dentro de la sesión /mcp.

Sin cliente MCP: uv run enaho-mcp --diagnostico lista herramientas, resources y prompts.

Uso desde la CLI

La CLI y el servidor MCP llaman a los mismos casos de uso. Lo que funciona en uno funciona en el otro.

# 1. ¿Cómo se llama la variable que busco?
enaho buscar variable "pobreza" --anio 2023
enaho buscar rastrear p207 --desde 2015 --hasta 2024   # ¿cambió de significado?

# 2. ¿Qué hay en ese módulo?
enaho modulos 2023
enaho describir 2023 34

# 3. Bajar y preparar
enaho descargar -a 2023 -m 01 -m 34
enaho unir -a 2023 -m 01 -m 34 --nivel hogar -o hogares2023

# 4. Estimar
enaho perfil hogares2023 -v pobreza -v factor07
enaho estimar hogares2023 pobreza -e proporcion --valor 1 --peso-adicional mieperho
enaho geografia hogares2023 --nivel departamento -o hogares2023_dep
enaho estimar hogares2023_dep pobreza -e proporcion --valor 1 -p departamento --peso-adicional mieperho

# 5. Analizar más a fondo
enaho comparar hogares2023 pobreza -g estrato --a 8 --b 1 -e proporcion --valor 1 --peso-adicional mieperho
enaho desigualdad hogares2023 gashog2d -i gini -i p90_p10 --peso-adicional mieperho
enaho serie pobreza --desde 2019 --hasta 2023 -m 01 -m 34 -e proporcion --valor 1 --peso-adicional mieperho

# 6. Sacar el resultado
enaho exportar hogares2023 -f dta
enaho informe mi_informe.json --formato docx

Todos los comandos aceptan --json.

Informes

enaho_informe no redacta copiando números: recibe la narrativa y una especificación de qué calcular, ejecuta las estimaciones con la maquinaria de diseño complejo y pinta los cuadros. Los números del documento no pasan por el contexto del modelo, así que no se degradan al recopiarlos.

{
  "titulo": "Pobreza monetaria en el Perú, 2023",
  "autor": "…",
  "secciones": [
    {"tipo": "texto", "titulo": "Introducción", "texto": "…"},
    {"tipo": "estimacion", "titulo": "Incidencia por dominio",
     "dataset": "hogares2023", "variable": "pobreza",
     "estadistico": "proporcion", "valor": 1,
     "por": ["dominio"], "peso_adicional": "mieperho"},
    {"tipo": "desigualdad", "dataset": "hogares2023", "variable": "gashog2d",
     "indicadores": ["gini", "p90_p10"]},
    {"tipo": "cruce", "dataset": "hogares2023", "fila": "pobreza", "columna": "estrato"},
    {"tipo": "comparacion", "dataset": "hogares2023", "variable": "pobreza",
     "variable_grupo": "estrato", "grupo_a": 8, "grupo_b": 1},
    {"tipo": "serie", "anio_inicio": 2019, "anio_fin": 2023,
     "modulos": ["01", "34"], "variable": "pobreza"}
  ]
}

Formatos: docx, xlsx (una hoja por cuadro, números como números), pdf, md, html. Los tres primeros necesitan uv sync --extra informes; md y html no necesitan nada.

Tres cosas que hace y que un «escribe un docx con estos números» no da:

• Los códigos salen etiquetados. Un cuadro por dominio dice «Lima Metropolitana», no «8».

• Las advertencias viajan pegadas a su cuadro. Si tres celdas tienen CV > 15 %, el cuadro sale con su nota al pie diciendo que el INEI no las publica.

• Una sección rota no tumba el informe. Queda marcada dentro del documento con su sugerencia de arreglo y el resto se genera igual.

Herramientas MCP

Resources: enaho://modulos, enaho://cache, enaho://modulos/{anio}, enaho://ficha/{anio}/{modulo}

Prompts: /enaho-pobreza, /enaho-empleo, /enaho-explorar, /enaho-verificar

El detalle que más importa: el universo de población

Comprobado contra la ENAHO 2023, con tres formas de calcular lo mismo y tres resultados distintos:

El roster del módulo 02 incluye trabajadores del hogar, pensionistas y sus familiares, que quedan fuera de mieperho. Para indicadores de población que deban reproducir cifras oficiales hay que usar el archivo a nivel hogar con peso_adicional="mieperho".

El servidor detecta la situación y la advierte cuando estimas sobre un roster de personas sin peso adicional, en vez de dejar que publiques un número que se parece al bueno.

Arquitectura

Cuatro capas con la regla de dependencia hacia adentro:

interfaces/          MCP y CLI. Capas finas: validan, delegan, formatean.
   │
   ▼
aplicacion/          Casos de uso. El contrato compartido por ambas interfaces.
   │                 contenedor.py es el composition root.
   ▼
dominio/             Núcleo. Sin red, sin disco, sin MCP.
   ├── modelo/       Value objects y entidades (Anio, CodigoModulo, Ubigeo…)
   ├── conocimiento/ La tabla de módulos: nivel, llaves y trampas de cada uno
   ├── servicios/    Unión, estimación, tabulación, geografía, perfilado
   └── puertos.py    Interfaces (Protocol) que la infraestructura implementa
   ▲
   │
infraestructura/     Adaptadores: catálogo INEI, descarga, lectura, parquet, ubigeo

La regla de dependencia está bajo test: tests/test_interfaces.py analiza el AST de cada módulo del dominio y falla si aparece un import de infraestructura o una llamada a E/S.

Dos decisiones que conviene conocer antes de leer el código:

• pandas.DataFrame es un primitivo del dominio (ADR-001, en dominio/modelo/tabla.py). El dominio de este sistema es estadística sobre tablas rectangulares; inventar una tabla propia y traducir en cada frontera no compra nada. Lo que sí queda prohibido en el dominio es tocar E/S.

• Los casos de uso son funciones, no clases. Reciben primitivos y devuelven un dict chico y serializable. Ese dict es lo que hace que cada comando de CLI sean diez líneas de presentación en vez de una segunda implementación.

Desarrollo

uv sync --group dev --all-extras
uv run pytest              # 256 tests, ninguno toca la red
uv run ruff check src tests
uv run mypy src/enaho_mcp

Los ZIP de juguete se construyen en tiempo de test con pyreadstat en vez de versionarse como binarios: son deterministas, se leen con el mismo código que los reales y no engordan el repositorio.

Variables de entorno: ENAHO_MCP_HOME (raíz del cache), ENAHO_MCP_LIMITE_GB, ENAHO_MCP_MAX_MODULOS, ENAHO_MCP_DEBUG.

Limitaciones conocidas

• La tabla de ubigeo empaquetada cubre solo los 25 departamentos. Escribir de memoria los 1 800+ distritos sería inventar datos. Para trabajar a nivel provincia o distrito: enaho ubigeo importar ruta/al/ubigeo.csv con columnas codigo,departamento,provincia,distrito.

• El catálogo es una foto fija con fecha de generación (consultable con enaho doctor). Viene empaquetado con inei-microdatos.

• ENAHO Panel no está resuelto, está acotado. Es otro dataset: formato ancho, llaves de seguimiento propias y factores calibrados para la submuestra seguida. enaho_panel_inspeccionar reporta las columnas reales del archivo y enaho_panel_armar reestructura a formato largo, pero no asigna factor de expansión: eso hay que verificarlo con el manual del panel.

• Módulos curados: 01, 02, 03, 04, 05, 07, 34, 37, 77, 78, 84 y 85. El resto funciona con nivel y llaves inferidos, y la salida lo declara con verificado: false.

Ver DECISIONES.md para las desviaciones respecto del documento de diseño original y por qué.

Licencia

MIT.