# BrandKit MCP

> Give every AI tool access to your company's complete brand atomic system via the Model Context Protocol.

[![npm version](https://img.shields.io/npm/v/brandkit-mcp)](https://www.npmjs.com/package/brandkit-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node 20+](https://img.shields.io/badge/Node-20%2B-green.svg)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org)
[![ejwhite7/brandkit-mcp MCP server](https://glama.ai/mcp/servers/ejwhite7/brandkit-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ejwhite7/brandkit-mcp)

BrandKit MCP v2 is an open-source MCP server that exposes a company's complete **brand atomic system** -- verbal identity (positioning, audience, messaging, differentiation, concepts, voice) and visual identity (colors, typography, components, tokens, motion, assets) -- to Claude and other AI tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). It ships 18 tools and 14 resources. When an LLM helps build a website, app, or marketing asset, it has instant structured access to the exact brand language and visual rules it needs -- including a human-authored taste primer that carries the brand's instincts, not just its specs.

## Quick Start

```bash
# 1. Install
npm install -g brandkit-mcp

# 2. Scaffold a new brand atomic system from the starter template
brandkit-mcp init

# 3. Edit the scaffolded files with your brand content

# 4. Wire into Claude Desktop (or any MCP-compatible client)
#    Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
#    {
#      "mcpServers": {
#        "brandkit": {
#          "command": "brandkit-mcp",
#          "args": ["serve"]
#        }
#      }
#    }
```

## Repository Structure

A brand atomic system lives under a single `<brand-root>/` directory (default: `./brand_atomic_system`):

```
<brand-root>/
├── readme.md
├── magic_trick.md               # human-authored taste primer
├── brandkit.config.yaml         # version: 2
├── human/                       # PDFs and human-only material (MCP ignores)
│   └── *.pdf
└── agent/
    ├── verbal/
    │   ├── positioning.md
    │   ├── audience.yaml
    │   ├── messaging.md
    │   ├── differentiation.md
    │   ├── concepts.md
    │   └── voice.md
    └── visual/
        ├── colors_and_type.css
        ├── fonts/
        ├── assets/
        ├── components/
        ├── tokens/
        ├── motion/
        │   ├── motion.json
        │   └── motion.css
        └── artifacts/
            ├── web/             # override layer
            └── product/         # override layer
```

The `human/` directory is intentionally ignored by the MCP server -- put PDFs, print specs, or any other human-only material there. Everything under `agent/` is indexed and served.

## MCP Tools Reference

BrandKit MCP exposes 18 tools to AI assistants:

| Tool | Description |
|------|-------------|
| `get_brand_overview` | High-level overview + taste primer |
| `get_magic_trick` | Verbatim magic_trick.md |
| `get_positioning` | Positioning document |
| `get_audience` | Audience YAML, parsed |
| `get_messaging` | Messaging document |
| `get_differentiation` | Differentiation document |
| `get_concepts` | Creative concepts/directions |
| `get_voice` | Voice document |
| `get_colors_and_type` | Colors + typography custom properties |
| `get_assets` | Logos + brand assets |
| `get_fonts` | Font faces |
| `get_components` | UI primitives |
| `get_tokens` | Token specimens |
| `get_motion` | Motion system (json + css) |
| `get_css` | colors_and_type.css + motion.css text |
| `search_brand` | Full-text search |
| `validate_usage` | Validate brand compliance |
| `get_context_diff` | Diff base vs web vs product |

### Taste primer

Seven creative/verbal tools (`get_brand_overview`, `get_positioning`, `get_audience`, `get_messaging`, `get_differentiation`, `get_concepts`, `get_voice`) inject a `_taste_primer` field carrying `magic_trick.md` verbatim. `get_magic_trick` returns the primer directly without wrapping.

## MCP Resources

BrandKit MCP exposes 14 `brand://` URIs as MCP resources:

| URI | Description |
|-----|-------------|
| `brand://overview` | Brand overview |
| `brand://magic_trick` | Taste primer |
| `brand://verbal/positioning` | Positioning document |
| `brand://verbal/audience` | Audience YAML |
| `brand://verbal/messaging` | Messaging document |
| `brand://verbal/differentiation` | Differentiation document |
| `brand://verbal/concepts` | Creative concepts |
| `brand://verbal/voice` | Voice document |
| `brand://visual/colors_and_type` | Colors + typography CSS |
| `brand://visual/assets` | Asset index |
| `brand://visual/fonts` | Font face index |
| `brand://visual/components` | Component index |
| `brand://visual/tokens` | Token specimens |
| `brand://visual/motion` | Motion system |

## Configuration

The `brandkit.config.yaml` file at your project root controls BrandKit MCP:

```yaml
version: 2
brand:
  name: Acme Corp
  description: Plumbing for builders.
  root: ./brand_atomic_system
contexts: [base, web, product]
ignore:
  - human/
```

`version: 2` is required. A config file missing this field or declaring `version: 1` causes the server to throw `BrandkitV1ConfigError` at startup.

## Context System

BrandKit v2 supports three contexts:

| Context | Purpose |
|---------|---------|
| `base` | Shared foundation -- fonts, core colors, global tokens |
| `web` | Overrides for the public-facing website (`agent/visual/artifacts/web/`) |
| `product` | Overrides for the SaaS application (`agent/visual/artifacts/product/`) |

Verbal content (`agent/verbal/`) has no context overrides -- it applies globally. Visual content can be overridden per context via the `artifacts/` layer.

## Migrating from v1

**2.0.0 is a breaking release.** The directory layout, context vocabulary, and tool surface have all changed. No automated migration is included -- the path mapping is manual:

| v1 path | v2 path |
|---------|---------|
| `brand/shared/colors/*.css` | `agent/visual/colors_and_type.css` |
| `brand/shared/typography/*.css` | `agent/visual/colors_and_type.css` |
| `brand/shared/logos/*` | `agent/visual/assets/` |
| `brand/shared/components/*.md` | `agent/visual/components/*.md` |
| `brand/shared/voice/brand-voice.md` | `agent/verbal/voice.md` |
| `brand/shared/guidelines/*.md` | `agent/verbal/{positioning,messaging,differentiation,concepts}.md` |
| `brand/marketing/*` | `agent/visual/artifacts/web/*` |
| `brand/product/*` | `agent/visual/artifacts/product/*` |

Your `brandkit.config.yaml` must also be updated to declare `version: 2` and use the new `brand.root` field. v1 configs throw `BrandkitV1ConfigError` at startup -- the server will not start until the config is updated.

## Conventions

**`magic_trick.md` is human-authored.** The MCP reads it but no tool writes to it. If write tools are added in a future version, they must denylist this path. The taste primer is the brand's instincts -- it must stay human.

**Token output formats.** The `get_tokens` tool supports CSS custom properties, SCSS variables, Tailwind config, W3C Design Tokens, and flat JSON.

**Transports.** The server supports stdio (recommended for Claude Desktop), SSE (legacy HTTP), and Streamable HTTP (current MCP spec).

## CLI Reference

```
brandkit-mcp <command> [options]

Commands:
  init [directory]      Scaffold a brand atomic system from the starter template
  validate [config]     Validate configuration and scan for issues
  serve                 Start the MCP server
  preview               Start the local preview UI for browsing the brand atomic system
  docs                  Generate project documentation files

Global Options:
  --version             Show version number
  --help                Show help
```

## Contributing

Contributions are welcome.

```bash
git clone https://github.com/ejwhite7/brandkit-mcp
cd brandkit-mcp
npm install
npm run build
npm test
```

- TypeScript strict mode
- ESM imports with `.js` extensions
- No `any` types -- use proper interfaces
- Tests use Vitest

## License

MIT -- see [LICENSE](LICENSE) for details.

---

Built with the [Model Context Protocol](https://modelcontextprotocol.io) by [Anthropic](https://anthropic.com).