tlc-portal-mcp

Un servidor MCP basado en stdio que permite a clientes MCP como Claude Code y Codex utilizar las funciones de vacaciones y horarios del portal de TwolineCloud.

Al ejecutar el paquete con npx, puedes utilizar herramientas MCP para tareas como inicio de sesión en el navegador, consulta/solicitud de vacaciones, consulta/entrada de horarios y diagnóstico de versiones.

Funciones admitidas actualmente

• Inicio de sesión en el portal y verificación del estado de autenticación

• Consulta de tipos de vacaciones, saldo de vacaciones e historial de solicitudes de vacaciones

• Solicitud y cancelación de vacaciones

• Información de gestión de horarios, períodos de entrada disponibles y detalles diarios

• Consulta de lista de proyectos de horarios

• Cálculo de horas disponibles por día considerando las vacaciones

• Preparación y envío de entradas de horarios individuales/por período

• Eliminación completa de horarios diarios

• Verificación de la versión actual del servidor y comparación con la última versión de npm

Requisitos

• Node.js 18+

• Entorno de navegador donde sea posible iniciar sesión en el portal

Instalación y registro

Claude Code

# 사용자 전역 등록
claude mcp add tlc-portal-mcp --scope user -- npx -y tlc-portal-mcp

# 현재 프로젝트에만 등록
claude mcp add tlc-portal-mcp -- npx -y tlc-portal-mcp

Codex CLI

# 사용자 전역 등록
codex mcp add tlc-portal-mcp -- npx -y tlc-portal-mcp

Dado que Codex no tiene un comando add dedicado para proyectos actuales, puedes añadirlo directamente a .codex/config.toml en la raíz del proyecto si es necesario.

[mcp_servers.tlc-portal-mcp]
command = "npx"
args = ["-y", "tlc-portal-mcp"]

Notas sobre el método de ejecución

• mcp add ... -- npx -y tlc-portal-mcp no es una instalación global, sino un registro del comando de ejecución.

• La descarga real del paquete ocurre cuando el cliente ejecuta el servidor por primera vez.

• No se reinstala cada vez; dependiendo del entorno de ejecución, se puede reutilizar la versión almacenada en caché.

• Por ello, el servidor incluye herramientas system.* para verificar la versión actual y la última versión.

Método de autenticación

Recomendado: auth.login

Al abrir el navegador y realizar el inicio de sesión manualmente, se guarda automáticamente el JWT de localStorage['vuex'].

1. Ejecutar auth.login

2. Completar el inicio de sesión en el portal y el MFA en el navegador

3. El token se guarda automáticamente tras un inicio de sesión exitoso

4. Verificar el estado de autenticación con auth.status

Tras un inicio de sesión exitoso, se mostrará una superposición de guía en el navegador.

Alternativa: auth.import_vuex

Si es difícil utilizar el flujo de inicio de sesión automático, puedes obtener y pegar el valor de vuex directamente desde el navegador.

1. Iniciar sesión en el portal en el navegador

2. Ir a Application > Local Storage > https://portal.twolinecloud.com en las DevTools

3. Copiar el valor de vuex

4. Ejecutar auth.import_vuex y pegar el valor

Lista de herramientas

Sistema

Autenticación

Vacaciones

Horarios

Reglas de horarios

• El tiempo de entrada predeterminado es de 8 horas al día.

• Si hay medio día de vacaciones (AM, PM, admitAm, admitPm), solo se pueden registrar un máximo de 4 horas.

• Si hay vacaciones de día completo (allDay, admit), no se puede registrar nada en esa fecha.

• Los días festivos de Corea se consultan básicamente a través de la API de Nager.Date, y en caso de fallo, se utilizan datos de respaldo integrados.

• Los fines de semana y los días festivos comunes de la empresa (PORTAL_COMPANY_HOLIDAYS) también se tratan como no ingresables.

• La superposición de vacaciones personales se calcula según los resultados de ordenación de requestDt en vacation-svc/request/secure de acuerdo con las reglas de resumen del portal.

• workDate y taskType son siempre necesarios.

• projectId es necesario por defecto.

• Sin embargo, si taskType === NORMAL, se puede ingresar sin projectId.

• Las operaciones de escritura siguen el flujo prepare -> submit.

Orden de uso recomendado

Diagnóstico inicial

1. system.info

2. system.check_update

3. auth.status

4. auth.login si es necesario

Flujo de vacaciones

1. leave.get_balances

2. leave.list_requests

3. leave.prepare_request

4. leave.submit_prepared_request

Flujo de horarios

1. timetable.get_available_range

2. timetable.get_range_overview

3. timetable.list_projects

4. timetable.get_day_capacity

5. timetable.prepare_day_entry o timetable.prepare_bulk_entries

6. timetable.submit_prepared_day_entry o timetable.submit_prepared_bulk_entries

Ejemplos de uso

"현재 서버 버전이랑 최신 버전 비교해줘"
-> system.check_update

"내 휴가 잔여 일수 보여줘"
-> leave.get_balances

"이번 달 휴가 신청 이력 보여줘"
-> leave.list_requests

"4월 30일 오전 반차 신청 준비해줘"
-> leave.prepare_request

"오늘 입력 가능한 타임테이블 시간 계산해줘"
-> timetable.get_day_capacity

"2026년 2월 타임테이블 전체를 공휴일 포함해서 요약해줘"
-> timetable.get_range_overview

"2026-04-05에 프로젝트 274로 4시간, taskType EXECUTE로 입력 준비해줘"
-> timetable.prepare_day_entry

"오늘 일반업무 2시간, taskType NORMAL로 입력 준비해줘"
-> timetable.prepare_day_entry

"4월 1일부터 4월 3일까지 같은 내용으로 일괄 입력 준비해줘"
-> timetable.prepare_bulk_entries

Variables de entorno

Limitaciones

• El tiempo de validez del JWT es de aproximadamente 2 horas según el estándar actual.

• Si el token caduca, se debe volver a ejecutar auth.login o auth.import_vuex.

• No se utiliza token de actualización (refresh token).

• El archivo de sesión solo se guarda localmente y no se carga al servidor.

• system.check_update solo puede verificar la última versión en entornos con acceso al registro de npm.

• Si la API de consulta de festivos falla, se determina mediante datos de respaldo integrados.

• La combinación de NORMAL + sin projectId en los horarios está implementada como un flujo permitido según la documentación, pero la aceptación real por parte del backend del portal debe verificarse adicionalmente en el entorno operativo.