노동 업무 도구 (k-labor)

k-labor — 노동 업무 도구 (Korea Labor Tools)

4대보험 신고서·근로계약서·노동 계산기·취업규칙 점검을 일의 무늬가 만든 그대로 내 PC 의 AI(Claude Code·Claude Desktop 등) 에서 쓰도록 한 패키지로 묶은 로컬 MCP 서버입니다. 도구는 묶음(group) 단위로 들어 있고, 필요한 묶음만 켤 수 있습니다. 묶음은 앞으로 늘어납니다.

npm k-labor · 공식 MCP 레지스트리 이름 io.github.seojaehong/k-labor · 도구 안내 https://yellowenvelope.kr/ai-tools

🚀 설치 (내 PC)

Node.js 20 이상만 있으면 됩니다.

Claude Code

claude mcp add --scope user k-labor -- npx -y k-labor mcp

일부 묶음만 켜려면 --groups 를 붙입니다.

claude mcp add --scope user k-labor -- npx -y k-labor mcp --groups nhis

Claude Desktop

claude_desktop_config.json 에 추가합니다.

{
  "mcpServers": {
    "k-labor": {
      "command": "npx",
      "args": ["-y", "k-labor", "mcp"],
      "env": {
        "POPBILL_LINK_ID": "내 링크아이디",
        "POPBILL_SECRET_KEY": "내 비밀키",
        "POPBILL_CORP_NUM": "내 사업자번호",
        "POPBILL_FAX_SENDER": "내 팩스 발신번호"
      }
    }
  }
}

{
  "mcpServers": {
    "k-labor": { "command": "cmd", "args": ["/c", "npx", "-y", "k-labor", "mcp"] }
  }
}

붙이고 나서 AI 에게 이렇게 말해 보세요.

「충북 청주시 상당구 상당로 155 사업장의 건강보험 관할 지사 팩스 번호 찾아줘.」 「people.json 명단으로 건강보험 자격상실 신고서 PDF 만들어 줘.」

🧰 도구

묶음 고르기

• 기본은 전 묶음입니다.
• 명령줄 --groups nhis,popbill 또는 환경변수 LLG_MCP_GROUPS=nhis,popbill (둘 다 있으면 --groups 우선)
• fax·sms 는 popbill 의 다른 이름으로 받습니다.
• 없는 묶음 이름을 넣으면 서버가 뜨지 않고 있는 묶음 목록을 알려 줍니다.

npx -y k-labor --help

contract · calc 묶음

사이트 근로계약서 작성(/tools/contract-write)·점검(/tools/contract-check)과 계산기(/tools/min-wage·weekly-holiday-pay·headcount·take-home-pay·notice-pay·leave-pay·severance.html·holiday-pay·pay-proration·shutdown-allowance)의 엔진을 그대로 묶었습니다. 같은 입력이면 사이트와 같은 값이 나옵니다.

• 주민등록번호를 받지 않습니다. 근로자 이름은 선택이고, 없으면 「근로자」로 적습니다. check_contract 는 입력에 주민등록번호 모양이 있으면 점검하지 않습니다.
• design_contract_wage 는 사업체명·근무장소·업무가 없어도 금액을 계산하고, 빠진 칸을 contractFieldsMissing 으로 알려 줍니다. make_contract_files 는 그 칸이 있어야 파일을 만들고, 이미 있는 파일은 덮어쓰지 않습니다.
• 결과 문구는 사이트 화면과 같습니다. 점검 규칙 글의 임금 구조 용어도 사이트처럼 「임금 구성」으로 바꿔 냅니다.
• 각 묶음 파일이 원격(HTTP)판에 실어도 되는 도구 목록을 내보냅니다 — contractRemoteSafe(설계·점검), calcRemoteSafe(전부). 파일을 쓰는 make_contract_files 는 contractLocalOnly 로 따로 표시했습니다.

claude mcp add --scope user k-labor -- npx -y k-labor mcp --groups contract,calc

「주4 월화수목 10:00~22:00, 휴게 155분, 공휴일 22일, 월 260만원으로 근로계약서 임금 구성 짜 줘.」 「시급 10,320원, 주 22.5시간이면 주휴수당 얼마야?」

• calc_holiday_pay 는 월급에 휴일·연장 가산이 들어 있다는 약정 칸을 받지 않습니다(사이트 화면에만 있는 칸). 법정 기준 값만 냅니다.
• calc_pay_proration 은 회사 기준을 모르면 방식마다 값을 나란히 내고, 원 미만이 남는데 끝수 기준(rounding)이 없으면 금액을 null 로 둡니다.

leave · tax · duties 묶음

• leave — 사이트 연차 계산기(/tools/leave)와 퇴직 정산(/tools/leave/settlement) 엔진. 날짜·일수만 받습니다. settle_leave_on_exit 는 빈 칸을 0 으로 보지 않고, 회계연도 쪽이 많을 때 취업규칙 재산정 규정 유무를 모르면 확정하지 않습니다(verdict: insufficient-input). 일수만 세고 금액은 calc_leave_pay 로 냅니다.
• tax — 퇴직소득세 계산기(/tools/retirement-tax) 엔진과 화면 문장(연금계좌로 받는 경우·원천징수영수증·홈택스 모의계산 안내)을 그대로 싣습니다.
• duties — 사이트 /duties 의 묶은 자료(법제처 현행 법령 원문 확인일 포함)와 같은 고르기 규칙(src/lib/duties.ts, 화면과 같은 함수)으로 답합니다. 네트워크를 쓰지 않습니다.
• 원격(HTTP)판에 실어도 되는 도구 = leaveRemoteSafe·taxRemoteSafe·dutiesRemoteSafe(전부).

claude mcp add --scope user k-labor -- npx -y k-labor mcp --groups calc,leave,tax,duties

「2014년 1월 2일 입사, 2026년 7월 15일 퇴사, 퇴직금 6,000만원이면 퇴직소득세 얼마야?」 「상시 근로자 7명 사업장이 지켜야 할 의무 알려 줘.」

work-rules 묶음

사이트 노동법 개정 알림판(/laws)의 자료(개정 이벤트·표준취업규칙 2026·매핑)와 「취업규칙 점검」 엔진을 그대로 묶었습니다. 같은 본문·같은 기간·같은 오늘이면 사이트 화면과 같은 항목이 나옵니다(묶을 때의 자료 기준).

• 법령 범위 — 저장소 scripts/laws/labor_laws.json(법령이 정한 노동 관계 법령 목록, 38개 법률)과 그 시행령·시행규칙(subordinate_laws.json)입니다.
• 법제처 Open API(DRF) — 묶은 자료 뒤에 공포된 판과 조문 원문은 국가법령정보 공동활용 Open API 로 그때그때 받습니다. 본인 OC(이용자 ID)를 LAW_OC 에 넣어야 하고, 기본값은 없습니다. OC 가 없거나 법제처가 막으면 묶은 자료로만 답하고 그 사실을 응답(live.error·liveError)에 적습니다.
  • list_law_revisions 는 기본으로 실시간 확인을 더합니다(live: false 면 묶은 자료만). law 를 주면 그 법령들의 판 목록을, 안 주면 묶은 자료 생성일 뒤 공포분을 봅니다. 실시간으로 더한 개정에는 개정 요지·취업규칙 연결이 아직 없습니다.
  • compare_law_versions 는 두 판의 전문을 조문 단위로 직접 비교합니다. 법제처 본문의 「조문변경여부」 표시는 새로 생긴 조문을 놓쳐서(예: 근로기준법 2027. 1. 1. 판의 제44조의4) 쓰지 않습니다.
  • check_work_rules_revisions·check_work_rules_file 은 refresh: true 일 때 묶은 자료 뒤 공포분을 liveAdditions 로 따로 싣습니다. 자동 대조 결과는 바뀌지 않습니다. 법제처에는 날짜만 묻고 본문은 보내지 않습니다.
  • make_work_rules_report_forms 의 changes[].lawRef 를 주면 그 조문 원문을 받아 대비표 아래 「근거 법령 원문」에 글자 그대로 싣습니다.
  • 법제처는 해외 IP 를 막습니다. 원격(HTTP)판에 올릴 때는 국내 리전 필요(Vercel icn1). OC 신청 때 등록한 IP·도메인이 아니면 「사용자 정보 검증에 실패하였습니다」가 옵니다.
• 신고 서류 — 근로기준법 시행규칙 제15조·[별지 제15호서식] <개정 2021. 4. 5.> 신고서, 신·구 조문 대비표(변경신고), 의견청취서(제94조 제1항), 불리한 변경 동의서(같은 항 단서)를 만듭니다. 사업장명·대표자·상시 근로자 수 같은 칸이 비면 만들지 않고 빈 칸 목록을 돌려줍니다. 작성일은 기본 오늘이고, 서명·날인 칸은 비워 두며 응답에 「날인 필요」로 알립니다. 이미 있는 파일은 덮어쓰지 않습니다. 제출은 사용자가 고용노동부 노동포털(민원신청 › 취업규칙·퇴직연금)이나 관할 지방고용노동관서에 합니다.
• PDF 글꼴(나눔고딕)에 없는 항 번호 ①~⑳ 은 원과 숫자로 그려 넣습니다. 그 밖에 글꼴에 없는 글자(한자 등)가 있으면 그 PDF 만 만들지 않고(skipped) 한글·워드 파일은 만듭니다.
• 원격(HTTP)판에 실어도 되는 도구 = workRulesRemoteSafe(목록·조문 원문·판 비교·글자 점검). 파일을 읽거나 쓰는 도구는 workRulesLocalOnly.
• 법령명·조문 원문·개정 요지는 법제처·사이트 자료 글자를 고치지 않고 싣습니다.

claude mcp add --scope user k-labor -e LAW_OC=내OC -- npx -y k-labor mcp --groups work-rules

「우리 취업규칙(C:/규정/취업규칙.hwpx) 2024-03-01 개정본인데, 그 뒤 시행된 노동법 개정 반영됐는지 봐 줘. 법제처 최신 공포분도 같이.」 「근로기준법 2026. 12. 8. 판과 2027. 1. 1. 판 뭐가 바뀌었는지 조문별로 보여 줘.」

⚙️ 环境变量

如需使用传真和短信，必须填写您自己的 Popbill 账户信息。本软件包没有默认账户，也没有默认发件号码。 如果缺少必要值，发送工具会返回缺少的项目（missing），不会发送任何内容。

• 环境变量优先。如果未设置，则读取 ~/.claude/.env 中的 POPBILL_* 和 LAW_OC 行。
• 密钥值不会出现在工具响应或日志中。
• find_branch 和 make_form 无需 Popbill 设置即可使用。

🔒 个人信息

• make_form 只通过**文件路径（peopleFile）**接收人员名单。居民登记号码不会出现在 AI 对话中，工具会直接读取文件。
• 居民登记号码只会在这台 PC 上生成 PDF。它们不会放入工具响应中；如果响应中出现类似居民登记号码的内容，会在发出前遮盖。
• 如果短信正文中出现类似居民登记号码的内容，send_sms 不会发送。
• 只有在调用中提供 confirm:true 时，传真和短信才会实际发出。在此之前只会返回预览。
• 只有以下三类信息会发送到外部。① 向 find_branch 提供营业执照号码时，只会将该号码发送到“日的纹样”网站以获取地址（如果提供地址，则不会发送任何内容）。② send_fax 和 send_sms 会通过您自己的 Popbill 账户发送 PDF 和短信。③ work-rules 组只会向法制处 Open API 查询法令名称、日期和版本号。不会发送就业规则正文或营业场所信息。
• 就业规则正文和文件只会在这台 PC 上进行比对。如果正文中出现类似居民登记号码的内容，则不会进行检查；申报文件工具不接收居民登记号码。

🙅 不会做的事

• 不会提交申报。 本工具仅会生成申报表 PDF，并协助您在确认后通过您自己的 Popbill 账户和号码发送。请向相关公团确认是否已受理以及处理结果。
• 也不会提交就业规则申报。仅会生成文件，并指出需要盖章的位置。
• 就业规则比对是基于词语匹配的一次初步检查。修改建议是法律规定的最低标准，请根据公司实际情况确认后再使用。
• 不会自行选择接收传真号码。只会使用 find_branch 结果中经人工确认的号码。如果通知书或 EDI 上记载了其他管理支社，则以该支社为准。
• 不会保存或收集输入值。

🛠️ 开发（在存储库中）

本软件包通过 esbuild 打包网站引擎（src/lib/nhis-forms、src/lib/branch-directory）和支社数据（data/branch-directory/），确保表单与网站版本一致。修改引擎后，必须重新构建才能生效。

cd tools/k-labor
npm.cmd install
npm.cmd run build        # dist/server.mjs + dist/assets/(서식 PDF 2종·글꼴·OFL.txt, 계약서 PDF 용 나눔고딕·라이선스, hwp 읽기 rhwp WASM)
node smoke.mjs           # 합성 값 시험, 전송 안 함. 법제처는 가짜 법제처(tests/fixtures/laws/drf 고정 응답)로
npm.cmd pack --dry-run   # 올라갈 파일 확인

• 如果 shell 中设置了 LAW_OC，smoke 会在结束时调用真实的法制处工具两次（条文原文、版本比较）；如果未设置，则会输出 SKIP。

• work-rules 组会打包网站资料（public/data/laws）和 pdf.js，因此 dist/server.mjs 大约为 17MB；此外还会附带 HWP 读取组件 dist/assets/rhwp_bg.wasm（约 12MB，从存储库根目录的 node_modules/@rhwp/core 复制）。如果没有 wasm，只会提示 HWP 文件「请另存为 hwpx 后重试」。

• 新建组时，在 groups/<이름>.mjs 中创建 register…(server)，并在 server.mjs 的 GROUPS 中再添加一行。

• contract 和 calc 组会连同存储库根目录中的依赖项（exceljs、jszip 等）一起打包，因此构建前也要在存储库根目录运行 npm.cmd ci。

• 直接注册存储库构建版本时：claude mcp add <이름> -s user -- node <이 폴더>/dist/server.mjs

📄 许可证

• 代码：MIT（LICENSE）
• 字体 dist/assets/LLGFormsSans-Regular.ttf：由 NanumGothic（Copyright (c) 2010, NHN Corporation）缩减并更名而来，遵循 SIL Open Font License 1.1。许可证全文一并包含在 dist/assets/OFL.txt 中。
• 表单 PDF：国民健康保险公团官方表单（空白表格）
• 字体 dist/assets/NanumGothic-Regular.ttf（劳动合同书、就业规则申报文件 PDF）：NanumGothic（Copyright (c) 2010, NHN Corporation），SIL Open Font License 1.1。许可证全文见 dist/assets/NanumGothic-OFL.txt。
• dist/assets/rhwp_bg.wasm（HWP 读取）：rhwp，MIT。许可证全文见 dist/assets/rhwp-LICENSE.txt。
• 法令原文：法制处国家法令信息共同利用 Open API。