AMIRI Commercial Analytics MCP

A local-first, interview-ready Model Context Protocol (MCP) server for a luxury fashion commercial analytics team.

It turns executive questions such as:

“SS26 is six weeks old. What should we chase, what is becoming markdown risk, and is wholesale demand actually healthy?”

into calls to governed, deterministic analytics tools over a synthetic DTC + owned-retail + wholesale data model.

Important: every row in this repository is synthetic. This is a methodology demonstration shaped like a modern luxury-commerce analytics environment; it is not AMIRI internal data or a claim about AMIRI's actual KPIs.

Live Executive Demo

Launch the SS26 Executive Review →

Explore the interactive executive experience for commercial performance, sell-through, returns, wholesale health, inventory, and decision support.

All company, customer, product, and transaction data shown in the demo is synthetic and created solely for demonstration purposes.

Related MCP server: replenishradar

Why this project exists

The role is not just “build dashboards.” It is an operating-model problem: move from ad-hoc reporting toward a disciplined commercial analytics rhythm, give executives a consistent view across retail/e-commerce/wholesale/client data, define KPI frameworks, and pilot AI-assisted analytics with transparency and measurable value.

This project is deliberately designed around that job:

• Executive rhythm: weekly flash, exceptions, and decision prompts.

• Merchandising: aligned-week sell-through, chase vs hold vs markdown risk.

• E-commerce: return-rate root cause with metric-validation and cohort discipline.

• Retail: comparable-store growth vs total growth so new doors cannot hide comp softness.

• Wholesale: sell-in vs sell-through, reorder health, stuffing warning.

• Clienteling/marketing: adjusted descriptive clienteling read + causal warning; promo pull-forward check.

• Finance: channel-specific P&L instead of one misleading blended margin.

• Governance: named metrics, provenance, explicit caveats, synthetic-data flag, no unrestricted run_sql tool.

Architecture

synthetic source-shaped CSVs -> governed analytics -> FastMCP tools -> MCP host / LLM
             ^                         ^
     manifest + SHA256          metric_catalog.csv

The design deliberately separates reasoning from calculation. The host LLM decides which tool to call and how to synthesize the evidence; analytics.py owns the governed math. See docs/CODE_WALKTHROUGH.md for the file-by-file explanation.

Production evolution would be:

Shopify / POS / wholesale / clienteling sources
        -> Airbyte / ingestion
        -> BigQuery
        -> dbt staging -> intermediate -> marts
        -> tested semantic metrics
        -> MCP analytics service
        -> authorized AI host / internal UI

The MCP server does not call an LLM. The host LLM decides which tool to call; the analytics layer computes the numbers. This keeps reasoning and metric computation separate.

See docs/PROBLEM_MAP.md for the stakeholder-by-stakeholder problem/decision map.

Tools

Seeded stories you can demonstrate

The generator is deterministic and byte-verifiable. It uses seed 260829, writes data/manifest.json with SHA-256 hashes, and ships src/verify_reproducibility.py, which generates two independent temporary copies and compares both with the checked-in CSVs. A fresh rebuild intentionally creates several cases the tools should uncover:

1. Return anomaly: SS26 MX1 Hero Denim, DTC, late in the drop, with sizing dominating the reason mix and the largest seeded deterioration in US_West. The tool uses a non-overlapping 3-week recent / 4-week prior baseline, a minimum-volume gate, geography drill-down, suggested actions, and a fixed-cohort measurement plan.

2. Pipeline bug: six duplicated return rows that data_quality_checks catches; governed return-rate math dedupes first.

3. Chase vs markdown: fast hero styles and slow styles inside the same current collection.

4. Wholesale sell-in trap: synthetic partner Northstar Luxury has high sell-in, ~25% sell-through, and no reorders.

5. Retail mix trap: total retail is much healthier than comp-store growth because a new Milan door adds revenue.

6. Promo pull-forward: a private-client event spikes the promo week and softens the next two weeks.

These are not random Easter eggs. Each corresponds to a real analytical judgment an interviewer can probe.

Quick start — local analytics first

Preferred: uv

cd amiri_commercial_analytics_mcp
uv sync                      # first run resolves dependencies; if uv.lock exists, it uses it
uv run python src/make_data.py
uv run python src/verify_reproducibility.py
uv run python -m unittest discover -s tests -v
uv run python src/cli.py all

Or run the one-command health check:

./scripts/setup_and_test.sh

Pip fallback

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python src/make_data.py
python src/verify_reproducibility.py
python -m unittest discover -s tests -v
python src/cli.py all

Dependency-lock note: pyproject.toml is included and FastMCP is pinned to the current stable 3.4.6. This build environment has no package-registry network access, so I could not honestly generate a resolved uv.lock here. On the first networked local uv sync, uv will create it; commit that file before publishing. Do not use --frozen until the lock exists.

If the generator, reproducibility check, tests, and CLI all pass, the business logic is working independently of the MCP host.

Start the MCP server

python src/mcp_server.py

The process uses stdio and waits for an MCP client.

MCP Inspector

If Node/npm is installed:

npx @modelcontextprotocol/inspector .venv/bin/python src/mcp_server.py

Invoke the tools manually in Inspector before debugging an AI host. That isolates “analytics problem” from “MCP connection problem.”

Claude Desktop configuration

macOS configuration file:

~/Library/Application Support/Claude/claude_desktop_config.json

Example:

{
  "mcpServers": {
    "amiri-commercial-analytics": {
      "command": "/ABSOLUTE/PATH/amiri_commercial_analytics_mcp/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/amiri_commercial_analytics_mcp/src/mcp_server.py"
      ],
      "env": {
        "AMIRI_DATA_DIR": "/ABSOLUTE/PATH/amiri_commercial_analytics_mcp/data"
      }
    }
  }
}

Restart Claude Desktop after saving the config.

Five-minute interview demo

Use this sequence rather than clicking around randomly:

1. Trust first: “Before we diagnose anything, run the data-quality checks.”

2. Ambiguous case: “Our return rate spiked. Prove it's real, then localize the root cause.”

3. Commercial decision: “SS26 is six weeks old. What should we chase vs mark down?”

4. Cross-channel trap: “Wholesale shipments look strong. Is consumer demand actually strong by partner?”

5. Executive synthesis: “Give me the weekly commercial flash and the decisions leadership should discuss.”

The interview point is not “look, AI.” The point is: the same business definitions are reusable, tested, source-tagged, and callable from a natural-language interface.

Guardrails that are intentional

• No unrestricted run_sql(sql) tool for the LLM.

• Every tool response includes a trust block.

• Return rates are cohorted to order date, not return date.

• Duplicate return IDs are detected and deduped before rate math.

• Sell-through comparisons use aligned weeks of life.

• Retail comp growth excludes new stores.

• Wholesale sell-in is explicitly separated from sell-through.

• Clienteling output contains a causal-selection warning.

• Cannibalization uses a difference-in-differences framing and calls out its assumptions.

• Scenario/teaching assumptions are labeled rather than presented as facts.

Repository layout

amiri_commercial_analytics_mcp/
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .gitignore
├── config/
│   └── metric_catalog.csv
├── data/
│   ├── dim_product.csv
│   ├── dim_customer.csv
│   ├── dim_store.csv
│   ├── fct_orders.csv
│   ├── fct_order_lines.csv
│   ├── fct_returns.csv
│   ├── fct_inventory_snapshot.csv
│   ├── fct_wholesale_sellthrough.csv
│   └── dim_promo.csv
├── src/
│   ├── analytics.py
│   ├── cli.py
│   ├── make_data.py
│   ├── verify_reproducibility.py
│   └── mcp_server.py
├── tests/
│   └── test_analytics.py
├── scripts/
│   ├── setup_and_test.sh
│   └── run_inspector.sh
└── docs/
    ├── ARCHITECTURE.md
    ├── CODE_WALKTHROUGH.md
    ├── DEMO_QUESTIONS_DEEP_DIVE.md
    ├── INTERVIEW_DEMO.md
    ├── PROBLEM_MAP.md
    ├── LOCAL_SETUP.md
    ├── GOLDEN_QUESTIONS.md
    ├── architecture.svg
    ├── return_rootcause.svg
    └── GITHUB_PUBLISH.md

What I would say in the interview

“I treated this as an operating-system problem, not a chatbot project. I modeled the commercial questions the role is responsible for — sell-through, markdown exposure, returns, comp stores, wholesale sell-through, clienteling, channel economics — as governed tools. The LLM can decide which tool to call, but it cannot invent a KPI definition or silently query arbitrary raw data. The demo uses synthetic data, but the production pattern is the same one I would put over tested dbt marts in BigQuery.”

MIT licensed.