Chat Commerce MCP Hub

This repository is the centralised specification for Pick n Pay's chat commerce MCP (Model Context Protocol) tools. It serves as the single source of truth for what the AI shopping assistant can do across all platforms.

Who is this for?

Audience	What to read
Product Owners & BAs	Capabilities Overview — plain-language summary of every feature
Product Owners & BAs	Platform Matrix — which features are on which platform
Developers	MCP Tools — full technical specs per tool
Developers	Architecture — how the system works end to end
New contributors	Adding a New Tool — step-by-step guide

What is MCP?

MCP (Model Context Protocol) is the way the AI assistant interacts with the Pick n Pay app. When a customer asks the assistant to do something (like "add milk to my cart"), the assistant calls an MCP tool — a function that the app executes locally on the customer's device.

Think of MCP tools as the assistant's "hands" — they let it search products, manage the cart, check orders, and navigate the app on behalf of the customer.

How this repo works

┌─────────────────────────────────────────────┐
│           mcp-docs (this repo)              │
│                                             │
│   specs/tools/*.yaml  ─── Source of truth   │
│         │                                   │
│         ▼                                   │
│   npm run generate   ─── Builds docs        │
│         │                                   │
│         ▼                                   │
│   docs/ pages        ─── Docusaurus site    │
└─────────────────────────────────────────────┘
         │
         │  Feeds into
         ▼
┌────────────┐  ┌────────────┐  ┌────────────┐
│  iOS App   │  │ Android App│  │ LLM Proxy  │
└────────────┘  └────────────┘  └────────────┘

Current workflow (pull)

Tool implementations exist in the iOS and Android apps. This repo was initially populated by extracting those definitions into YAML specs.

Target workflow (push)

New tools are specified here first via pull request. Once the spec is approved, developers implement it in the respective apps and update the platform status in the YAML spec.

Quick start

cd mcp-docs

# Install dependencies
npm install

# Generate docs from YAML specs
npm run generate

# Start local dev server
npm start

# Validate YAML specs
npm run validate