Work Journal MCP Server

Un servidor MCP alojado que permite a cualquier miembro del equipo leer su Simplified HR Work Journal a través de Claude — siempre sus propias entradas, y las de sus compañeros en aquellos casos en los que sus permisos de Work Journal existentes ya lo permitan.

Solo lectura. Ninguna herramienta puede crear, modificar ni eliminar una entrada.

Conexión desde cualquier cliente de Claude

Un único flujo, sea cual sea el cliente que uses: añade el servidor por URL y luego inicia sesión en la ventana del navegador que se abre.

Claude Desktop o claude.ai — Configuración → Conectores → Añadir conector personalizado →

https://wj-mcp.dev.besimplified.net/mcp

Claude Code

claude mcp add work-journal --transport http https://wj-mcp.dev.besimplified.net/mcp

En cualquier caso, se abre una ventana del navegador. Inicia sesión con tu correo electrónico y contraseña de Simplified HR. En dev también tienes que introducir tu workspace, por ejemplo development-hr.dev.besimplified.net.

Si este es un dispositivo que el servicio de cuentas no ha visto antes, recibirás un código de verificación por correo electrónico o SMS. Introdúcelo una sola vez; no se te volverá a pedir desde el mismo cliente.

Tu contraseña nunca llega a Claude, y este servidor nunca la almacena.

Herramientas

work_journal_get_entries

Entradas con el detalle completo de las tareas para una fecha o un rango de hasta 31 días.

Pregunta: "muestra mis entradas EOD de la semana pasada"

work_journal_get_day

Una fecha completa: cada tarea con notas y adjuntos, destinatarios notificados, ETA y hora de envío.

Pregunta: "¿qué registré el 4 de agosto?"

work_journal_get_summary

Recuentos por tipo y estado durante cualquier período, sin detalle diario. Úsalo para cualquier período de más de 31 días.

Pregunta: "¿cuántos informes EOW no presenté este año?"

work_journal_find_member

Busca a un compañero por parte de su nombre o correo electrónico y devuelve su id de miembro, para usarlo como member en las herramientas anteriores.

Pregunta: "encuentra el id de miembro de Rahul"

work_journal_get_team_report

Una fila por miembro con los recuentos de presentados, pendientes y no presentados para un período.

Pregunta: "¿quién no presentó su EOD la semana pasada?"

Alias de tipo

La coincidencia ignora mayúsculas y minúsculas y trata los espacios, guiones y guiones bajos como equivalentes.

Quién puede ver el Work Journal de quién

Este servidor no aplica ningún permiso propio. Cada solicitud lleva tu propia sesión de Simplified HR, y la API de Work Journal aplica exactamente los mismos permisos que aplica en la interfaz web:

• Permiso de instancia — puedes leer el Work Journal de cualquier miembro de tu empresa

• Permiso de grupo — puedes leer el Work Journal de los miembros de tu subárbol de reporte

• Ninguno de los dos — solo puedes leer tu propio Work Journal, y cualquier intento de leer el de otro miembro es rechazado

Dos cosas que debes saber al leer las entradas de un compañero: la solicitud puede ser rechazada directamente, y una vista de administrador excluye los borradores, las entradas programadas y las privadas. Por lo tanto, una entrada ausente no demuestra que no se registró nada.

Límites

• work_journal_get_entries rechaza rangos de más de 31 días y te remite a work_journal_get_summary

• Como máximo 4 solicitudes se ejecutan simultáneamente por llamada de herramienta, para que un rango amplio no sobrecargue la API

• Las fechas relativas, como "la semana pasada", las resuelve Claude antes de la llamada; las herramientas solo aceptan YYYY-MM-DD

Ejecutarlo localmente

npm install
cp .env.example .env      # then fill in the two secrets
WJ_ENV=dev \
WJ_PUBLIC_BASE_URL=http://localhost:8080 \
WJ_TOKEN_KEY=$(openssl rand -hex 32) \
WJ_FINGERPRINT_SECRET=$(openssl rand -hex 32) \
npm start

GET /healthz debería responder {"status":"ok"}. Al ejecutar node src/index.js sin variables de entorno, debe salir inmediatamente y enumerar cada variable que falte.

Entorno

WJ_FINGERPRINT_SECRET debe ser idéntico en todas las tareas y no debe rotarse a la ligera. Deriva la huella de dispositivo estable de cada miembro; cambiarlo vuelve a solicitar un código de verificación a todo el equipo.

Notas de despliegue

• La persistencia de cookies solo es necesaria en /authorize. El envío de un OTP debe llegar a la tarea que inició el inicio de sesión, porque el inicio de sesión en curso se mantiene en la memoria de ese proceso durante cinco minutos. /mcp y /token no tienen estado y no deben ser persistentes.

• Ambos secretos deben estar en SSM Parameter Store como SecureString, referenciados desde el bloque secrets de la definición de tarea, nunca como literales de entorno. Créalos una vez por entorno antes del primer despliegue; nada más en la plataforma usa el prefijo /hr/work-journal-mcp/, así que no existirán ya:

  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/token_key           --value "$(openssl rand -hex 32)"
  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/fingerprint_secret  --value "$(openssl rand -hex 32)"

  ecsTaskExecutionRole necesita ssm:GetParameters y kms:Decrypt sobre ambos, o la tarea falla al arrancar con ResourceInitializationError, antes de que se ejecute cualquiera de este código.

• Producción rechaza el campo de inicio de sesión workspace que dev requiere, por lo que la página de inicio de sesión lo oculta fuera de dev.

Seguridad

• Las contraseñas nunca se almacenan, nunca se registran y nunca se devuelven al navegador de ninguna forma. Solo existen en memoria, durante los segundos que dura un inicio de sesión.

• El estado de la sesión viaja en un sobre cifrado AES-256-GCM que solo este servidor puede abrir. El JWT de Simplified HR nunca llega a Claude ni al modelo.

• Los sobres de acceso, de refresco y de código de autorización están criptográficamente vinculados a su tipo, de modo que uno no puede gastarse como otro.

• Los intentos de inicio de sesión tienen límite de frecuencia por dirección de correo electrónico.

• Cada llamada de herramienta se registra con quien llama, la herramienta y el miembro cuyo Work Journal se ha leído, de modo que las lecturas entre miembros sean auditables. Los tokens y el contenido de las entradas nunca se registran.

Pruebas

npm test