Pandapé MCP

Servidor MCP para gestión de reclutamiento sobre la API oficial de Pandapé v2 (ATS de Grupo Redarbor). Pensado para que Claude revise candidatos contra los criterios que tú le indiques.

Estado

Todo está implementado y probado salvo lo único que no se resuelve desde el código: client_id / client_secret. Se piden al Customer Success Specialist de tu cuenta.

Related MCP server: Lever ATS MCP Server

La API (verificado)

La API oficial existe y está documentada, aunque no se anuncie públicamente. Hay tres versiones:

ATS web: https://ats.pandape.com (login en login.pandape.com) · Base de API: https://api.pandape.com.br · Auth: OAuth2 client_credentials (IdentityServer), scope PandapeApi.

• LATAM: https://login.pandape.com/connect/token

• Brasil: https://login.pandape.com.br/connect/token

Ambos aceptan el grant (responden invalid_client con credenciales falsas, no unsupported_grant_type). Descripciones del spec en portugués.

⚠️ Host de API y región. Solo resuelve api.pandape.com.br; api.pandape.com no existe en DNS, aunque el token LATAM sí sale de login.pandape.com. Confirma con tu CS qué host corresponde a tu cuenta de Perú y ajusta PANDAPE_API_URL.

Detalles que cuestan una tarde si no los sabes

• PATCH /v2/matches/{idMatch}/update (mover de etapa) exige multipart/form-data, no JSON — lleva un campo Photo binario opcional. Con JSON falla.

• pandape_endpoints muestra el contentType de cada endpoint con cuerpo; míralo antes de usar pandape_api.

• La API v2 no expone el CV en PDF. Expone algo mejor para evaluar: el CV como datos estructurados.

Revisar candidatos con tus criterios

pandape_revisar_candidatos trae el pool de una vacante con el CV ya estructurado: resumen profesional, experiencias (puesto, empresa, fechas, actividades), estudios, habilidades, idiomas, meses de experiencia, expectativa salarial, disponibilidad, y el Affinity que calcula Pandapé.

Flujo típico en Claude:

1. "Lístame las vacantes activas"                    → pandape_listar_vacantes (estado 2)
2. "¿Qué etapas tiene la vacante 4821?"              → pandape_etapas_vacante
3. "Revisa los candidatos nuevos de la 4821 y
    clasifícalos: necesito 3+ años en nómina,
    Excel avanzado y que viva en Lima"               → pandape_revisar_candidatos
4. "Dame el contacto de los tres mejores"            → pandape_ver_candidato
5. "Mueve esos tres a Entrevista"                    → pandape_mover_candidato (requiere READONLY=0)

Sesgo y minimización de datos

pandape_revisar_candidatos omite deliberadamente CPF, fecha de nacimiento, sexo, identidad de género, orientación sexual, raza, discapacidad, estado civil, hijos, dirección y contacto. No aportan al criterio profesional y su presencia sesgaría la evaluación. El contacto sale por pandape_ver_candidato cuando ya decidiste avanzar con alguien concreto.

El self-check verifica esa exclusión (npm run check), así que no se rompe por accidente.

Uso rápido (sin credenciales de API): tu cookie del navegador

Funciona hoy con tu sesión del ATS, sin esperar credenciales:

npm ci && npm run build
# exporta la cookie del ATS con la extensión Cookie-Editor (Export → Netscape)
npm run set-cookie -- /ruta/cookies.txt     # guarda en .auth/ (600) y VERIFICA la sesión

Luego, con el MCP registrado, el flujo es:

• pandape_web_candidatos { idVacante } — candidatos de una vacante (idVacante = número de la URL del proceso).

• pandape_web_cv { idMatch } — CV completo en texto, listo para evaluar por criterios.

• pandape_web_descargar_cv { idMatch } — guarda el CV imprimible (HTML → PDF desde el navegador).

La cookie caduca con tu sesión; cuando pandape_diagnostico avise, re-exporta y vuelve a correr set-cookie. Guía completa para operarlo (incluso para otro agente) en CLAUDE.md.

Descargar el PDF del CV

La API oficial no expone el documento del CV en ninguna de las tres versiones. Verificado: CandidateResumeModel es solo datos, y los únicos campos de descarga que existen (RequestDetailDocument.DownloadUrl, PreCollaboratorDocumentModel.Link) son de documentos de requisiciones y de pre-colaboradores, no del pool de postulantes.

Así que el PDF va por cookies de tu sesión del ATS (pandape_descargar_cv). Configuración de una sola vez:

1. La URL de descarga. En el ATS abre un candidato, clic derecho en el botón de descarga del CV → Copiar dirección del enlace. Reemplaza el id por {idMatch} (o {idCandidate}):

PANDAPE_CV_URL="https://ats.pandape.com/Candidate/DownloadCv?idMatch={idMatch}"

2. Las cookies. DevTools → Application → Cookies, o una extensión tipo Cookie-Editor. Dos formas:

PANDAPE_COOKIE="ASPNET_SessionId=…; .AspNetCore.Cookies=…"   # cabecera cruda
PANDAPE_COOKIE_FILE="/ruta/cookies.json"                     # o un archivo

El archivo acepta cabecera cruda, JSON [{name,value}] de extensiones, o un storageState de Playwright. Caducan con tu sesión: cuando expiren, el error te lo dice y las re-exportas.

Los documentos se guardan en PANDAPE_CV_DIR (por defecto ./cv). El nombre se sanea siempre, así que la tool no puede escribir fuera de ese directorio. Se verifica la firma binaria: si el ATS devuelve el HTML del login en vez del PDF, falla con un mensaje claro en vez de guardar basura con extensión .pdf.

Para clasificar candidatos por criterios no necesitas el PDF: pandape_revisar_candidatos ya trae el CV como datos estructurados. Usa la descarga cuando quieras el documento original.

Puesta en marcha

npm install
npm run spec      # descarga swagger.json (v2 por defecto)
npm run build
npm run check     # self-check sin red

Configuración

Registro en Claude Code / Desktop

{
  "mcpServers": {
    "pandape": {
      "command": "node",
      "args": ["/home/jairo/Documentos/pandape-mcp/dist/index.js"],
      "env": {
        "PANDAPE_CLIENT_ID": "…",
        "PANDAPE_CLIENT_SECRET": "…",
        "PANDAPE_TOKEN_URL": "https://login.pandape.com/connect/token",
        "PANDAPE_API_URL": "https://api.pandape.com.br"
      }
    }
  }
}

Tools

Las dos últimas cubren lo que no tiene tool propia (requisiciones, finalistas y sus evaluaciones, clientes, sedes, usuarios, plantillas de vacante, diccionarios, campos personalizados) sin escribir 68 wrappers.

Seguridad y datos personales

• Solo lectura por defecto. Las escrituras exigen PANDAPE_READONLY=0 explícito.

• El client_secret va en la config del cliente MCP, nunca en el repo.

• Datos de candidatos = datos personales (Ley 29733 en Perú). La evaluación asistida por IA de personas conviene documentarla: criterios explícitos, evidencia citada y decisión humana al final.

legacy/

Scaffold anterior que hablaba con la SPA vía Playwright, archivado sin borrar (está en el primer commit de git). Se abandonó porque:

1. Asumía una SPA con API JSON en /api/v1/*. Pandapé es ASP.NET Core MVC sobre IIS con Razor y jquery.unobtrusive-ajax: devuelve HTML, y /api/ da 404.

2. Sus escrituras no enviaban __RequestVerificationToken, así que habrían fallado con antiforgery.

3. Existiendo API oficial que cubre el caso de uso, el scraping añade riesgo legal y fragilidad sin aportar nada.

Ya no hace falta ni para el PDF: pandape_descargar_cv cubre ese caso con cookies y sin dependencias de navegador. Rescátalo solo si las cookies resultan demasiado incómodas de renovar y prefieres un login automatizado (requiere npm i playwright).