shift-maker — Labor-Law-Aware Shift Scheduling MCP Server

Generate legally-compliant weekly shift schedules for Korean workplaces through pure conversation — powered by OR-Tools CP-SAT.

🇰🇷 한국어 README

Why

Ask an LLM to build a weekly shift roster and it will confidently hand you one that double-books a person into two shifts at once, blows past the 52-hour weekly cap, or puts a minor on a midnight shift. Rostering is a constraint-satisfaction problem, and next-token prediction is the wrong tool for it — the answer looks right and is quietly illegal.

shift-maker doesn't ask the model to do the math. The conversation only collects facts (store, shifts, employees, constraints); the actual schedule is solved by an OR-Tools CP-SAT engine on the backend. You get either a schedule that is provably valid under the constraints, or a clear "infeasible + reason" — never a plausible-looking violation.

Related MCP server: LAWMADI

Features

Eight MCP tools cover the full flow from store setup to publishing:

Labor-law engine

generate_schedule takes a laborMode that selects how the Korean Labor Standards Act is applied:

Minor workers (isMinor: true, under 18): no night work (22:00–06:00), max 7 hours/day, max 35 hours/week — all enforced as hard constraints.

Weekly holiday allowance (주휴수당): this is not auto-avoided. When an employee crosses 15 scheduled hours in a week they become eligible for the statutory paid-holiday allowance. shift-maker surfaces that fact transparently as a warning so the owner can decide — it never silently trims hours to dodge the threshold.

Also supports

• Day-of-week staffing overrides — need 2 people on weekday nights but 3 on weekends? Add a shift slot with a day and its count replaces the base headcount for that day (it does not stack).

• Per-employee fixed assignments — pin someone to a recurring day × shift every week (e.g. "manager always works Friday/Saturday night").

• Date-specific unavailability — block a single date × shift ("can't close on 7/8") without marking the whole day off.

• Overnight shifts — an end time earlier than the start time is treated as crossing midnight and rendered with an (익일) / "next day" tag.

• Self-serve availability links — share one link in a group chat and each employee submits their own availability.

Live demo

A hosted instance is live over Streamable HTTP:

https://shift-maker.playmcp-endpoint.kakaocloud.io/mcp

Connect it in three steps:

1. In Claude Desktop, open Settings → Connectors → Add custom connector (or launch the MCP Inspector).

2. Paste the endpoint URL above as a Streamable HTTP server.

3. Start chatting — the tools appear automatically.

Verified 3-message scenario (cinema)

These three Korean messages take the server from empty to a finished, law-compliant roster plus an availability link:

1. "우리 영화관 등록해줘. 3교대 각 2명, 주말 야간은 3명으로" "Register my cinema. Three shifts, 2 people each, but 3 on weekend nights."

2. "점장, 주3일 고3, 직원 8명 등록. 점장은 금·토 야간 고정" "Add a manager (3 days/week, high-school senior) and 8 staff. Pin the manager to Friday/Saturday night."

3. "2026-07-20 주 근무표 짜고, 가용시간 입력 링크도 만들어줘" "Build the roster for the week of 2026-07-20 and create an availability-input link."

Architecture

flowchart LR
  A[AI client\nClaude / ChatGPT / Kakao PlayMCP] -->|MCP Streamable HTTP| B[shift-maker MCP server\nthis repo]
  B -->|REST + shared secret| C[SmartShift backend\nNext.js on Vercel]
  C --> D[(PostgreSQL)]
  C -->|solve| E[OR-Tools CP-SAT\nPython on Render]

This repo is the MCP layer. The backend/solver run as a hosted service; point SMARTSHIFT_API_URL at your own deployment if you fork the full stack.

Run locally

npm ci && npm run build
cp .env.example .env      # set SMARTSHIFT_API_URL and MCP_SHARED_SECRET
node dist/index.js

Then connect a client to the local server with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Built for Kakao AGENTIC PLAYER 10 (2026).

License

MIT — see LICENSE.