mef_subnational_efficiency_mcp

Sistema multi-agente local para auditar el gasto público del Perú usando Claude Code Skills, un servidor MCP local y PaddleOCR: analiza la ejecución presupuestal 2025 del MEF y digitaliza registros históricos de 1964.

Tarea HW_05 — Auditoría del Gasto Público vía Sistemas Multi-Agente, Claude Code Skills y MCP Local.

Arquitectura

Related MCP server: PNDA-MCP

Fuentes de datos

• 2025: dataset “Presupuesto y Ejecución de Gasto – Devengado Mensual” del portal datosabiertos.gob.pe (CSV 2025-Gasto-Devengado-Mensual.csv, con MONTO_PIM, MONTO_DEVENGADO_ANUAL, departamento, pliego, etc.).

• 1964: PDF de la Cuenta General de la República (1964) → data/raw_pdfs/cuenta_general_1964.pdf (descarga manual).

• Vulnerabilidad social (Tab 2): dataset “Resumen de Hogares afiliados… Programa JUNTOS 2025” del portal datosabiertos.gob.pe (hogares en pobreza por departamento, proxy de vulnerabilidad).

• Geo: peru_departamental_simple.geojson (repo juaneladio/peru-geojson).

Métricas

• Avance de ejecución = (Devengado / PIM) × 100

• Saldo No Devengado = PIM − Devengado

Estructura del proyecto

mef_subnational_efficiency_mcp/
├── app.py                    # Dashboard Streamlit (4 tabs)
├── requirements.txt
├── .streamlit/config.toml
├── .claude/skills/           # Skills Executor y Evaluator (.json + SKILL.md)
├── src/
│   ├── mcp_server.py         # Servidor MCP + 10 herramientas
│   ├── data_pipeline.py      # Ingesta 2025 (DuckDB → Parquet)
│   ├── ocr_engine.py         # OCR de 1964 (PaddleOCR + PyMuPDF)
│   ├── analytical_engine.py  # Métricas (Avance, Saldo No Devengado)
│   ├── vulnerabilidad.py     # Vulnerabilidad por depto (JUNTOS 2025)
│   └── utils.py              # Cliente CKAN + helpers
├── data/
│   ├── raw_pdfs/             # PDF crudo de 1964 (no versionado)
│   ├── snapshots/            # Muestras de esquema (5–10 filas)
│   ├── geo/                  # GeoJSON de departamentos del Perú
│   └── processed/            # Salidas Parquet "microscópicas"
├── docs/evaluator_report.md  # Reporte de auditoría del Evaluator (Tab 4)
└── video/link.txt            # Enlace del video de presentación

Requisitos e instalación

⚠️ Usar Python 3.12 (PaddleOCR no soporta 3.14).

# Crear entorno virtual con Python 3.12
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1

# Instalar dependencias
pip install -r requirements.txt

Uso

# 1) Servidor MCP (transporte stdio, sin auth)
py -3.12 src/mcp_server.py

# 2) Dashboard
py -3.12 -m streamlit run app.py

Flujo de desarrollo (Git)

El proyecto se construye por componentes en branches feature/* y se integra a main mediante Pull Requests (nunca commits directos a main):

feature/mcp-server-core · feature/data-snapshot-pipeline · feature/historical-1964-paddle-ocr · feature/executor-dashboard-draft · feature/evaluator-qa-refinement

Notas de ejecución

• Los Parquet procesados (data/processed/) ya están versionados, así que el dashboard funciona tras clonar sin reprocesar los GB de origen.

• El CSV crudo del MEF (~2.66 GB) se descarga a una carpeta temporal del sistema (fuera del repo) cuando se ejecuta el pipeline.

• PaddleOCR/CPU: el código fija FLAGS_use_mkldnn=0 automáticamente para evitar un fallo de oneDNN en PaddlePaddle 3.x (no requiere acción manual).

• El reporte de auditoría del Evaluator está en docs/evaluator_report.md y se muestra en el Tab 4 del dashboard.