tlc-portal-mcp

Это MCP-сервер на базе stdio, позволяющий использовать функции отпусков и расписания портала TwolineCloud в MCP-клиентах, таких как Claude Code и Codex.

При запуске пакета через npx вы можете использовать инструменты MCP для входа в систему через браузер, просмотра/подачи заявлений на отпуск, просмотра/ввода данных в расписание и проверки версий.

Текущие поддерживаемые функции

• Вход на портал и проверка статуса аутентификации

• Просмотр типов отпусков, остатков отпусков и истории заявок

• Подача и отмена заявлений на отпуск

• Управление информацией о расписании, доступные периоды ввода, детальный просмотр по дням

• Просмотр списка проектов для расписания

• Расчет доступного времени ввода по дням с учетом отпусков

• Подготовка и отправка данных в расписание (единичные записи или периоды)

• Полное удаление данных расписания за день

• Проверка текущей версии сервера и сравнение с последней версией в npm

Требования

• Node.js 18+

• Браузерное окружение, поддерживающее вход на портал

Установка и регистрация

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

Поскольку в Codex на данный момент нет отдельной команды add для конкретного проекта, при необходимости вы можете добавить его вручную в файл .codex/config.toml в корне проекта.

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

Заметки о способе запуска

• mcp add ... -- npx -y tlc-portal-mcp — это не глобальная установка, а регистрация команды запуска.

• Фактическая загрузка пакета происходит при первом запуске сервера клиентом.

• Пакет не переустанавливается каждый раз; в зависимости от среды выполнения может использоваться кэшированная версия.

• Поэтому сервер содержит инструменты system.* для проверки текущей и последней версий.

Способы аутентификации

Рекомендуемый: auth.login

При открытии браузера и входе пользователя в систему JWT из localStorage['vuex'] сохраняется автоматически.

1. Запустите auth.login

2. Выполните вход на портал и MFA в браузере

3. После успешного входа токен будет сохранен автоматически

4. Проверьте статус аутентификации с помощью auth.status

После успешного входа в браузере отобразится информационное наложение.

Альтернативный: auth.import_vuex

Если автоматический поток входа затруднен, можно вручную скопировать и вставить значение vuex из браузера.

1. Войдите на портал в браузере

2. В DevTools перейдите в Application > Local Storage > https://portal.twolinecloud.com

3. Скопируйте значение vuex

4. Запустите auth.import_vuex и вставьте значение

Список инструментов

Система

Аутентификация

Отпуск

Расписание

Правила расписания

• Стандартное доступное время ввода — 8 часов в день.

• При наличии отпуска на полдня (AM, PM, admitAm, admitPm) можно записать максимум 4 часа.

• При наличии отпуска на весь день (allDay, admit) запись на этот день невозможна.

• Государственные праздники Южной Кореи по умолчанию запрашиваются через API Nager.Date, в случае сбоя используются встроенные резервные данные.

• Выходные и общие корпоративные выходные дни (PORTAL_COMPANY_HOLIDAYS) также считаются недоступными для ввода.

• Наложение личных отпусков рассчитывается на основе результатов сортировки requestDt из vacation-svc/request/secure в соответствии с правилами обзора портала.

• workDate и taskType требуются всегда.

• projectId требуется по умолчанию.

• Однако, если taskType === NORMAL, можно вводить данные без projectId.

• Операции записи следуют потоку prepare -> submit.

Рекомендуемый порядок использования

Начальная диагностика

1. system.info

2. system.check_update

3. auth.status

4. При необходимости auth.login

Поток работы с отпусками

1. leave.get_balances

2. leave.list_requests

3. leave.prepare_request

4. leave.submit_prepared_request

Поток работы с расписанием

1. timetable.get_available_range

2. timetable.get_range_overview

3. timetable.list_projects

4. timetable.get_day_capacity

5. timetable.prepare_day_entry или timetable.prepare_bulk_entries

6. timetable.submit_prepared_day_entry или timetable.submit_prepared_bulk_entries

Примеры использования

"현재 서버 버전이랑 최신 버전 비교해줘"
-> 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

Переменные окружения

Ограничения

• Срок действия JWT на данный момент составляет около 2 часов.

• Если токен истек, необходимо снова запустить auth.login или auth.import_vuex.

• Refresh token не используется.

• Файл сессии сохраняется только локально и не загружается на сервер.

• system.check_update может проверить версию только в среде с доступом к реестру npm.

• Если API для запроса праздников недоступно, используются встроенные резервные данные.

• Комбинация NORMAL + отсутствие projectId в расписании реализована как допустимый поток согласно документации, но фактическая поддержка бэкендом портала требует проверки в рабочей среде.