tlc-portal-mcp

Ein stdio-basierter MCP-Server, der es MCP-Clients wie Claude Code oder Codex ermöglicht, die Urlaubs- und Zeitplanfunktionen des TwolineCloud-Portals zu nutzen.

Wenn das Paket mit npx ausgeführt wird, können Aufgaben wie Browser-Login, Urlaubsabfrage/-beantragung, Zeitplanabfrage/-eingabe und Versionsdiagnose als MCP-Tools verwendet werden.

Aktuell unterstützte Funktionen

• Portal-Login und Überprüfung des Authentifizierungsstatus

• Abfrage von Urlaubsarten, Resturlaub und Historie der Urlaubsanträge

• Beantragung und Stornierung von Urlaub

• Verwaltungsinformationen für Zeitpläne, Eingabezeiträume und tägliche Detailansichten

• Abfrage der Projektliste für Zeitpläne

• Berechnung der täglichen verfügbaren Arbeitszeit unter Berücksichtigung von Urlaub

• Vorbereitung und Einreichung von Zeitplaneinträgen (einzeln/zeitraumbezogen)

• Vollständiges Löschen von täglichen Zeitplaneinträgen

• Überprüfung der aktuellen Serverversion und Vergleich mit der neuesten npm-Version

Anforderungen

• Node.js 18+

• Eine Browserumgebung, in der ein Portal-Login möglich ist

Installation und Registrierung

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

Da Codex derzeit keinen dedizierten add-Befehl für Projekte hat, kann der Server bei Bedarf direkt in die .codex/config.toml im Projektstammverzeichnis eingetragen werden.

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

Hinweise zur Ausführung

• mcp add ... -- npx -y tlc-portal-mcp ist keine globale Installation, sondern eine Registrierung des Ausführungsbefehls.

• Der eigentliche Paket-Download erfolgt, wenn der Client den Server zum ersten Mal startet.

• Es wird nicht jedes Mal neu installiert; je nach Ausführungsumgebung kann eine zwischengespeicherte Version wiederverwendet werden.

• Daher enthält der Server system.*-Tools, um die aktuelle Version mit der neuesten Version zu vergleichen.

Authentifizierungsmethode

Empfohlen: auth.login

Wenn der Benutzer sich über einen Browser anmeldet, wird das JWT aus localStorage['vuex'] automatisch gespeichert.

1. auth.login ausführen

2. Portal-Login und MFA im Browser abschließen

3. Nach erfolgreichem Login wird das Token automatisch gespeichert

4. Authentifizierungsstatus mit auth.status überprüfen

Nach erfolgreichem Login wird im Browser ein Hinweis-Overlay angezeigt.

Alternativ: auth.import_vuex

Wenn der automatische Login-Ablauf nicht genutzt werden kann, kann der vuex-Wert manuell aus dem Browser kopiert und eingefügt werden.

1. Im Browser am Portal anmelden

2. In den DevTools zu Application > Local Storage > https://portal.twolinecloud.com navigieren

3. Den vuex-Wert kopieren

4. auth.import_vuex ausführen und den Wert einfügen

Tool-Liste

System

Authentifizierung

Urlaub

Zeitplan

Zeitplan-Regeln

• Die standardmäßige Arbeitszeit beträgt 8 Stunden pro Tag.

• Bei Halbtagsurlaub (AM, PM, admitAm, admitPm) können maximal 4 Stunden erfasst werden.

• Bei Ganztagesurlaub (allDay, admit) können für diesen Tag keine Einträge vorgenommen werden.

• Südkoreanische Feiertage werden standardmäßig über die Nager.Date API abgefragt; bei Fehlern werden integrierte Fallback-Daten verwendet.

• Wochenenden und allgemeine Firmenfeiertage (PORTAL_COMPANY_HOLIDAYS) werden ebenfalls als nicht eingabefähig behandelt.

• Persönliche Urlaubs-Overlays werden gemäß den Portal-Overview-Regeln basierend auf dem Sortierergebnis von requestDt in vacation-svc/request/secure berechnet.

• workDate und taskType sind immer erforderlich.

• projectId ist standardmäßig erforderlich.

• Ausnahme: Wenn taskType === NORMAL, kann ohne projectId eingetragen werden.

• Schreibvorgänge folgen dem Ablauf prepare -> submit.

Empfohlene Reihenfolge der Verwendung

Erstdiagnose

1. system.info

2. system.check_update

3. auth.status

4. Bei Bedarf auth.login

Urlaubsablauf

1. leave.get_balances

2. leave.list_requests

3. leave.prepare_request

4. leave.submit_prepared_request

Zeitplanablauf

1. timetable.get_available_range

2. timetable.get_range_overview

3. timetable.list_projects

4. timetable.get_day_capacity

5. timetable.prepare_day_entry oder timetable.prepare_bulk_entries

6. timetable.submit_prepared_day_entry oder timetable.submit_prepared_bulk_entries

Anwendungsbeispiele

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

Umgebungsvariablen

Einschränkungen

• Die Gültigkeitsdauer des JWT beträgt derzeit etwa 2 Stunden.

• Wenn das Token abläuft, müssen auth.login oder auth.import_vuex erneut ausgeführt werden.

• Es werden keine Refresh-Tokens verwendet.

• Die Sitzungsdatei wird nur lokal gespeichert und nicht auf den Server hochgeladen.

• system.check_update kann die neueste Version nur in Umgebungen mit Zugriff auf die npm-Registry überprüfen.

• Wenn die Feiertags-API fehlschlägt, wird auf integrierte Fallback-Daten zurückgegriffen.

• Die Kombination NORMAL + kein projectId im Zeitplan ist gemäß Dokumentation als zulässiger Ablauf implementiert, die tatsächliche Akzeptanz durch das Portal-Backend sollte jedoch in der Betriebsumgebung überprüft werden.