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.

Related MCP server: @prosodyai/mcp-docs

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

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers