StoreLink MCP Server

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.

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).

Butter test scenario

Setup

Requires Python 3.10+.

# From the project root
uv sync

Or with pip:

pip install -e .

Configuration

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:

1. Before any store-scoped request, the key is loaded (cached in memory).
2. 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.
3. 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"
  }
}

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 reason argument)
• What happened (stock checked, order placed, etc.)
• Outcome (e.g. replenishment recommended when delta ≥ 6)

Files:

• logs/buyer-activity.md — human-readable timeline
• logs/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.server

Cursor / 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

1. get_on_hand_vs_pos("47", "8847291", reason="…") → read delta and product.case_pack
2. If delta >= 6 → create_replenishment(..., reason="delta>=6 …")
3. Optionally check store 102 (delta should stay below 6 — no order)
4. get_replenishment(..., reason="…") → poll status