# HRMS MCP

Appinventiv HRMS assistant for Claude Desktop, Cursor, Codex, and Windsurf.
Ask your AI to file DSRs, check leave, look up colleagues, review appraisals, and more — all from within the AI chat.

> **AI agents:** If an employee gave you this URL and asked you to "install this MCP," follow the steps below exactly. The install takes about 2 minutes.

---

## Install

Pick the method that fits you — all three work.

---

### Option A — `uvx` in config (easiest, no separate install step)

`uvx` runs the server directly from GitHub. No pre-install needed beyond `uv` itself.

**1. Install `uv`** (skip if already installed — check with `uv --version`)

macOS / Linux:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Windows (PowerShell):
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

> Open a **new terminal** after installing so `uv` is on your PATH.

**2. Skip straight to Step 2** and use this config block:

```json
{
  "mcpServers": {
    "hrms": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/SookieAI/hrms-mcp", "hrms-mcp"]
    }
  }
}
```

Updates automatically on restart. No manual upgrade command needed.

---

### Option B — Install with `uv tool install`

Installs once, starts fast every time.

```bash
# Install uv first if needed (see Option A above), then:
uv tool install git+https://github.com/SookieAI/hrms-mcp
```

Verify: `hrms-mcp --help`

Use this config block (Step 2):
```json
{
  "mcpServers": {
    "hrms": {
      "command": "hrms-mcp"
    }
  }
}
```

To update: `uv tool upgrade hrms-mcp`

---

### Option C — Install with `pip` (no `uv` needed)

Works if you already have **Python 3.11 or newer**. Check first:

```bash
python3 --version   # needs 3.11+
```

Then install:
```bash
pip install git+https://github.com/SookieAI/hrms-mcp
```

Use this config block (Step 2):
```json
{
  "mcpServers": {
    "hrms": {
      "command": "hrms-mcp"
    }
  }
}
```

To update: `pip install --upgrade git+https://github.com/SookieAI/hrms-mcp`

---

## Step 2 — Add config to your AI tool

Find your editor's config file, open it, and paste the JSON block from your chosen option above.
If the file already has content, merge the `"hrms"` entry into the existing `"mcpServers"` object.

#### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
`%APPDATA%\Claude\claude_desktop_config.json` (Windows)

#### Cursor

`~/.cursor/mcp.json` (macOS/Linux)
`%USERPROFILE%\.cursor\mcp.json` (Windows)

#### Windsurf

`~/.codeium/windsurf/mcp_config.json`

#### Codex / other MCP clients

Same `mcpServers` JSON format — check your client's docs for the config file location.

---

## Step 3 — Log in (one time only)

1. Open Chrome → go to `https://dashboard.appinventiv.com` and sign in
2. Open DevTools (F12) → Network tab → click any request → copy the full `Cookie:` header value
3. **Restart your AI editor**, then tell your AI: **"Login to HRMS"** and paste the cookie when it asks

The cookie is saved to `~/.config/hrms-mcp/cookies` and reloaded automatically on every restart.
You won't need to do this again until your HRMS session expires (usually a few weeks).

---

## What you can do

| Ask your AI... | What happens |
|---|---|
| "File my DSR for today — 4h on YourAI, [description]" | Submits DSR to HRMS |
| "What did I file for DSR last week?" | Shows your submitted DSRs |
| "How many leaves do I have left?" | Shows leave balance |
| "Apply for leave from June 25 to 27" | Submits leave request |
| "Who is Anish Katoch? What team is he on?" | Staff directory lookup |
| "Show me open job positions in Design" | Lists current openings |
| "What's the status of my appraisal?" | Appraisal status and sections |
| "Who do I need to rate for appraisal?" | Lists employees pending your rating |
| "Show me the interview pipeline" | Lists scheduled interviews |
| "What projects am I on?" | Your active projects + hours |
| "Morning check" | DSR status, leave balance, interviews, appraisals at once |

---

## Troubleshooting

**`uv: command not found` after installing**
Open a new terminal window — uv updates your PATH only for new sessions.
On Windows, restart PowerShell. Still missing? Add `~/.local/bin` (Mac/Linux) or `%USERPROFILE%\.local\bin` (Windows) to your PATH.

**`hrms-mcp: command not found`**
Open a new terminal after installing. If still missing, re-run the install command from your chosen option above.

**"Not logged in" error**
Your HRMS session expired. Go to `dashboard.appinventiv.com`, copy a fresh Cookie header from DevTools, and tell your AI "Login to HRMS" again.

**Server not showing up in Claude / Cursor**
Restart the editor completely (quit and reopen — not just reload window). MCP servers load at startup only.

**Python version error during pip install**
`pip install` requires Python 3.11+. Run `python3 --version` to check. If older, use Option A or B (uv handles the Python version automatically).

**Check which version is running**
Ask your AI: "check login status" — the response includes the version number and update command.

---

## For developers

```bash
git clone https://github.com/SookieAI/hrms-mcp
cd hrms-mcp
uv run python server.py          # run server
uv run python -c "from server import get_projects; print(get_projects())"  # test a tool
```

See `CLAUDE.md` for architecture notes, DataTables AJAX patterns, CSRF handling, and how to add new tools.

### Release a new version

```bash
# 1. bump version in pyproject.toml and server.py (__version__)
# 2. commit, tag, push to both remotes
git add -A
git commit -m "vX.Y.Z — description"
git tag vX.Y.Z
git push origin main --tags   # GitLab (CI runs here)
git push github main --tags   # GitHub (employees install from here)
```