# Brand Kit MCP

An open-source MCP server that gives any AI tool a brand to follow. It serves a **Brand Kit**, a small folder of plain files describing how a brand looks, sounds and adapts to different formats, and checks AI output against it.

Connect it to Claude, ChatGPT, Figma Make, Replit or Cursor, and what they make comes out on-brand.

All tools are plain code. The server never calls an AI model, so it runs free on Cloudflare's free plan.

## Tools

| Tool | What it does |
| --- | --- |
| `get_brand_overview` | Identity, audience, values, facts and guardrails. The AI calls this first. |
| `get_tokens` | Exact colours with roles, fonts, spacing, radius (DTCG format). |
| `get_rules` | Visual or voice rules, each marked **must** or **should**, with reasons. |
| `get_format_recipe` | How the brand translates to LinkedIn posts, carousels and slides. |
| `suggest_layouts` | Three different on-brand layouts for a piece of content, so designs vary. |
| `get_examples` | On-brand work, labelled as examples rather than templates. |
| `check_design` | Checks HTML, CSS or SVG: palette, near-miss colours, fonts, corners, decoration, contrast. |
| `check_copy` | Checks text: spelling variant, em dashes, words to avoid, LinkedIn rules. |
| `read_website_styles` | Reads a public site's CSS: exact colours, variables, fonts, sizes, spacing, ranked by use. |

## Run it on your computer

You need [Node.js](https://nodejs.org) 20 or newer.

```bash
npm install
npm run dev
```

The server runs at `http://localhost:8787/mcp`. In a second terminal, run the smoke test, which connects like a real AI tool and calls every tool:

```bash
npm test
```

To try it inside Claude Code while it runs locally:

```bash
claude mcp add --transport http brand-kit http://localhost:8787/mcp
```

## Put it online (free)

1. Create a free [Cloudflare](https://dash.cloudflare.com/sign-up) account.
2. In this folder, run:

   ```bash
   npx wrangler login
   npm run deploy
   ```

3. Wrangler prints your server's address, like `https://brand-kit-mcp.<your-subdomain>.workers.dev`. Your connector URL is that address plus `/mcp`.

The free plan allows 100,000 requests a day.

### Use your own domain

Once your domain's DNS is managed by Cloudflare, uncomment the `routes` line in `wrangler.jsonc` and deploy again. For example, `brandkit.soraiasoares.com/mcp`.

## Connect it to AI tools

Add the connector URL as a custom MCP connector in each tool. Menus change often, so check each tool's help if these names have moved.

- **Claude Code:** `claude mcp add --transport http brand-kit https://<your-address>/mcp`
- **Claude (web and desktop):** custom connectors in Settings. Some users have reported that claude.ai asks public servers without login to set one up; if that happens, use Claude Code or Claude Desktop meanwhile.
- **ChatGPT:** turn on Developer Mode, then create a custom connector with the URL. Needs a paid plan.
- **Replit:** Integrations, then MCP Servers for Replit Agent, then Add MCP server.
- **Figma Make and the Figma agent:** custom connectors. Needs a paid plan and a public HTTPS address (not localhost).
- **Cursor and VS Code:** add the URL as a remote MCP server.

## Add your own kit

1. Copy `kits/soraia-soares` to `kits/<your-id>` and replace the files with your brand's:
   - `brand.md`: identity, audience, values, facts and guardrails
   - `tokens.json`: colours, fonts, spacing, radius (DTCG format)
   - `visual-rules.md` and `voice.md`: rules as `- id (must|should): one sentence`
   - `formats.md`: motifs, constants, variables, format recipes, archetypes
   - `examples/README.md`: on-brand work
2. Import the files in `src/kits.ts` and add an entry to `KITS`.
3. Your kit is served at `/kits/<your-id>/mcp`. Set `DEFAULT_KIT` in `wrangler.jsonc` to serve it at `/mcp`.

The checks read your kit: `check_copy` only applies a rule like `no-em-dash` or `british-english` if your `voice.md` declares it.

**Privacy:** anyone with the URL can read the kit. Keep confidential material out of it, or deploy your own private copy.

## Project structure

```
kits/<id>/          the Brand Kit files
src/index.ts        routes: /, /mcp, /kits/<id>/mcp
src/server.ts       the MCP tools
src/checks.ts       check_design and check_copy
src/styles.ts       read_website_styles
src/layouts.ts      suggest_layouts
test/smoke.mjs      end-to-end test with a real MCP client
```

## Licence

MIT