Stockroom Copilot

Inspiration

I've worked in an Amazon warehouse and done supply chain analytics at Advance Auto, and one problem kept showing up: stockouts. Large companies have planning teams and ERP systems to prevent them. A small hardware shop usually has a spreadsheet and gut feeling. Most of the tools I've seen show days of stock remaining, but that number alone misleads. Five days of stock is fine if the supplier delivers in two days and a crisis if they need seven. I wanted to build the analyst a small shop can't afford.

What it does

Stockroom Copilot is an AI stockroom manager for small hardware and building-supply businesses. The owner asks questions in plain English, such as "What will stock out before my suppliers can deliver?" The copilot answers from live inventory data, then drafts purchase orders. Every order waits for human approval, and the agent has no way to approve its own work.

The core idea is lead-time-aware risk:

$$\text{days of cover} = \frac{\text{units on hand}}{\text{average daily sales}}$$

An item is critical when its days of cover is less than its supplier's lead time, because it will run out before a new order could arrive.

How I built it

• MCP server (FastMCP): a self-hosted server that exposes the inventory tools: check_inventory_levels, get_supplier_info, predict_stockout, trigger_reorder, and list_purchase_orders.
• Agent (Gemini with function calling): it reaches the data only through those tools and shows each call in the chat.
• Backend: FastAPI with a SQLite database of 500 SKUs, suppliers, and sales history.
• Interface (Streamlit): a simulated Alexa+ style screen with a live dashboard (stockout runway, inventory health, replenishment manifest) next to the chat panel and an activity log of every tool call.
• Guardrails: input checks, a cap on order quantities, duplicate-order protection, and a rule that all drafted orders stay pending_review until a person approves them.

Challenges

• Believable data. My first generated data had over half the catalog marked critical, which made every alert meaningless. I reshaped the data so only a small share of SKUs are truly at risk.
• Making the agent reliable. A model choosing the wrong tool gives an answer that sounds right but isn't. I learned to treat tool descriptions as instructions and to put safety in the tools themselves, not only in the prompt.
• A custom look in Streamlit. Matching a polished dashboard design took custom CSS and careful layout.
• Staying on free tiers. Every tool and service in the project is free to use.

What I learned

MCP makes agents far easier to trust, because the model can only do what the tools allow. I also learned that the best AI features sit inside a human workflow: the agent drafts, the person decides.

What's next for Stockroom Copilot

Real voice input and output, receiving goods and updating stock, multiple suppliers per item, and a hosted database for small shops to run it themselves.

Built With

• fastapi
• fastmcp
• gemini-api
• github
• google-genai
• model-context-protocol
• python
• sqlite
• streamlit