Coffee Company Server

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.

Tests Python License

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?

Audience	Value
Brand CTOs / Digital Leaders	Ship AI ordering for your brand in 2-3 weeks, not 6 months
AI/MCP Developers	Production-grade reference for multi-tenant MCP server design
Retail Tech Teams	Battle-tested security model (L0-L3) for AI-to-commerce flows
Founders	Fork this to build your own vertical MCP platform

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

Preset	Sizes	Extras	Sweetness
Coffee	tall / grande / venti	espresso shots, syrups	4 levels
Tea	regular / large	boba, pudding, taro	5 levels
Juice	regular / large	chia seeds, nata	3 levels
Bakery	single / combo	gift box	—

Consumer Tools (ToC Server — 21 Tools)

The full ordering journey, from discovery to delivery:

Group	Tools	Security
Utility	now_time_info	L0
Discovery	campaign_calendar · available_coupons · claim_all_coupons	L1-L2
Account	my_account · my_coupons · my_orders	L1
Menu	nearby_stores · store_detail · browse_menu · drink_detail · nutrition_info	L0
Points	stars_mall_products · stars_product_detail · stars_redeem	L1-L3
Order	delivery_addresses · create_address · store_coupons · calculate_price · create_order · order_status	L1-L3

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):

Tool	HTTP API	Description
member_query	POST /crmadapter/account/query	Query member by mobile/openId/memberId
member_tier	POST /crmadapter/account/memberTier	Tier details + stars balance
member_benefits	POST /crmadapter/customers/getBenefits	8 benefit statuses
member_benefit_list	POST /crmadapter/asset/coupon/getBenefitList	Coupon list
coupon_query	POST /coupon/query	Order coupon status
coupon_detail	POST /coupon/detail	Coupon details
equity_query	POST /equity/query	Equity distribution status
equity_detail	POST /equity/detail	Equity details
assets_list	POST /assets/list	All customer assets
cashier_pay_query	POST /cashier/payQuery	Payment status

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