Problema

En equipos que gestionan infraestructura como código, observabilidad y respuestas automáticas, es habitual que cada nuevo proyecto requiera consultar varios catálogos de herramientas: servidores MCP (Managed Control Plane), habilidades de agentes y toolkits. La información suele estar dispersa en documentación oficial, repositorios de terceros y wikis internas. Cuando se necesita validar que una herramienta sea “oficial” o “vendor‑backed”, el proceso se vuelve manual, propenso a errores y consume tiempo que podría dedicarse a la entrega de valor. El patrón que se repite es la falta de una fuente única, versionada y estructurada que incluya no solo el nombre del recurso sino también metadatos críticos como nivel de riesgo, capacidad de escritura y requerimientos de aprobación humana.

Causa

  1. Fuentes heterogéneas – Cada proveedor (AWS, Azure, GCP, GitHub, etc.) publica sus MCP en formatos diferentes (HTML, JSON, Swagger). Sin una capa de extracción normalizada, el equipo termina copiando y pegando datos manualmente.
  2. Ausencia de esquema de metadatos – Los catálogos oficiales rara vez incluyen campos de riesgo o políticas de aprobación. Cuando los equipos añaden esa información de forma ad‑hoc, la consistencia se pierde.
  3. Falta de CI/CD para el catálogo – Sin pruebas automáticas que verifiquen la disponibilidad de los endpoints o la validez del esquema, el repositorio se vuelve obsoleto rápidamente.
  4. Responsabilidad difusa – En muchos entornos no está claro quién mantiene la lista. Cuando varios miembros editan el mismo archivo sin reglas, aparecen conflictos y datos duplicados.

Solución

Crear un repositorio centralizado que siga estos principios:

  1. Estructura de datos basada en YAML/JSON

    • Cada entrada representa un servidor MCP o una habilidad de agente.
    • Campos obligatorios: name, vendor, type (server|skill), endpoint, risk, write_capability, human_approval, use_cases.
    • Campos opcionales: version, deprecated, notes.

  2. Automatizar la ingestión

    • Utilizar scripts (Python o Bash) que consuman APIs públicas de los proveedores y generen o actualicen los archivos YAML.
    • Ejecutar el script en un pipeline de CI cada 24 h o bajo demanda mediante un webhook.

  3. Validación de esquema

    • Añadir una etapa de CI que ejecute yamllint y un validador JSON‑Schema contra cada archivo.
    • Fallos en la validación bloquean el merge, garantizando que cualquier cambio cumpla con el contrato.

  4. Control de versiones y revisión

    • Mantener el repositorio en Git y aplicar Pull Requests obligatorios.
    • Requerir al menos una aprobación de un “owner” de dominio (por ejemplo, el equipo de Cloud o SRE) antes de mezclar.

  5. Documentar riesgos y políticas

    • Definir una tabla de riesgos (low, medium, high) basada en la capacidad de escritura y el impacto potencial.
    • Vincular cada entrada a la política de aprobación correspondiente (por ejemplo, “solo admin” para write_capability: true).

  6. Publicar artefactos

    • Generar un índice estático (HTML/JSON) que pueda ser consumido por otras pipelines o por la UI de un portal interno.
    • Usar GitHub Pages o un bucket S3 con caché de corta duración para que la información esté siempre fresca.

Paso a paso práctico

  1. Definir esquema – Guardar schema.json en la raíz del repo.
  2. Crear script de extracción – Un pequeño programa que recorra una lista de proveedores y genere archivos bajo catalog/.
  3. Configurar CI – En GitHub Actions, añadir jobs para lint, test y deploy.
  4. Establecer política de merge – Activar “Require pull request reviews before merging” y “Require status checks to pass”.

Cuándo aplicar esta solución

  • Síntomas: Cada vez que un nuevo proyecto necesita buscar “MCP server X” y el equipo pierde tiempo revisando documentación dispareja.
  • Entornos: Equipos con más de 3 proveedores de nube, uso intensivo de agentes AI/ML para automatización, o donde la seguridad de los cambios automatizados es crítica.
  • No aplica: En organizaciones que operan exclusivamente con una única herramienta propietaria y no requieren un catálogo externo; en ese caso, la sobrecarga de CI puede ser innecesaria.

Código

#!/usr/bin/env bash
set -euo pipefail

REPO_ROOT=$(git rev-parse --show-toplevel)
CATALOG_DIR="${REPO_ROOT}/catalog"
SCHEMA="${REPO_ROOT}/schema.json"

providers=(
  "aws"
  "azure"
  "gcp"
  "github"
  "gitlab"
)

fetch_aws() {
  curl -s https://api.aws.amazon.com/mcp/servers | jq -r '.servers[]' > "${CATALOG_DIR}/aws.yml"
}
fetch_azure() {
  curl -s https://management.azure.com/providers/Microsoft.DevOps/mcp?api-version=2023-01-01 | jq -r '.value[]' > "${CATALOG_DIR}/azure.yml"
}
# Añadir funciones similares para gcp, github, gitlab

# Borrar archivos antiguos
rm -f "${CATALOG_DIR}"/*.yml

for p in "${providers[@]}"; do
  "fetch_${p}"
done

# Validar contra el esquema
for file in "${CATALOG_DIR}"/*.yml; do
  python -c "import json, yaml, sys; \
    schema=json.load(open('${SCHEMA}')); \
    data=yaml.safe_load(open('$file')); \
    import jsonschema; jsonschema.validate(instance=data, schema=schema)"
done

Verificación

  1. CI pasa – Revisa que los jobs lint y test finalicen sin errores.
  2. Índice actualizado – Accede a https://<bucket>.s3.amazonaws.com/catalog.json y verifica que la nueva entrada aparece con los campos correctos.
  3. Prueba de riesgo – Ejecuta un script de auditoría que busque risk: high y write_capability: true; asegúrate de que esas combinaciones requieran al menos dos aprobaciones en la política de repositorio.

Notas adicionales

  • Manejo de deprecaciones – Marca los servidores obsoletos con deprecated: true y agrega una fecha estimada de retirada. Los pipelines pueden filtrar automáticamente esas entradas.
  • Escalabilidad – Si el número de entradas supera varios cientos, considera dividir el catálogo por dominio (cloud/aws.yml, ci/gitlab.yml).
  • Seguridad – Nunca incluyas credenciales en los archivos YAML; usa referencias a secretos gestionados por Vault o AWS Secrets Manager.
  • Colaboración – Usa plantillas de Pull Request que obliguen a rellenar los campos de riesgo y aprobación; esto reduce la carga cognitiva al crear una nueva entrada.