tlc-portal-mcp

这是一个基于 stdio 的 MCP 服务器，旨在让 Claude Code、Codex 等 MCP 客户端能够使用 TwolineCloud 门户的休假和时间表功能。

通过 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 后粘贴

工具列表

系统

认证

休假

时间表

时间表规则

• 默认每日可录入工时为 8 小时。

• 若有半天假（AM, PM, admitAm, admitPm），最多只能记录 4 小时。

• 若有全天假（allDay, admit），则当天无法记录。

• 韩国公休日默认通过 Nager.Date API 查询，失败时使用内置的 fallback 数据。

• 周末和公司统一公休日（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。

• 不使用 Refresh token。

• 会话文件仅存储在本地，不会上传到服务器。

• system.check_update 仅在可访问 npm registry 的环境下才能检查最新版本。

• 若公休日查询 API 失败，将使用内置的 fallback 数据进行判定。

• 时间表的 NORMAL + 无 projectId 组合虽按文档实现为允许流程，但实际门户后端是否接受，需在运营环境中进一步确认。