emovi-mcp

Servidor MCP para la encuesta ESRU-EMOVI 2023 de movilidad social en México.

MCP server for the ESRU-EMOVI 2023 social mobility survey (Mexico).

¿Qué es esto?

emovi-mcp permite que asistentes de IA (Claude, ChatGPT, etc.) consulten la encuesta de movilidad social más completa de México mediante lenguaje natural. Expone cómputos estadísticos ponderados, matrices de transición intergeneracional y exploración de variables como herramientas MCP.

Sobre la ESRU-EMOVI 2023

La encuesta ESRU-EMOVI 2023, levantada por el Centro de Estudios Espinosa Yglesias (CEEY), es representativa a nivel nacional sobre movilidad social en México. Cubre 17,843 entrevistados de 25 a 64 años, con factores de expansión que representan ~60 millones de personas.

Bases de datos incluidas:

Instalación

# Clonar el repositorio
git clone https://github.com/Lalitronico/emovi-mcp.git
cd emovi-mcp

# Crear entorno virtual
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Instalar en modo editable con dependencias de desarrollo
pip install -e ".[dev]"

# Opcional: soporte de visualización
pip install -e ".[dev,viz]"

O instalar directamente desde PyPI:

pip install emovi-mcp
# Con soporte de visualización
pip install emovi-mcp[viz]

Prerrequisitos

• Python >= 3.10
• Archivos .dta de la ESRU-EMOVI 2023 (obtener del CEEY)

Configuración

Establecer la variable de entorno EMOVI_DATA_DIR apuntando al directorio con los archivos .dta:

# Linux/Mac
export EMOVI_DATA_DIR="/ruta/a/Esru Emovi 2023/_extracted/3 BASES DE DATOS/Data"

# Windows (PowerShell)
$env:EMOVI_DATA_DIR = "C:\ruta\a\Esru Emovi 2023\_extracted\3 BASES DE DATOS\Data"

# Windows (cmd)
set EMOVI_DATA_DIR=C:\ruta\a\Esru Emovi 2023\_extracted\3 BASES DE DATOS\Data

Uso con Claude Desktop

Agregar lo siguiente al archivo claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "emovi-mcp": {
      "command": "C:/ruta/a/emovi-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "emovi_mcp"],
      "env": {
        "EMOVI_DATA_DIR": "C:/ruta/a/3 BASES DE DATOS/Data"
      }
    }
  }
}

En macOS/Linux, reemplazar Scripts/python.exe por bin/python.

Herramientas

El servidor expone 11 herramientas MCP:

Ejemplos de consultas

Una vez conectado, puedes preguntar al asistente de IA cosas como:

• "¿Cuál es la distribución educativa por sexo?"

→ Usa tabulate(row_var="educ", col_var="sexo")

• "Muéstrame la matriz de movilidad educativa intergeneracional"

→ Usa transition_matrix(dimension="education")

• "¿Cuál es el ingreso promedio por región?"

→ Usa weighted_stats(variable="ingc_pc", by="region_14")

• "Compara la movilidad educativa entre hombres y mujeres"

→ Usa transition_matrix(dimension="education", by="sexo")

• "¿Qué variables hay sobre educación?"

→ Usa list_variables(search="educ")

Diccionario de variables

El proyecto incluye un diccionario preconstruido con 792 variables extraídas de la documentación oficial del CEEY y los metadatos de los archivos .dta. Soporta búsqueda por nombre, descripción, base de datos y sección.

Para reconstruir el diccionario desde los datos fuente:

python scripts/build_dictionary.py

Esto requiere el archivo Diccionario ESRU EMOVI 2023.xlsx en el directorio de datos.

Ejecutar pruebas

pytest

Las 96 pruebas cubren estadísticas ponderadas, matrices de transición, índices de movilidad, errores estándar por linealización de Taylor, inclusión financiera, comparación temporal de ingreso, visualización y funcionalidad del diccionario de variables, todo con datos sintéticos (no se requieren microdatos reales).

Notas técnicas

• Todas las estadísticas son ponderadas usando la variable de expansión factor (o fac_inc para el módulo de inclusión financiera)
• pyreadstat carga los .dta con `apply_value_formats=False` para evitar crashes por etiquetas duplicadas de municipios
• `padres_edu` se construye como max(educp, educm) siguiendo la metodología del .do del CEEY
• Índice de riqueza usa PCA sobre indicadores binarios de activos del hogar (Filmer & Pritchett, 2001), como alternativa al enfoque MCA del CEEY
• Errores estándar usan linealización de Taylor para estimadores de razón bajo muestreo estratificado por conglomerados (UPM/estrato)
• Índices de movilidad: Shorrocks M, probabilidad de escape de Prais, correlación intergeneracional de Pearson r, razón de momios de esquina
• Transporte STDIO: El servidor se comunica por entrada/salida estándar, compatible con Claude Desktop y otros clientes MCP

Estructura del proyecto

emovi-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── .github/workflows/
│   ├── ci.yml                    # CI: pytest en Python 3.10/3.11/3.12
│   └── publish.yml               # Publicar en PyPI al crear release
├── scripts/
│   └── build_dictionary.py       # Constructor del diccionario
├── src/emovi_mcp/
│   ├── __init__.py
│   ├── __main__.py               # python -m emovi_mcp
│   ├── main.py                   # Punto de entrada del servidor FastMCP
│   ├── config.py                 # Entorno, mapeos, constantes
│   ├── data_loader.py            # Cargador lazy de .dta con caché
│   ├── dictionary.py             # Diccionario de variables (JSON)
│   ├── stats_engine.py           # Matrices de transición, descriptivas
│   ├── data/
│   │   └── dictionary.json       # 792 variables
│   ├── helpers/
│   │   ├── formatting.py         # Formateadores Markdown para salida LLM
│   │   ├── labels.py             # Resolución de etiquetas de valor
│   │   ├── mobility_indices.py   # Shorrocks, Prais, razón de momios
│   │   ├── survey_variance.py    # Linealización de Taylor para SE/CI
│   │   ├── validation.py         # Validación de columnas y filtros
│   │   ├── visualization.py      # Heatmaps, Sankey, gráficas de barras
│   │   └── weights.py            # Media, mediana, cuantil, frecuencia ponderados
│   └── tools/
│       ├── __init__.py            # Registro de herramientas (11 tools)
│       ├── compare.py             # compare_groups
│       ├── describe.py            # describe_survey
│       ├── financial.py           # financial_inclusion_summary
│       ├── mobility.py            # transition_matrix
│       ├── stats.py               # weighted_stats
│       ├── subset.py              # filter_data
│       ├── tabulate.py            # tabulate
│       ├── temporal.py            # income_comparison
│       ├── variables.py           # list_variables, variable_detail
│       └── visualize.py           # visualize_mobility
└── tests/
    ├── conftest.py                # Fixtures compartidos (datos sintéticos)
    ├── test_dictionary.py
    ├── test_financial.py
    ├── test_mobility.py
    ├── test_mobility_indices.py
    ├── test_stats_engine.py
    ├── test_survey_variance.py
    ├── test_temporal.py
    ├── test_visualization.py
    └── test_wealth_index.py

Licencia

MIT

Agradecimientos

Datos de la encuesta: Centro de Estudios Espinosa Yglesias (CEEY) — ESRU-EMOVI 2023.