노동 업무 도구 (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. 판 뭐가 바뀌었는지 조문별로 보여 줘.」

⚙️ 환경변수

팩스·문자를 쓰려면 본인 팝빌 계정의 값을 넣어야 합니다. 이 패키지에는 기본 계정도, 기본 발신번호도 없습니다. 값이 빠지면 보내기 도구는 무엇이 빠졌는지(missing)를 돌려주고 아무것도 보내지 않습니다.

• 환경변수가 우선입니다. 없으면 ~/.claude/.env 의 POPBILL_*·LAW_OC 줄을 읽습니다.
• 키 값은 도구 응답이나 로그 어디에도 찍지 않습니다.
• find_branch 와 make_form 은 팝빌 설정 없이 씁니다.

🔒 개인정보

• make_form 은 사람 명단을 파일 경로(peopleFile)로만 받습니다. 주민등록번호가 AI 대화에 실리지 않고, 도구가 파일을 직접 읽습니다.
• 주민등록번호는 이 PC 안에서 PDF 로만 만들어집니다. 도구 응답에는 싣지 않고, 응답에 주민등록번호 모양이 섞이면 나가기 전에 가립니다.
• 문자 본문에 주민등록번호 모양이 있으면 send_sms 가 보내지 않습니다.
• 팩스·문자는 confirm:true 를 준 호출에서만 실제로 나갑니다. 그 전에는 미리보기만 돌려줍니다.
• 밖으로 나가는 것은 세 가지뿐입니다. ① find_branch 에 사업자등록번호를 주면 그 번호만 일의 무늬 사이트로 보내 주소를 받아 옵니다(주소를 주면 아무것도 나가지 않습니다). ② send_fax·send_sms 는 본인 팝빌 계정으로 PDF·문자를 보냅니다. ③ work-rules 묶음은 법제처 Open API 에 법령명·날짜·판 번호만 묻습니다. 취업규칙 본문과 사업장 정보는 보내지 않습니다.
• 취업규칙 본문·파일은 이 PC 안에서만 대조합니다. 본문에 주민등록번호 모양이 있으면 점검하지 않고, 신고 서류 도구는 주민등록번호를 받지 않습니다.

🙅 하지 않는 일

• 신고를 접수하지 않습니다. 신고서 PDF 를 만들고, 사용자가 확인한 뒤 본인 팝빌 계정과 본인 번호로 보내도록 돕는 데까지입니다. 공단 접수 여부와 처리 결과는 공단에서 확인해 주세요.
• 취업규칙 신고도 접수하지 않습니다. 서류를 만들고 날인이 필요한 곳을 알려 주는 데까지입니다.
• 취업규칙 대조는 낱말을 맞춰 본 1차 결과입니다. 바꿀 문안은 법이 정한 최저 기준이라 회사 사정에 맞게 확인한 뒤 씁니다.
• 받을 팩스 번호를 스스로 고르지 않습니다. find_branch 결과 가운데 사람이 확인한 번호만 씁니다. 고지서나 EDI 에 적힌 관리지사가 따로 있으면 그 지사가 우선입니다.
• 입력값을 저장하거나 모으지 않습니다.

🛠️ 개발 (저장소 안에서)

이 패키지는 사이트 엔진(src/lib/nhis-forms·src/lib/branch-directory)과 지사 데이터(data/branch-directory/)를 esbuild 로 묶어 서식이 사이트와 한 벌로 유지됩니다. 엔진을 고치면 다시 빌드해야 반영됩니다.

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   # 올라갈 파일 확인

• 셸에 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: 나눔고딕(Copyright (c) 2010, NHN Corporation)을 줄이고 이름을 바꾼 것으로 SIL Open Font License 1.1 을 따릅니다. 전문은 dist/assets/OFL.txt 에 함께 들어 있습니다.
• 서식 PDF: 국민건강보험공단 공식 서식(빈 양식)
• 글꼴 dist/assets/NanumGothic-Regular.ttf(근로계약서·취업규칙 신고 서류 PDF): 나눔고딕(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.