# 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:

| Exception | Example | Default fix |
|---|---|---|
| **Overlap** | Two work orders both charged 11:30–12:30 | Split the overlap equally |
| **Prep / clean-up window** | Work-order time charged inside the blocked 08:00–08:30 prep or 15:30–16:00 clean-up window | Trim to the window edge |
| **Opex → Capex** | A maintenance (Opex) job becomes capital (Capex) work mid-day | Move the time to the Capex work order; queue the Opex work order for the SAP team to void, or to review if other time still charges to it |

## Architecture

```mermaid
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

| Tool | Type |
|---|---|
| `get_shift_rules`, `get_employee`, `get_work_order`, `get_time_entries` | Read |
| `detect_exceptions` | Read: runs the rules, returns each exception with a default fix |
| `summarize_exceptions` | Read: exact counts by type and manager, so summaries never rely on the model's arithmetic |
| `get_audit_trail` | Read: everything that happened to a proposal or exception |
| `flag_exception` | Write: exception log only |
| `notify_manager` | Write: outbox only |
| `propose_correction` | Write: creates a pending proposal; changes no time data |
| `apply_approved_correction` | Write: works only after the employee's manager approves |

## 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+.

```powershell
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):

   ```json
   "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

| File | Purpose |
|---|---|
| `server.py` | The MCP server and its 11 tools |
| `rules.py` | Detection rules, default corrections and counts |
| `approve.py` | Manager approval, the human-in-the-loop step, outside the agent |
| `test_client.py` | End-to-end test acting as an MCP client |
| `generate_data.py` | Recreates the synthetic data (20 technicians, 144 entries, 11 planted exceptions) |
| `data/` | Employees, work orders, time entries, shift rules, and the answer key |

## 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.