# HRIS MCP Connector

A Model Context Protocol (MCP) server that gives an AI client like Claude Desktop
read-only access to HR information system data through a typed tool layer. Built with the
official Python MCP SDK.

This public repository is a **reference implementation backed by a synthetic mock data
layer.** The production version swaps that layer for authenticated calls to a real HRIS
such as Rippling, leaving the tool surface identical. No real employee data, no
credentials, and no vendor-specific configuration are included here.

## What It Does

It exposes four read-only tools to an MCP client:

| Tool | What it returns |
|------|-----------------|
| `list_recent_hires` | Employees who started within the last N days, newest first |
| `get_employee` | A single employee record by ID |
| `list_departments` | Each department with its current headcount |
| `get_pto_balance` | Remaining paid-time-off hours for one employee |

Ask Claude something like "who joined in the last two weeks?" and it calls
`list_recent_hires` and answers from the result.

## Why It's Built This Way

**Read-only by design.** Every tool retrieves information; none changes HR data. Write
actions belong behind authentication, authorization, audit logging, and human approval,
which are deliberately out of scope for a public reference server.

**A clean tool surface over a swappable data layer.** The MCP tools call plain functions
in `mock_data.py`. In production, that one module is replaced with real HRIS API calls and
nothing else changes. That separation is the whole point: the AI client sees a stable
contract regardless of what's behind it.

**Testable without a server.** Because the query logic lives in plain functions, the test
suite checks it directly with a fixed reference date. No process, no network, no flakiness.
See `tests/`.

**Protocol-safe logging.** This is a stdio server, so stdout carries the protocol. All
diagnostics go to stderr, which keeps the message stream clean.

## Architecture

```mermaid
flowchart LR
    C[Claude / MCP Client] --> S[MCP Server: tools]
    S --> D[Data Layer]
    D --> M[Mock Data]
    D -. production .-> API[Real HRIS API]
```

## Setup

1. `pip install -r requirements.txt`
2. Run the server: `python src/server.py`

## Connect it to Claude Desktop

Add this to your Claude Desktop config file, using the absolute path to this repo:

```json
{
  "mcpServers": {
    "hris-connector": {
      "command": "python",
      "args": ["/absolute/path/to/hris-mcp-connector/src/server.py"]
    }
  }
}
```

Restart Claude Desktop fully (quit, don't just close the window). The four tools then
appear in the client.

## Going to Production

To connect a real HRIS, replace the functions in `src/mock_data.py` with authenticated API
calls. The API token goes in a `.env` file (see `.env.example`), which is gitignored and
never committed. The tool definitions in `src/server.py` stay exactly as they are.

## Status

Reference implementation with a mock data layer. A production version of this connector
runs against a live HRIS in a real HR environment; this public repository contains the
pattern and the mock layer only.