tlc-portal-mcp

TwolineCloudポータルの休暇およびタイムテーブル機能を、Claude CodeやCodexなどのMCPクライアントから利用できるようにしたstdioベースのMCPサーバーです。

パッケージを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

ブラウザを開いてユーザーが直接ログインすると、localStorage['vuex']のJWTが自動的に保存されます。

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を実行後に貼り付け

ツール一覧

システム

認証

休暇

タイムテーブル

タイムテーブルのルール

• 基本の入力可能時間は1日8時間です。

• 半休(AM, PM, admitAm, admitPm)がある場合は、最大4時間まで記録可能です。

• 全日休暇(allDay, admit)がある場合は、その日付には記録できません。

• 韓国の祝日は基本的にNager.Date APIから照会し、失敗した場合は内蔵のフォールバックデータを使用します。

• 週末と会社の共通休日(PORTAL_COMPANY_HOLIDAYS)も入力不可として処理します。

• 個人の休暇オーバーレイは、ポータルの概要ルールに合わせてvacation-svc/request/secureのrequestDtソート結果を基準に計算されます。

• 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を再度実行する必要があります。

• リフレッシュトークンは使用しません。

• セッションファイルはローカルにのみ保存され、サーバーにはアップロードされません。

• system.check_updateは、npmレジストリにアクセス可能な環境でのみ最新バージョンを確認できます。

• 祝日照会APIが失敗した場合は、内蔵のフォールバックデータで判定します。

• タイムテーブルのNORMAL + projectIdなしの組み合わせは、ドキュメント基準の許可フローとして実装されていますが、実際のポータルバックエンドでの受け入れ可否は運用環境で別途確認が必要です。