WFDASH-WEBAPP/docs/api-mcp-layer.md

# API + MCP Layer

## Environment
Add to `.env.local`:

```bash
NEXT_PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090
PB_ADMIN_EMAIL=your_admin_email
PB_ADMIN_PASSWORD=your_admin_password
AGENT_API_KEY=replace_with_secure_token
ORDER_ITEMS_COLLECTION=order_items
```

## REST Endpoints
- `GET /api/v1/health`
- `GET /api/v1/orders?page=1&perPage=50&status=new`
- `POST /api/v1/orders/from-quote`
- `GET /api/v1/collection-pool?page=1&perPage=50&status=queued`
- `PATCH /api/v1/order-items/{id}/status`
- `GET /api/v1/quotes/next-number` — atomic `Q-YYYY-MM-NNN` counter via the `quote_counters` collection. Used by the quote form and the inbound email pipeline.

Auth for agent routes:
- Header: `Authorization: Bearer <AGENT_API_KEY>`

`POST /orders/from-quote` body:
```json
{ "quote_id": "QUOTE_RECORD_ID" }
```

`PATCH /order-items/{id}/status` body supports:
```json
{
  "item_status": "processed",
  "drv_status": "assigned",
  "notes": "Assigned to route 2"
}
```

## MCP Endpoint
- `POST /api/mcp`

Supported methods:
- `tools/list`
- `tools/call`

Available tools:
- `orders.list`
- `orders.create_from_quote`
- `collection_pool.list`
- `order_items.update_status`
- `quotes.create_from_email` — create a new quote (with customer/company/items) from a parsed email payload. Idempotent on `message_id`. **Attachments are no longer uploaded inline in this call** — the legacy `attachments` field in the payload is accepted but ignored. After the create call returns the new quote id, call `attachments.upload_for_quote` once per file. This split exists because embedding base64 attachments in the create POST would blow past the Next.js 1 MB request body limit on a 5 MB PDF.
- `attachments.upload_for_quote` — upload a single attachment (PDF, image, Word, Excel, CSV, plain text, or any binary up to 25 MB) to an existing quote. One call per file. Errors are surfaced per-attachment so a single bad file does not roll back the quote.
- `quotes.append_reply` — append a structured reply to an existing quote. Matches by `In-Reply-To` header first, then `Q-YYYY-MM-NNN` in the subject.
- `quotes.find_by_message_id` — look up a quote by the inbound email's RFC 5322 `Message-ID` header.

The `quotes.*` tools are the inbound side of the [Quote Email Monitor](quotes-email-monitor.md) n8n workflow. They are the only path new quotes and replies should be created through. The `orders.*` and `order_items.*` tools are likewise the only path for the orders side.

## Notes
- `ORDER_ITEMS_COLLECTION` controls where order-item writes/updates go.
- Set `ORDER_ITEMS_COLLECTION=order_items` once new collection is created/imported.
- Status endpoint accepts `driver_status` input and normalizes to `drv_status`.
- `quotes.create_from_email` **must** receive a `message_id` for idempotency — duplicate sends of the same email return the existing record with `deduped: true`.
- `quotes.append_reply` returns `matched_by: 'in_reply_to' | 'subject' | 'none'`. The `'none'` case is the workflow's signal to move the email to `INBOX.Quotes-Unmatched` and not create a reply row.