MEF Subnational Efficiency MCP 🇵🇪

Sistema de Auditoría de Gasto Público Subnacional — Perú 2025 + Archivo Histórico 1964

Pipeline multi-agente local construido con Claude Code CLI, MCP y PaddleOCR para auditar la ejecución presupuestal de gobiernos regionales y locales del Perú.

---

Arquitectura General

Claude Code CLI
      │
      ├── executor_skill.json  →  Orquesta extracción, transformación y composición del dashboard
      └── evaluator_skill.json →  Audita, optimiza y pule el output del Executor
              │
              ▼
      src/mcp_server.py        →  Servidor MCP local (10 herramientas CKAN + OCR)
              │
      ┌───────┴────────┐
      │                │
src/data_pipeline.py   src/ocr_engine.py
(Track 2025)           (Track 1964 — PaddleOCR)
      │                │
      └───────┬────────┘
              ▼
       data/processed/         →  Parquets micro-footprint + KPIs JSON
              │
              ▼
           app.py              →  Dashboard Streamlit 4 tabs

---

Quick Start

1. Instalación

git clone <repo-url>
cd mef_subnational_efficiency_mcp
pip install -r requirements.txt

Para Ubuntu/Debian: sudo apt-get install poppler-utils (requerido por pdf2image)

2. Iniciar el MCP Server

python src/mcp_server.py

3. Ejecutar el pipeline vía Claude Code CLI

# Pipeline mensual
claude "run executor_skill for period 2025-12"

# Pipeline trimestral
claude "execute mef_update for 2025-Q4"

# Modo mock (desarrollo sin conexión)
python src/data_pipeline.py --period 2025-12 --mock

4. Lanzar el Dashboard

streamlit run app.py

---

Estructura del Repositorio

mef_subnational_efficiency_mcp/
│
├── app.py                             # Dashboard Streamlit — 4 tabs
├── README.md                          # Este archivo
├── requirements.txt
│
├── .claude/
│   └── skills/
│       ├── executor_skill.json        # Skill de extracción y composición
│       └── evaluator_skill.json       # Skill de auditoría y optimización
│
├── src/
│   ├── mcp_server.py                  # Servidor MCP local (10 herramientas)
│   ├── data_pipeline.py               # Pipeline 2025: snapshot → filter → Parquet
│   ├── ocr_engine.py                  # PaddleOCR — mínimo 15 páginas del PDF 1964
│   ├── analytical_engine.py           # Métricas fiscales y agrupaciones
│   └── utils.py                       # Logging, parseo de períodos, helpers
│
├── data/
│   ├── raw_pdfs/                      # PDF 1964 descargado
│   ├── snapshots/                     # schema.json (contrato de columnas)
│   └── processed/                     # Parquets 2025 + JSONs KPI + logs de runs
│
└── video/
    └── link.txt                       # URL del video de presentación (5 min)

---

Reglas Anti-Context-Flooding

⚠️ CRÍTICO: Los datasets del portal MEF pueden superar 200MB–1GB. Está estrictamente prohibido cargarlos completos en el contexto del LLM.

Protocolo obligatorio:

1. inspeccionar_esquema_csv → captura solo primeras 10 filas para mapear columnas
2. data_pipeline.py corre externamente en chunks de 50k filas con pandas
3. Solo el Parquet resultante (< 5MB) es leído por app.py

---

Métricas Fiscales (Track 2025)

Métrica	Fórmula
Avance %	(Devengado / PIM) × 100
Saldo No Devengado	PIM − Devengado
Clasificación	≥70% ✅ Aceptable · 40-70% ⚠️ Riesgo · <40% 🔴 Crítico

Filtros aplicados:

• Nivel gobierno: Regional o Local
• PIM mínimo: S/ 10,000,000

---

Track Histórico 1964

El pipeline procesa mínimo 15 páginas del PDF "Ministerio de Hacienda y Comercio — Presupuesto, Balance y Cuenta General de la República 1964" usando PaddleOCR.

Los resultados se presentan de forma completamente independiente en el Tab 1 del dashboard, sin comparaciones directas con cifras 2025 (los marcos contables son incompatibles).

---

Contrato de Esquema (Para integración P1 ↔ P3)

{
  "columns": ["region", "entidad", "nivel_gobierno", "funcion",
               "PIM", "devengado", "avance_pct", "saldo_no_devengado"],
  "types": {
    "region": "str", "entidad": "str",
    "nivel_gobierno": "str", "funcion": "str",
    "PIM": "float64", "devengado": "float64",
    "avance_pct": "float64", "saldo_no_devengado": "float64"
  }
}

Ver data/snapshots/schema.json para el contrato completo con rutas de archivos.

---

GitHub Workflow

# Ramas de desarrollo (NUNCA commitear directo a main)
git checkout -b feature/mcp-server-core
git checkout -b feature/data-snapshot-pipeline
git checkout -b feature/historical-1964-paddle-ocr
git checkout -b feature/executor-dashboard-draft
git checkout -b feature/evaluator-qa-refinement

Merge exclusivamente vía Pull Requests con descripción del cambio.

---

Team

Persona	Responsabilidad
Mayra (P1)	MCP Server + Pipeline 2025 + Skills JSON
Camila (P2)	OCR Engine 1964 + Tab 1 del Dashboard
P3	Tabs 2-4 + Evaluator + Video

---

Video de Presentación

Ver video/link.txt — máximo 5 minutos, 3-4 slides + demo live del dashboard.