Use existing brand guidelines with AI. Turn websites, PDFs, and Figma into a .brand runtime.
This MCP server helps use existing brand guidelines with AI, producing a “.brand runtime.” It is positioned for turning design and content inputs—such as websites, PDFs, and Figma—into a format suitable for brand system execution. The server is associated with Model Context Protocol (MCP).
🛠️ Key Features
Uses existing brand guidelines with AI
Converts inputs like websites, PDFs, and Figma into a “.brand runtime”
🚀 Use Cases
Brand governance workflows
Building or maintaining brand identity and brand voice standards
Applying brand guidelines across design and content sources
⚡ Developer Benefits
Supports MCP-based integration
Uses themes such as design tokens and brand design systems via a consistent runtime output
⚠️ Limitations
Limited to what is explicitly described: websites, PDFs, and Figma conversion into a “.brand runtime”
No additional operational details (e.g., specific tools or configuration) are provided
@brandsystem/mcp turns the brand material you already have into context AI agents can use. Give it a website, PDF guide, Figma library, local files, or a Brandcode Studio brand. It produces a portable .brand/ runtime with design tokens, voice rules, provenance, and compliance checks.
Local-first. No account required. The default Core profile exposes 12 tools covering the complete adopt → use → check loop.
Start here
Install it for your agent, then ask: “How do I use my brand guidelines with AI?”
bash
# Codex
npx @brandsystem/mcp install --client codex --write
# Claude Code, Cursor, Windsurf, or Claude Desktop
npx @brandsystem/mcp install --client claude-code --write
# Cline
npx @brandsystem/mcp install --client cline --write
install is a dry run unless you pass --write. Replace claude-code with cline, cursor, windsurf, or claude-desktop as needed. JSON-file targets preserve existing settings; Cline and Codex setup delegate to their official MCP commands so their current schemas remain authoritative. Agents can follow the compact installation guide without reading this entire README.
Already configured? Tell your agent:
Use my existing brand guidelines with AI. Start from this website/PDF/Figma library and show me what needs human confirmation.
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, Claude Desktop, Cursor, and Windsurf connect to this server directly over stdio and load brand-runtime.json at generation time
ChatGPT and other remote-first clients consume the same runtime as an uploaded artifact (brand-report.html / brand-runtime.json) or via a remote MCP connection — see Compatibility
@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. Codex users can run npx @brandsystem/mcp install --client codex --write instead:
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
code
.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. 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 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 for human review, and never promotes canon.
Hosted availability: Brandcode MCP is pre-release and available to approved clients only — it is not yet publicly launched or registry-listed. Brand data on the hosted service is client-owned; feedback is append-only; agent history is scoped and redacted. Deletion and export requests are handled through your Brandcode Studio contact. Until public 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.
Maintainers can verify a hosted deployment end-to-end with the smoke harness (npm run smoke:hosted-mcp with BRANDCODE_MCP_SMOKE_URL and scoped test keys). It verifies MCP initialize, tools/list, the locked hosted tool order, core hosted tool calls, and read-only insufficient-scope behavior. It never hardcodes keys; missing proof inputs are reported as blocked or skipped.
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
Tool Profiles (0.10+)
By default the server registers the Core profile — 12 tools covering the complete loop: adopt → runtime/context → create → check → export, plus the Studio connector entry points and the clarify/promote path. This keeps first-tool selection sharp for agents.
The full profile registers the entire authoring system (all tools below). Opt in via env or args:
Or set BRANDSYSTEM_PROFILE=full. Core tools: brand_start, brand_status, brand_runtime, brand_context, brand_check, brand_preflight, brand_report, brand_export, brand_clarify, brand_compile, brand_brandcode_auth, brand_brandcode_connect.
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.
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_context
Select a task-scoped slice of the runtime deterministically (task_type → sections, audience → persona match, compact budget). Returns matched selectors and explicit no-match — never silent fallback.
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 tells the LLM what to run next:
install never overwrites other servers' entries: it deep-merges, backs up the existing file first, and refuses invalid JSON. For protected hosted brands, add --share-token=TOKEN.
The .brand/ Directory
After running the full pipeline, your .brand/ directory looks like this:
All extracted brand data: colors (with roles and confidence), typography (with families and weights), logo specs (with inline SVG and data URIs), spacing
extraction-evidence.json
JSON
Multi-page rendered evidence captured from representative pages and viewports. Contains screenshots, computed elements, and CSS custom properties used to ground synthesis
design-synthesis.json
JSON
Structured design interpretation of the brand. Includes radius, shadow, spacing, layout, component, motion, and personality signals derived from evidence and current identity
DESIGN.md
Markdown
Portable agent-facing design brief synthesized from the evidence bundle and current brand state
tokens.json
JSON
DTCG design tokens. Includes colors and typography plus synthesis-driven radius, shadow, layout, spacing, and motion groups when available
brand-runtime.json
JSON
Single-document brand contract for AI agents. Merges all 4 session YAMLs into flat, fast-access format. Only medium+ confidence values. Compiled by brand_compile, read by brand_runtime
interaction-policy.json
JSON
Enforceable rules engine. Visual anti-patterns, voice constraints (never-say, AI-ism patterns), and content claims policies. Used by preflight and scoring tools
needs-clarification.yaml
YAML
Prioritized list of items the system could not resolve confidently: missing primary color, low-confidence values, unassigned roles
brand-report.html
HTML
Self-contained brand report. Works offline, embeds all assets inline. Paste into any AI tool as brand guidelines
assets/logo/
SVG/PNG
Extracted logo files. SVGs include inline path data in core-identity.yaml for portability
Platform Setup
Codex
Use the package installer, which delegates to Codex's official MCP configuration command:
Start a new Cline task, then ask: “How do I use my brand guidelines with AI?” Cline CLI and the IDE extension share the same global configuration at ~/.cline/data/settings/cline_mcp_settings.json.
Three distinct ways to get your brand into an AI tool — don't conflate them:
Path
Clients
What it takes
Direct local MCP (stdio)
Claude Code, Claude Desktop, Cursor, Windsurf
The .mcp.json config above — the server runs on your machine
Remote hosted MCP
ChatGPT (developer mode) and other remote-MCP clients
An approved Brandcode Studio brand + bearer key (pre-release, approved clients only). ChatGPT connects to remote MCP servers, not local stdio processes; OpenAI documents a secure-tunnel option for private servers
Runtime artifact copy
Any AI tool
Upload brand-report.html or brand-runtime.json to the conversation — no MCP connection needed
Claude Chat (no MCP)
If you are using Claude Chat without MCP support:
Run the pipeline in a code environment first to generate brand-report.html
Upload the HTML file to your Claude Chat conversation
Say: "Use this as my brand guidelines for everything we create"
The report HTML is self-contained and works as a standalone brand reference in any AI tool.
Troubleshooting
"No .brand/ directory found"
Every tool except brand_start, brand_init, and brand_feedback requires a .brand/ directory. Run brand_start first.
If you are using the hosted-brand flow instead of local extraction, brand_brandcode_connect also scaffolds .brand/ automatically on first connect.
Empty extraction (no colors or fonts found)
This usually means the website loads CSS dynamically via JavaScript. brand_extract_web only parses static CSS from <style> blocks and linked stylesheets. Solutions:
Run brand_extract_visual to analyze a single rendered page with headless Chrome and computed styles
Run brand_extract_site to sample representative pages across desktop and mobile and save extraction-evidence.json
Run brand_generate_designmd after extraction or manual edits to regenerate design-synthesis.json and DESIGN.md
Try a different page that uses more inline/linked CSS (e.g., the homepage, a blog post)
Use Figma extraction (brand_extract_figma) for higher accuracy
Set values manually using brand_clarify after extraction
brand_start in mode='auto' already tries this visual fallback when extraction quality is low and Chrome/Chromium is available, then generates design-synthesis.json and DESIGN.md from the best available evidence.
Figma extraction fails
brand_extract_figma doesn't connect to Figma directly. It works in two phases:
Plan returns instructions for what data to fetch (variables, styles, logo)
Ingest processes data you pass back from the Figma MCP tools
Make sure you have a separate Figma MCP server connected (e.g., @anthropics/figma-mcp) and pass the fetched data to brand_extract_figma in ingest mode.
Logo not detected
Web extraction looks for <img>, <svg>, and <link rel="icon"> elements. If your logo is rendered via JavaScript or embedded as a CSS background, use brand_set_logo to add it manually with SVG markup, a URL, or a data URI.
This is a soft warning, not an error. Some tools (brand_write, brand_deepen_identity) return rich conversation guides that exceed 5K characters. The hard limit is 50K, which triggers truncation.
Server won't start
bash
# Verify Node.js >= 20.18.1
node --version
# Test the server manually
npx @brandsystem/mcp
# Check for port conflicts (stdio transport shouldn't have any)# The server uses stdio, not HTTP -- it reads from stdin and writes to stdout
Reporting feedback
Use brand_feedback to report bugs, friction, or ideas:
code
brand_feedback with category="bug", summary="Logo SVG has empty gradient stops",
detail="The extractor found the SVG structure but <linearGradient> stops have no
stop-color attributes. Logo renders as a black rectangle.",
tool_name="brand_extract_web", severity="degrades_experience"
For agent telemetry, use category="agent_signal" with signal, tool_used, and signal_context. Brand context is auto-populated from .brand/config.
How It Works
Confidence Scoring
Every extracted value carries a confidence level:
Level
Meaning
Token Behavior
confirmed
Human-verified
Included in tokens
high
Strong signal (e.g., Figma variable, CSS custom property named --brand-primary)
Included in tokens
medium
Reasonable inference (e.g., most-frequent chromatic color in CSS)
Included in tokens
low
Weak signal (e.g., color appears once in a generic property)
Excluded from tokens, added to needs-clarification.yaml
Source Precedence
When the same brand element is found in multiple sources, the higher-precedence source wins:
code
figma > manual > web
A Figma-sourced primary color will replace a web-extracted one. A manually confirmed value overrides both automated sources. Within the same source, higher confidence wins.
Web Extraction
brand_extract_web fetches the target URL and:
Parses all <style> blocks and up to 5 linked stylesheets
Extracts color values from CSS properties and custom properties
Infers color roles from property names (e.g., --primary, --brand-accent)
Promotes the most-frequent chromatic color to "primary" if no explicit primary is found
Extracts font families and ranks by frequency
Finds logo candidates from <img>, <svg>, and <link rel="icon"> elements
Downloads and embeds logos as inline SVG or base64 data URIs
Visual Extraction
brand_extract_visual launches headless Chrome against the target URL and:
Captures a 2x DPR screenshot of the rendered page
Extracts computed styles from semantic elements such as body, header, hero, links, cards, and buttons
Reads CSS custom properties from :root
Infers likely color roles from visual context (for example, button background → primary)
Returns the screenshot as an MCP image block so the calling agent can do qualitative visual analysis
This is the fallback path for JS-rendered apps and page builders where static CSS parsing misses key brand signals.
Deep Site Extraction
brand_extract_site extends the rendered-path beyond the homepage:
Discovers representative pages on the same domain
Captures desktop and mobile screenshots for each selected page
Samples multiple instances of buttons, cards, links, inputs, sections, and other components
Persists the results to .brand/extraction-evidence.json
Feeds that evidence into brand_generate_designmd / brand_compile to produce .brand/design-synthesis.json and .brand/DESIGN.md
Merges additional colors and fonts back into core-identity.yaml when merge=true
Use this when the homepage is not enough to understand the brand system, or when you want richer evidence before token compilation.
Figma Extraction
brand_extract_figma works in two steps to bridge between the Figma MCP and brandsystem:
Plan mode -- Returns specific instructions for what data to fetch from Figma (variables, text styles, logo components)
Ingest mode -- Processes the collected Figma data, maps variable names to roles, and merges into core-identity.yaml at high confidence
Typography becomes grouped tokens with fontFamily, dimension (size), and fontWeight entries
Spacing becomes dimension tokens with scale values
Each token includes $extensions["com.brandsystem"] with source and confidence metadata
Only values with medium or higher confidence are included
The Bigger Picture
Four verbs stack — Build, Use, Evolve, Deploy. @brandsystem/mcp owns Build. The .brand runtime is what moves between them.
code
Build Use Deploy
───── ─── ──────
@brandsystem/mcp ────► @brandcode/mcp ────► Every surface
(this package) (mcp.brandcode.studio) Claude Design
Claude Code
authors the ─────────► .brand/ runtime ─────────► Cursor
portable runtime (portable artifact) ChatGPT
NotebookLM
▲ Gemini
│ ...any MCP client
│
Evolve ─── Brandcode Studio
(governance promotion,
taste compilation,
memory wall)
Build — this package. Extract identity. Compile governance. Produce a .brand/ directory.
Use — @brandcode/mcp hosted at mcp.brandcode.studio/{slug}. Authorized MCP clients fetch the live Full Brand Runtime by default.
Evolve — Brandcode Studio. Taste notes graduate from memory to formal governance. Anti-patterns accumulate. The runtime sharpens with every production cycle.
Deploy — the governed .brand repo travels with you. Point Claude Design at it. Compile packs for Claude Code, Chat, Gemini, NotebookLM. Every surface consumes the same runtime.
Progressive Depth
Each stage builds on the previous. Stop anywhere — you get value immediately.
Stage
What You Get
How
1. Free scan
Brand tokens + DESIGN.md + HTML report with platform setup guides
Hosted package pull, sync history, shared distribution
brand_brandcode_connect → brand_brandcode_sync → brand_brandcode_live for Live Mode reads
6. Live Use MCP
Authorized agents hit mcp.brandcode.studio/{slug} for current runtime, knowledge search, draft checks, asset fetch
@brandcode/mcp connects once with bearer-key auth; reads stay fresh across agent sessions
7. Deploy to Claude Design
Claude Design grounds on the .brand/ directory natively — governance, narratives, proof points, taste notes all load without translation
Point Claude Design at a repo containing .brand/; output is on-brand from the first generation
Stages 1–4 are the standalone local MCP flow. Open source, fully portable, no account required.
Stages 5–7 are the Deploy path — where the .brand runtime becomes shared, served live, and consumed by every generation surface. Available through Brandcode Studio and Column Five Media.
What's Portable
Artifact
Portable?
Owned By
@brandsystem/mcp (authoring tool)
Fully — open source, any brand
MIT license
.brand/ directory (the runtime)
Fully — the portable artifact that travels with your brand
Client
Brandcode framework (schema + stances + U-mech)
Fully — universal layer imported by every brand instance
Open
Client claims, narratives, rules (I-content)
Per-instance — unique to each brand
Client
@brandcode/mcp (hosted Use MCP)
Serves the runtime — authorized MCP clients connect
Brandcode
Development
bash
# Install dependencies
npm install
# Build TypeScript
npm run build
# Watch mode for development
npm run dev
# Run tests
npm test# Watch mode for tests
npm run test:watch
# Type check without emitting
npm run lint
# Start the server (stdio transport)
npm start
The eval/ directory ships fixtures, methodology, and a runnable harness measuring what matters to agents: first-tool selection on real prompts, response token budgets, envelope conformance, compliance-check accuracy against labeled cases, and whether a second agent can use a generated runtime with no explanation. Run the deterministic tier with npm run eval; the model-dependent tier (first-tool selection) is opt-in via ANTHROPIC_API_KEY. Results are published only from actual runs with stated model versions and dates — the repo ships evidence machinery, not claims. See eval/README.md.
Security
Report vulnerabilities privately via the repository's Security page → Advisories → "Report a vulnerability". See SECURITY.md. Please don't open public issues for suspected vulnerabilities.
Local-first by design. Extraction and compilation run on your machine. Network activity is limited to: fetching the sources you point the tools at (websites, Figma via your own Figma MCP), optional Brandcode Studio connector calls when you connect a hosted brand, and optional brand_feedback reports.
What gets written locally: everything lands in .brand/ inside your working directory. Connector credentials are stored in .brand/brandcode-auth.json (gitignored).
