Korral StoreLink MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Korral StoreLink MCP Server Check inventory and sales for store 47, SKU 8847291"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Korral StoreLink MCP Server
A standalone Model Context Protocol server, written in
TypeScript with the official @modelcontextprotocol/sdk,
that exposes the StoreLink backend of the Korral grocery chain to an AI agent.
It ships two collapsed, semantic tools designed for a stock-out / replenishment workflow:
Tool | Purpose |
| One call returns on-hand inventory and trailing-24h POS sales, plus a pre-computed |
| Fires a mock |
The transport is Stdio — the server reads JSON-RPC from stdin and writes to stdout, which is how MCP hosts (Claude Desktop, IDEs, agent runtimes) launch local servers.
Quick start
npm install
npm test # vitest — unit tests for the tool logic
npm run build # esbuild — bundles a single production file to dist/index.js
npm start # runs dist/index.js over stdioDuring development you can run the TypeScript source directly without building:
npm run dev # tsx src/index.tsWiring it into an MCP host
{
"mcpServers": {
"korral-storelink": {
"command": "node",
"args": ["E:/temp/duvo-mcp-assignment/dist/index.js"]
}
}
}Related MCP server: korral-mcp
Mock data
The mock backend (src/mockData.ts) tracks one SKU — 8847291, Madeta butter 250g — across two
stores, deliberately seeded to show contrasting demand gaps:
Store | On-hand | POS (last 24h) | Demand gap | Risk |
47 | 2 | 10 | 8 | high |
102 | 12 | 14 | 2 | moderate |
demand_gap = units_sold_last_24h - on_hand. Store 47 sold far more than it has on the shelf — a
clear restock candidate; Store 102 is keeping pace.
Architectural choices & tradeoffs
1. Collapsed, semantic tools over a 1:1 API mirror
In the real StoreLink API, inventory and POS sales live behind two separate endpoints. A naïve MCP server would expose them as two tools, forcing the agent to make two round-trips, hold both payloads in context, and do the subtraction itself.
Instead, get_store_inventory_and_sales collapses both endpoints into one payload and
pre-computes demand_gap and stockout_risk. The benefits for an agent:
Fewer tokens / less context churn — one tool result instead of two, with only the fields that matter for the decision.
Fewer round-trips — one tool call to assess a store/SKU instead of two-then-reason.
Less room for error — the server, not the model, does the arithmetic and risk bucketing.
Tradeoff: the tool is opinionated and less general-purpose than raw endpoints. A different
consumer that wanted only inventory now over-fetches POS data, and the stockout_risk thresholds
(gap >= 5 → high, >= 1 → moderate) are baked into the server rather than chosen by the caller.
For an agent-first tool surface this is the right trade — we optimize for the agent's context window
and decision quality, not for maximal API flexibility.
2. Action tool returns a confirmation, not a raw HTTP echo
create_replenishment_order models a side-effecting POST. It returns a small, structured
confirmation (order_id, status: "submitted", echoed inputs) rather than a verbose HTTP response,
so the agent gets just enough to confirm success and report back.
3. Schema validation with Zod
Tool inputs are validated with Zod schemas registered through the SDK. Each field carries a
.describe() string that the SDK surfaces in the JSON Schema sent to the model — so the agent learns
what store_id, sku, and quantity mean. quantity is constrained to a positive integer both
in the schema and defensively in the handler.
4. Pure functions + thin server wiring (testability)
The tool logic (getStoreInventoryAndSales, createReplenishmentOrder) is implemented as pure,
exported functions; buildServer() only wires them to the MCP transport. This keeps the
Vitest suite fast and transport-free — it tests behavior directly, with no stdio mocking.
5. esbuild → single bundled file
npm run build (see build.mjs) bundles everything — including the SDK and Zod — into one
self-contained, minified dist/index.js with a #!/usr/bin/env node shebang. An MCP host can run it
with a single node dist/index.js command, no node_modules required at the deploy target. Node
built-ins are left external since the runtime provides them.
Tradeoff: bundling dependencies makes the output larger (~330 KB) and pins them at build time, but removes any runtime install step — the right call for a server meant to be dropped into a host config.
Project layout
.
├── build.mjs # esbuild bundle script -> dist/index.js
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── src
│ ├── index.ts # MCP server: schemas, tools, stdio wiring
│ ├── index.test.ts # Vitest unit tests
│ └── mockData.ts # Mock StoreLink inventory + POS data
└── dist
└── index.js # Bundled production server (generated)Available Tools
2 toolscreate_replenishment_orderCreate replenishment orderA
Raise a replenishment (restock) order for a store/SKU via StoreLink. Use after get_store_inventory_and_sales shows a meaningful demand gap. quantity is the number of units to order (positive integer).
Inputs: sku (required), quantity (required), store_id (required).
get_store_inventory_and_salesGet store inventory and salesA
Fetch on-hand inventory AND trailing-24h POS sales for a single store/SKU in one call. Returns a pre-computed demand_gap and stockout_risk so you can decide whether to replenish without making two separate requests.
Inputs: sku (required), store_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one retrieves inventory and sales data, the other creates a replenishment order. There is no overlap or ambiguity.
Both tools follow a consistent verb_noun pattern in snake_case: get_store_inventory_and_sales and create_replenishment_order.
Only 2 tools is minimal, but acceptable for a narrowly scoped replenishment server. However, typical integrations might benefit from a few more tools.
The server covers the core check-and-create cycle but lacks essential operations like listing, updating, or canceling replenishment orders, which agents may need.
Maintenance
Related MCP Connectors
Connect AI to store orders, products and inventory with scoped access and human approvals.
Search live store shelves, verify delivery windows, and run instant AI agent checkouts.
Launch and manage online stores with AI agents: products, inventory, pricing, orders and promotions.
Run your Zepsell store from AI: sales, orders, products, stock, customers and discount codes.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables store operations including inventory and sales queries and automated replenishment ordering through natural language.3-
- FlicenseNot gradedqualityDmaintenanceMCP server that lets a Duvo agent talk to Korral's StoreLink API, enabling category buyers to offload daily stock checking, replenishment ordering, and order tracking tasks.-
- FlicenseAqualityDmaintenanceEnables an AI grocery replenishment agent to interface with Korral's StoreLink stock API, providing tools to look up SKUs, get stock positions and gaps across stores, create replenishment orders (with buyer approval), and track order status.4-
- FlicenseAqualityBmaintenanceEnables AI agents to access real co-purchase intelligence and merchant operations tooling from an ecommerce store's order history, including product recommendations, bundle analysis, insights, replenishment forecasts, and merchant ops workflows.1948 npm1-