CvLAC (MinCiencias) README

cvlac-mcp

Actualiza tu CvLAC conversando con tu asistente de IA, sin llenar formularios a mano.

Llenar el CvLAC de MinCiencias es lento: un formulario por cada curso, premio o proyecto, con catálogos de instituciones y municipios que no siempre encuentran lo que buscas. cvlac-mcp le da a tu asistente de IA (Claude, por ejemplo) la capacidad de hacerlo por ti: le dices en el chat qué agregar o corregir, y él entra a CvLAC con tu cuenta, llena el formulario, lo guarda y revisa que haya quedado guardado.

Funciona en tu computador. Tus credenciales no salen de él y no pasan por ningún servidor intermedio.

• Cómo se ve
• Qué puede hacer y qué no
• Qué necesitas
• Instalación paso a paso — unos 15 minutos
• Qué pedirle
• Cómo te protege
• Problemas frecuentes
• Seguridad y privacidad
• Actualizar o desinstalar
• Para desarrolladores

Cómo se ve

Una conversación se parece a esto:

Tú: Muéstrame los reconocimientos que tengo en CvLAC.

Asistente: Tienes 6. Entre ellos, "Distinción a la labor docente" (2023) y "Mejor ponencia, Congreso Nacional de Ingeniería" (2021)…

Tú: Agrega este: "Mención de honor a la labor docente", Universidad del Norte, 2024, nacional.

Asistente: No lo guardé todavía: se parece a "Distinción a la labor docente" (2023), que ya está en tu CvLAC. ¿Es el mismo reconocimiento y quieres corregirlo, o es otro y lo creo aparte?

Tú: Es otro, créalo.

Asistente: Listo, CvLAC confirmó el guardado. Ya aparece en tu lista: "Mención de honor a la labor docente", 2024, ámbito nacional.

El asistente no borra nada ni crea duplicados sin preguntarte primero. Los nombres de este ejemplo son ficticios.

Qué puede hacer y qué no

Puede leer, agregar, corregir y borrar:

Todavía no puede:

• Subir certificados desde complete_product: esa operación gestiona palabras clave, áreas, coautores, reconocimientos y estudiantes vinculados en tesis. Los certificados de libros se adjuntan mediante update_section con rutas locales; no forman parte de las listas de complete_product.
• Crear revistas, libros, editoriales, programas o áreas que no existan en los catálogos de CvLAC. Si un catálogo devuelve varias opciones, te las muestra para que elijas.
• Iniciar sesión con una cuenta de nacionalidad extranjera. Por ahora el inicio de sesión asume nacionalidad colombiana.
• Tocar tus datos de identificación y direcciones, ni nada de GrupLAC.
• Crear un programa en formación complementaria que CvLAC no tenga registrado. El buscador de CvLAC solo ofrece los que ya existen para esa institución, y la web tampoco deja crear otros.

Comparar automáticamente tu CvLAC con otra fuente (la herramienta diff) hoy solo funciona con un portafolio web que tenga una estructura concreta (detalles). Si no tienes uno, no importa: le pegas en el chat el texto de tu hoja de vida, o se lo dictas, y el asistente lee tu CvLAC y agrega lo que falte, ítem por ítem, preguntándote ante cualquier parecido.

Qué necesitas

• Tu usuario de CvLAC: primer nombre, número de cédula y contraseña, los mismos con los que entras a la web.
• Un computador con Windows, macOS o Linux.
• Node.js 20 o superior, un programa gratuito que hace funcionar esta herramienta. En el paso 1 está cómo instalarlo.
• Una app de IA que acepte servidores MCP. MCP es el estándar con el que estas apps se conectan a herramientas como esta. Si no tienes ninguna, empieza con Claude Desktop: es la más sencilla y es la que usa esta guía. También sirven Claude Code, Cursor, VS Code, Windsurf, Zed y JetBrains (cómo conectarlas).

No necesitas saber programar. Vas a copiar y pegar unos comandos en la terminal; la guía dice exactamente cuáles.

Instalación paso a paso

¿Qué es la terminal? Una ventana donde se escriben comandos. En Windows: tecla Windows, escribe PowerShell y ábrelo. En macOS: Cmd + Espacio, escribe Terminal y ábrela. Para pegar un comando: clic derecho en Windows, Cmd + V en macOS. Luego presiona Enter.

Paso 1 · Instala Node.js

Descarga la versión LTS desde nodejs.org e instálala con las opciones que vienen marcadas. Luego cierra y vuelve a abrir la terminal y comprueba:

node --version

Debe mostrar v20 o un número mayor (por ejemplo v22.11.0).

Paso 2 · Descarga el navegador que usa la herramienta

cvlac-mcp maneja CvLAC con su propia copia de Chromium, un navegador que funciona sin ventana. Se descarga una sola vez (unos 150 MB):

npx -y cvlac-mcp@1 install-browser

Al final debe decir que Chromium quedó instalado.

$env:NODE_OPTIONS="--use-system-ca"; npx -y cvlac-mcp@1 install-browser   # Windows (PowerShell)

NODE_OPTIONS=--use-system-ca npx -y cvlac-mcp@1 install-browser           # macOS / Linux

Paso 3 · Guarda tus datos de acceso

Van en un archivo de texto aparte, dentro de tu carpeta de usuario, que solo tú puedes leer.

Windows — en PowerShell:

mkdir "$HOME\.config\cvlac-mcp" -Force
notepad "$HOME\.config\cvlac-mcp\.env"

El Bloc de notas pregunta si quieres crear el archivo: di que sí. Pega estas tres líneas, cambia lo que está entre comillas por tus datos, conserva las comillas simples y guarda con Ctrl + S:

CVLAC_NOMBRE='Tu primer nombre'
CVLAC_CEDULA='1234567890'
CVLAC_PASSWORD='tu clave'

Cierra el Bloc de notas y deja el archivo legible solo por tu usuario:

icacls "$HOME\.config\cvlac-mcp\.env" /inheritance:r /grant:r "${env:USERNAME}:(R,W)"

macOS / Linux — cambia los tres valores antes de pegar, conservando las comillas simples:

mkdir -p ~/.config/cvlac-mcp
cat > ~/.config/cvlac-mcp/.env <<'EOF'
CVLAC_NOMBRE='Tu primer nombre'
CVLAC_CEDULA='1234567890'
CVLAC_PASSWORD='tu clave'
EOF
chmod 600 ~/.config/cvlac-mcp/.env

• CVLAC_NOMBRE es tu primer nombre tal como lo registraste en CvLAC, con tildes y ñ.
• Las comillas simples importan: sin ellas, una clave con # se corta ahí.
• No guardes este archivo en Escritorio ni en Documentos si esas carpetas se sincronizan con OneDrive o Google Drive. La carpeta de arriba no se sincroniza.

$contenido = @'
CVLAC_NOMBRE='Tu primer nombre'
CVLAC_CEDULA='1234567890'
CVLAC_PASSWORD='tu clave'
'@
[IO.File]::WriteAllText("$HOME\.config\cvlac-mcp\.env", $contenido)

Paso 4 · Conecta cvlac-mcp con Claude Desktop

1. Abre Claude Desktop y ve a Configuración → Desarrollador → Editar configuración (en inglés: Settings → Developer → Edit Config). Se abre la carpeta con el archivo claude_desktop_config.json: ábrelo con el Bloc de notas o TextEdit.
2. Pega el bloque de tu sistema, cambiando TU_USUARIO por tu usuario del computador. Para saber cuál es: echo $env:USERNAME en PowerShell, o whoami en la terminal de macOS.

Windows:

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "cvlac-mcp@1"],
      "env": {
        "CVLAC_ENV_FILE": "C:\\Users\\TU_USUARIO\\.config\\cvlac-mcp\\.env"
      }
    }
  }
}

macOS (en Linux, la ruta empieza por /home/ en vez de /Users/):

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "npx",
      "args": ["-y", "cvlac-mcp@1"],
      "env": {
        "CVLAC_ENV_FILE": "/Users/TU_USUARIO/.config/cvlac-mcp/.env"
      }
    }
  }
}

3. Guarda y cierra Claude Desktop del todo; no basta con cerrar la ventana. En Windows, clic derecho en su ícono junto al reloj → Salir. En macOS, Cmd + Q. Luego ábrelo de nuevo.

Detalles que suelen fallar:

• Si el archivo ya tenía algo, no lo reemplaces: agrega "cvlac-mcp": {...} dentro del "mcpServers" que ya existe, separado con una coma.
• En Windows las barras de la ruta van dobles (\\), porque el archivo es JSON. cmd /c va delante porque en Windows npx no es un programa sino un script.
• CVLAC_ENV_FILE es obligatorio: le dice a cvlac-mcp dónde quedó el archivo del paso 3.

Paso 5 · Pruébalo

En un chat nuevo de Claude Desktop, escribe:

1. "Inicia sesión en CvLAC" — debe responder que inició sesión.
2. "Muéstrame mi formación académica en CvLAC" — debe listar lo que ya tienes.

Si las dos funcionan, quedó listo. La primera vez puede tardar unos 15 segundos en conectar, porque se descarga el paquete; si aparece desconectado, espera un momento y reinicia Claude Desktop.

¿Algo falló? → Problemas frecuentes.

Otras apps de IA

La configuración es la misma del paso 4 en todas; cambia dónde se pega.

Claude Code:

# macOS / Linux
claude mcp add cvlac-mcp --scope user -e CVLAC_ENV_FILE=$HOME/.config/cvlac-mcp/.env -- npx -y cvlac-mcp@1

# Windows, desde Git Bash
MSYS_NO_PATHCONV=1 claude mcp add cvlac-mcp --scope user -e 'CVLAC_ENV_FILE=C:\Users\TU_USUARIO\.config\cvlac-mcp\.env' -- cmd /c npx -y cvlac-mcp@1

En Git Bash, sin MSYS_NO_PATHCONV=1, el /c se convierte en C:/ y el servidor no conecta. Desde PowerShell el comando falla con unknown option '-y', porque PowerShell se come el --: usa Git Bash, pon --% antes de los argumentos, o pega el JSON de Windows con claude mcp add-json.

Qué pedirle

Habla normal, en español. Algunas ideas:

Consejos:

• Pide primero ver, después cambiar. "Dime qué agregarías, sin guardar nada" es una buena forma de empezar.
• Da los datos completos: fechas, institución, horas, ámbito (nacional o internacional). Si falta un dato que CvLAC exige, el asistente te avisa en vez de inventarlo.
• Revisa en CvLAC lo que quede escrito. Lo que figura en tu hoja de vida es tu responsabilidad, y el asistente, aunque verifica cada guardado, se puede equivocar al interpretar lo que le pides.

Cómo te protege

CvLAC no tiene botón de deshacer, así que cvlac-mcp prefiere preguntar antes que equivocarse:

• No crea duplicados sin preguntar. Si lo que vas a agregar se parece a algo que ya está, no escribe nada y te muestra los parecidos.
• No borra a la primera. Todo borrado exige una segunda confirmación, incluido quitar una red académica o un área de actuación.
• No elige por ti. Si el nombre de una institución coincide con varias en el catálogo de CvLAC —hay seis "Universidad de los Andes"—, te muestra las opciones.
• No inventa datos. Si falta un dato, te avisa en vez de rellenarlo con algo que suene bien.
• Comprueba el resultado. No da por guardado algo solo porque envió el formulario: mira cómo respondió CvLAC y, si queda duda, vuelve a leer el registro. Si CvLAC se cae a mitad de un guardado, te dice que no pudo confirmarlo, para que lo revises antes de intentarlo otra vez.
• Dice qué falló. Si CvLAC rechaza un formulario, te dice qué campo y por qué.
• Cuida tu cuenta. Si CvLAC rechaza tu clave, no vuelve a intentarlo, para no bloquearte. Además espacia sus visitas a CvLAC para no saturarlo.

Problemas frecuentes

¿Otra cosa? Abre un issue, pero sin tus datos ni capturas con información personal.

Seguridad y privacidad

Qué pasa con tus datos, en concreto:

• Tus credenciales no salen de tu computador. Viven en el archivo del paso 3. cvlac-mcp las lee al arrancar y las escribe únicamente en el formulario de inicio de sesión de scienti.minciencias.gov.co.
• No hay servidor intermedio, cuentas, telemetría ni analítica. cvlac-mcp corre como un programa en tu computador y habla directamente con tu app de IA. Solo se conecta a CvLAC, al portafolio que configures y a api.crossref.org cuando pides la consulta DOI de solo lectura.
• Tu asistente de IA sí ve tu hoja de vida. No tus credenciales —cvlac-mcp nunca las devuelve—, pero sí lo que lee de tu CvLAC, porque eso viaja al chat. Tenlo en cuenta al elegir la app si tu hoja de vida tiene datos sensibles.
• La sesión vale tanto como tu clave. Para no pedir la clave en cada paso, cvlac-mcp guarda la sesión en .cvlac-session.json, en tu carpeta de usuario. Mientras siga vigente, quien copie ese archivo entra a tu CvLAC y puede modificarlo sin tu clave. En macOS y Linux se crea legible solo por ti; en Windows hereda los permisos de tu carpeta de usuario. Para restringirlo a mano: chmod 600 ~/.cvlac-session.json (macOS/Linux) o icacls "$HOME\.cvlac-session.json" /inheritance:r /grant:r "${env:USERNAME}:(R,W)" (Windows).
• Ni el archivo de datos ni la sesión en carpetas sincronizadas (OneDrive, Google Drive, Dropbox). Las rutas de esta guía no lo están.
• Para cerrar la sesión, borra .cvlac-session.json. La próxima vez, cvlac-mcp inicia sesión de nuevo.
• Los registros no muestran secretos. Aunque actives el modo detallado para depurar, la clave, la cédula y las cookies aparecen como ***. Si configuras CVLAC_LOG_FILE, el archivo se crea con permisos solo para tu usuario (0600).
• Las capturas de pantalla pueden tener datos personales. Revísalas antes de compartirlas.
• La navegación autenticada está limitada a CvLAC. inspect_form, screenshot y los enlaces internos solo aceptan HTTPS en scienti.minciencias.gov.co; se rechazan file://, otros hosts y enlaces de acción como borrar/guardar.
• El navegador conserva el sandbox de Chromium por defecto. Solo entornos que no puedan iniciarlo así deben configurar explícitamente CVLAC_NO_SANDBOX=true, entendiendo el riesgo adicional.
• Si sospechas que se filtró algo, cambia tu clave en CvLAC y borra el archivo de sesión.

Uso responsable

• Esto automatiza un sitio del Estado colombiano con tu propia cuenta y tus propios datos. No evade la autenticación, no entra a hojas de vida ajenas y no usa ninguna API oculta: hace lo mismo que harías tú en el navegador, más rápido.
• Revisa los términos de uso de ScienTI/MinCiencias y las políticas de tu institución antes de usarlo.
• Supervisión humana siempre. Pide ver los cambios antes de aplicarlos, no lo dejes trabajando sin mirar y no lo programes para que corra solo.
• No lo corras en paralelo sobre varias cuentas ni subas su ritmo de peticiones.
• Lo que quede en tu hoja de vida es tu responsabilidad. Es una declaración con efectos ante convocatorias y evaluaciones: verifica en CvLAC lo que se haya escrito.

Proyecto independiente. No está afiliado a MinCiencias ni respaldado por esa entidad. No reproduce su logotipo ni su identidad visual: el símbolo de arriba es original —unas llaves { } de JSON-RPC dentro de un anillo de trazos que convergen— y las marcas «CvLAC», «ScienTI» y «MinCiencias» se nombran solo para identificar el sistema con el que habla el servidor.

Actualizar o desinstalar

• Actualizar: no tienes que hacer nada. Con cvlac-mcp@1, cada vez que abres tu app de IA se usa la última versión 1.x. Si alguna vez sale una 2.x, cambia @1 por @2 en la configuración (lee antes qué cambió en el ROADMAP).
• Ver qué versión tienes: npx -y cvlac-mcp@1 --version.
• Desinstalar: quita el bloque "cvlac-mcp" de la configuración de tu app y borra la carpeta .config/cvlac-mcp y el archivo .cvlac-session.json de tu carpeta de usuario.

Para desarrolladores

Todo lo de aquí en adelante es para quien quiera auditar el código, contribuir, usar las herramientas MCP directamente o comparar el CvLAC con un portafolio web.

Servidor MCP (stdio) en TypeScript + Playwright, ESM estricto, probado con Vitest en Linux, Windows y macOS. Qué está verificado, qué falta y las limitaciones conocidas están en el ROADMAP.

• Instalación desde el código fuente
• Configuración avanzada
• Comparar con un portafolio (diff y sync)
• Referencia de tools MCP
• Variables de entorno
• Arquitectura
• Pruebas y build
• Problemas de desarrollo
• Estado y roadmap

Instalación desde el código fuente

Para desarrollar, contribuir o auditar el código. Si solo quieres usar el servidor, la instalación paso a paso es más corta. 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.

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. Descarga el build que corresponde a la versión de Playwright del proyecto:

node dist/index.js install-browser

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'
PORTFOLIO_URL='https://tu-usuario.github.io'
# Opcional: por defecto, .cvlac-session.json en tu carpeta de usuario
# CVLAC_SESSION_PATH='/ruta/a/tu/.cvlac-session.json'

Restringe los permisos del archivo (Linux/macOS):

chmod 600 .env

En Windows, el equivalente de chmod es icacls .env /inheritance:r /grant:r "${env:USERNAME}:(R,W)".

CVLAC_SESSION_PATH por plataforma (ejemplos, si quieres cambiarlo):

• 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",
  "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 tu app

Igual que en la instalación paso a paso, cambiando npx por node y la ruta a tu dist/index.js. No hace falta CVLAC_ENV_FILE: clonado, el servidor lee el .env de la raíz del repo.

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "node",
      "args": ["/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" (barras dobles en JSON; aquí no hace falta cmd /c, porque node sí es un ejecutable)
• Claude Code: claude mcp add cvlac-mcp --scope user -- node /ruta/a/cvlac-mcp/dist/index.js
• Dónde va el JSON en cada app: Otras apps de IA.

Deja las credenciales solo en .env. Los archivos de configuración de las apps suelen estar sin permisos restringidos o sincronizados entre máquinas. Si aun así las pones en un bloque env, ganan sobre el .env.

Paso 6 - Verificar la instalación

1. Build y tests en verde:

   TerminalCopy

   npm run build
   npm test
   

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

   bashCopy

   node dist/index.js
   

3. En tu editor: reinícialo (Claude Desktop necesita cerrarse del todo) y confirma que cvlac-mcp aparece activo y lista sus tools — Settings → MCP en Cursor, claude mcp list o /mcp en Claude Code, el selector de herramientas del chat agente en VS Code.

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

   • login (debe autenticar y persistir sesión)
   • read_cvlac con section: "formacion" (debe devolver lo que ya está en CvLAC)
   • si configuraste un portafolio: read_portfolio y luego diff

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

Configuración avanzada

Nada de esto hace falta para usar el servidor. Instalado con npx, cada archivo se apunta con una variable en el mismo bloque env de la configuración de tu app, junto a CVLAC_ENV_FILE; clonado, se toman de la raíz del repo.

Sugerido: guárdalos junto al .env, en ~/.config/cvlac-mcp/. Si falta un valor por defecto, el campo queda vacío y la respuesta trae un warning: el servidor nunca inventa un dato para una hoja de vida.

Comparar con un portafolio (diff y sync)

diff compara el CvLAC con un portafolio web y clasifica cada ítem en cuatro grupos: faltantes, a actualizar, parecidos (algo similar ya existe: decide una persona) y al día. sync previsualiza por defecto; solo aplica los faltantes y los de actualizar cuando se llama con dry_run: false, y nunca los parecidos.

Limitación importante: read_portfolio está hecho para un sitio concreto —una app React con la ruta #/resume, pestañas Experiencia, Educación y Cursos, y una sección "Logros Destacados"— y si no encuentra esa estructura devuelve listas vacías, con un warning en el log. Proyectos, software y eventos no salen del sitio sino de portfolio-extra.json. Tampoco entran al diff: experiencia profesional (los nombres de empresa difieren demasiado), idiomas, líneas ni demás trabajos.

Separar la fuente del motor —que diff acepte un JSON normalizado de hoja de vida, venga de un PDF, de ORCID o del dictado— está en el ROADMAP.

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 con dry_run: false, o update_section por ítem revisando los warnings
6. Verificar con read_cvlac de las secciones tocadas, o read_cvlac_detail

read_portfolio ─┐
                ├─► diff ─► sync (dry_run → apply) ─► update_section (add / update / delete)
read_cvlac ─────┘

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

Referencia de tools MCP

Una tool que falla devuelve isError: true. needs_confirmation y unverified no son errores: piden que una persona decida o revise.

complete_product

label encuentra un producto existente y la operación recibe una o más listas completas:

• keywords: palabras clave ordenadas.
• areas: áreas de conocimiento ordenadas, por nombre o código de CvLAC.
• coauthors: nombres de coautores ordenados desde el catálogo de perfiles previamente registrados; el propietario de la hoja de vida se conserva automáticamente.
• recognitions: títulos de reconocimientos ordenados desde los reconocimientos ya registrados en el currículo CvLAC.
• students: solo para tesis; objetos {name, participation, person_id?}. participation acepta TUT, ASE, COT, ORI o sus etiquetas (Tutor, Asesor, Cotutor, Orientado). Si se omite, se usa ORI.

Las listas reemplazan lo almacenado. Si la operación quitaría valores existentes, primero devuelve needs_confirmation con removed; repite con confirm_delete:true. Una persona no resuelta o con varios perfiles posibles vuelve en choices y no se escribe nada.

update_section

Secciones: formacion, formacionComple, experiencia, cursos, reconocimientos, proyectos, software, eventos, idiomas, lineas, demasTrabajos, articulos, libros, capitulos, tesis, jurados, informesTecnicos, innovacionesProceso, productosTecnologicos, consultorias, prototipos. El esquema de data de cada una está en src/schemas.ts; un campo mal formado se rechaza nombrándolo, antes de abrir el navegador.

Más detalles:

• Un update que no logre cambiar ningún campo del formulario no se envía: devuelve failed con los warnings.
• Una institución con coincidencia exacta se resuelve sola. El catálogo tiene duplicados exactos —seis "Universidad de los Andes"—, así que el nombre no siempre basta.
• formacionComple usa el mismo formulario que formacion, con otro catálogo de niveles (Y Otros, 8 Extensión, F Cursos de corta duración, E MBA) y startMonth. El add solo funciona con un programa académico que CvLAC ya tenga registrado para esa institución y nivel.
• libros: certificateCLCDO y certificateCLRI son rutas locales opcionales para los dos certificados PDF del formulario real. Se valida la firma %PDF-, la extensión, que el archivo exista y el límite de 2 MiB antes de enviar. CvLAC no devuelve esos archivos como valores de formulario, así que una edición solo de certificados puede responder unverified; confirma la ficha antes de reintentar.
• demasTrabajos: name, year, month, medio (Papel, Internet u Otro), finalidad, y opcionalmente idioma y ciudad. El formulario trae Enero y Papel preseleccionados: si faltan month o medio se guardan esos, y lo avisa.
• idiomas: language (nombre en español o código ISO de 2 letras) y los niveles read/write/speak/listen, o un level que los fija todos: Deficiente, Aceptable o Bueno.
• lineas: name, active (por defecto true, y lo avisa) y objective.
• experiencia: el formulario de CvLAC no tiene campo de cargo; si el ítem trae role, se avisa que no se escribió.

update_profile

• description reemplaza el texto de perfil. No se puede vaciar: CvLAC lo marca obligatorio (máx. 3950 caracteres).
• networks se fusionan con lo guardado: el formulario de CvLAC reescribe la tabla entera, así que la tool la lee primero y reenvía todo. url:null quita una red y exige confirm_delete:true. Redes aceptadas: google_scholar, researchgate, ssr, ssrn, academia_edu, mendeley, linkedin, repositorios_disciplinares, repositorios_institucionales, researcher_id, scopus_author_id, orcid y otro (con su nombre en label).
• areas es la lista completa de áreas de actuación en orden —la primera es la principal—, por nombre o por código de CvLAC (0-1B01). Reemplaza lo guardado: dejar una fuera es borrarla y exige confirm_delete:true. El catálogo tiene 267 áreas en tres niveles; un nombre ambiguo vuelve en choices en vez de adivinarse.

Variables de entorno

Se definen en el .env, o en el bloque env de la configuración de la app, que tiene prioridad.

Al arrancar, el servidor escribe en stderr qué .env leyó: env file: <ruta> (found, 3 vars), o NOT FOUND, o read as utf16le / read as latin1 si no estaba en UTF-8.

Ritmo de las peticiones

CvLAC empieza a responder 5xx cuando las peticiones llegan pegadas. El servidor espacía cada navegación, reintenta con backoff y, si el sitio rechaza varias seguidas, deja de insistir hasta que pase un enfriamiento. Los valores por defecto sirven para un sync normal; súbelos si notas 503 seguidos:

Arquitectura

src/
├── index.ts                  # Entry point: subcomandos, carga del .env, stdio transport
├── cli.ts                    # install-browser, --version, --help
├── env.ts                    # Ubicación y lectura del .env (UTF-8, UTF-16 o ANSI)
├── server.ts                 # Registro de tools MCP, isError
├── types.ts                  # Tipos de portfolio/CvLAC/diff/update
├── schemas.ts                # Un schema zod por sección
├── config.ts                 # cvlac.config.json
├── logger.ts                 # Logs a stderr, con secretos ocultos
├── 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
│   ├── navigate.ts           # Toda navegación: ritmo, reintentos, cortes
│   ├── pacing.ts             # Espaciado de peticiones y backoff
│   ├── availability.ts       # Distingue "CvLAC caído" de un error propio
│   └── catalogue.ts          # Catálogos de CvLAC (municipios, instituciones)
├── tools/
│   ├── login.ts  read-cvlac.ts  read-cvlac-detail.ts  read-portfolio.ts  diff.ts  sync.ts
│   ├── update-section.ts     # add/update/delete por sección
│   ├── write-verdict.ts      # ¿Se guardó? saved / rejected / unverified
│   ├── profile.ts            # Perfil y redes académicas
│   ├── areas.ts              # Áreas de actuación
│   └── screenshot.ts
└── extractors/
    ├── portfolio.ts          # Renderiza el portafolio + portfolio-extra.json
    └── cvlac/                # Un extractor por sección, sobre rows.ts

Las decisiones de diseño y las trampas de CvLAC que ya costaron un bug están en CLAUDE.md, y las URLs, columnas y nombres de campos verificados en vivo, en docs/cvlac-findings.md.

Pruebas y build

npm test          # suite completa: sin red, sin credenciales, sin CvLAC
npm run build     # compila src/ a dist/, que es lo que ejecuta la app
npm run dev       # corre src/ con tsx, sin compilar
npm run test:watch

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

El workflow smoke corre en Linux, Windows y macOS: compila, corre los tests, instala Chromium con install-browser y ejecuta scripts/smoke.mjs, que comprueba el arranque, el protocolo MCP, las tools registradas, el mensaje sin credenciales y que el navegador abra. Otro job escribe el .env en PowerShell 5.1 y 7 de las tres formas habituales y verifica que el servidor lo lea. Lanzado a mano, prueba además el paquete tal como se instala desde npm.

Suite en vivo (opcional, escribe en tu CvLAC real)

CVLAC_E2E=1 npm run test:e2e:live                      # las secciones con lista
CVLAC_E2E=1 npm run test:e2e:live -- --sections=cursos  # solo una
CVLAC_E2E=1 npm run test:e2e:live -- --sections=perfil  # perfil y redes

Recorre el CRUD completo por sección contra tu cuenta real: lista → add → lista → read_cvlac_detail → add repetido (debe devolver needs_confirmation) → update → detalle para comprobar el cambio → delete → lista final. Cada ítem que crea lleva el prefijo ZZ PRUEBA MCP, siempre intenta borrarlo y, si algo sobrevive, lo reporta al final para que lo borres a mano. --sections=perfil toma un snapshot, escribe en una red que nadie use, la edita, la borra y restaura lo que había.

Es la única suite que toca datos reales: por eso exige CVLAC_E2E=1 y no corre con npm test. Habla con dist/index.js, así que va después de npm run build. Deja el reporte en tests/e2e/report-<fecha>.json (gitignored).

Problemas de desarrollo

• La app usa una versión vieja del código: ejecuta npm run build tras cambiar src/. La app corre dist/index.js, no src/index.ts.
• No aparece en la app (instalación clonada): revisa la ruta absoluta a dist/index.js en args, con barras dobles en Windows, y reinicia la app.
• Un formulario no guarda un campo: varios campos de CvLAC son readonly y se llenan por JS. Usa inspect_form para ver los nombres reales, CVLAC_HEADLESS=false para ver el navegador y CVLAC_LOG_LEVEL=debug para el detalle de cada campo.
• Falsos faltantes en diff: nameMatches() normaliza tildes y sufijos ((en línea), - Aprobado ...); la experiencia está fuera del diff a propósito.

Estado y roadmap

Las 11 secciones originales, el perfil, las redes académicas y las áreas de actuación se leen y escriben (add/update/delete), con CRUD verificado contra el CvLAC real. También están implementadas las secciones de artículos, libros, capítulos, tesis, jurados y producción técnica. El CRUD real se verificó completo en artículos; en informes técnicos y consultorías se verificaron altas, listado, detalle, bloqueo de duplicados y borrado. Algunos campos de edición dependen de variaciones del formulario real y quedan documentados en el roadmap. El diff y el bloqueo de duplicados también cubren las listas completas mediante paginación JMesa.

complete_product ya completa palabras clave, áreas, coautores y reconocimientos de productos existentes, y vincula estudiantes de tesis con su participación. Los libros también aceptan las rutas locales certificateCLCDO y certificateCLRI en update_section; cada PDF debe pesar como máximo 2 MiB. La operación fue verificada e2e con registros temporales.

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