Servidor MCP de Work Journal

Un servidor MCP alojado que permite a cualquier miembro del equipo leer su Work Journal de Simplified HR a través de Claude: siempre sus propias entradas, y las de sus colegas cuando sus permisos existentes de Work Journal ya lo permitan.

Solo lectura. Ninguna herramienta aquí puede crear, modificar o 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 — Ajustes → 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 y contraseña de Simplified HR. En desarrollo también introduces tu workspace, por ejemplo development-hr.dev.besimplified.net.

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

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

Iniciar sesión en el servicio de cuentas en su lugar

WJ_LOGIN_MODE=redirect sustituye al formulario anterior. /authorize envía el navegador a la página de inicio de sesión de cuentas del entorno, el miembro inicia sesión allí, y el servicio de cuentas lo devuelve a /identifier con un token de traspaso de corta duración que este servidor intercambia por la sesión. De ello se derivan dos cosas: no se escribe ninguna contraseña en una página que este servidor renderiza, y el miembro queda conectado a las aplicaciones web de BeSimplified al mismo tiempo, porque la sesión es la que el servicio de cuentas emitió en su propio origen.

Está desactivado por defecto porque tiene requisitos previos que el modo formulario no tiene:

• Un registro app_registrations en el servicio de cuentas que nombre el host de este servidor, como fqdn verificado o como workspace, en cada organización cuyos miembros lo usen. La página de inicio de sesión extrae el host del referrer que se le da y lo busca; sin registro responde valid_workspace: false y devuelve el navegador a la aplicación de RR. HH. en lugar de aquí. Es un registro en la propia base de datos del servicio de cuentas: no cambia ningún código allí.

• WJ_PUBLIC_BASE_URL como https sin puerto. El servicio de cuentas reconstruye la devolución de llamada como https://<host>/identifier solo a partir del nombre de host, por lo que un puerto o un esquema de texto plano no pueden recibirla. El servidor se niega a arrancar de otro modo, en lugar de servir un inicio de sesión que puede comenzar y nunca terminar.

• Acceso de lectura al almacén de sesiones de cuentas, WJ_REDIS_HOST y WJ_ACC_CACHE_PREFIX. El token de traspaso nombra una clave allí; sin él no hay nada con lo que intercambiar el token.

El host de la devolución de llamada se comprueba contra una lista de permitidos en ambos modos. Importa más aquí: una vez que el miembro se autentica en el servicio de cuentas, quien haya nombrado redirect_uri recibe el código de autorización, y PKCE no ayuda contra un atacante que inició el flujo.

Related MCP server: zulip-mcp

Herramientas

work_journal_get_entries

Entradas con detalle completo de 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 en cualquier período, sin detalle por día. Úsalo para cualquier cosa de más de 31 días.

Pregunta: "¿cuántos informes EOW me faltaron este año?"

work_journal_find_member

Encuentra a un colega por parte de su nombre o correo 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 recuentos de enviados, pendientes y omitidos para un período.

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

Alias de tipos

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

Quién puede ver el journal de quién

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

• Permiso de instancia — puedes leer a cualquier miembro de tu empresa

• Permiso de grupo — puedes leer a miembros de tu subárbol de informes

• Ninguno — solo puedes leer tu propio journal, y cualquier intento de acceder al de otro miembro es rechazado

Dos cosas a tener en cuenta al leer las entradas de un colega: la solicitud puede ser rechazada directamente, y una vista de administrador excluye borradores, programadas y entradas privadas. Por tanto, una entrada ausente no prueba que no se haya registrado 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 concurrentemente por llamada a herramienta, por lo que un rango amplio se mantiene suave con 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"}. Ejecutar node src/index.js sin entorno debe salir inmediatamente, listando cada variable que falta.

Entorno

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

Notas de despliegue

• La adherencia de cookies en /authorize es un requisito solo de WJ_LOGIN_MODE=form. En modo redirect no se retiene nada en la memoria del proceso entre las dos etapas: la solicitud de autorización regresa del servicio de cuentas en un token redirect_page cifrado, por lo que /authorize y /identifier son ambos sin estado y no necesitan adherencia.

• La adherencia de cookies es necesaria solo en /authorize. Un envío de 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 son sin estado y no deben ser pegajosos.

• Ambos secretos pertenecen al Parameter Store de SSM como SecureString, referenciados desde el bloque secrets de la definición de tarea, nunca como literales de entorno. Créelos una vez por entorno antes del primer despliegue; nada más en la plataforma usa el prefijo /hr/work-journal-mcp/, por lo 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 en ambos, o la tarea falla al inicio 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 en ninguna forma. Solo existen en memoria, durante los segundos que dura un inicio de sesión.

• El estado de 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, actualización y código de autorización están criptográficamente vinculados a su tipo, por lo que uno no puede gastarse como otro.

• Los intentos de inicio de sesión están limitados por dirección de correo electrónico.

• Cada llamada de herramienta se registra con el llamador, la herramienta y el miembro cuyo diario se leyó, de modo que las lecturas entre miembros sean auditables. Los tokens y el contenido de las entradas nunca se registran.

Pruebas

npm test