ukg_pro_wfm_mcp_server

<p align="center"> <img src="docs/assets/ukg-mcp-hero.svg" alt="UKG Pro WFM MCP Server" width="100%"> </p>

<h1 align="center">UKG Pro WFM MCP Server</h1>

<p align="center"> <strong>Self-sufficient reasoning, hydration, orchestration, and execution layer for the UKG Pro Workforce Management API ecosystem.</strong> </p>

<p align="center"> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-100%25-3178C6?style=for-the-badge&logo=typescript&logoColor=white"> <img alt="MCP Server" src="https://img.shields.io/badge/MCP-Server-2ECC71?style=for-the-badge"> <img alt="UKG Pro WFM" src="https://img.shields.io/badge/UKG%20Pro-WFM-111827?style=for-the-badge"> <img alt="Status" src="https://img.shields.io/badge/Status-Active-22C55E?style=for-the-badge"> </p>

---

What This Is

This is not a thin OpenAPI wrapper.

This server is designed to behave like a UKG Pro WFM reasoning layer. It accepts natural language, determines what the user is really asking, resolves missing inputs, discovers the correct API path, hydrates partial objects, traverses references, validates completeness, scores confidence, and returns full operational answers.

---

Core Rule

Search and list endpoints are discovery only. They are not final truth.

If an API response contains IDs, references, partial objects, child references, parent references, profile references, or linked configuration, the server must hydrate those objects before answering.

---

Execution Model

<table> <tr> <th>Traditional API Flow</th> <th>UKG Pro WFM MCP Flow</th> </tr> <tr> <td>User request</td> <td>Natural language request</td> </tr> <tr> <td>Pick endpoint manually</td> <td>Detect intent and entities</td> </tr> <tr> <td>Call one API</td> <td>Resolve missing inputs</td> </tr> <tr> <td>Return raw result</td> <td>Discover, hydrate, validate, and answer</td> </tr> </table>

---

Capabilities

Capability	Purpose
Natural language routing	Understands operational questions without requiring endpoint knowledge
Missing input resolution	Finds IDs, refs, dates, employees, groups, profiles, and related objects
Discovery-only enforcement	Prevents list/search responses from being treated as final truth
Universal hydration	Pulls full detail for every reachable partial object
Object graph traversal	Follows parent, child, profile, group, org, and setup references
Completeness validation	Calculates whether the answer is complete enough to return
Confidence scoring	Classifies answers as CERTAIN, HIGH, MEDIUM, LOW, or BLOCKED
Write safety	Requires hydration, dry-run, explicit confirmation, and re-read after writes
Audit logging	Records source chain, duration, confidence, and affected objects

---

Supported Domains

Domain	Coverage Intent
Attendance	Events, patterns, and attendance-related operational context
Common Resources	Shared objects, lookup values, Hyperfinds, and common references
Employee Self Service	Employee-facing objects and request flows
Forecasting	Forecast-related workforce planning data
Healthcare Productivity	Productivity and staffing context
HCM	HCM-connected workforce data
Leave	Leave cases, requests, balances, and related context
People	Person, employee, manager, job, and org details
Person Assignments	Assignments, roles, and workforce relationships
Platform	Tenant, metadata, and platform-level capabilities
Scheduling	Schedules, shifts, coverage, and schedule analysis
Scheduling Setup	Scheduling configuration and setup references
Timekeeping	Timekeeping objects and operational time data
Timekeeping Setup	Pay rules, work rules, pay codes, and setup metadata
Timekeeping Timecards	Timecards, punches, exceptions, totals, approvals
Timekeeping Bulk Operations	Controlled bulk workflows with guardrails
Universal Device Manager	Device and clock-related operational context
Webhook Events	Event subscriptions and event payload normalization

---

Hydration Behavior

Traditional API result:

<pre><code>{ "id": 1234, "name": "Hillcrest South" }</code></pre>

Server behavior:

<pre><code>Resolve object → Discover detail endpoint → Retrieve complete object → Detect references → Hydrate references → Traverse relationships → Validate completeness → Return final answer</code></pre>

This applies to every object type, not just Known Places.

---

Confidence Levels

Level	Meaning
CERTAIN	Unique immutable identifier, full hydration, no unresolved dependencies, no conflicts
HIGH	Strong candidate, full target detail, minor non-critical references unavailable
MEDIUM	Likely answer, but some relevant references remain unresolved
LOW	Ambiguous or incomplete
BLOCKED	Cannot proceed safely because required data, access, or endpoint is unavailable

---

Architecture

<table> <tr> <th>Layer</th> <th>Responsibilities</th> </tr> <tr> <td>Catalog</td> <td>OpenAPI ingestion, endpoint normalization, classification, endpoint graph</td> </tr> <tr> <td>Reasoning Engine</td> <td>Intent detection, entity extraction, missing input resolution, candidate ranking</td> </tr> <tr> <td>Hydration Engine</td> <td>Response graph parsing, dependency traversal, object hydration, completeness validation</td> </tr> <tr> <td>API Client</td> <td>Authentication, retries, pagination, rate limits, request tracing</td> </tr> <tr> <td>Tool Layer</td> <td>MCP tool registration, workflow composition, write safety, final answer formatting</td> </tr> </table>

---

Execution Pipeline

<pre><code>Natural Language → Intent Detection → Entity Extraction → Missing Input Resolution → Discovery Endpoint → Candidate Ranking → Primary Endpoint → Response Graph Parsing → Hydration Engine → Completeness Validation → Confidence Scoring → Business Interpretation → Response Formatting → Audit Logging</code></pre>

---

Primary Tool

ukg_wfm_ask

Use this for natural language requests.

Examples:

<pre><code>Show me the complete employee profile for employee 12345 and hydrate all manager and organizational references.

Explain every exception on employee 12345's timecard for last week.

Investigate why employee 12345 failed geofence validation yesterday.

Compare scheduled versus actual worked hours for ICU employees this pay period.

Hydrate the Emergency Department employee group and identify all connected profiles and references.</code></pre>

---

Write Safety

Every write operation follows the same lifecycle:

<pre><code>Resolve Inputs → Hydrate Target → Hydrate Dependencies → Dry Run → Explicit Confirmation → Execute → Rehydrate → Return Before/After State</code></pre>

Write, delete, and bulk operations cannot execute from:

• name-only matches
• search results
• partial objects
• inferred identities
• ambiguous references

Only fully hydrated targets are eligible for mutation.

---

Installation

Clone the repository:

<pre><code>git clone https://github.com/fvmuzik00/UKG_Pro_WFM_MCP_Server.git cd UKG_Pro_WFM_MCP_Server</code></pre>

Install dependencies:

<pre><code>npm install</code></pre>

Configure environment:

<pre><code>cp .env.example .env</code></pre>

Required environment variables:

<pre><code>UKG_BASE_URL= UKG_CLIENT_ID= UKG_CLIENT_SECRET= UKG_APP_KEY= UKG_USERNAME= UKG_PASSWORD= UKG_AUTH_MODE=client_credentials</code></pre>

Start development server:

<pre><code>npm run dev</code></pre>

Build production:

<pre><code>npm run build</code></pre>

Run tests:

<pre><code>npm test</code></pre>

---

Scorecard

Generate endpoint intelligence and risk outputs:

<pre><code>npm run scorecard</code></pre>

Outputs:

• docs/endpoint-scorecard.json
• docs/tool-risk-matrix.json

---

Project Goals

This project exists to eliminate three common problems in workforce management integrations:

1. Partial answers
2. Manual endpoint selection
3. Missing relationship awareness

The server's responsibility is not merely to call APIs.

Its responsibility is to understand the request, discover what information is missing, retrieve that information, validate it, and return the most complete answer possible from the available system of record.