# UKG Ready MCP

MCP server for UKG Ready REST endpoints, including employees, timecards, exceptions, compensation, saved reports, and a generic authenticated endpoint tool.

## Configuration

Copy `.env.example` to a local environment configuration and set:

- `UKG_BASE_URL`: UKG tenant base URL, defaulting to `https://secure.entertimeonline.com`.
- `UKG_API_KEY`, `UKG_USERNAME`, `UKG_PASSWORD`, `UKG_COMPANY`.
- `UKG_DEFAULT_REPORT_ID`: optional saved report ID.

Never commit real credentials or place them in source files.

## Run

```powershell
npm install
npm run build
npm start
```

The server communicates over MCP stdio. Available tools:

- `get_ukg_saved_report_csv`
- `list_ukg_employees`
- `get_ukg_employee`
- `get_ukg_timecards`
- `list_ukg_exceptions`
- `get_ukg_compensation`
- `call_ukg_endpoint`

The workforce tools use documented-style defaults and expose an optional `path` override because UKG Ready endpoint availability varies by tenant and enabled module. The generic tool accepts any API path, so credentials remain inside the server configuration. Add write tools only after the tenant's endpoint contract and permissions are confirmed.

## UKG employee and Command Cloud driver mapping

The intended integration is that a UKG employee corresponds to a driver in Command Cloud. This mapping is a planned cross-system relationship, not an automatic assumption yet.

When implementing it, reconcile records using stable identifiers where available, then validate with supporting fields such as employee/driver name, employee number, phone, email, and active status. Keep an explicit mapping of the UKG employee ID to the Command Cloud driver ID; do not rely on names alone because names can change or be duplicated.

The mapping will support future workflows such as comparing UKG timecards or clock status with Command Cloud driver, dispatch, and ticket activity. The actual matching rules and source-of-truth decisions still need to be confirmed before writing synchronization tools.