Brandcode MCP

[](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:

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

2. Create your brand system

Tell your AI tool:

> Run brandstart with clientname="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 brandbrandcodeconnect to save on Brandcode Studio

Your brand persists on 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:

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. 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
• Source: Brandcode-Studio/brandsystem-mcp
• License: MIT
• Homepage: https://brandsystem-mcp.vercel.app

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