mef_subnational_efficiency_mcp
DiegoTurpo/mef_subnational_efficiency_mcp
Multi-agent system for auditing Peruvian public expenditure using Claude Code Skills, local MCP, and PaddleOCR — 2025 MEF data + 1964 historical digitization.
Instalação
npx convez-ai DiegoTurpo/mef_subnational_efficiency_mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
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
| Capa | Tecnología | Rol |
|---|---|---|
| Servidor MCP | FastMCP (SDK oficial) + httpx | 10 herramientas sobre la API CKAN del portal |
| Ingesta / datos | DuckDB + pandas → Parquet | Procesa sin saturar memoria (anti-flooding) |
| OCR histórico | PaddleOCR + PyMuPDF | Digitaliza 15+ páginas de 1964 |
| Dashboard | Streamlit + Plotly | 4 pestañas (2025 + 1964) |
| Agentes | 2 Claude Code Skills | Executor (construye) + Evaluator (audita/pule) |
Fuentes de datos
- 2025: dataset “Presupuesto y Ejecución de Gasto – Devengado Mensual” del
portal
datosabiertos.gob.pe(CSV2025-Gasto-Devengado-Mensual.csv, conMONTO_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(repojuaneladio/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=0automá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.mdy se muestra en el Tab 4 del dashboard.