Assistant

Ask questions about your data in Claude, and build draft purchase orders from a confirmed replenishment order.

The assistant is a set of tools that Claude can use on your behalf. You connect Claude to the National Commerce server once, then talk to it in plain language. Claude picks the right tool, runs it against your data, and answers.

The assistant runs in the apps/mcp app as a Model Context Protocol (MCP) server. It is separate from the portal screens, but it reads and writes the same database.

Connect Claude

Add the server as a custom connector in Claude (desktop or claude.ai) using the server's /api/mcp URL. Claude sends you through the portal login, and from then on every tool runs as you: you only see the accounts you have access to.

What you can ask

Every tool except the two purchase-order tools only reads data.

Tool	What it answers
`list_brands`	Which accounts you can see.
`get_order_summary`	Revenue, orders, and units shipped for a date range.
`get_low_stock_items`	Inventory that needs restocking, by warehouse.
`get_top_skus`	The best-selling SKUs for a date range.
`get_warehouse_stats`	Units shipped per warehouse.
`get_shipping_costs`	Shipping spend for a date range.
`get_daily_trend`	Units shipped per day.
`preview_draft_purchase_orders`	What draft POs a confirmed order would become. Reads only.
`commit_draft_purchase_orders`	Creates or updates those draft POs in the portal. Writes.

Build draft POs from a confirmed order

Every replenishment cycle the client sends back a confirmed order after their cuts. Instead of keying it into the portal line by line, hand it to the assistant and let it build the drafts for you.

How it works

Paste the confirmed sheet into Claude and ask it to build the draft POs for the account. Claude reads the sheet, whatever shape it is in, and turns it into rows of warehouse, SKU, and quantity. The tool never parses the file itself.
Claude previews the result. It calls the preview tool, which groups the rows one per warehouse, matches each SKU to an existing Base SKU or Case SKU by exact code, and resolves the vendor from the account. Nothing is written yet.
Check the preview. Claude shows you each warehouse group with its vendor, lines, and quantities, plus every row it could not match and why. Give it the correct SKU or warehouse for any flagged row.
Confirm. Only after you say so does Claude call the commit tool. It creates one draft PO per warehouse with the matched lines. Rows that are still unmatched come back again in the reply; they are never dropped silently.
Re-run to fold in fixes. If you resolve a flagged line afterwards, ask Claude to run it again. It passes the draft IDs from the first run, so the line is added to the existing draft and no duplicate PO is created.
Review and submit in the portal. The drafts appear in the Purchase Orders list like any other draft. Open each one, check it, and click Submit to ShipHero yourself.

The assistant never pushes to ShipHero

Its job ends when the drafts exist. Submitting stays a button you click in the portal, so the human check stays in the loop.

Matching rules

Account comes from the name you give; use list_brands for the exact names.
Warehouse matches by name against the warehouses linked to that account.
SKU matches by exact code, ignoring only letter case and surrounding spaces. Base SKU codes are tried first, then Case SKU codes. There is no fuzzy matching: a partial code comes back as unmatched.
Vendor is the account's vendor. If the account has more than one, the preview lists them and Claude asks which to use.
Quantity must be a positive whole number. Two rows for the same warehouse and SKU are merged into one line.
Price is always 0, the same as a draft built by hand.

What it writes

The drafts use the same records as the manual create form, so the PO list, the edit screen, and Submit to ShipHero all work on them unchanged:

One row in Inventory Replen Draft Purchase Orders per warehouse, named PO-<timestamp>, status Draft, vendor stored as the ShipHero vendor ID.
One row in the draft line items table per matched line, pointing at either the Base SKU or the Case SKU.

On a re-run against existing drafts, a SKU already on the draft has its quantity updated, a new SKU is added, and lines you removed from the sheet are left alone. A draft that has already been sent to ShipHero, or belongs to another account or warehouse, is refused and reported.

Write access

Every tool was read-only until the commit tool. Writes are switched on by one server setting: MCP_WRITE_ENABLED=true in the environment of the MCP deployment. Without it, the commit tool refuses and writes nothing. The preview tool always works.

Who can write is decided the same way as who can read: you only ever see, and write to, the accounts you are assigned to in the portal.

Test it by hand

Use this checklist after a deploy, or whenever the tool instructions change.

Connect Claude to the server. Confirm list_brands returns your accounts.
With MCP_WRITE_ENABLED off, paste a confirmed order that spans two warehouses and includes one SKU that does not exist. Ask Claude to build the drafts. It should show a preview with two groups and one flagged line, and the Purchase Orders list should show no new draft.
Ask Claude to commit anyway. It should refuse with a write-access message.
Turn MCP_WRITE_ENABLED on, redeploy, and repeat the request. Confirm the preview. Two drafts should appear in the Purchase Orders list with the right lines and quantities, and the flagged line should be listed in the reply.
Give Claude the correct SKU and ask it to re-run. The line should land on the existing draft for its warehouse. There should still be exactly two drafts.
Open each draft and check it against the sheet. Delete the test drafts from the list when you are done. Do not submit test drafts to ShipHero; a pushed PO is a real order and adds inbound quantity.

On this page