David/WFDASH-WEBAPP
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
WFDASH-WEBAPP/docs/api-mcp-layer.md

3.1 KiB
Raw Blame History

API + MCP Layer

Environment

Add to .env.local:

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:

{ "quote_id": "QUOTE_RECORD_ID" }

PATCH /order-items/{id}/status body supports:

{
  "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 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.