Skip to main content
Glama

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.

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.

Related MCP server: mcp-coffee

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

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

Available Tools

10 tools
assets_listC

查询客户全部资产(优惠券 + 权益券),一览式展示。

对应 HTTP API: POST /assets/list

Args: member_id: Coffee Company会员ID

Inputs: member_id (required). Returns: result

cashier_pay_queryB

查询支付状态(收银台下单后的支付结果)。

对应 HTTP API: POST /cashier/payQuery

状态: 0=支付中, 1=支付成功, 2=支付失败

Args: pay_token: 支付令牌(收银下单接口返回的 payToken)

Inputs: pay_token (required). Returns: result

coupon_detailA

查询单张券码的详细信息,包括状态、面值、有效期、核销次数。

对应 HTTP API: POST /coupon/detail

券码状态: 4=未使用, 10=已使用, 20=已过期, 30=已作废

Args: coupon_code: 券码(如 "CC20260301A001")

Inputs: coupon_code (required). Returns: result

coupon_queryC

查询订单关联的券码生成状态。

对应 HTTP API: POST /coupon/query

Args: order_id: 订单号

Inputs: order_id (required). Returns: result

equity_detailB

查询权益详情,包括券码、状态、金额、核销次数等完整信息。

对应 HTTP API: POST /equity/detail

Args: order_id: 权益订单号

Inputs: order_id (required). Returns: result

equity_queryB

查询权益发放状态(电子券是否发放成功)。

对应 HTTP API: POST /equity/query

Args: order_id: 权益订单号

Inputs: order_id (required). Returns: result

member_benefit_listB

查询会员的优惠券和权益券列表。

对应 HTTP API: POST /crmadapter/asset/coupon/getBenefitList

Args: member_id: Coffee Company会员ID

Inputs: member_id (required). Returns: result

member_benefitsB

查询会员 8 项权益状态(新人礼、生日奖励、升级奖励等)。

对应 HTTP API: POST /crmadapter/customers/getBenefits

状态说明: 0=隐藏, 1=未解锁, 2=可使用, 3=已使用/已过期

Args: member_id: Coffee Company会员ID

Inputs: member_id (required). Returns: result

member_queryB

查询Coffee Company会员信息。通过手机号、openId 或会员ID查询。

对应 HTTP API: POST /crmadapter/account/query

Args: mobile: 手机号(模糊匹配,如 "138****1234") open_id: 第三方平台 openId member_id: Coffee Company会员ID

Inputs: mobile, open_id, member_id. Returns: result

member_tierB

查询会员等级详情,包括当前星星数、等级有效期、距下一级的差距。

对应 HTTP API: POST /crmadapter/account/memberTier

Args: member_id: Coffee Company会员ID

Inputs: member_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific resources like assets, payments, coupons, equity, and member data. However, 'assets_list' and 'member_benefit_list' both query member assets/coupons with similar descriptions, creating some ambiguity. The other tools are clearly differentiated by their specific functions.

    Naming Consistency3/5

    The naming follows a mostly consistent pattern of 'resource_action' (e.g., coupon_detail, equity_query), but there are notable deviations: 'assets_list' uses plural while others use singular (e.g., 'coupon_query'), and 'member_benefit_list' and 'member_benefits' have inconsistent naming despite similar domains. The pattern is readable but mixed.

    Tool Count5/5

    With 10 tools, the count is well-scoped for a coffee company server covering assets, payments, coupons, equity, and member management. Each tool serves a specific purpose in this domain, and the number is typical for such a scope, avoiding bloat or thin coverage.

    Completeness4/5

    The tool set provides good coverage for querying and managing member data, assets, coupons, equity, and payments, with clear CRUD-like operations for details and lists. Minor gaps exist, such as no explicit tools for creating or updating assets/coupons, but agents can likely work around this with the provided query tools for core workflows.

    Related MCP Connectors

    Related MCP Servers