Coffee MCP

The MCP platform that connects beverage brands to every AI assistant.

When a customer says "help me order a latte" to ChatGPT, Claude, Doubao, or any AI assistant — only brands connected via MCP get discovered. This platform is how you get connected.

The Problem

AI assistants are becoming the new storefront. Hundreds of millions of users already ask AI to help them shop, order food, and make decisions. But most brands have zero presence in this channel — no way to be discovered, recommended, or ordered from.

Traditional APIs don't solve this. AI assistants speak MCP (Model Context Protocol) — the open standard for connecting AI to external tools and data.

The Solution

Coffee MCP is an open-source, multi-brand MCP platform that lets any coffee, tea, juice, or bakery brand plug into the AI ecosystem — with a YAML config and a brand adapter.

Customer → AI Assistant → MCP Protocol → Coffee MCP → Your Brand's Backend API

What you get:

• 21 consumer-facing tools (browse menu, find stores, order, pay, track)
• 10 B2B enterprise tools (member query, coupons, loyalty, payments)
• 4-tier security model (L0-L3) with rate limiting and transaction safety
• Multi-brand support — one platform, unlimited brands
• Category presets for coffee, tea, juice, and bakery
• Brand onboarding in as little as 5 minutes (CLI) or 30 minutes (AI-assisted)

What it costs: Nothing. MIT licensed. Self-host or extend as you wish.

Who Is This For?

Quick Start

# Install (requires uv + Python 3.13)
uv sync

# Run consumer ordering server (default brand)
uv run coffee-company-toc

# Run with a different brand
BRAND=tea_house uv run coffee-company-toc

# Run B2B enterprise server
uv run coffee-company-mcp

# Run all tests (122 passing)
uv run python tests/test_toc_mcp.py     # 89 ToC tests
uv run python tests/test_mcp_real.py     # 33 B2B tests

# Initialize a new brand (interactive)
uv run brand-init

Architecture

                    ┌──────────────────────────────┐
                    │   AI Assistants (MCP Clients) │
                    │   ChatGPT / Claude / Doubao   │
                    │   OpenClaw / Cursor / Custom   │
                    └──────────────┬───────────────┘
                                   │ MCP Protocol
                    ┌──────────────▼───────────────┐
                    │     Gateway (Kong/CloudFlare)  │
                    │   OAuth · Rate Limit · WAF     │
                    └──────────────┬───────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              │                                         │
     ┌────────▼─────────┐                  ┌────────────▼───────────┐
     │   B2B Server      │                  │    ToC Server (factory) │
     │   10 read tools   │                  │    21 tools · L0-L3    │
     │   Kong HMAC auth  │                  │    Multi-brand YAML    │
     └──────────────────┘                  └────────────┬───────────┘
                                                        │
                                           ┌────────────▼───────────┐
                                           │    BrandAdapter (ABC)   │
                                           │    21 abstract methods  │
                                           ├────────────────────────┤
                                           │  DemoAdapter (mock)     │
                                           │  YourBrandAdapter (HTTP)│
                                           └────────────────────────┘

Brand Onboarding

Three paths, pick what fits your team:

1. CLI Init (5 min) — Zero-code, YAML-driven:

uv run brand-init
# → Select: coffee / tea / juice / bakery
# → Generates brands/<your_brand>/brand.yaml
# → Done. Run the server.

2. AI-Assisted (30 min) — Give your API docs to Claude:

/brand-onboard https://api.yourbrand.com/docs
# → Generates adapter.py + brand.yaml + integration tests

3. Full Custom (1-2 weeks) — Implement BrandAdapter with 21 methods:

class MyBrandAdapter(BrandAdapter):
    def nearby_stores(self, city=None, keyword=None):
        resp = httpx.get(f"{self.api}/stores", params={"city": city})
        return resp.json()["stores"]
    # ... 20 more methods

See Brand Integration Guide for the complete walkthrough.

Category Presets

Consumer Tools (ToC Server — 21 Tools)

The full ordering journey, from discovery to delivery:

Security Model

Four tiers designed for AI-to-commerce, where the AI acts on behalf of the user:

• L0 (60/min) — Public data: menus, stores, nutrition
• L1 (30/min) — User data: account, coupons, orders
• L2 (5/hour) — Write ops: claim coupons, add address
• L3 (10/day) — Transactions: create order, redeem points
  • Requires confirmation_token from calculate_price
  • Requires idempotency_key to prevent duplicate operations

Enterprise Tools (B2B Server — 10 Tools)

For partner integrations (delivery platforms, loyalty aggregators, payment providers):

Connect to AI Assistants

Claude Desktop / Cursor (stdio):

{
  "mcpServers": {
    "coffee-toc": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/coffee-mcp", "coffee-company-toc"],
      "env": { "BRAND": "coffee_company" }
    }
  }
}

OpenClaw / Agent SDK (Streamable HTTP):

coffee = McpServer.http(
    url="https://mcp.yourbrand.com/mcp",
    headers={"Authorization": f"Bearer {token}"}
)
agent.add_mcp_server(coffee)

Project Structure

brands/                          # Brand configs (zero-code onboarding)
├── coffee_company/brand.yaml    #   Default demo brand
└── tea_house/brand.yaml         #   Example: tea chain

src/coffee_mcp/
├── toc_server.py                # ToC server factory (21 tools)
├── brand_config.py              # YAML config loader
├── brand_adapter.py             # BrandAdapter ABC (21 methods)
├── demo_adapter.py              # Mock data adapter
├── brand_init.py                # CLI brand initializer
├── presets/catalog.py           # Category presets
├── server.py                    # B2B server (10 tools)
└── cli.py                       # CLI + REPL

docs/
├── BRAND_INTEGRATION_GUIDE.md   # Step-by-step brand onboarding
├── TOC_MCP_PLATFORM_DESIGN.md   # Platform design & competitive analysis
├── TOC_SECURITY.md              # Security architecture (L0-L3)
└── MCP_API_DESIGN_GUIDE.md      # MCP tool design principles

Docs

• Brand Integration Guide — Connect your brand step by step
• Platform Design — Architecture, competitive analysis, roadmap
• Security Model — L0-L3 threat model for AI-commerce
• API Design Guide — MCP tool design principles

Roadmap

• Hosted multi-tenant mode (brands self-register, zero-deploy)
• Payment provider integrations (Alipay, WeChat Pay, Stripe)
• Analytics dashboard (AI ordering funnel, conversion tracking)
• More verticals beyond beverage (fast food, convenience stores)

Contributing

PRs welcome. See the Brand Integration Guide if you want to add support for a new brand or category.

License

MIT