grocers-design-mcp

MCP server exposing the Grocers Design System as queryable tools for coding agents.

Hosted on Fly.io. Auth is a single long-lived token embedded in the URL path — no OAuth, no client config beyond pasting the URL.

Live: https://grocers-design-mcp.fly.dev/<TOKEN>/mcp Health (no auth): https://grocers-design-mcp.fly.dev/health

What it serves

• Design tokens — every CSS custom property from the Grocers DS (colors, spacing, radii, shadows, type scale, motion). 101 tokens indexed at boot.

• Semantic type classes — t-h1, t-display, t-body, t-price, etc. (16 ready-to-apply utility classes).

• UI components — JSX source from the web, mobile, and admin UI kits. 44 components — Dashboard, KpiCard, OrdersScreen, OrderRow, CartSheet, MProductTile, etc.

• Brand foundations — content rules (tone, casing, no-emoji), visual rules (red ≠ error, destructive uses ink + type-to-confirm), iconography (Lucide, 2px stroke, 24px grid).

• Skill manifest — one-paragraph brand brief for fast agent bootstrap.

Tools

Lint rules in validate_snippet

Intent map in suggest_component

30 curated entries spanning all three kits plus 5 non-component patterns (destructive-action, error-state, price-display, icon-usage, tone-of-voice). Kit inference from natural language ("mobile", "painel", "web") biases the ranking.

Using with Claude Code

Add to ~/.claude.json or project .mcp.json:

{
  "mcpServers": {
    "grocers-design": {
      "type": "http",
      "url": "https://grocers-design-mcp.fly.dev/<TOKEN>/mcp"
    }
  }
}

The token lives in fly secrets and rotates via fly secrets set GROCERS_MCP_TOKEN=$(openssl rand -hex 32) -a grocers-design-mcp.

Quick example flow (agent building a Grocers admin screen)

1. get_foundations({section:"visual"})         → brand rules
2. suggest_component({intent:"tabela de pedidos no admin"})
                                                → admin/OrdersScreen
3. suggest_component({intent:"modal de cancelar pedido"})
                                                → pattern destructive-action
                                                  (ink + type-to-confirm)
4. get_component({name:"OrdersScreen", kit:"admin"})
                                                → JSX source
5. validate_snippet({snippet: <composed JSX>})  → catch drift before ship

Local dev

npm install
GROCERS_MCP_TOKEN="$(openssl rand -hex 32)" PORT=8080 npm run dev
# Health:  http://localhost:8080/health
# MCP:     http://localhost:8080/<TOKEN>/mcp

Architecture

• Hono + @hono/node-server for HTTP.

• @modelcontextprotocol/sdk for JSON-RPC / streamable HTTP transport, stateless mode (fresh McpServer per request — no session state).

• Token-in-URL middleware: timingSafeEqual against GROCERS_MCP_TOKEN; wrong token returns 404 (not 401 — hides existence).

• The DS bundle ships inside the container at bundle/ and is indexed once at boot into in-memory maps (O(1) lookups).

• Fly app runs 2 machines (HA) in gru, 256MB each, auto-stops when idle.

Deploy

fly deploy -a grocers-design-mcp --remote-only

Layout

bundle/                              # Grocers DS handoff bundle (source of truth)
  project/
    colors_and_type.css              # all design tokens
    README.md                        # foundations
    SKILL.md                         # one-paragraph brand brief
    ui_kits/{web,mobile,admin}/      # React/JSX components
    preview/*.html                   # visual specimens (not served by MCP)
src/
  index.ts                           # entrypoint
  server.ts                          # Hono app + token middleware
  indexer.ts                         # CSS + JSX + README parser
  tools/
    tokens.ts                        # list_tokens, get_token, list_semantic_classes
    components.ts                    # list_components, get_component
    foundations.ts                   # get_foundations, get_skill
    search.ts                        # search (synonym-aware)
    validate.ts                      # validate_snippet (11 rules)
    suggest.ts                       # suggest_component (30 entries)
Dockerfile
fly.toml

Roadmap

Out of scope for v0.3, candidates for next iteration:

• Multi-theme support (Zona Sul and other clients as override layers).

• validate_snippet: semantic copy lint (e.g. "Erro: ..." string detection).

• suggest_component: broader UI primitive coverage (TableHeader, Pagination states, EmptyState variants).

• get_screen(name): return a parent component + all its children in one call.

• shadcn/ui compatibility layer (map Grocers semantic tokens → --primary/--background etc.).