Field Time Exception Agent

An MCP server that lets an AI agent find and help resolve field technicians' time-entry exceptions before time reaches the payroll and time system (for example, WorkForce Software in an SAP SuccessFactors landscape).

The agent detects problems, explains them, and proposes fixes. A manager must approve every change before it's applied, and every action is recorded in an audit trail.

All data is synthetic.

The problem

Field technicians charge time to work orders. Three kinds of errors are common and costly:

Related MCP server: commerce-ops-harness

Architecture

flowchart LR
    U["Manager or time analyst"] -->|asks in plain language| C["AI client<br/>(Claude desktop app)"]
    C <-->|"MCP tools (stdio)"| S["MCP server<br/>server.py"]
    S --> R["Rules engine<br/>rules.py<br/>(deterministic)"]
    S --> D[("Synthetic data<br/>employees, work orders,<br/>time entries")]
    S -->|write| L[("Exception log, proposals,<br/>manager outbox, audit log")]
    A["Manager approval<br/>approve.py<br/>(outside the agent)"] -->|approve / reject| L
    S -->|"apply only if approved"| X[("Corrected time entries")]
    S -->|queue| V[("Work orders for the SAP team:<br/>Void or Review before void")]

Rules find the facts; the AI handles judgment. Detection and counts are deterministic code. The model explains, prioritizes, drafts messages, and reasons about cases the rules don't cover, such as time charged after a job's cutover date or an entry caught by two exceptions at once.

Tools

Governance built in

• No unapproved changes. Writes are limited to logs and pending proposals until a manager approves.

• Only the right approver. Only the employee's own manager can approve, and time dated in the future can't be approved.

• Source data is never edited. Corrections go to a separate file.

• The agent never changes ERP data. Work orders are only queued for the SAP team, and marked "Void" only when no other time remains on them; otherwise "Review before void", with the remaining charges listed.

• Everything is audited, and the AI client asks permission before each tool call.

Lessons from testing

• The model miscounted in an early summary ("10 exceptions" when its own tables showed 11). Fix: a summarize_exceptions tool, and server instructions to use its numbers.

• The agent caught a flaw in the rules. The first version flagged a parent work order for voiding while other technicians still had time on it. The agent's reasoning spotted this, and because it could only propose, the approval step stopped it before any harm. The rule now checks for remaining charges, both when proposing and again when applying.

Setup (Windows, PowerShell)

Requires Python 3.10+.

cd field-time-agent
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Try it

1. Run the end-to-end test: python test_client.py

2. Connect an AI client. In the Claude desktop app, open Settings → Desktop app → Extensions → Edit config, and add (with your own paths):

   "mcpServers": {
     "field-time-exceptions": {
       "command": "C:/path/to/field-time-agent/.venv/Scripts/python.exe",
       "args": ["C:/path/to/field-time-agent/server.py"]
     }
   }

   Restart the app, then ask: "Summarize this week's field time exceptions by type and manager, then propose corrections for the Opex-to-Capex ones."

3. Approve as a manager: python approve.py lists pending proposals; python approve.py PR0001 approve M203 approves one.

4. Explore the tools in a browser (needs Node.js): npx @modelcontextprotocol/inspector python server.py

To reset, delete the generated files in data/: exception_log.json, proposals.json, outbox.json, audit_log.json, time_entries_corrected.csv, work_orders_to_void.json.

What's here

Roadmap

• Move the model to SAP Generative AI Hub (SAP AI Core) and ground it on shift rules and SOPs.

• Build the agent in SAP Joule Studio, calling the same tools.

• Replace CSV files with S/4HANA and SuccessFactors APIs through SAP Integration Suite.

• Cutover-date rule: move all time after a job turns capital, not just the same day's.

Change log

• v2 (Nov 2026): safer void rule, re-checked at apply time; summarize_exceptions and get_audit_trail tools; approval blocked for future-dated time; expanded test.

• v1 (Nov 2026): 9 tools; rules for overlaps, prep/clean-up windows and Opex-to-Capex; manager approval and audit log.

License

MIT. Built by Bipin Premachandran.