WFDASH-WEBAPP/src/app/api/mcp/FEATURE-REQUESTS.md

# MCP Feature Requests & Gaps

Captures requests the existing WFDASH MCP tools can't fulfil, surfaced from real
questions asked by agent operators / the agent itself. Each entry should be
small enough to ship in a single PR.

When one ships, move it to **Implemented** with a one-line commit/PR reference.

## Entry template

```
### [SHORT TITLE]
- **Surfaced:** YYYY-MM-DD — <quoted or paraphrased user question>
- **Workaround:** <what we did in the meantime to answer the question>
- **Severity:** now | nice-to-have
- **Suggested tool:** <name + signature, e.g. `orders.stats({from, to})`>
- **Schema needs:** <PB field additions / changes, or "none">
- **Open questions:** <anything to clarify with ops before implementing>
```

## Open requests

### Orders: filter by customer
- **Surfaced:** 2026-08-06 — "last 3 orders for Seth"
- **Workaround:** filter `order_items` by `order.customer = "<id>"`, dedupe to distinct orders
- **Severity:** now — every "orders for customer X" question hits this
- **Suggested tool:** add `customer` (id or name) + `from`/`to` filters to `orders.list`
- **Schema needs:** none

### Orders: date-range filter on `orders.list`
- **Surfaced:** 2026-08-06 — "how many orders were placed yesterday"
- **Workaround:** fall back to `order_items.list` with `created` filter, dedupe to distinct orders
- **Severity:** now — every "yesterday / last week / this month" question hits this
- **Suggested tool:** add `filter` (PB syntax) + `createdAfter` / `createdBefore` to `orders.list`
- **Schema needs:** none

### Orders: aggregate money value (count + selling total + cost total)
- **Surfaced:** 2026-08-06 — "...give me the money value aswell"
- **Workaround:** sum `selling_price × quantity` across items client-side
- **Severity:** now — every count question also wants a value
- **Suggested tool:** `orders.stats({from, to, groupBy?: 'day'|'customer'|'supplier'})` returning `{count, totalSell, totalCost}`
- **Schema needs:** none

### Order items: clarify "received" — no unambiguous field
- **Surfaced:** 2026-08-06 — "how many orders were received yesterday"
- **Workaround:** filtered by `qty_collected > 0 && updated` on target date — proxy, not exact
- **Severity:** now — user had to disambiguate ("received" can mean received-from-supplier, collected-from-warehouse, or delivered-to-customer)
- **Open questions:** ops must decide which definition to standardise on; current candidates are `drv_collected_at` (12 items/d yesterday) and `delivered_at` (0 items/d yesterday)
- **Suggested tool:** once defined, add a `received_at` filter param to `order_items.list` and a `orders.received_between` helper
- **Schema needs:** *probably* none if we pick an existing field; might need a new `received_at` if the chosen definition isn't already captured

### Order items: detect items missing `selling_price`
- **Surfaced:** 2026-08-06 — 4 of 42 items placed yesterday had `selling_price = 0` (still unpriced at end of day)
- **Workaround:** filter `selling_price = 0 && created > X` and report
- **Severity:** nice-to-have — these are unpriced orders that shouldn't ship without review
- **Suggested tool:** `orders.unpriced_items({from, to, minAgeHours?: number})` returning `{orderId, itemId, description, createdAt, hoursUnpriced}`
- **Schema needs:** none

### Dashboard: single-call daily summary
- **Surfaced:** 2026-08-06 — combining counts + values across multiple tools to answer one question
- **Workaround:** 3–4 separate tool calls + client-side aggregation
- **Severity:** nice-to-have
- **Suggested tool:** `dashboard.daily_summary({date, includeReceived: bool})` returning a single payload with placed + received counts and totals
- **Schema needs:** none

### Order items: whitelist missing `sku` field
- **Surfaced:** 2026-08-06 — "the items on PO-2026-08-006 add this sku for each item and save it" — every patch with `sku` rejected
- **Workaround:** none — `sku` is a real PB field on `order_items`, but the route.ts whitelist (`ORDER_ITEM_PATCH_FIELDS`) omitted it. Locally fixed by adding `"sku"` to the array at `route.ts:145`; still pending deploy on `wfdash.apphub.co.za`
- **Severity:** now — every supplier PO needs SKUs and the agent can't set them
- **Suggested tool:** no new tool — just keep the whitelist in sync with the real PB schema. Better long-term: derive whitelist from the live PB schema on each call (or at boot) instead of a hardcoded array, so schema drift never silently blocks writes
- **Schema needs:** none — PB field exists, the gap is MCP-only
- **Open questions:** should the patch tool also reject unknown keys silently (current behaviour is a hard 4xx — fine), or warn-and-accept? User seems happy with hard rejects for now.

### Orders: no create-from-scratch — only from a quote
- **Surfaced:** 2026-08-06 — "can you create a order or load items as a order using mcp?"
- **Workaround:** the only path is `quotes.*` → `orders.create_from_quote`. To create an order from scratch via MCP: (1) seed a quote via `quotes_create_from_email` or `quotes_create_from_template`, (2) add items with `quote_items_create` (or `bulk_update_quote_items`), (3) call `orders.create_from_quote`. There is NO `orders.create` and NO `order_items.create`.
- **Severity:** nice-to-have — the quote-pipe works, but it's 3+ calls and forces the user to materialise a quote just to load an order
- **Suggested tool:** `orders.create({customer, company, items: [{description, quantity, unit?, sku?, cost_price?, selling_price?}]})` returning the new order + items. (Pushes the same idea further: `order_items.create({order_id, ...})` if items need to be appended to an existing order.)
- **Schema needs:** none — every field already exists on `orders` / `order_items`
- **Open questions:** if we ship this, does `quotes.*` still matter as a destination, or do we collapse quote and order into "draft vs committed"? Currently the app forces the two-step dance; an opinionated answer here would also clean up the buyer flow.

### Quote/order items: whitelist missing `category` field
- **Surfaced:** 2026-08-06 — "can you see the category and ai insights? can you change the category"
- **Workaround:** reads work fine (`category` is returned on every item + `expand=category` exposes the name/match_keywords). Writes are blocked — same shape as the `sku` whitelist gap: `QUOTE_ITEM_PATCH_FIELDS` and `ORDER_ITEM_PATCH_FIELDS` in `route.ts` don't list `category`, so any patch with it is rejected with `forbidden_field`. Until that whitelist gap is closed + deployed, the only way to recategorize is via PB admin UI. Audit found 2 items needing change: KYOCERA TIPS (Fasteners → Cutting Tools) and Bulldog Disc (Unknown → Fasteners).
- **Severity:** now — recategorization is a real operator workflow and Hermes can't do it
- **Suggested tool:** no new tool — fold into the same `route.ts` whitelist expansion that fixes `sku` (and consider regenerating the whitelists from the live PB schema so this stops happening). Optional companion tool: `categories.classify({description})` running the master-list keyword logic in `route.ts` so the AI agent doesn't have to memorise the 10 categories.
- **Schema needs:** none
- **Open questions:** none — same pattern as the `sku` entry above.

### Stock purchases: no PDF → stock order ingestion
- **Surfaced:** 2026-08-06 — "can you load a stock order from a pdf that i give you or items"
- **Workaround:** `stock_purchases_create({supplier, items:[...]})` works for structured input but the operator has to type each line. No tool accepts a PDF or an email payload. Existing attachment uploads (`purchase_orders_add_attachment`, `quotes_list_attachments`) attach files *to existing records*; they don't parse them.
- **Severity:** nice-to-have
- **Suggested tool:** `stock_purchases.create_from_pdf({supplier, base64, content_type})` that parses supplier PO PDFs (using something like `pdf-parse` or `unpdf`) and emits a draft `stock_purchase` for review. Alternatively, `stock_purchases.create_from_email({from, subject, body, ...})` mirroring `quotes_create_from_email`.
- **Schema needs:** none — the `stock_purchase` + `stock_purchase_item` collections already exist
- **Open questions:** which PDF format(s) does the user want supported? Many SA suppliers send bespoke PO PDFs — a generic parser would need supplier-specific extraction rules. Probably needs an LLM-driven extraction step rather than layout heuristics. Worth scoping before implementation.

### Stock purchases: paperclip badge on list table
- **Surfaced:** 2026-08-06 — surfaced during the attachments-card PR (UI ships the detail-page affordance but the list table still shows no document indicator)
- **Severity:** nice-to-have
- **Suggested tool:** add a `count_additional_attachments` field to `stock_purchases.list` (or a separate `/api/v1/stock-purchases/attachment-counts` endpoint mirroring `/api/v1/sprint/attachment-counts`), render the sprint-style `<Paperclip>` chip in `StockOrdersTable` per row
- **Schema needs:** none — derived from `additional_attachments.length`

### Drivers: no MCP visibility or assignment
- **Surfaced:** 2026-08-06 — "can you see the driver stops and assign stops to drivers?"
- **Workaround:** "driver" data lives only as three fields on `order_items` (`drv_id`, `drv_assigned_at`, `drv_collected_at`). There is no separate `drivers` collection, no MCP tool to list drivers, no tool to see today's stops for one driver, no tool to bulk-assign stops to a driver. Operators can call `orders.list` and manually click through. Effectively the driver flow is invisible to the agent.
- **Severity:** now — driver dispatch is a daily workflow and currently bypasses the agent entirely
- **Suggested tool:** `drivers.list()` returning `{id, name, currentLoad, maxStops}`. `drivers.assign_stops({drv_id, order_item_ids:[...]})` to bulk-assign. `drivers.stops({drv_id, date})` returning today's route. If `drivers` isn't a real PB collection, the simplest first cut is virtual (read drivers off `users` or `suppliers` where they probably already exist) — but that needs ops to confirm the canonical source.
- **Schema needs:** possibly a new `drivers` collection if there isn't one already; otherwise a way to identify the driver relation (`drv_id` currently points to a freeform string, not a PB relation)
- **Open questions:** where is the canonical drivers list today? `users`? `suppliers`? a CSV? "Assign" semantics — operator workflow or agent-controlled?

### Suppliers: read/update works, geocoding does not
- **Surfaced:** 2026-08-06 — "can you access suppliers and geocode them update the lat and long if needed ? and the address ?"
- **Read:** ✅ `suppliers.list` / `suppliers.get` already return full records including `coordinates` (legacy "lat, lng" string) and `supplieraddress`
- **Update:** ✅ `suppliers.update({id, patch:{supplieraddress, coordinates, ...}})` patches those fields today
- **Geocode:** ❌ no MCP tool — there's no geocoding service exposed, so the agent can't *generate* the lat/lng from an address. Anyone wanting current coordinates has to call Google Maps / Nominatim externally and then patch the result via `suppliers.update`. `coordinates` is also still the legacy text "lat, lng" string on `suppliers` (it's pre-`geoPoint`) — even when the agent *has* lat/lng it has to know to format it as "lat,lng".
- **Severity:** now — the user clearly wants the round-trip (read missing coords → geocode → write back) automated, not hand-driven
- **Suggested tool:** `suppliers.geocode({id?, address?, limit?: 10})` calling a hosted geocoder (OpenStreetMap Nominatim is free and sufficient; Google would need a key). Returns `{lat, lng, formatted_address, confidence}` and optionally persists via `suppliers.update` if `id` is passed. Migrate `coordinates` to `geoPoint` while we're here so the round trip becomes a single field write.
- **Schema needs:** migrate `suppliers.coordinates` from text to PB `geoPoint` (delete the field, recreate it as lat/lng pair). Backfill existing rows from the parsed "lat,lng" strings first.

## Schema questions for ops

These came up but need a human answer before code changes:

- **"Received" semantics** — see `Order items: clarify "received"` above. Also, the `order_items_update` docstring references fields (`collection_date`, `collected_date`, `verified_date`, `delivered_date`) that don't exist in the current PB schema (only `drv_collected_at`, `delivered_at`, `assigned_at`, `drv_assigned_at` exist). Either the docstring is stale or those fields were planned and never created.
- **Currency notes** — prices are stored as numbers but the `notes` field on items embeds "R" (ZAR) strings. Confirm the system is single-currency ZAR before adding any multi-currency stats.

## Implemented

- 2026-08-06 — `stock_purchases.add_attachment` shipped (commits `f89bbb3`, `dd57d29`). Adds a sibling to `purchase_orders.additional_attachments` plus the matching REST upload/delete routes and a UI card on `/stock-orders/[id]`. PB schema: new `stock_purchases.additional_attachments` file field (multi, maxSelect 10, any MIME).
- 2026-08-07 — Split-invoice stock-PO workflow shipped. 5 new MCP tools (`stock_purchase_items.update`, `stock_purchase_items.bulk_update`, `stock_purchase_items.assign_driver`, `stock_purchase_items.mark_collected`, `stock_items.update`) and the underlying services (`stock-purchase-items-service.ts`, extended `stock-items-service.ts`). Closes the per-line write gap surfaced by the operator's split-delivery scenario (PO with multiple supplier invoices arriving on different days). `mark_collected` auto-flips the parent PO header to `received` when every line is fully collected. PB schema: new `stock_purchase_items.sku` / `unit` / `supplier_sku` text fields (migration `scripts/migrations/2026-08-07-stock-purchase-items-catalogue-fields.ts`, user applies via PB admin).
- 2026-08-09 — Buyer-side supplier-invoice reconciliation shipped. New MCP tool `stock_purchases.match_and_receive_from_invoice` (single commit, no schema change). The agent parses a scanned supplier invoice with its native vision, passes the structured fields (`po_reference`, `invoice.{document_no,date,supplier_name?,lines[]}`, optional `attachment` bytes) plus a `confirm` flag. Deterministic line-by-line matching: `stock_item.sku` exact → `stock_purchase_item.supplier_sku` exact → description token overlap (≥80%). Verdict enum (`ready_to_receive | po_not_found | wrong_status | supplier_mismatch | unmatched_po_lines | unmatched_invoice_lines | qty_mismatch | cost_mismatch`) drives the HTTP status (200/404/409/422). Dry-run by default; `confirm=true` only commits when `verdict === "ready_to_receive"` — on success it attaches the invoice image using the `supplier_invoice_<supplier-slug>_<invoice-no>_<YYYY-MM-DD>.<ext>` naming convention (PB appends its random token at write time, matching the operator's existing `supplier_invoice_afriq_ina64721_2026_08_06_…` format on PO26073109STK), then calls `stock_purchases.receive` in the same round-trip. Closes the "AI checks my invoices for the buyer" workflow surfaced 2026-08-09. Implementation: new `src/lib/server/stock-purchase-invoice-matching-service.ts` (+ matching `.test.ts`), wired into `src/app/api/mcp/route.ts` (one new tool entry + one dispatch block + 4 dispatch tests). 1,654/1,657 vitest tests pass; the 3 failing tests are pre-existing (PocketBase SDK mock mismatch in `pocketbase-admin.test.ts`, 5s timeout in `quotes/items/[id]/attachments/upload/route.test.ts` — both reproducible on `main` without this change).