# MCP tools decision

## Public Tools

`server.py`

- list_store() > read only
  -- agent tool to determine which stores are available to access
- raise_replenishment_order() > write
  -- provide the agent the capability to place orders on behalf of Korral
- replenishment_order_status() > read only
  -- agent tool to determine the status of a placed order
- sku_report() > read only
  -- agent tool to assess sku information, including supplier and lead time

## Utility private functions (not agent tools)

`server.py`

- sku_lead_time() > read only (private)
  -- utility tool for the sku_report public tool to determine how fast an order can be fulfilled.
- stock_report(sku) > read only (private)
  -- compare what is in stock/on-hand vs recent post transactions for the sku

## Observability

Package in `observability/`

### 1. Technical trace — for support / engineers

Structured JSON on the `storelink_mcp.trace.technical` logger, meant for
diagnosing issues as they happen:

- **Explicit MCP server version** (`mcp_server.name` + `version`) on every record.
- Correlation `trace_id` (shared with the audit stream) and the MCP `request_id`.
- Tool name and business arguments (the audit-only `reason` is stripped out).
- **Per-leg downstream spans** — every StoreLink HTTP call with method, path,
  status, latency, and retry `attempts`, tagged `leg: "mcp<->storelink"`.
- On failure: the **failing connection leg** (`duvo<->mcp` vs `mcp<->storelink`),
  the unwrapped root-cause error type/message (FastMCP wraps tool errors in a
  `ToolError`; the original `StoreLinkAPIError` is surfaced with `wrapped_by`),
  and the **full chained stack trace**.

### 2. Audit trace — for buyers (non-technical stakeholders)

A readable line on the `storelink_mcp.trace.audit` logger:

- A **plain-English description** of each step the agent took.
- The agent's **reasoning**, captured via an optional `reason` argument added to
  every public tool (the model is instructed to always provide it).
- A buyer-friendly **outcome** — a summary of the result on success, or a calm
  "this step could not be completed" note on failure (never a stack trace).
- A running `step_number` so the actions read in order.

## Keys transactions

Each StoreLink API key (`X-Korral-Store-Key`) is scoped to one store id.

There are two scenarios to consider per the assessment brief: a) key rotates mid-flight and b) unknown store id is referenced.

-- For a, when a key is rotated while a request is in flight e.g. storelink api returns 40x errors, invalidate the currently stored key, reload with the newly rotated key, and retry (max 3).

-- For b, when a new or unknown store is provided, before making any request to the storelink API, inform the end user (buyer) that the store number referenced is not included in the available stores, provide them explicit written instructions to ask the Korral IT team to provision a key for the store provided.

## Shipping

-- Where this runs: The MCP server will run in Korall's GCP instance via GCP Cloud Run where all the data is already internal/private. Assuming that StoreLink API also exists in the same GCP instance, all the data that comes into the MCP server is also internal/private.

-- How it gets there: The MCP server will be built as a docker image that Duvo maintains and ships out to Korral for verification before they deploy new builds/changes done by Duvo.

-- How secrets are handled: see Keys transactions section