노동 업무 도구 (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": "내 팩스 발신번호" } } } }

🪟 Windows 에서 Claude Desktop 이 npx 를 못 찾을 때

cmd /c 로 감쌉니다.

{

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

</details>

🧩 Cursor · Windsurf · 그 밖의 MCP 호스트

같은 command / args 를 각 도구의 MCP 설정에 넣습니다. stdio 전송이면 전부 됩니다.

붙이고 나서 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 를 해 둡니다.
• 저장소 빌드본을 바로 등록할