gov-ec-mcp-server

dfevx/gov-ec-mcp-server

3.1

If you are the rightful owner of gov-ec-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The MCP Server for Citizen Co-decision in Ecuador is a secure and verifiable platform that provides access to public government data, enabling participatory analysis and citizen co-decision.

gov-ec-mcp-server — MCP Server para co-decisión ciudadana (Ecuador)

Servidor Model Context Protocol (MCP) que expone, de forma segura y verificable, vistas de una base de datos Postgres/Supabase con datos públicos del Gobierno de Ecuador. Este repositorio corresponde al módulo 2 de un proyecto mayor: una infraestructura de datos semántica para habilitar análisis participativo y co-decisión ciudadana en el Observatorio Ciudadano para Estado Abierto (CPCCS).

El MVP se centra en el conjunto Detenidos/Aprehendidos de datosabiertos.gob.ec, entregando consultas en modo solo-lectura, reportes auditables y registros de acceso/errores con mínimos privilegios.

📌 Objetivos

  • Bajar la barrera técnica: permitir a equipos no técnicos (CPCCS, ciudadanía, periodistas) consultar y descargar datos abiertos con semántica documentada.
  • Veracidad y trazabilidad: exponer vistas controladas, documentar campos/relaciones, y registrar uso/errores para auditoría.
  • Arquitectura portable: correr en local (con túnel HTTPS via grok) y en Railway (PaaS), con configuración por .env.

🧩 Arquitectura (visión general)

  • MCP Server (este repo): FastAPI/Uvicorn + MCP; carga YAMLs de metadata y reportes; aplica guardarraíles (timeouts, paginación, modo “full-scan”).
  • Postgres/Supabase (read-only): vista pública v_detenidos_public, índices de consulta, roles de solo lectura (mcp_ro) y solo inserción de logs (mcp_log).
  • YAML maestro: describe datasets y reportes; paths por defecto: metadata/datasets.yml y metadata/reports.yml.
  • Logs: access_logs y error_logs con RLS (INSERT-only para mcp_log).
  • Despliegue: Procfile (Railway), configuración en pyproject.toml y dependencias en requirements.txt.

🗂️ Estructura del repositorio

.
├─ metadata/                     # YAML maestro (datasets y reportes)
│  ├─ datasets.yml
│  ├─ detenidos_aprehendidos.yml
│  └─ reports.yml
├─ sql/                          # Migraciones/objetos de BD (ordenadas por prefijo)
│  ├─ 010_view_v_detenidos_public.sql
│  ├─ 020_indexes_analytics.sql
│  ├─ 030_roles_and_grants.sql
│  └─ 040_logs_tables_policies.sql
├─ src/mcp_ec/                   # Código del servidor MCP
│  ├─ __init__.py
│  ├─ config.py
│  ├─ db.py
│  ├─ http_app.py
│  ├─ logging_config.py
│  ├─ metadata.py
│  ├─ reports.py
│  ├─ run_http.py
│  └─ security.py
├─ .gitignore
├─ Procfile
├─ pyproject.toml
├─ requirements.txt
├─ SECURITY.md
└─ README.md
  • Nota: el proyecto usa layout src/ y empaquetado con setuptools/pyproject; include-package-data = true permite que lo indicado en MANIFEST.in (YAML/SQL) viaje en el sdist.

✅ Requisitos

  • Python 3.11+
  • Postgres/Supabase con usuarios de mínimo privilegio:
    • mcp_ro: read-only sobre vistas públicas
    • mcp_log: insert-only en access_logs y error_logs
  • Variables de entorno en .env (usa la plantilla .env.example). Claves principales:
    • DB_URL_RO, DB_URL_LOG, STATEMENT_TIMEOUT_MS, PAGE_MAX, METADATA_FILE, REPORTS_FILE, HOST, PORT, RELOAD, TRUST_PROXY.

⚙️ Instalación

Opción A (rápida, para testers):

python -m venv .venv
# Windows:
.venv\Scripts ctivate
# macOS/Linux:
# source .venv/bin/activate

pip install -r requirements.txt

Opción B (proyecto editable, extras de desarrollo opcionales):

pip install -e .      # instala según pyproject.toml
# o con extras de dev:
# pip install -e .[dev]
  • Las dependencias principales están definidas en pyproject.toml (PEP 621) y reflejadas en requirements.txt para facilitar pruebas por terceros.

🔧 Configuración

  1. Copia la plantilla y completa valores reales (no subas .env al repo):
cp .env.example .env
  1. Variables clave (extracto):
  • DB_URL_RO, DB_URL_LOG: DSNs con sslmode=require y connect_timeout=5.
  • REQUIRE_FULL_SCAN_DEFAULT, ERROR_LOGGING_ENABLED, STATEMENT_TIMEOUT_MS, PAGE_DEFAULT, PAGE_MAX.
  • METADATA_FILE, REPORTS_FILE: rutas al YAML maestro (por defecto metadata/*.yml).
  • HOST, PORT, RELOAD, WEB_CONCURRENCY, TRUST_PROXY, FORWARDED_ALLOW_IPS.

El repo incluye .gitignore para evitar que .env, entornos y artefactos de build se suban por error.

🗃️ Preparar Base de Datos

Ejecuta los SQL en este orden:

psql "$DB_URL_ADMIN" -f sql/010_view_v_detenidos_public.sql
psql "$DB_URL_ADMIN" -f sql/020_indexes_analytics.sql
psql "$DB_URL_ADMIN" -f sql/030_roles_and_grants.sql
psql "$DB_URL_ADMIN" -f sql/040_logs_tables_policies.sql
  • 010: crea la vista v_detenidos_public (superficie de lectura).
  • 020: índices para filtros más comunes y rangos temporales.
  • 030: crea usuarios de mínimo privilegio y concede permisos.
  • 040: tablas de logs, índices y RLS (INSERT-only para mcp_log).

En Supabase, puedes aplicar cada script desde SQL Editor con un rol administrador del proyecto.

▶️ Ejecución en local

# Con el entrypoint del proyecto (recomendado para reproducir prod)
python -m mcp_ec.run_http --host 127.0.0.1 --port 8000

# Alternativa directa (si necesitas)
# uvicorn mcp_ec.http_app:app --host 127.0.0.1 --port 8000 --reload
  • Para exponerlo a un cliente MCP externo (p. ej., Claude Pro Desktop), crea un túnel HTTPS (ej. grok): 
    grok http 8000
    Usa la URL pública resultante como endpoint del servidor MCP en tu cliente.

☁️ Despliegue en Railway

  1. Crear proyecto en Railway y conectar el repo.
  2. Variables: define en el panel (DB_URL_RO, DB_URL_LOG, etc.; no subas .env).
  3. Procfile: el repo incluye un proceso web que arranca el servidor: 
    web: python -m mcp_ec.run_http --host 0.0.0.0 --port $PORT
  4. Deploy: Railway/Nixpacks detecta Python y usará el Procfile.

Si desplegaste detrás de proxy, el run_http.py aplica cabeceras de proxy y configura HOST/PORT desde entorno (ver .env.example).

🔐 Seguridad (resumen)

  • Principio de mínimo privilegio: mcp_ro (read-only), mcp_log (insert-only).
  • RLS en logs: bloquea lecturas por roles de aplicación.
  • Guardarraíles: STATEMENT_TIMEOUT_MS, PAGE_MAX, REQUIRE_FULL_SCAN_DEFAULT.
  • Transporte: siempre detrás de HTTPS (Railway) o túnel HTTPS (local).
  • Gestión de secretos: no versionar .env; rotar credenciales si se exponen.

Consulta para detalles operativos y flujo de responsible disclosure.

🧪 Salud y endpoints

  • Healthcheck: ruta /__health
  • Documentación interactiva: si está habilitada por tu build, la UI de OpenAPI suele estar en /docs.
  • MCP: las herramientas/recursos se anuncian vía protocolo MCP para clientes compatibles (p. ej., Claude Desktop).

🧰 Comandos útiles

# Instalar solo runtime
pip install -r requirements.txt

# Instalar editable con extras de dev
pip install -e .[dev]

# Ejecutar servidor (local)
python -m mcp_ec.run_http --host 127.0.0.1 --port 8000

🗺️ Roadmap

  • Exportadores tabulares (CSV/Parquet) y endpoints de descarga controlada.
  • Validaciones esquemáticas y data contracts por dataset.
  • Anotaciones semánticas ampliadas (definiciones, periodicidad, cobertura).
  • Métricas de uso (agregadas) y observabilidad de rendimiento.

🤝 Agradecimientos y referencias

📝 Licencia

MIT — ver .

📦 Notas de empaquetado

  • pyproject.toml define metadatos, dependencias y entry point mcp-serve.
  • requirements.txt replica las dependencias de ejecución para instalaciones rápidas por terceros.
  • .gitignore excluye .env, entornos, caches y artefactos locales.
  • Variables por defecto y rutas de YAML están ejemplificadas en .env.example.