peru-gob-mcp

Servidor MCP enfocado en contratacion publica y seguimiento legislativo del Peru. MVP con dos pilares:

1. Contrataciones Abiertas (OSCE) - busqueda de procesos de contratacion publica (estandar OCDS) y un tool de deteccion de anomalias: postor unico, montos muy por encima de la mediana de su categoria, y concentracion de proveedor.
2. Proyectos de Ley (Congreso) - busqueda y seguimiento de proyectos de ley, y descarga de sus PDFs.
3. Busqueda semantica (vectorial) - sobre ambos dominios: encuentra contrataciones o proyectos de ley por significado (embeddings + ChromaDB), no solo por coincidencia exacta de texto. Ver seccion dedicada abajo.

Estado de verificacion de los endpoints (leer antes de usar)

• Congreso - listado y busqueda: confirmado end-to-end en vivo (endpoint real, formato del body, y nombres de campo, no solo el dominio):
  • El listado real es POST {base}/proyecto-ley/lista-con-filtro con body {"perParId": <int>} (id de periodo parlamentario, ej. 2021 para "2021-2026"; 0 = periodo activo sin filtrar). No pagina del lado del servidor - una sola llamada sin filtro devuelve los ~15,000 proyectos del periodo activo, asi que este cliente pagina y filtra por keyword del lado del cliente (ver docstring de CongresoClient.buscar_proyectos).
  • El dominio bloquea (403, WAF) peticiones sin un User-Agent de navegador - ya viene resuelto en el codigo, pero es la causa mas probable si alguna vez ves 403 en vez de 404 en cualquier fuente.
  • Campos reales confirmados en las respuestas de listado: proyectoLey (numero, ej. "14861/2025-GR"), titulo, fecPresentacion. El listado no trae sumilla ni el id de archivo PDF (proyectoArchivoId).
  • Verificado corriendo indexar_proyectos_ley real: 50/50 documentos indexados sin errores, y buscar_proyectos_ley_semantico("informalidad laboral") devolvio resultados relevantes (proyectos sobre trabajo forzoso, remuneraciones, etc.) sin que esas palabras exactas aparecieran en los titulos.
  • Congreso - detalle: NO confirmado, a pesar de intentarlo en profundidad. obtener_proyecto_ley usa GET {base}/proyecto-ley/{numero}?codigo={periodo} como mejor esfuerzo, pero devolvio "success" con data vacia en todas las combinaciones reales de numero/periodo probadas. Inspeccionando el bundle JS del portal, el unico punto donde se llama a un metodo con esa forma de URL en realidad pasaba (perParId, codigo-de-congresista) como argumentos - es decir, es posible que ni siquiera sea un endpoint de "detalle por numero de proyecto". No confies en obtener_proyecto_ley hasta verificarlo mejor - usa buscar_proyectos_ley para obtener titulo/estado/fecha de un proyecto conocido en su lugar. Por la misma razon, no hay forma confirmada hoy de obtener un archivo_id real para descargar_pdf_proyecto_ley.
• OSCE: el dominio contratacionesabiertas.osce.gob.pe y la publicacion de datos en formato OCDS estan confirmados por documentacion oficial (gob.pe, OECD-OPSI), pero no se pudo verificar en vivo - el dominio no resuelve DNS desde ningun entorno usado durante el desarrollo (navegador y HTTP directo). La ruta exacta de busqueda (/releases por defecto) sigue siendo un supuesto razonable, no confirmado.

Las rutas son configurables por variable de entorno sin tocar codigo (ver .env.example). Si usas buscar_contrataciones y te da 404: corre el tool verificar_conectividad, abri el portal en un navegador normal, mira la pestana Network al hacer una busqueda, y ajusta OSCE_RELEASES_PATH / OSCE_RELEASE_DETAIL_PATH en tu .env (Congreso ya deberia funcionar tal cual esta).

Instalacion

python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -e .
cp .env.example .env          # y ajustar si hace falta

El install es notablemente mas pesado que un servidor MCP tipico por las dependencias transitivas de chromadb (onnxruntime, numpy, sqlite embebido). No requiere PyTorch ni GPU.

Ejecutar en modo desarrollo

mcp dev src/peru_gob_mcp/server.py

Configurar en Claude Desktop / Claude Code

Agregar a la configuracion de servidores MCP:

{
  "mcpServers": {
    "peru-gob-mcp": {
      "command": "python",
      "args": ["-m", "peru_gob_mcp.server"],
      "cwd": "C:/source/NONAME-MCP"
    }
  }
}

Tools disponibles

Tool	Descripcion
buscar_contrataciones	Busca procesos de contratacion publica (OCDS) por texto, entidad y fechas
obtener_contratacion	Detalle completo de un proceso por OCID
detectar_anomalias_contratacion	Tamizaje: postor unico, sobreprecios (z-score vs mediana de categoria), concentracion de proveedor
buscar_proyectos_ley	Busca proyectos de ley por texto, periodo o comision
obtener_proyecto_ley	Detalle de un proyecto de ley - endpoint no confirmado, ver arriba
descargar_pdf_proyecto_ley	Descarga el PDF de un proyecto de ley (base64)
verificar_conectividad	Diagnostico: prueba si OSCE y Congreso son alcanzables con la config actual
indexar_contrataciones	Indexa contrataciones OSCE (chunking + embeddings) en la base vectorial local
buscar_contrataciones_semantico	Busca contrataciones por significado sobre lo indexado
indexar_proyectos_ley	Indexa proyectos de ley (titulo+sumilla+PDF) en la base vectorial local
buscar_proyectos_ley_semantico	Busca proyectos de ley por significado sobre lo indexado

detectar_anomalias_contratacion es un tamizaje estadistico, no una acusacion - cada hallazgo debe verificarse caso por caso antes de sacar conclusiones.

Busqueda semantica

Los tools buscar_*_semantico NO buscan sobre todo OSCE/Congreso en vivo: buscan sobre lo que ya indexaste con indexar_contrataciones / indexar_proyectos_ley. Flujo tipico:

indexar_proyectos_ley(periodo="2021-2026", max_paginas=3)
buscar_proyectos_ley_semantico("informalidad laboral")

Detalles de implementacion:

• Vector store: ChromaDB, embebido, persiste en VECTOR_DB_PATH (default ./data/chroma). Sin servidor que levantar.
• Embeddings: fastembed (ONNX Runtime), 100% offline/CPU, sin API key. Modelo default jinaai/jina-embeddings-v2-base-es (~0.64GB) - se descarga una sola vez en el primer uso a EMBEDDING_CACHE_DIR y queda cacheado. Configurable via .env (ver alternativas mas livianas/pesadas ahi).
• Idempotencia: reindexar el mismo documento (mismo ocid/numero) actualiza sus chunks en vez de duplicarlos - seguro llamar indexar_* repetidamente.
• Filtros: entidad/comision/periodo en los tools _semantico son coincidencia EXACTA (a diferencia de los tools de palabra clave, que hacen substring match del lado del servidor de OSCE/Congreso).
• El listado de proyectos de ley no trae el id de archivo PDF (proyectoArchivoId) ni la sumilla - confirmado en vivo. Por eso indexar_proyectos_ley va a reportar tiene_texto_pdf: false en casi todos los casos hoy, e indexa solo el titulo. El endpoint de detalle que en teoria traeria esos datos no esta confirmado (ver seccion de arriba), asi que incorporar sumilla/PDF al indexado queda bloqueado hasta encontrar el endpoint real (ver Roadmap).
• keyword en buscar_proyectos_ley (el tool de palabra clave, no el semantico) filtra del lado del cliente sobre titulo unicamente, porque el endpoint real del Congreso ignora un campo de texto libre en el filtro (confirmado en vivo probando con valores desconocidos en el body).

Tests

pytest tests/ -v

La logica pura (anomalias, chunking, extraccion de PDF, construccion de documentos indexables) y la orquestacion de los services de busqueda semantica (paginacion, idempotencia, manejo de errores) estan cubiertas con tests que no requieren red ni descargar el modelo de embeddings real (se usan fakes de EmbeddingProvider/VectorStore en tests/fakes.py). Lo que no se puede testear sin red (rutas HTTP reales de OSCE/Congreso, el modelo de embeddings real) queda fuera del alcance automatico de este MVP.

Roadmap / ideas no incluidas en este MVP

• Encontrar el endpoint real de detalle de un proyecto de ley (el supuesto actual, /proyecto-ley/{numero}?codigo=..., no esta confirmado - ver seccion de arriba). Una vez confirmado, indexar_proyectos_ley deberia consultarlo por cada item para incorporar sumilla y PDF al texto indexado.
• Confirmar en vivo las rutas de OSCE (no accesible desde este entorno) y descubrir los campos reales de filtro por comision/texto en el DTO de Congreso (FiltroProyecLeyDto - hoy solo perParId esta confirmado).
• Radar de ejecucion presupuestal (MEF - Consulta Amigable)
• Resolucion de series BCRP en lenguaje natural + comparativas con Banco Mundial/FMI
• Panel de disparidad regional (INEI)
• RAG sobre Reporte de Inflacion (BCRP) y Marco Macroeconomico Multianual (MEF)