Project Overview

The Mock IT Onboarding Automator is a backend service that automates employee onboarding based on HR webhook events.

When a new employee is hired, the HR system sends an onboarding event to the service. The system validates the event, determines which applications the employee should receive based on their role, provisions access records, records audit information, and ensures duplicate events are handled safely through idempotent processing.

The project also exposes an MCP (Model Context Protocol) server that allows AI assistants and operators to inspect employee access, review failed onboarding events, and retry failed provisioning operations.

---

Features

Webhook Processing

Supports HR onboarding events via:

POST /webhooks/hris

Supported event type:

employee.hired

Role-Based Access Provisioning

Application access is automatically assigned based on employee role.

engineer

• slack
• google_workspace
• jira

sales

• slack
• google_workspace
• salesforce

it_admin

• slack
• google_workspace
• jira
• salesforce

Idempotent Event Processing

Duplicate webhook deliveries using the same event_id are safely ignored.

The system guarantees:

• No duplicate employees
• No duplicate access grants
• No duplicate provisioning actions

Audit Logging

Every successful provisioning operation creates an audit log containing:

• event_id
• role
• granted applications
• idempotency status

MCP Server

The MCP server exposes the following tools:

get_employee_access

Retrieve employee details and provisioned application access.

list_failed_events

List failed onboarding events.

retry_provision

Retry a previously failed onboarding event.

---

Architecture Summary

flowchart TB
    HR[HR System]

    HR -->|POST /webhooks/hris| WEBHOOK[FastAPI Webhook]
    WEBHOOK --> PROV[Provisioning Service]

    PROV --> EMP[Employees]
    PROV --> ACCESS[Access Grants]
    PROV --> AUDIT[Audit Log]

    DB[(SQLite Database)]

    EMP --> DB
    ACCESS --> DB
    AUDIT --> DB

    MCP[MCP Server]

    MCP --> TOOL1[get_employee_access]
    MCP --> TOOL2[list_failed_events]
    MCP --> TOOL3[retry_provision]

    TOOL1 --> DB
    TOOL2 --> DB
    TOOL3 --> DB

---

Technology Stack

Component	Technology
Language	Python 3.12+
API Framework	FastAPI
ORM	SQLAlchemy 2.0
Database	SQLite
MCP	Official Python MCP SDK
Testing	pytest
Package Management	uv

---

Prerequisites

Install:

• Python 3.12+
• uv
• Git

Verify installation:

python --version
uv --version
git --version

---

Installation

Clone repository:

git clone https://github.com/Aman3786/IT-Onboarding-Automator.git
cd IT-Onboarding-Automator

Install dependencies:

uv sync

OR

uv pip install -r requirements.txt

---

Initialize Database

Create tables and seed initial role mappings:

uv run python setup_db.py

Expected output:

Database initialized successfully

Database location:

data/onboarding.db

---

Run API

Start FastAPI server:

uv run uvicorn api.main:app --reload

API available at:

http://localhost:8000

Interactive documentation:

http://localhost:8000/docs

---

Run MCP Server

Start MCP server (Prequisite: Nodejs Should be installed for MCP Inspector)

npx @modelcontextprotocol/inspector uv run python -m mcp_server.server

OR

uv run mcp dev mcp_server/server.py

OR

uv run python -m mcp_server.server
npx -y @modelcontextprotocol/inspector

The MCP server uses stdio transport and is intended to be consumed by MCP Inspector, cursor and other MCP-compatible clients.

---

Configure Cursor MCP

Create:

.cursor/mcp.json

Configuration:

{
  "mcpServers": {
    "onboarding-automator": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "mcp_server.server"
      ]
    }
  }
}

Restart Cursor after creating the configuration.

The following tools should become available through MCP Inspector/Cursor:

• get_employee_access
• list_failed_events
• retry_provision

---

Run Tests

Run all tests:

uv run pytest

Run verbose output:

uv run pytest -v

Run a specific test file:

uv run pytest tests/test_webhook.py -v

---

Example Requests

Successful Employee Onboarding

curl -X POST http://localhost:8000/webhooks/hris \
-H "Content-Type: application/json" \
-d '{
  "event_id":"evt_hire_001",
  "event_type":"employee.hired",
  "email":"[email protected]",
  "full_name":"Alex Chen",
  "role":"engineer"
}'

Example response:

{
  "event_id": "evt_hire_001",
  "status": "completed",
  "idempotent": false,
  "employee": {
    "email": "[email protected]",
    "role": "engineer"
  },
  "granted_apps": [
    "slack",
    "google_workspace",
    "jira"
  ]
}

---

Duplicate Event

Submitting the same request again:

{
  "event_id": "evt_hire_001",
  "status": "completed",
  "idempotent": true
}

---

Invalid Role

curl -X POST http://localhost:8000/webhooks/hris \
-H "Content-Type: application/json" \
-d '{
  "event_id":"evt_invalid_role",
  "event_type":"employee.hired",
  "email":"[email protected]",
  "full_name":"Bad User",
  "role":"unknown_role"
}'

Response:

{ 
  "event_id":"evt_invalid_role",
  "status":"failed",
  "error":"Unknown role: 'unknown_role'"
}

---

Assumptions

1. Employee email addresses are unique.
2. Roles are predefined and managed internally.
3. Application provisioning is simulated through database records.
4. SQLite is sufficient for local execution and evaluation.
5. Duplicate webhook deliveries reuse the same event_id.