Cvlac

Servidor MCP (stdio) para sincronizar tu perfil de CvLAC (MinCiencias) con tu portafolio web, usando TypeScript + Playwright.

No trae datos de nadie: tus credenciales, tus valores por defecto y tus proyectos curados viven en archivos locales que el repo ignora. Sirve para cualquier persona con una hoja de vida en CvLAC.

Permite:

• leer datos en vivo del CvLAC (read_cvlac)
• leer el portafolio (read_portfolio)
• calcular diferencias (diff): faltantes, a actualizar, parecidos y al día
• aplicar cambios por sección (update_section: add / update / delete)
• sincronizar de forma masiva (sync, con dry_run)

Dos garantías al escribir: nunca crea un duplicado sin preguntar (si ya hay algo igual o parecido devuelve needs_confirmation en vez de escribir) y siempre dice qué campo falló cuando CvLAC rechaza un formulario.

Uso responsable. Esto automatiza un sitio gubernamental con tu propia cuenta. Úsalo con supervisión humana, revisa cada dry_run antes de aplicar y no lo dejes corriendo sin mirar.

Qué está verificado, qué falta y las limitaciones conocidas: ROADMAP.md.

---

Tabla de contenido

• Inicio rápido: instalar y configurar el MCP (Linux, Windows, macOS)
• Arquitectura
• Tools MCP disponibles
• Variables de entorno
• Uso local
• Flujo recomendado
• Pruebas y build
• Troubleshooting
• Seguridad y buenas prácticas
• Estado y roadmap

---

Inicio rápido: instalar y configurar el MCP (Linux, Windows, macOS)

Esta es la guía oficial de instalación y configuración. Sigue los pasos en orden; cada uno incluye una verificación para no avanzar con un entorno roto.

Paso 0 - Prerrequisitos (todas las plataformas)

Necesitas Node.js 20 o superior, npm 10+ y git.

Plataforma	Cómo instalar Node 20+
Linux (Debian/Ubuntu)	curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs git
Linux (cualquier distro, recomendado)	Instalar nvm y luego nvm install 20 && nvm use 20
macOS	brew install node@20 git (con Homebrew) o nvm
Windows	winget install OpenJS.NodeJS.LTS y winget install Git.Git (o instalador desde nodejs.org)

Verifica (sirve igual en bash, zsh o PowerShell):

node --version   # debe mostrar v20.x o superior
npm --version    # debe mostrar 10.x o superior
git --version

Paso 1 - Clonar el repositorio

Linux / macOS (bash o zsh):

cd ~/dev            # o la carpeta que prefieras
git clone https://github.com/stivenson/cvlac-mcp.git
cd cvlac-mcp

Windows (PowerShell):

cd $HOME\dev        # crea la carpeta antes si no existe: mkdir $HOME\dev
git clone https://github.com/stivenson/cvlac-mcp.git
cd cvlac-mcp

Paso 2 - Instalar dependencias y compilar

Igual en las tres plataformas:

npm install
npm run build

Verifica: debe existir el archivo de entrada compilado dist/index.js.

# Linux / macOS
ls dist/index.js

# Windows (PowerShell)
Test-Path dist\index.js   # debe imprimir True

Paso 3 - Instalar el navegador de Playwright

El servidor automatiza CvLAC con Chromium headless. Descárgalo explícitamente (robusto en cualquier SO):

npx playwright install chromium

En Linux, si faltan librerías del sistema, instala también las dependencias nativas:

npx playwright install-deps chromium   # requiere sudo en algunas distros

Paso 4 - Configurar variables de entorno (.env)

Copia la plantilla y edita los valores:

Linux / macOS:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

Edita .env con tus datos:

CVLAC_NOMBRE=TuNombre
CVLAC_CEDULA=TuDocumento
CVLAC_PASSWORD=TuPassword
CVLAC_SESSION_PATH=/ruta/a/tu/.cvlac-session.json
PORTFOLIO_URL=https://tu-usuario.github.io

Restringe los permisos del archivo (Linux/macOS):

chmod 600 .env

CVLAC_SESSION_PATH por plataforma (ejemplos):

• Linux: /home/TU_USUARIO/.cvlac-session.json
• macOS: /Users/TU_USUARIO/.cvlac-session.json
• Windows: C:\\Users\\TU_USUARIO\\.cvlac-session.json

Paso 4b - Configurar tus valores por defecto (cvlac.config.json)

Varios formularios de CvLAC exigen campos que tu portafolio no tiene (municipio, intensidad horaria, idioma). Se declaran una vez aquí:

cp cvlac.config.example.json cvlac.config.json

{
  "portfolioUrl": "https://tu-usuario.github.io",
  "ownerNamePattern": "Tu Nombre",
  "defaults": {
    "municipio": { "nombre": "Bogotá", "codigoDane": "11001" },
    "institucionFallback": "Universidad Nacional de Colombia",
    "horasSemanales": 1,
    "idioma": "ES",
    "pais": "CO"
  }
}

Todo es opcional. Si un valor falta, el campo se deja vacío y la respuesta trae un warning — el servidor no inventa datos para tu hoja de vida.

Paso 4c - Curar proyectos, software y eventos (data/portfolio-extra.json)

Estas tres secciones no se pueden leer del portafolio: necesitan metadatos que solo existen en CvLAC (tipo de proyecto, código DANE, códigos de enum). Se mantienen a mano:

cp data/portfolio-extra.example.json data/portfolio-extra.json

El archivo se valida al cargarse; si un ítem está mal formado, el servidor lo reporta y sigue con las demás secciones.

Paso 5 - Registrar el MCP en Cursor

El servidor corre por stdio y su entrypoint real es dist/index.js. Añádelo al archivo de configuración MCP de Cursor.

Ubicación del archivo mcp.json:

• Global — Linux/macOS: ~/.cursor/mcp.json · Windows: %USERPROFILE%\.cursor\mcp.json
• Por proyecto — <proyecto>/.cursor/mcp.json

Contenido (ajusta la ruta de args a tu sistema):

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "node",
      "args": ["/home/TU_USUARIO/dev/cvlac-mcp/dist/index.js"]
    }
  }
}

Ruta de args según el SO:

• Linux: "/home/TU_USUARIO/dev/cvlac-mcp/dist/index.js"
• macOS: "/Users/TU_USUARIO/dev/cvlac-mcp/dist/index.js"
• Windows: "C:\\Users\\TU_USUARIO\\dev\\cvlac-mcp\\dist\\index.js" (usa dobles barras invertidas en JSON)

Deja las credenciales solo en .env. El servidor lo carga desde su propio directorio, así que no hace falta repetirlas en mcp.json — y ese archivo suele estar en tu home sin permisos restringidos, o sincronizado entre máquinas. Si aun así las pones en el bloque env, ganan sobre .env.

Paso 6 - Verificar la instalación

1. Build y tests en verde:

   npm run build
   npm test
   

2. Arranque del servidor (sanity check; queda esperando por stdio, ciérralo con Ctrl+C):

   node dist/index.js
   

3. En Cursor: reinicia/recarga, abre los ajustes de MCP y confirma que cvlac-mcp aparece activo (indicador verde) y lista sus tools.

4. Prueba funcional mínima desde el chat de Cursor, en este orden:

   • login (debe autenticar y persistir sesión)
   • read_portfolio (debe devolver datos del portafolio)
   • diff (debe reportar missing / upToDate)

Si los tres responden sin error, el MCP quedó correctamente instalado y configurado.

---

Arquitectura

src/
├── index.ts                  # Entry point (dotenv + stdio transport)
├── server.ts                 # Registro de tools MCP
├── types.ts                  # Tipos de portfolio/CvLAC/diff/update
├── diff.ts                   # Motor de comparación (normalize + nameMatches)
├── browser/
│   ├── session.ts            # Login, sesión persistente, Playwright context
│   └── navigation.ts         # URLs de listas y formularios CvLAC
├── tools/
│   ├── login.ts
│   ├── read-cvlac.ts
│   ├── read-portfolio.ts
│   ├── diff.ts
│   ├── update-section.ts     # add/update/delete por sección
│   ├── sync.ts
│   └── screenshot.ts
└── extractors/
    ├── portfolio.ts
    └── cvlac/
        formacion.ts experiencia.ts cursos.ts reconocimientos.ts
        proyectos.ts software.ts eventos.ts

---

Tools MCP disponibles

• login: autentica en CvLAC y persiste sesión.
• read_cvlac: lee una sección o todas (all) desde CvLAC.
• read_portfolio: obtiene y parsea el portafolio.
• diff: compara CvLAC vs portafolio y reporta cuatro grupos: missing, toUpdate, similar (parecidos a algo existente) y upToDate.
• update_section: aplica cambio puntual (add, update, delete). Devuelve status, warnings por campo y, si detecta un posible duplicado, needs_confirmation con los candidatos. confirm_duplicate:true fuerza la creación.
• sync: ejecuta diff + aplica missing y toUpdate (con dry_run opcional). Los similar nunca se aplican solos.
• screenshot: captura pantalla del estado actual.
• inspect_form: inspecciona campos reales (input/select/textarea) de una URL CvLAC.

Secciones soportadas: formacion, experiencia, cursos, reconocimientos, proyectos, software, eventos.

---

Variables de entorno

Definidas en .env (ver Paso 4):

Variable	Descripción
CVLAC_NOMBRE	Nombre con el que inicias sesión en CvLAC
CVLAC_CEDULA	Documento de identidad
CVLAC_PASSWORD	Contraseña de CvLAC
CVLAC_SESSION_PATH	Ruta donde se guarda storageState para reusar sesión
PORTFOLIO_URL	Portafolio a comparar. También configurable como portfolioUrl en cvlac.config.json

Opcionales:

Variable	Descripción
CVLAC_HEADLESS	false abre el navegador para ver qué hace
CVLAC_LOG_LEVEL	debug | info (default) | warn | error | silent. Los logs van a stderr
CVLAC_LOG_FILE	Además de stderr, agrega cada línea a este archivo
CVLAC_USER_AGENT	Reemplaza el user-agent del navegador
CVLAC_CONFIG_PATH	Ubicación alterna de cvlac.config.json
CVLAC_PORTFOLIO_EXTRA_PATH	Ubicación alterna de portfolio-extra.json

---

Uso local

Modo desarrollo (sin compilar)

npm run dev

Modo producción local (compilado)

npm run build
npm start

---

Flujo recomendado

1. login
2. sync con dry_run: true
3. Revisar el reporte con una persona: faltantes, a actualizar, parecidos y al día
4. Resolver los parecidos uno a uno — update sobre el existente, o add con confirm_duplicate:true
5. Aplicar el resto: sync sin dry_run, o update_section por ítem revisando los warnings
6. Verificar con read_cvlac de las secciones tocadas, o screenshot

Si trabajas con Claude Code, la skill cvlac-sync del workspace cliente encapsula este flujo.

Diagrama

flowchart LR
  portfolio["read_portfolio"] --> diffEngine
  cvlacRead["read_cvlac"] --> diffEngine["diff"]
  diffEngine --> syncTool["sync (dry_run / apply)"]
  syncTool --> updateSection["update_section add/update/delete"]

---

Pruebas y build

npm test        # suite completa: sin red, sin credenciales, sin CvLAC
npm run build

Los tests cubren extractores (contra fixtures HTML anonimizados), el motor de diff, los schemas, la carga de configuración, la redacción de secretos en logs y el reporte de sync. Los fixtures llevan datos ficticios a propósito: si capturas HTML real para uno nuevo, anonimízalo antes de commitear.

Comandos disponibles:

npm run dev
npm run test:watch
npm start

---

Troubleshooting

El MCP usa una versión vieja del código

• Asegúrate de ejecutar npm run build tras cambiar src/.
• El cliente MCP ejecuta dist/index.js, no src/index.ts.

cvlac-mcp no aparece en Cursor

• Verifica la ruta absoluta en args del mcp.json (Paso 5) y que dist/index.js exista.
• En Windows, usa dobles barras invertidas (\\) en las rutas dentro del JSON.
• Reinicia/recarga Cursor tras editar mcp.json.

Errores de Playwright al iniciar el navegador

• Ejecuta npx playwright install chromium.
• En Linux, añade dependencias del sistema con npx playwright install-deps chromium.

Redirección inesperada a login

• La sesión pudo expirar. Ejecuta login nuevamente.
• Verifica que .env (o el env del mcp.json) tenga credenciales correctas.

Cambios no aplican en formularios

• Algunos campos de CvLAC son readonly y se setean por JS.
• Usa inspect_form y screenshot para validar nombres de campo reales.
• Revisa docs/cvlac-findings.md como fuente de verdad.

Falsos faltantes en diff

• nameMatches() normaliza acentos y sufijos (ej. (Platzi), - Aprobado ...).
• experiencia está intencionalmente fuera del diff automático.

---

Seguridad y buenas prácticas

• No hardcodear credenciales.
• No commitear .env ni archivos de sesión/screenshot.
• Correr primero sync en dry_run.
• Para pruebas de escritura real en CvLAC, usar ítems dummy y luego eliminar.

---

Estado del proyecto

• Lectura de las 7 secciones verificada contra navegación real.
• update_section soporta add / update / delete.
• dist/ debe regenerarse tras cambios en src/.

Para detalles operativos de desarrollo interno, ver CLAUDE.md.

---

Estado y roadmap

Lectura de las 7 secciones, diff, bloqueo de duplicados y escritura add/delete están verificados contra el CvLAC real. update está implementado pero sin probar en vivo.

Detalle completo, limitaciones conocidas y lo que sigue: ROADMAP.md.

Hallazgos de navegación en vivo (URLs, columnas de tabla, nombres de campos, comportamiento de la sesión): docs/cvlac-findings.md.