# Brandcode MCP

> Make your brand machine-readable. Extract identity from any website into tokens and policies.

- **Type:** MCP server
- **Install:** `agentstack add mcp-brand-system-brandsystem-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Brandcode-Studio](https://agentstack.voostack.com/s/brandcode-studio)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.4.3
- **License:** MIT
- **Upstream author:** [Brandcode-Studio](https://github.com/Brandcode-Studio)
- **Source:** https://github.com/Brandcode-Studio/brandsystem-mcp
- **Website:** https://brandsystem-mcp.vercel.app

## Install

```sh
agentstack add mcp-brand-system-brandsystem-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://github.com/Brandcode-Studio/brandsystem-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@brandsystem/mcp)
[](https://www.npmjs.com/package/@brandsystem/mcp)
[](https://glama.ai/mcp/servers/Brandcode-Studio/brandsystem-mcp)
[](https://www.npmjs.com/package/@brandsystem/mcp)
[](https://lobehub.com/mcp/brandcode-studio-brandsystem-mcp)

# @brandsystem/mcp — Build

**The authoring tool for the portable `.brand` runtime.** Extract identity from websites, Figma, and PDFs. Compile governance, tokens, and voice rules into a single `.brand/` directory. Deploy that runtime to Claude Design, Claude Code, Cursor, ChatGPT — every surface that can read a governed brand. One artifact, every surface on brand.

## What It Solves

AI tools default to category-average output because they have no brand context. Brand guidelines live in PDFs, Figma files, and people's heads — none of which AI tools can read at the moment of creation. The dominant failure mode isn't "broken output"; it's "correct but generic" — output that passes mechanical checks but reads like a competent generalist could have made it.

This MCP server is the authoring half of the **"Two MCPs, One Brand"** model. It extracts brand identity from live sources, compiles it into a `.brand/` directory with structured governance (anti-patterns, proof-point status, voice rules, application rules) plus DTCG tokens, brand-runtime.json, and interaction-policy.json. That directory is the **portable brand runtime** — the artifact that travels with your brand from surface to surface.

- **Claude Design** reads the `.brand/` directory natively when pointed at a governed repo
- **Claude Code**, **Cursor**, **ChatGPT**, **Windsurf**, and any other MCP client load `brand-runtime.json` at generation time
- **@brandcode/mcp** (the hosted Use MCP) serves the same runtime over HTTP for teams that want authenticated live reads at `mcp.brandcode.studio/{slug}`

With brand-runtime.json loaded, agent prompts collapse from 200-400 tokens of inline brand context to just the delta. First output is on-brand. No review bottleneck.

---

## Quick Start

### 1. Add to your MCP config

Copy this into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), or Windsurf MCP settings:

```json
{
  "mcpServers": {
    "brandsystem": {
      "command": "npx",
      "args": ["-y", "@brandsystem/mcp"]
    }
  }
}
```

### 2. Create your brand system

Tell your AI tool:

> Run brand_start with client_name="Acme Corp", website_url="https://acme.com", and mode="auto"

That single command extracts colors, fonts, and logo from the website, escalates to rendered or deeper multi-page extraction when the cheap pass is weak, compiles DTCG tokens, generates `design-synthesis.json` + `DESIGN.md`, and generates a portable HTML brand report -- all in under 60 seconds.

### 3. What you get

```
.brand/
  brand.config.yaml          ← brand name, source URLs, session state
  core-identity.yaml         ← colors (with roles), fonts, logo specs
  tokens.json                ← DTCG design tokens
  brand-runtime.json         ← single-file brand context for any AI agent
  interaction-policy.json    ← anti-patterns, voice constraints, never-say words
  design-synthesis.json      ← spacing, radius, shadows, component signals
  DESIGN.md                  ← portable design brief (agent-readable)
  brand-report.html          ← visual report (paste into any AI chat)
  assets/logo/               ← extracted logo files (SVG/PNG)
```

Load `brand-runtime.json` into any sub-agent's context. First output is on-brand. No per-prompt boilerplate.

### 4. Use it

> Run brand_write for a social-graphic about "Q3 product launch"

The AI now has your full brand context — colors, typography, logo, anti-patterns, voice rules — and generates on-brand content.

### 5. Go deeper (optional)

| Session | What it adds | Command |
|---------|-------------|---------|
| 1. Core Identity | Colors, fonts, logo, tokens | `brand_start` (done above) |
| 2. Visual Identity | Composition, anti-patterns, illustration style | `brand_deepen_identity` |
| 3. Messaging | Voice, tone, never-say words, brand story | `brand_compile_messaging` |
| 4. Content Strategy | Personas, journey stages, themes | `brand_build_personas` |

Each session enriches `brand-runtime.json`. Stop at any point — Session 1 alone is valuable.

### 6. Share with your team

> Run brand_brandcode_connect to save on Brandcode Studio

Your brand persists on [brandcode.studio](https://brandcode.studio). Teammates pull the same brand into their tools. One source of truth.

---

## What It Does

**Session 1: Core Identity** -- Extract colors, fonts, and logo from a website or Figma file. Compile into DTCG tokens, a structured design synthesis layer, a portable `DESIGN.md`, and an HTML report.

**Session 2: Visual Identity** -- Define composition rules, pattern language, illustration style, and anti-patterns through a guided interview. Anti-patterns become enforceable compliance rules.

**Session 3: Messaging** -- Audit existing website voice, then define perspective, voice codex (tone, vocabulary, AI-ism detection), and brand story through a guided interview.

**Session 4: Content Strategy** -- Build buyer personas, journey stages, editorial themes, and a persona x stage messaging matrix.

Each session builds on the previous. Stop anywhere -- you get value immediately.

### Two Ways To Use It

**Local-first MCP flow** -- Start from a website or Figma file, build a `.brand/` directory locally, and use it immediately in chat or code tools with no account required.

**Brandcode Studio-connected flow** -- Connect an existing hosted brand from Brandcode Studio, pull the packaged brand into `.brand/`, and keep it synced over time.

### Two MCPs, One Brand

The `.brand` runtime is the product. Two MCPs serve it:

**`@brandsystem/mcp` — Build (this package).** Author and compile the `.brand` runtime locally. Extract from websites, Figma, and PDFs. Compile governance (anti-patterns, proof-point status, voice rules, application rules) plus DTCG tokens, brand-runtime.json, and interaction-policy.json into a single `.brand/` directory. Portable, versionable, ready to commit to any repo.

**`@brandcode/mcp` — Use (hosted).** Connect authorized MCP clients to the live Full Brand Runtime at `https://mcp.brandcode.studio/{slug}` with Brandcode bearer-key auth. Agents fetch the current runtime, search approved knowledge, check drafts, retrieve package-safe assets, leave append-only review feedback, and, with explicit `capture` scope, queue taste captures for human review — no per-tool guideline copy, no stale snapshots, no canonical mutation from the MCP. Tagline: *"Your brand, live in every AI tool."*

Same `.brand` runtime artifact. Two consumption paths. Build authors it; Use serves it.

Phase 0 for Brandcode MCP is locked in [specs/brandcode-mcp-phase-0-lock.md](specs/brandcode-mcp-phase-0-lock.md) as the original 8-tool read/append-only surface. The current hosted implementation adds `capture_taste` as a scoped contribute-tier tool: it requires explicit `capture` scope, queues a review candidate through UCS, and never promotes canon. Staging proof is command-backed at `https://mcp.staging.brandcode.studio/{slug}`. The hosted-service posture is approved for pre-release authorized access, and the hosted router supports durable shared Redis REST rate limiting when the hosted store env is configured, with in-process fallback for local/pre-release development. Pre-release abuse response is owned by Jason Lankow / Brandcode Studio Ops at `jlankow@columnfive.com`. The hosted data-policy draft now states client-owned/client-controlled brand data, append-only feedback, scoped/redacted history, package-safe custody, and the accepted deletion/export operating posture: brand owner/admin, recorded legal/contract contact, or Jason authorization; manual ops review; curated support-packet export; and no public SLA or self-serve deletion/export. For v0.1 limited-client work, public `@brandcode/mcp` package/source distribution is deferred; approved clients use the hosted service with brand-scoped bearer keys only after client/brand approval, scoped key issuance, per-client smoke proof, support/abuse/deletion/export intake, package-safe custody checks, the key operations runbook, support intake ledger, and limited-client go/no-go checklist. The limited-client onboarding template is in [specs/brandcode-mcp-limited-client-onboarding-template.md](specs/brandcode-mcp-limited-client-onboarding-template.md), the key operations runbook is in [specs/brandcode-mcp-limited-client-key-ops-runbook.md](specs/brandcode-mcp-limited-client-key-ops-runbook.md), the support intake ledger is in [specs/brandcode-mcp-limited-client-support-intake-ledger.md](specs/brandcode-mcp-limited-client-support-intake-ledger.md), the go/no-go checklist is in [specs/brandcode-mcp-limited-client-go-no-go-checklist.md](specs/brandcode-mcp-limited-client-go-no-go-checklist.md), the deletion/export launch decision brief is in [specs/brandcode-mcp-deletion-export-launch-decision-brief.md](specs/brandcode-mcp-deletion-export-launch-decision-brief.md), and an internal Column Five Brandcode staging proof is in [specs/brandcode-mcp-column-five-brandcode-staging-onboarding-proof.md](specs/brandcode-mcp-column-five-brandcode-staging-onboarding-proof.md). The operational roadmap for the remainder of M001 through the first half of M003 is in [specs/brandcode-mcp-operational-roadmap-m001-m003.md](specs/brandcode-mcp-operational-roadmap-m001-m003.md). Production release is still gated by final legal/subprocessor launch language, future public package/source approval, directory metadata, and explicit Jason approval; see [specs/brandcode-mcp-limited-client-readiness-plan.md](specs/brandcode-mcp-limited-client-readiness-plan.md), [specs/brandcode-mcp-hosted-data-policy.md](specs/brandcode-mcp-hosted-data-policy.md), [specs/brandcode-mcp-hosted-terms-rate-limit-gate.md](specs/brandcode-mcp-hosted-terms-rate-limit-gate.md), and [specs/brandcode-mcp-hosted-service-terms-decision-brief.md](specs/brandcode-mcp-hosted-service-terms-decision-brief.md). Until the production launch, use `@brandsystem/mcp` for local build/sync, and Live Mode (`brand_brandcode_live`) for connected reads that refresh from the hosted runtime within a short cache TTL.

The Use MCP roadmap alignment lives in [specs/brandcode-mcp-use-roadmap-alignment.md](specs/brandcode-mcp-use-roadmap-alignment.md).

Hosted proof is command-backed through:

```bash
BRANDCODE_MCP_SMOKE_URL="https://mcp.staging.brandcode.studio/{slug}" \
BRANDCODE_MCP_SMOKE_FULL_KEY="bck_test_..." \
BRANDCODE_MCP_SMOKE_READ_KEY="bck_test_..." \
npm run smoke:hosted-mcp
```

The smoke harness verifies MCP `initialize`, `tools/list`, the locked hosted order, core hosted tool calls, and read-only insufficient-scope behavior for `brand_check`, `brand_feedback`, and `capture_taste`. It never hardcodes keys; missing optional proof inputs are reported as `blocked` or `skipped` with the exact env or hosted dependency.

### Claude Design integration

The `.brand/` directory is engineered as a first-class input for [Claude Design](https://www.anthropic.com/news/claude-design). Point Claude Design at a repo that contains `.brand/` — governance YAML, narrative library, proof-point files, taste notes, DTCG tokens — and it grounds on the governed brand instead of improvising from uploaded assets. This is the Deploy path: author once with `@brandsystem/mcp`, then every Anthropic surface (Claude Design, Claude Code, Chat via compile packs) consumes the same runtime.

---

## Tools Reference

### Entry Points

| Tool | What it does |
|------|-------------|
| `brand_start` | **Begin here.** Creates a brand system from a website URL in under 60 seconds. Use `mode='auto'` for one-call setup with rendered and deep-site fallback on weak JS-rendered sites. |
| `brand_status` | Check progress, get next steps, or see a getting-started guide if no brand exists yet. |

### Session 1: Core Identity

| Tool | What it does |
|------|-------------|
| `brand_extract_web` | Extract logo (SVG/PNG), colors, and fonts from any website URL. |
| `brand_extract_visual` | Screenshot the rendered page in headless Chrome and extract computed colors, fonts, and visual context from JS-heavy sites. |
| `brand_extract_site` | Discover representative pages, render them across desktop and mobile, capture screenshots, sample multiple components, and persist `extraction-evidence.json`. |
| `brand_generate_designmd` | Generate `design-synthesis.json` and `DESIGN.md` from extracted evidence or the current brand state. |
| `brand_extract_figma` | Extract from Figma design files (higher accuracy). Two-phase: plan then ingest. |
| `brand_set_logo` | Add/replace logo via SVG markup, URL, or data URI. |
| `brand_compile` | Generate DTCG design tokens, brand runtime contract, and interaction policy from extracted data. |
| `brand_clarify` | Resolve ambiguous brand values interactively (color roles, font confirmations). |
| `brand_audit` | Validate .brand/ directory for completeness and correctness. |
| `brand_report` | Generate portable HTML brand report. Upload to any AI chat as instant guidelines. |
| `brand_init` | Low-level directory scaffolding. Prefer `brand_start` instead. |

### Session 2: Visual Identity

| Tool | What it does |
|------|-------------|
| `brand_deepen_identity` | Define composition rules, patterns, illustration style, and anti-patterns (6 interview sections). |
| `brand_ingest_assets` | Scan and catalog brand assets with MANIFEST.yaml metadata. |
| `brand_preflight` | Check HTML/CSS against brand rules -- catches off-brand colors, wrong fonts, anti-pattern violations. |

### Session 3: Messaging

| Tool | What it does |
|------|-------------|
| `brand_extract_messaging` | Audit existing website voice -- fingerprint, vocabulary, claims, AI-isms, gaps. |
| `brand_compile_messaging` | Define perspective, voice codex (tone, vocabulary, AI-ism detection), and brand story. |

### Session 4: Content Strategy

| Tool | What it does |
|------|-------------|
| `brand_build_personas` | Build buyer personas through a 7-question guided interview. |
| `brand_build_journey` | Define buyer journey stages (ships with 4 proven defaults). |
| `brand_build_themes` | Define editorial content themes balanced across awareness, engagement, and conversion. |
| `brand_build_matrix` | Generate messaging variants for every persona x journey stage combination. |

### Content Scoring

| Tool | What it does |
|------|-------------|
| `brand_audit_content` | Score content against brand rules (0-100) across multiple dimensions. |
| `brand_check_compliance` | Quick pass/fail compliance gate before publishing. |
| `brand_audit_drift` | Detect systematic brand drift across multiple pieces of content. |

### Runtime + Utilities

| Tool | What it does |
|------|-------------|
| `brand_runtime` | Read the compiled brand runtime contract (single-document brand context for AI agents). |
| `brand_write` | Load full brand context (visual + voice + strategy) for content generation. |
| `brand_export` | Generate portable brand files for Chat, Code, team sharing, or email. |
| `brand_feedback` | Report bugs, friction, or feature ideas to the brandsystem team. |

### Brandcode Studio Connector

| Tool | What it does |
|------|-------------|
| `brand_brandcode_connect` | Connect a local `.brand/` directory to a hosted Brandcode Studio brand and pull the current package. |
| `brand_brandcode_sync` | Pull updates from a previously connected hosted brand using sync-token-aware delta behavior. |
| `brand_brandcode_status` | Inspect the current Brandcode Studio connection, sync history, and local package summary. |
| `brand_brandcode_live` | Toggle connected read tools to refresh from the hosted runtime within a short cache TTL. |

### Tool Flow

Tools auto-chain -- each tool's response

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Brandcode-Studio](https://github.com/Brandcode-Studio)
- **Source:** [Brandcode-Studio/brandsystem-mcp](https://github.com/Brandcode-Studio/brandsystem-mcp)
- **License:** MIT
- **Homepage:** https://brandsystem-mcp.vercel.app

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.4.3 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.4.3** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-brand-system-brandsystem-mcp
- Seller: https://agentstack.voostack.com/s/brandcode-studio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.