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

⚙️ 環境変数

ファクス・SMSを使うには、ご自身のポップビルアカウントの値を設定する必要があります。このパッケージにはデフォルトのアカウントも、デフォルトの発信番号もありません。 値が不足している場合、送信ツールは不足している項目（missing）を返し、何も送信しません。

• 環境変数が優先されます。設定されていない場合は、~/.claude/.env の POPBILL_*・LAW_OC の行を読み込みます。
• キーの値は、ツールの応答やログに一切出力しません。
• find_branch と make_form は、ポップビルの設定なしで使えます。

🔒 個人情報

• make_form は、名簿をファイルパス（peopleFile）でのみ受け取ります。住民登録番号がAIとの会話に含まれることはなく、ツールがファイルを直接読み込みます。
• 住民登録番号は、このPC内でPDFにのみ出力されます。ツールの応答には含めず、応答に住民登録番号のような形式が含まれている場合は、外部に出る前にマスキングします。
• SMS本文に住民登録番号のような形式が含まれている場合、send_sms は送信しません。
• ファクス・SMSは、confirm:true を指定した呼び出しでのみ実際に送信されます。それまではプレビューのみを返します。
• 外部に送信されるのは次の3つだけです。① find_branch に事業者登録番号を渡した場合、その番号のみをイルの模様サイトに送って住所を取得します（住所を渡した場合は何も送信されません）。② send_fax・send_sms は、ご自身のポップビルアカウントでPDF・SMSを送信します。③ work-rules グループは、法制処の Open API に法令名・日付・版番号のみを問い合わせます。就業規則の本文や事業所情報は送信しません。
• 就業規則の本文・ファイルは、このPC内でのみ照合します。本文に住民登録番号のような形式が含まれている場合はチェックせず、届出書類ツールは住民登録番号を受け取りません。

🙅 対応しないこと

• 届出を受け付けることはありません。 届出書のPDFを作成し、ユーザーが確認した後、ご自身のポップビルアカウントとご自身の番号で送信できるよう支援するところまでです。公団への受付状況と処理結果は、公団にご確認ください。
• 就業規則の届出も受け付けません。書類を作成し、押印が必要な箇所をお知らせするところまでです。
• 就業規則の照合は、単語を照らし合わせた一次チェックの結果です。変更案は法律で定められた最低基準なので、会社の事情に合わせて確認してから使用してください。
• 送信先のファクス番号を自動で選ぶことはありません。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 は最後に実際の法制処を2回だけツール呼び出しします（条文原文・版の比較）。設定されていない場合は 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 に1行追加します。

• 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。