storelink-mcp
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., "@storelink-mcp Check on-hand vs POS for SKU 8847291 at store 47 and replenish as needed."
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.
StoreLink MCP Server
Python MCP server that exposes the hypothetical StoreLink grocery stocking API as agent tools over stdio.
StoreLink is used by a European grocer with locations across Europe, primarily in Czechia (also Slovakia and Austria in the mock data).
Tools
Built for a category buyer workflow: check on-hand vs last-24h POS, apply the delta rule, then replenish.
Tool | Description |
| List stores |
| Store details |
| Primary check: on-hand + POS + |
| Raise a replenishment order |
| Order status |
get_on_hand_vs_pos defaults the POS window to the last 24 hours when since is omitted. It returns delta = units_sold − available and a product block (case_pack, lead_time_days, etc.).
Buyer rule: if delta >= 6, call create_replenishment (prefer multiples of product.case_pack).
Related MCP server: storelink-mcp
Butter test scenario
Field | Value |
SKU |
|
Store 47 | Praha Budějovická — available 4, ~12 sold / 24h → delta 8 → replenish |
Store 102 | Brno Vaňkovka — available 18, ~5 sold / 24h → delta −13 → do not replenish |
Setup
Requires Python 3.10+.
# From the project root
uv syncOr with pip:
pip install -e .Configuration
Variable | Default | Description |
|
|
|
|
| Base URL used in |
| (unset) | Optional Bearer for non-store endpoints |
| (required in http) | GCP project where Korral stores weekly-rotated store keys |
|
| Secret id = |
|
| NDJSON audit log file path |
| (session id) | Optional agent/thread id for correlating a chat |
|
| Category-buyer activity (JSON lines) |
|
| Category-buyer activity (readable markdown) |
Every tool requires a reason string (why the agent is calling it). That value is written into the audit trail as ground-truth rationale.
Korral per-store API keys
Korral IT rotates a per-store API key weekly in GCP Secret Manager. Store-scoped StoreLink calls send:
X-Korral-Store-Key: <key>Secret naming: projects/{KORRAL_GCP_PROJECT}/secrets/{KORRAL_SECRET_PREFIX}{store_id}/versions/latest
Example for store 47: korral-store-47.
Auth behavior:
Before any store-scoped request, the key is loaded (cached in memory).
If the secret does not exist, the tool fails immediately with a clear message for the agent (no HTTP call):
No Korral API key configured for store … Ask Korral IT to provision the weekly-rotated key.If StoreLink returns 401 (key rotated in flight), the cache is invalidated, the latest secret is fetched, and the request is retried once.
Store-scoped tools/endpoints: get_store, inventory/POS inside get_on_hand_vs_pos, create_replenishment, get_replenishment.list_stores / SKU-supplier lookups do not require a store key.
Use Application Default Credentials (GOOGLE_APPLICATION_CREDENTIALS or workload identity) so the MCP process can read Secret Manager.
Audit logging
All audit events are standardized JSON (one object per line / NDJSON), written to stderr and appended to STORELINK_AUDIT_LOG.
Common envelope:
{
"schema_version": "1.0",
"event_type": "tool_call_started",
"timestamp": "2026-08-01T17:00:00.123Z",
"session_id": "…",
"interaction_id": "…",
"thread_id": "…",
"service": "storelink-mcp",
"level": "info",
"payload": {
"tool": "get_on_hand_vs_pos",
"arguments": { "store_id": "47", "sku": "8847291", "reason": "…" },
"reason": "Check store 47 butter sell-through before replenish decision"
}
}
| When |
| Process lifetime |
| Tool invoked |
| Tool returned (includes |
| Tool error (includes |
interaction_id is unique per tool invocation and shared across that call’s started/succeeded/failed events.
Category buyer activity feed
Alongside the engineer audit log, every agent action is also written in plain language for category buyers:
Why the agent acted (from the required
reasonargument)What happened (stock checked, order placed, etc.)
Outcome (e.g. replenishment recommended when delta ≥ 6)
Files:
logs/buyer-activity.md— human-readable timelinelogs/buyer-activity.ndjson— same entries as structured JSON
MCP resource (not a tool — does not clutter the buyer agent loop):
buyer://activity— current-session feed in markdown
Example markdown entry:
### 2026-08-01T17:22:49Z — Checked on-hand vs recent sales for Madeta butter 250g at store 47
**Status:** Needs attention
**Why the agent did this:** Check butter delta at store 47 before replenish decision
**What happened:** In the last 24 hours, about 12 units sold; 4 units are still available on the shelf (gap/delta: 8).
**Outcome:** Sales are outpacing stock (delta 8 ≥ 6). A replenishment order is recommended.Mock mode includes Czech/EU stores (plus scenario stores 47 and 102), metric SKUs including 8847291, inventory, POS history (CZK/EUR), and Central European suppliers.
Run
uv run storelink-mcp
# or
uv run python -m storelink_mcp.serverCursor / Claude Desktop config
Add to your MCP settings (e.g. Cursor mcp.json):
{
"mcpServers": {
"storelink": {
"command": "/Users/aleccritser/.local/bin/storelink-mcp-cursor",
"env": {
"STORELINK_MODE": "mock"
}
}
}
}Important: the project path contains a space (Duvo Task). Cursor splits the command field on spaces, so pointing command at .venv/bin/storelink-mcp under that folder fails with spawn /Users/aleccritser/Duvo ENOENT. Use the no-space launcher at ~/.local/bin/storelink-mcp-cursor (created by the project setup), or uv with the directory passed as a separate arg:
{
"mcpServers": {
"storelink": {
"command": "/Users/aleccritser/.local/bin/uv",
"args": ["run", "--directory", "/Users/aleccritser/Duvo Task", "storelink-mcp"],
"env": {
"STORELINK_MODE": "mock"
}
}
}
}For live HTTP against a StoreLink deployment:
{
"mcpServers": {
"storelink": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/Duvo Task", "storelink-mcp"],
"env": {
"STORELINK_MODE": "http",
"STORELINK_BASE_URL": "https://storelink.com",
"STORELINK_API_KEY": "your-api-key"
}
}
}
}Example agent flow
get_on_hand_vs_pos("47", "8847291", reason="…")→ readdeltaandproduct.case_packIf
delta >= 6→create_replenishment(..., reason="delta>=6 …")Optionally check store
102(delta should stay below 6 — no order)get_replenishment(..., reason="…")→ poll status
Available Tools
5 toolscreate_replenishmentA
Raise a replenishment order when get_on_hand_vs_pos delta >= 6.
Call after get_on_hand_vs_pos when units_sold − available is at least 6. Prefer ordering in multiples of product.case_pack from that response.
Args: store_id: Store identifier (e.g. 47). sku: Product SKU to replenish (e.g. 8847291). quantity: Units to order (must be > 0; prefer case_pack multiples). reason: Why you are raising this order (required for audit). order_reason: Optional note stored on the replenishment order record. priority: One of low, normal, high, urgent (default normal).
Inputs: sku (required), reason (required), quantity (required), store_id (required), +2 more. Returns: result
get_on_hand_vs_posA
Current on-hand plus POS sales for a SKU at a store (category buyer view).
Returns inventory, last-24h POS (by default), delta = units_sold − available, and a product block (name, case_pack, supplier lead_time_days) for order sizing. If delta >= 6, call create_replenishment (prefer multiples of case_pack).
Args: store_id: Store identifier (e.g. 47 or 102). sku: Product SKU (e.g. 8847291 for Madeta butter 250g). reason: Why you are checking on-hand vs POS (required for audit). since: Optional ISO-8601 start of the POS window. If omitted, defaults to 24 hours ago (UTC).
Inputs: sku (required), reason (required), store_id (required), since. Returns: result
get_replenishmentB
Get status of a replenishment order by store_id and order_id.
Args: store_id: Store identifier. order_id: Replenishment order id. reason: Why you are checking order status (required for audit).
Inputs: reason (required), order_id (required), store_id (required). Returns: result
get_storeA
Get details for a single store by store_id (e.g. 47 or store-001).
Args: store_id: Store identifier. reason: Why you need this store's details (required for audit).
Inputs: reason (required), store_id (required). Returns: result
list_storesA
List all StoreLink stores (id, name, city, country code, active flag).
Args: reason: Why you are listing stores (required for audit).
Inputs: reason (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct action and resource: listing stores, getting store details, checking inventory/POS, creating a replenishment, and retrieving a replenishment. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern (list_stores, get_store, get_on_hand_vs_pos, create_replenishment, get_replenishment). The naming is predictable and clear, with the compound 'get_on_hand_vs_pos' still fitting the convention.
The server has 5 tools, which is well-scoped for its purpose of store and replenishment management. Each tool serves a necessary function without redundancy, making the set neither too thin nor too heavy.
The main workflow is covered: list/get stores, check inventory vs POS, create a replenishment, and check its status. A minor gap is the lack of a 'list_replenishments' tool or update/cancel capabilities, but the core lifecycle is functional.
Maintenance
Related MCP Connectors
MCP server for Product Management
MCP server for MarketTime — wholesale orders, customers, catalog and shipment tracking.
MCP server for SkuVault — products, inventory, sales, purchase orders and stock adjustments.
Remote MCP server for product discovery catalog and retrieving product details.
Related MCP Servers
- 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.-
- FlicenseAqualityDmaintenanceMCP server for managing store replenishment, including listing stores, raising orders, checking order status, and viewing SKU reports with observability and key rotation handling.4-
- AlicenseAqualityDmaintenanceAn MCP server that enables Duvo agents to perform Korral category buyer tasks against the StoreLink API, including checking stock risk, reviewing sales, and raising replenishment orders.5MIT
- FlicenseAqualityBmaintenanceMCP server that exposes read-only NetSuite tools for querying warehouse stock levels and order status, using mock data locally and a pluggable client interface.2-