Employee-Management-MCP-Server

# Employee Management MCP Server (EMP-MCP-2026) An MCP server exposing 6 employee-management tools over **stdio**, backed by a synthetic JSON employee dataset. ## Tools | Tool | Purpose | |---|---| | `list_employees` | Filter/search employees (department, status, location, free-text query). | | `get_employee` | Fetch one employee's full profile by `employee_id`. | | `get_org_summary` | Headcount aggregation by department / status / location. | | `create_employee` | Onboard a new hire. | | `update_employee` | Partial update of an existing employee's mutable fields. | | `deactivate_employee` | Soft-delete (sets `status` to `inactive`; record stays retrievable). | ## Setup Requires Python 3.10+. ```bash python -m venv .venv .venv\Scripts\activate # Windows pip install -e . ``` Copy `.env.example` to `.env` and adjust if needed (no secrets live in either file — only paths and mode flags). Note: the server does **not** auto-load `.env` — nothing in `config.py` calls `load_dotenv()`. `python-dotenv` is listed as a dependency but isn't wired in. `.env` is documentation of what to set; to make it take effect you either export those variables in your shell before running, set them directly in the `env` block of your MCP host's server config (the common case — see "Host configuration" below), or run `dotenv run -- python -m employee_mcp.server` yourself if you want the file loaded. ## Running the server ```bash python -m employee_mcp.server ``` On first run, if `EMP_MCP_DATA_PATH` doesn't exist yet, the server copies the committed seed (`data/employees.seed.json`, 14 synthetic employees across all 5 departments) to that path and treats it as the mutable working dataset. Delete that file to reset to a clean seed on the next run. **Windows note:** make sure `python` resolves to the interpreter with `mcp` installed (or point a host's `command` at the venv's absolute `python.exe`). Prefer an absolute `EMP_MCP_DATA_PATH` when a host launches this as a subprocess — a relative path combined with a host-chosen working directory is the most common cause of "connected but no tools" / "connection closed" on Windows. In this codebase, relative `EMP_MCP_DATA_PATH` values are resolved against the repo root (not the process's cwd) specifically to avoid that trap, but an absolute path is still the most robust choice for host configs. ## Data storage Employees live in a single JSON array file (`data/employees.json`), loaded in full at startup into an `employee_id -> Employee` dict (`store.py`) for O(1) lookups. Every write (`create_employee` / `update_employee` / `deactivate_employee`) re-serializes the whole in-memory set and persists it atomically — write to a `.tmp` file, then `os.replace()` over the target — so a crash or kill mid-write can't leave a half-written, corrupt data file. JSON (rather than a real database) is a deliberate choice for this project's scale: the seed is 14 employees, and this design targets small in-memory datasets on the order of hundreds to low thousands of records, not enterprise HRIS volumes. At that size, loading the entire file into memory on every server start has no meaningful cost, and JSON buys a human-readable, git-diffable store with zero schema migrations, no separate database process to run, and no driver to install — appropriate for a synthetic-data assignment/demo, not a claim that this approach would scale past that ceiling (see "Known limitations" for what would need to change if it did — e.g. real pagination, an actual DB engine, and finer-grained locking than the current "rewrite the whole file" strategy allows for concurrent writers). ## Configuration (environment variables) | Env var | Default | Meaning | |---|---|---| | `EMP_MCP_DATA_PATH` | `./data/employees.json` | Mutable working data file. | | `EMP_MCP_READ_ONLY` | `false` | When `true`, all write tools refuse with a `READ_ONLY` error and make no changes. | | `EMP_MCP_DEBUG` | `false` | When `true`, unexpected-error messages include a traceback. Keep `false` in normal/demo use. | | `EMP_MCP_AUDIT_PATH` | `./logs/audit.log` | Path to the audit log file (one JSON line per tool call). | No secrets are configured anywhere — these are mode flags and paths only. ## Host configuration ```json { "mcpServers": { "employee-mcp": { "command": "<ABSOLUTE-PATH-TO-YOUR-python.exe>", "args": ["-m", "employee_mcp.server"], "env": { "PYTHONPATH": "<ABSOLUTE-PATH-TO-THIS-REPO-ROOT>", "EMP_MCP_DATA_PATH": "<ABSOLUTE-PATH-TO-THIS-REPO-ROOT>\\data\\employees.json", "EMP_MCP_AUDIT_PATH": "<ABSOLUTE-PATH-TO-THIS-REPO-ROOT>\\logs\\audit.log", "EMP_MCP_READ_ONLY": "false", "EMP_MCP_DEBUG": "false" } } } } ``` Fill in the two placeholders for your own machine (every path must be absolute — a relative path combined with a host-chosen working directory is the most common cause of "connected but no tools" / "connection closed" on Windows): - **`<ABSOLUTE-PATH-TO-YOUR-python.exe>`** — the interpreter you installed this project into. If you used a venv (`python -m venv .venv` per Setup above), activate it and run `(Get-Command python).Source` in PowerShell, then paste that path, e.g. `C:\Users\you\...\Employee_management_MCP_server\.venv\Scripts\python.exe`. - **`<ABSOLUTE-PATH-TO-THIS-REPO-ROOT>`** — the folder containing this README on your machine, e.g. `C:\Users\you\Documents\Employee_management_MCP_server`. It's used four times above: once for `PYTHONPATH`, and as the prefix for both data-file paths — replace all of them consistently. `PYTHONPATH` matters specifically when `command` points at a bare interpreter that this project was never `pip install -e .`'d into — without it, `python -m employee_mcp.server` can't locate the `employee_mcp` package and the host will show the server as failed/disconnected. If `command` points at a venv's `python.exe` where you already ran `pip install -e .`, `PYTHONPATH` is unnecessary — the editable install makes the package importable from anywhere — but it doesn't hurt to leave it set. ## Debugging with MCP Inspector ```bash npx @modelcontextprotocol/inspector python -m employee_mcp.server ``` This opens a local web UI (`http://localhost:6274/...`) where you can run `tools/list`, inspect each tool's JSON Schema, and call tools interactively with a form built from that schema. To test read-only mode, set `EMP_MCP_READ_ONLY=true` in the Inspector's "Environment Variables" panel before connecting. ## Human-in-the-loop (HITL) expectation This server does not gate write tools on its own confirmation step — it expects the **MCP host** to show the user the write tool's resolved input (the employee fields about to be created/updated/deactivated) before actually calling it, the way most MCP-aware chat hosts do for consequential tool calls. `EMP_MCP_READ_ONLY=true` is the hard backstop for hosts/contexts where that isn't available. ## Email-uniqueness interpretation The requirement is "email unique across active employees." This server enforces it as: on create, and on update that changes `email`, reject with `DUPLICATE_EMAIL` if any *other* employee whose `status == "active"` already holds that email (case-insensitive compare). Two `inactive`/`on_leave` records may share an email with each other or with what later becomes an active employee's old email — the constraint only looks at currently-active holders at the moment of the write. ## Other documented interpretations - **`list_employees` limit > 100:** clamped to 100, not rejected. - **Deactivating an already-inactive employee:** succeeds idempotently; the response reports `previous_status == new_status == "inactive"` rather than erroring. - **`update_employee` and `manager_id`:** omitting `manager_id` means "no change." There's currently no way to explicitly clear an employee's manager back to `null` via `update_employee` (the tool can't distinguish "field omitted" from "field explicitly set to null" with this parameter shape) — reassign to a different manager, or edit `manager_id` at creation time. A future iteration could resolve this with a sentinel/"unset" value if that gap matters for real usage. - **SDK-level argument validation:** FastMCP validates each tool's arguments (types, enums) against its generated JSON Schema *before* our tool code runs. Such failures are non-crashing and surfaced as `isError: true` with a message starting `VALIDATION_ERROR: invalid arguments for <tool>: ...`, and are still recorded as one `logs/audit.log` line with `status: "error"`, `code: "VALIDATION_ERROR"` — a thin server-level wrapper (`_AuditedFastMCP` in `server.py`) exists specifically to guarantee that, since it doesn't happen for free. ## Audit logging Every tool call appends exactly one JSON line to `logs/audit.log` (created at startup if missing) with `timestamp`, `tool`, `args_summary` (PII-light — email local-part masked, full names omitted), `status` (`ok`/`error`), `latency_ms`, and on failure a taxonomy `code`. Nothing is ever written to stdout — stdout is reserved for JSON-RPC frames; all logging goes to this file and/or stderr. ## Error taxonomy `VALIDATION_ERROR`, `DUPLICATE_EMAIL`, `NOT_FOUND`, `MANAGER_CYCLE`, `READ_ONLY`, `INTERNAL_ERROR` — see `employee_mcp/errors.py`. Every domain failure message has the shape `CODE: human-readable detail`, e.g. `NOT_FOUND: no employee with id EMP-999`. ## Tests ```bash python -m pytest tests/test_smoke.py -v ``` Spins up the real server as a subprocess per test and drives it over stdio with an `mcp.ClientSession`, exercising protocol discovery, all 6 tools' success/failure paths, read-only mode, malformed-argument robustness, and audit-log completeness. This — not "the LLM said it worked" — is the evidence that the transport contract holds. ## Demo See `demo/demo_transcript.md` for a captured run of three flows (search/list, create, org summary) plus one intentional failure path (duplicate email), against the seed dataset, with the corresponding `logs/audit.log` lines shown alongside each call. ## Known limitations - No pagination cursor for `list_employees` beyond `limit`/clamp — fine at the small, in-memory scale this project targets (low thousands of records at most), would need revisiting at larger scale. - `update_employee` can't clear `manager_id` back to `null` (see above). - Audit log location defaults to `logs/audit.log` and is configurable via `EMP_MCP_AUDIT_PATH`, but nothing enforces a 1:1 pairing with `EMP_MCP_DATA_PATH` — server instances that don't override it share the same default file. - Out of scope by design: no HTTP/SSE transport, no auth/OAuth provider, no frontend UI, no real HRIS/payroll integration, no stretch tools (`search_by_skill`, `get_direct_reports`, `export_employees_csv`, MCP Resources).