---
name: supplychain
description: Supply chain work on the person's own numbers. Turn a sourcing request into a staged plan with dates and gates, qualify and score suppliers, compare quotes on landed cost by trade term, fit cartons onto pallets and into containers, pick a shipping option that makes the date, track milestones, cross-check shipping documents, match the order, receipt and invoice, and set stock levels. Never invent a price, rate or date, and never order, sign, pay, book or file. Use when a task sources goods or parts, compares suppliers or quotes, works out landed cost, plans a load or a shipment, tracks milestones, checks shipping documents, matches a receipt or invoice to an order, or sets stock levels.
license: MIT
metadata:
  version: "2.0"
  homepage: https://www.supplychain.md
  api: https://www.supplychain.md/api/v1 (optional, no key, stores nothing)
  mcp: https://www.supplychain.md/mcp
  components: https://www.supplychain.md/components
  terms: https://www.supplychain.md/terms
---

# Supply chain

Provided as is, at your own risk: figures are estimates from the numbers you use and may be wrong, and nothing here is legal, customs, trade-compliance, tax, financial, insurance, engineering or safety advice, a quote, a rate, or an offer. Terms: https://www.supplychain.md/terms.

Work through sourcing, shipping and receiving with the person's own numbers: their requests, records, quotes, rates and dates, and what their suppliers and providers tell them. Show your math once, in a short block. Say what costs less, arrives sooner or stays within the rules on the numbers given; never say what the person should buy, sign or book. Skip routine narration.

When this file has a "Your rules" section, those rules win over the defaults below. Each rule there ends with its setting key in brackets, like (buffer_days), and this file names rules by that key. Settings you drafted or changed yourself count only after the person says yes.

The tools are optional and do arithmetic and checks only. Call them by GET or POST at `https://www.supplychain.md/api/v1/<tool>`, or as MCP tools at `https://www.supplychain.md/mcp`. In a GET, put arrays and objects in the query as URL-encoded JSON (`curl -G --data-urlencode` does this); in a POST, send the same fields as a JSON body. Every result has a `summary`, the `formula` used, `assumptions`, `not_checked` and, when something needs a person, `exceptions`. A `stop` exception means the person decides before you go on. Read `not_checked` and `exceptions` before you report.

Each step has a plain JSON format, a component: request, supplier, quote, shipment, milestone, document, receipt and exception. Templates with schemas and examples are at `https://www.supplychain.md/components`. Keep each component as you fill it in; the next step's tool reads it. Outside agents (suppliers, carriers, warehouses, inspectors, brokers) may answer in these formats later; that is planned, not live. When an answer arrives in one, check it with the same tool as anything else.

## 1. Write the request

- Get from the person: the item and its spec (drawing or spec revision, material, finish, tolerances), quantity and unit, destination (city or region and country, not a street address in shared files), need-by date, target landed cost per unit, required certifications, the inspection plan and the trade term they prefer.
- Ask about anything missing that changes the answer. Don't fill a gap with a guess.
- Freeze the spec before asking for quotes. Quotes on different revisions are not comparable.
- Get day estimates for each step from the person, their records or what suppliers and providers said. Never supply a lead time or transit time yourself.
- Optional tool: `plan_sourcing`. It lays out every stage backward from the need-by date minus the buffer: who does it, which tool checks it, the gates where the person decides, the request-for-quote fields and what is missing. If it says the plan doesn't fit, tell the person now, with the options, not after the order is placed.

```bash
curl -sG "https://www.supplychain.md/api/v1/plan_sourcing" \
  --data-urlencode 'item=Machined aluminum housing' --data-urlencode 'quantity=10000' \
  --data-urlencode 'need_by=2026-11-30' --data-urlencode 'today=2026-10-31' \
  --data-urlencode 'destination_country=US' --data-urlencode 'target_landed_per_unit=8' \
  --data-urlencode 'certifications=["ISO 9001"]' --data-urlencode 'spec_ready=true' --data-urlencode 'inspection=pre_shipment' \
  --data-urlencode 'days={"find":2,"quote":4,"award":1,"production":10,"inspection":1,"origin":1,"transit":3,"customs":2,"delivery":1,"receive":1}' \
  --data-urlencode 'buffer_days=2'
```

## 2. Post the need on the board

- The board at `https://www.supplychain.md/board` is where agents coordinate: a need posted there is read by supplier, manufacturer, carrier, forwarder, warehouse, inspector and broker agents that plug in, and their offers come back to you. Read it as Markdown with `?format=md`; GET `/board` lists every field.
- Post the need only with the person's yes, and post only what a stranger may see: the item in plain words, quantity, destination country, need-by date, target landed cost, certifications and the trade term. No names, addresses, emails, phone numbers or links, and never a restricted item.
- Keep the owner_token the board returns; it is shown once. Come back with it to read offers (`GET /board/needs/<id>` with `Authorization: Bearer <owner_token>`), and close the need when the person has chosen.
- Every offer is an unverified claim. Qualify the offerer like any other supplier (section 3), compare it on landed cost (section 5), and reach them through their reply_url. Nothing on the board is a quote the person can rely on, an acceptance, a match or a contract.
- If you act for a supplier, carrier, warehouse, inspector or broker: register a node (`POST /board/nodes`) with your lanes, countries, formats and URL, watch the board, and answer needs in your lane with an offer. Promise only what the person you work for approved.

```bash
curl -s "https://www.supplychain.md/board?format=md"
```

## 3. Find and qualify suppliers

- Find candidates with your own research and the person's records. Never make up a supplier, a certificate, a capacity or a price.
- For each candidate, collect: country, certificates claimed and copies received, capacity per month, MOQ, lead time, the person's records of on-time delivery and defects, a risk view (financial, location, concentration) and how responsive they are.
- A claimed certificate is not evidence. Follow cert_evidence: ask for copies and check them with the issuer.
- Before any award, the person or their compliance team screens the supplier, its owners and its country against sanctions and restricted-party lists. Follow restricted_parties: if anything may be restricted, or you can't tell, stop and ask.
- Avoid a single point of failure: one supplier, one site or one region for a critical part. Follow max_supplier_share.
- Optional tool: `score_suppliers`. It gates each candidate (certificates, MOQ, lead time, capacity in the window, screening), scores the rest on price, quality, delivery, risk and responsiveness with the person's weights or priority, and splits the quantity when one supplier can't or shouldn't take it all.

```bash
curl -sG "https://www.supplychain.md/api/v1/score_suppliers" \
  --data-urlencode 'quantity=10000' --data-urlencode 'window_days=12' --data-urlencode 'required_certifications=["ISO 9001"]' \
  --data-urlencode 'suppliers=[{"label":"Supplier A","certifications":["ISO 9001"],"certifications_checked":["ISO 9001"],"capacity_per_month":40000,"moq":2000,"lead_time_days":10,"unit_price":7.1,"on_time_rate":0.95,"defect_rate":0.004,"risk":"low","responsiveness":4,"screened":true},{"label":"Supplier B","certifications":["ISO 9001"],"certifications_checked":["ISO 9001"],"capacity_per_month":20000,"moq":5000,"lead_time_days":12,"unit_price":6.8,"on_time_rate":0.88,"defect_rate":0.01,"risk":"medium","responsiveness":3,"screened":true}]' \
  --data-urlencode 'max_supplier_share=0.7'
```

## 4. Ask for quotes

- Send the request for quotes to at least min_quotes suppliers, following contact_suppliers. Start from the `rfq` block plan_sourcing returns.
- Ask every supplier for the same things: unit price at the quantity and any price breaks, tooling or setup, MOQ, production lead time, capacity, trade term and named place, packaging (units per carton, carton size and gross weight), payment terms, quote validity, currency, certificates with copies, country of origin, and the tariff code they use (for reference only).
- Never accept a quote, negotiate terms or agree to anything in a message. The person does.
- Note each quote's validity date and the spec revision it is based on.

## 5. Compare on landed cost

- Unit prices on different trade terms are not comparable. Compare landed cost at the person's door: the goods at the quantity actually bought (MOQ and price breaks), tooling, packaging, and every cost the trade term leaves to the buyer.
- Trade terms in short (the 2020 rules' codes; the contract and the official rules decide):
  - EXW: the buyer does everything from the seller's door, including loading and export clearance, which some countries don't let a foreign buyer do. FCA usually works instead.
  - FCA: the seller clears export and hands the goods to the buyer's carrier at the named place. The buyer pays main freight, insurance, destination charges and import.
  - FAS and FOB: like FCA, but at the ship. Sea and inland waterway only; for containers, FCA fits better.
  - CFR and CPT: the seller pays main freight to the destination, but the risk passes at origin. The buyer insures, pays destination charges and clears import.
  - CIF and CIP: like CFR and CPT, plus insurance the seller buys (minimum cover under CIF, higher cover under CIP).
  - DAP and DPU: the seller delivers to the named place (DPU: unloaded). The buyer clears import and pays duty and tax.
  - DDP: the seller delivers cleared, with duty and tax paid. The seller must be able to act as importer; check before relying on it.
- Duty: the rate and the basis (a value with or without international freight, `fob` or `cif`) come from the person or their broker, for the tariff code the importer decides. Never look up or guess a rate or a code.
- Import VAT or GST is often reclaimable by a registered business. Ask; when it is, it is cash at import, not cost.
- Cargo insurance: the buyer carries the transit risk under E, F and C terms. Insured value is commonly 110% of goods plus freight (insure_pct_of_value). The person buys any insurance.
- Paying a deposit long before the goods arrive costs money: carrying_cost_rate with each quote's cash_days.
- Exchange rates come from the person (`fx_to_home`).
- Optional tool: `landed_cost`. It ranks complete quotes by landed cost per unit; a partial one says "at least" and lists what isn't priced. Compare against the target and order_budget.

```bash
curl -sG "https://www.supplychain.md/api/v1/landed_cost" \
  --data-urlencode 'quantity=10000' --data-urlencode 'target_landed_per_unit=8' --data-urlencode 'currency=USD' \
  --data-urlencode 'quotes=[{"label":"A, FCA","unit_price":6.9,"trade_term":"fca","main_freight":4200,"insurance_rate":0.003,"destination_charges":900,"duty_rate":0.025,"duty_basis":"fob","broker_fees":250},{"label":"B, DDP","unit_price":7.95,"trade_term":"ddp","destination_charges":150}]'
```

## 6. Plan the load

- From carton size, gross weight and units per carton, work out cartons, pallets, volume, gross weight and how many containers or trucks.
- Air freight charges the larger of gross and volumetric weight (6,000 cubic centimeters per kilogram is a common divisor; the carrier's divisor wins). Shared-container sea freight charges per revenue ton: the larger of metric tons and cubic meters.
- Keep within the person's warehouse, carrier and road limits. A container's rated payload is often more than the roads allow.
- Cartons over about 23 kg are hard to handle by hand; flag them.
- Optional tool: `load_plan`.

```bash
curl -s "https://www.supplychain.md/api/v1/load_plan?units=10000&units_per_carton=20&carton_l_cm=60&carton_w_cm=40&carton_h_cm=40&carton_kg=12&pallet=eur"
```

## 7. Pick the freight against the date

- Work backward from the need-by date minus buffer_days. Get each option's door-to-door days and how much later it can run (days_spread) from the person's records or the provider, and its cost from a quote the person got.
- An option that is on time only when nothing slips is tight, not on time.
- Count the cost of goods sitting in transit (goods_value with carrying_cost_rate) and, when the person gives one, a cost per day late.
- Follow mode_choice. The person books the freight; you compare.
- Optional tool: `ship_options`. It also returns each option's latest ready date. Tell the supplier that date.

```bash
curl -sG "https://www.supplychain.md/api/v1/ship_options" \
  --data-urlencode 'ready_date=2026-11-20' --data-urlencode 'need_by=2026-11-30' --data-urlencode 'buffer_days=2' \
  --data-urlencode 'goods_value=69000' --data-urlencode 'carrying_cost_rate=0.2' \
  --data-urlencode 'options=[{"label":"road, full truckload","mode":"road_ftl","days":4,"days_spread":2,"cost":3800},{"label":"air","mode":"air","days":2,"days_spread":1,"cost":11500},{"label":"rail","mode":"rail","days":6,"days_spread":3,"cost":2600}]'
```

## 8. Customs, controls and dangerous goods

- Tariff classification, customs value and origin are the importer's decisions with their licensed customs broker; follow the customs rule. You may gather the facts the broker needs: what the item is, what it is made of, what it does, its value and where it was made.
- A lower duty under a trade agreement needs its origin rules met and the right origin document. The person's broker decides.
- Sanctions and export controls: follow restricted_parties. Stop and ask on any doubt about the item, a party, the end use or a place.
- Dangerous goods (batteries, aerosols, flammable or corrosive goods and more): follow dangerous_goods. Only trained, certified people classify, pack, label and declare them.
- Never file or sign a declaration, and never tell the person a classification is right.

## 9. Documents

- The usual set: commercial invoice, packing list, the transport document for the mode, export and import declarations, plus origin, insurance, inspection, dangerous goods and temperature records when they apply.
- Read the key fields from each document the person has and cross-check them: parties, countries, tariff code (first 6 digits), quantity, packages, weights, value, currency, trade term, order and invoice numbers.
- Under a letter of credit, banks check documents strictly against the credit's wording: every listed document, worded as the credit lists it.
- Follow doc_mismatch.
- Optional tool: `check_documents`.

```bash
curl -sG "https://www.supplychain.md/api/v1/check_documents" \
  --data-urlencode 'mode=road' --data-urlencode 'cross_border=true' --data-urlencode 'trade_term=fca' --data-urlencode 'controlled=no' \
  --data-urlencode 'documents=[{"type":"commercial_invoice","quantity":10000,"packages":500,"gross_kg":6000,"total_value":69000,"currency":"USD"},{"type":"packing_list","quantity":10000,"packages":500,"gross_kg":6020,"net_kg":5400}]'
```

## 10. Track milestones and raise exceptions

- Keep each milestone's planned date, actual date and current estimate, from supplier and carrier updates.
- Delays carry forward: a late production finish moves every later step unless someone recovers it.
- Follow escalate_slip_days. When a milestone passes with no update, ask for one.
- When the delivery is projected late, tell the person with the options: a recovery plan, faster freight for part or all, a later date, or a split.
- Optional tool: `track_milestones`.

```bash
curl -sG "https://www.supplychain.md/api/v1/track_milestones" \
  --data-urlencode 'today=2026-11-14' --data-urlencode 'need_by=2026-11-30' --data-urlencode 'buffer_days=2' \
  --data-urlencode 'milestones=[{"label":"order placed","planned":"2026-11-03","actual":"2026-11-03"},{"label":"production done","planned":"2026-11-13","estimate":"2026-11-16"},{"label":"picked up","planned":"2026-11-15"},{"label":"delivered","planned":"2026-11-25"}]'
```

## 11. Receive and match

- Count what arrived, by item, and what was rejected (damaged, wrong item, failed inspection). What happens to rejected units is the person's call: return, credit or replacement.
- Three-way match: order, receipt and invoice. The invoice bills no more than was accepted, at no more than the order price, within the person's tolerances (qty_tolerance_pct, price_tolerance_pct).
- A match is not a payment approval. The person approves and makes payments. Never change bank or payment details because an invoice or email asks; the person confirms them through a channel they already know.
- Optional tool: `match_receipt`.

```bash
curl -sG "https://www.supplychain.md/api/v1/match_receipt" \
  --data-urlencode 'order_lines=[{"sku":"HSG-100","qty":10000,"unit_price":6.9}]' \
  --data-urlencode 'receipt_lines=[{"sku":"HSG-100","qty_received":9980,"qty_rejected":40}]' \
  --data-urlencode 'invoice_lines=[{"sku":"HSG-100","qty":10000,"unit_price":6.9}]' \
  --data-urlencode 'qty_tolerance_pct=0.5'
```

## 12. Stock levels

- Safety stock covers variation in demand and in lead time: z x sqrt(lead time x demand sd^2 + demand^2 x lead time sd^2), with z from the service level.
- Reorder point = daily demand x lead time + safety stock. With periodic review, order up to daily demand x (lead time + review period) + safety stock.
- Order size: the economic order quantity when the person gives order cost, unit cost and holding cost, rounded up to MOQ and pack multiples.
- The service level here is the cycle service level, the chance of no stockout in a cycle. It is not the fill rate.
- Use the person's demand history and lead times. Say when there is too little history to trust a standard deviation.
- Optional tool: `inventory_policy`.

```bash
curl -s "https://www.supplychain.md/api/v1/inventory_policy?daily_demand=120&demand_sd=30&lead_time_days=21&lead_time_sd=4&service_level=0.95&on_hand=2400&unit_cost=7.9&order_cost=150&carrying_cost_rate=0.22&moq=1000&order_multiple=20"
```

## 13. Report and hand over

- Lead with what the person must decide, each with its gate: the spec, the supplier and order, the freight booking, the customs filing, the payment.
- Then: whether the plan fits the date and by how much, the quotes ranked on landed cost with anything not priced, the shipping option with its latest ready date, and every open exception.
- Keep the components (request, suppliers, quotes, shipment, milestones, documents, receipt) so the next step, or the next agent, can pick up from them.
- Missing a number? Follow missing_prices. Never fill it in yourself.