Retail

A complete enterprise portfolio that connects AI clients to retail customer, inventory, sales, order, and support capabilities through the Model Context Protocol (MCP). It combines strategic assessment, a working server, and production security/deployment artifacts in one repository.

Portfolio coverage

1. MCP architecture assessment and design: architecture, MCP evaluation, risk assessment, ROI, and executive summary.
2. Production MCP server: resources, tools, prompt, PostgreSQL adapter, Redis cache, connection pool, validation, transactions, idempotency, tests, and API documentation.
3. Enterprise framework: security, Prometheus/Grafana, Docker, Kubernetes, TLS gateway, CI/CD, deployment, and disaster recovery.
4. Multi-agent extension proposal: dialogue synthesis, safeguards, conflict resolution, and human intervention.

Architecture

flowchart LR
  U[Enterprise User] --> H[AI Host / MCP Client]
  H -->|Streamable HTTP + TLS| G[Gateway / WAF]
  G --> M[Stateless MCP Replicas]
  M --> A[Authentication + RBAC]
  A --> R[Resource Manager]
  A --> T[Tool Manager]
  R --> C[(Redis Cache)]
  R --> P[Connection Pool]
  T --> P
  P --> D[(PostgreSQL)]
  D -. adapters .-> E[CRM / ERP / Inventory / Support]
  M --> O[Metrics / Audit / Alerts]

The editable diagram is docs/architecture.mmd.

MCP contract

Resources

URI template	Permission	Description
retail://customers/{customer_id}	customer:read	Customer profile with role-based PII filtering
retail://inventory/{sku}	inventory:read	Quantity, reorder threshold, and price
retail://sales/{sale_id}	sales:read	Confirmed retail sale

Tools

Tool	Permission	Safety property
process_order	order:write	Transaction, row lock, idempotency key, stock validation
update_inventory	inventory:write	Bounds validation, non-negative invariant, cache invalidation
create_support_ticket	ticket:write	Length/control-character validation and audit event

The investigate_customer_issue prompt provides workflow guidance but grants no permission.

Quick start

Prerequisites: asdf, uv, and optionally Docker. The repository pins Python in .tool-versions, following the workspace standard.

asdf install
asdf current python
cp .env.example .env
uv sync --python "$(asdf which python)" --extra dev
uv run pytest
uv run retail-mcp --transport http

In another terminal, run the non-destructive protocol smoke test, or let it manage a temporary local server with --start-server:

uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --start-server

Connect an MCP client to http://localhost:8000/mcp and send one of these headers:

X-API-Key: dev-admin-key

or:

Authorization: Bearer dev-admin-key

Bundled keys work only in development. Production mode rejects them. For STDIO:

RETAIL_MCP_STDIO_API_KEY=dev-admin-key uv run retail-mcp --transport stdio

Full stack

docker compose up --build -d
docker compose ps
curl http://localhost:8000/health/ready

Services:

• MCP server: localhost:8000/mcp
• Prometheus: localhost:9090
• Grafana: localhost:3000
• PostgreSQL and Redis: private Compose network only

See deployment.md for production Compose, Kubernetes, TLS, secrets, SLOs, scaling, and rollback.

Configuration

All settings use the RETAIL_MCP_ prefix.

Variable	Purpose	Production requirement
ENVIRONMENT	development, test, or production	production
DATA_BACKEND	memory or postgres	postgres
DATABASE_URL	PostgreSQL DSN	Secret
REDIS_URL	Shared cache URL	Secret/private endpoint
API_KEYS	JSON key/subject/role records	Secret; no dev-* keys
STDIO_API_KEY	Credential for local STDIO process	Environment secret
RATE_LIMIT_PER_MINUTE	Per-principal application limit	Tune from load test
REQUEST_TIMEOUT_SECONDS	Dependency operation timeout	Below gateway timeout

Example API_KEYS value:

[
  {"key": "a-long-random-secret", "subject": "support-agent", "role": "customer_service"}
]

API keys are the scenario's required authentication mechanism. Enterprise evolution should replace them with OAuth 2.1 and audience-bound tokens while retaining the same Principal and RBAC boundary.

Quality and validation

uv run ruff check .
uv run ruff format --check .
uv run pytest
docker compose config
docker build -t retail-mcp:local .

The CI pipeline performs linting, tests with coverage, package build, dependency review, and container build. Before production, add organization-specific SAST, secret scanning, image vulnerability scanning, signing, provenance, and deployment approval.

Repository map

src/retail_mcp/       MCP server and enterprise application layers
tests/                Unit, authorization, resilience, and API tests
migrations/           PostgreSQL schema and seed data
monitoring/           Prometheus alerts and provisioned Grafana dashboard
deploy/               TLS gateway and Kubernetes deployment/HPA
docs/                 Architecture, business, security, operations, and DR
.github/workflows/    CI pipeline

Important limitations

• The API-key manager is intentionally replaceable; use the corporate IdP for user-delegated production access.
• The sample is single-tenant. Tenant identity must be enforced in principals, queries, row policies, and cache keys before multi-tenant use.
• The PostgreSQL projection represents integration with systems of record; real CRM/ERP adapters and synchronization are organization-specific.
• Performance and ROI figures are hypotheses until validated with production-like load tests and business measurements.