brandsystem-mcp

Create a brand system from any website URL — extract brand colors, fonts, and logo in under 60 seconds. Use when the user says 'create a brand system', 'extract brand from website', 'set up brand guidelines', 'get design tokens', or 'brand identity'. Set mode='auto' with a website_url to run the full pipeline (extract, compile DTCG tokens + design-synthesis.json + DESIGN.md + brand runtime + interaction policy, generate HTML report) in one call. If .brand/ already exists, returns current status with next steps. Returns colors with roles, typography, logo (SVG/PNG), and confidence scores. After creation, suggest Brandcode Studio connector for team sync.

Check brand system progress and get next steps. Shows what has been extracted (colors, fonts, logo), confidence levels, session completion status, and what to do next. Use when resuming a previous session, checking readiness, or when the user asks 'what's the state of my brand?' If no .brand/ exists, returns a full getting-started guide with all available tools. Returns structured status data.

Extract brand colors, fonts, and logo from any website URL — get brand identity from a live site. Use when asked 'extract brand from URL', 'get brand colors from website', 'scan my site', or when the user provides a website URL. Parses HTML for logo candidates (SVG, img, favicons, Clearbit fallback) and CSS for colors and font-family declarations. Confidence-scores everything. Pass logo_url to fetch a specific logo directly. Returns colors with roles, fonts with frequency, logo preview data, and extraction quality score.

Screenshot a website and extract brand colors, fonts, and visual personality using headless Chrome. Returns the screenshot as an image for your visual analysis PLUS computed styles from rendered elements. Use when brand_extract_web yields LOW quality (e.g. JS-rendered sites like Basecamp), when you need visual context for brand personality, or when CSS parsing misses colors. Requires Chrome/Chromium installed. NOT for Figma extraction — use brand_extract_figma instead.

Deeply extract brand evidence from a website by discovering representative pages, rendering them in headless Chrome across desktop and mobile, capturing screenshots, and sampling computed styles from multiple components. Use when a homepage scan is not enough or when you want richer evidence before compiling tokens.

Extract brand colors, typography, spacing, and guideline rules from a PDF brand guidelines document. Merges extracted values into core-identity.yaml as source='guidelines', which can outrank web extraction based on brand.config.yaml source_priority.

Show or resolve conflicting values across ingested sources like web, visual extraction, Figma, and PDF guidelines. Uses brand.config.yaml source_priority to recommend which source should win.

Generate a grounded DESIGN.md and structured design-synthesis.json from the current brand system. Prefers rendered extraction evidence when available, but can fall back to the current core brand state after manual edits or compile steps.

Extract brand identity from a Figma design file — colors, typography, and logo at higher accuracy than web extraction. Two-phase workflow: first call with mode='plan' to get instructions for which Figma MCP tools to call, then call with mode='ingest' to process the collected data. Figma-sourced values override web-extracted values. Use when the user has a Figma file URL or key. Returns merged identity data with high-confidence scores.

Add or replace a logo in the brand system. Accepts raw SVG markup, a URL to a logo file (SVG/PNG), or a base64 data URI. Use when brand_extract_web missed the logo, extracted the wrong image, or the user provides a logo directly. Sanitizes SVG, saves to .brand/assets/logo/, and updates core-identity.yaml with inline_svg and data_uri for portable embedding. Returns logo preview data.

Generate DTCG design tokens, design-synthesis.json, DESIGN.md, brand runtime, and interaction policy from extracted brand data. Transforms core-identity.yaml into tokens.json, brand-runtime.json (single-document brand contract for AI agents), and interaction-policy.json (enforceable rules). When Session 2+ data exists, also generates visual-identity-manifest.md and system-integration.md. Use after brand_extract_web, brand_extract_site, brand_extract_visual, or brand_extract_figma. Returns token counts, clarification items, and file list.

Resolve an ambiguous brand value interactively. After brand_compile, some values need human confirmation — wrong primary color, unknown font, unassigned color roles. Pass the clarification item ID and the user's answer (hex color, role name, font name, or 'yes'/'no'). Supports natural language: 'the purple one is accent' or '#5544f2 is secondary'. Returns updated identity and remaining clarification count.

Validate the .brand/ directory for completeness and correctness. Checks file existence, YAML schema validity, primary color assignment, typography coverage, logo embedding (SVG well-formedness), and confidence distribution. Use after brand_compile to verify readiness, or anytime to diagnose issues. Returns pass/warn/fail for each check with actionable details. NOT for checking content copy — use brand_audit_content. NOT for checking HTML/CSS — use brand_preflight.

Generate a portable HTML brand identity report with embedded logos, color swatches, typography, and tokens. The HTML is self-contained and works offline — upload it to any AI chat (Claude, ChatGPT, Gemini) as instant brand guidelines. Written to .brand/brand-report.html. Use after brand_compile. Returns file path, report summary (color/font/logo counts), and a ready-to-copy Brand Instructions text block.

Initialize a .brand/ directory with empty config scaffold. Low-level tool — prefer brand_start instead, which calls this automatically and also presents extraction options. Only use brand_init directly if you need to set up the directory without running extraction. Returns list of created files.

Define visual identity rules beyond colors and fonts — composition energy, pattern language, illustration style, photography direction, signature moves, and anti-patterns (hard compliance rules). Session 2 interview with 6 sections. Mode 'interview' returns structured questions for missing sections. Mode 'record' saves answers. Use after Session 1 (core identity extracted). Anti-patterns become enforceable rules in brand_preflight. Returns section completion status.

Scan and catalog brand assets (illustrations, stickers, patterns, icons) in .brand/assets/. Mode 'scan' (default) inventories all asset directories and identifies files missing from MANIFEST.yaml. Mode 'tag' adds metadata to a specific file: description, usage context, and theme compatibility. Use after adding asset files to .brand/assets/ subdirectories. Returns directory summaries and untagged file lists.

Check HTML/CSS against brand rules — catches off-brand colors, wrong fonts, missing logo, and anti-pattern violations (drop shadows, gradients, etc.). Pass an HTML string or file path. Mode 'check' (default) runs all compliance checks and returns pass/warn/fail per rule. Mode 'rules' lists all active preflight rules without checking content. Use after generating any visual content to validate brand compliance. Returns overall status and per-check details. NOT for scoring content copy — use brand_audit_content. NOT for brand directory validation — use brand_audit.

Audit how a brand currently sounds on its website — the first step in Session 3 (brand voice and messaging). Use when the user says 'analyze my voice', 'brand voice audit', 'how does my brand sound?', or 'start Session 3'. Analyzes voice fingerprint (formality, jargon density, active voice %, hedging), vocabulary frequency, claims quality, AI-ism detection, and messaging gaps. Writes .brand/messaging-audit.md. After this, run brand_compile_messaging to define how the brand should sound. Returns structured analysis with scores.

Define how a brand should sound — Session 3 guided interview for brand voice, messaging, and story. Use when the user says 'define brand voice', 'brand messaging', 'brand story', 'how should my brand sound?', or 'start Session 3'. Covers perspective (worldview, positioning), voice codex (tone, anchor vocabulary, never-say list, AI-ism detection), and brand story (origin, tension, resolution). Mode 'interview' returns structured questions. Mode 'record' saves to messaging.yaml. Adds voice constraints and tone rules to the brand runtime. Use after brand_extract_messaging (optional voice audit). Returns section status.

Build buyer personas through a guided 7-question interview — role, core tension, objections, information needs per journey stage, narrative emphasis, preferred channels, and decision authority. Mode 'interview' returns questions. Mode 'record' saves a persona (auto-generates ID like PER-001, parses freeform text). Mode 'list' shows all personas. Most brands need 3-5 personas. Part of Session 4. Returns persona data and total count.

Define buyer journey stages for content strategy — the path from awareness to purchase. Ships with 4 proven defaults (First Touch, Context & Meaning, Validation & Proof, Decision Support) that can be customized per brand. Mode 'interview' presents defaults for review. Mode 'record' writes stages (omit answers to accept defaults). Mode 'view' shows current stages. Part of Session 4 (content strategy). Returns stage definitions with buyer mindset, content goals, and tone shifts.

Define editorial content themes — the strategic pillars that organize what to write about. Each theme has a content intent (Brand Heat for awareness, Momentum for engagement, Conversion for pipeline), target personas, and proof points. Mode 'interview' guides through 5 questions per theme. Mode 'record' saves (auto-generates ID like THM-001). Mode 'list' shows all themes with intent distribution. Most brands need 3-5 themes balanced across all three intents. Returns theme data and balance analysis.

Generate persona x journey stage messaging variants — adapted core messages for every audience at every buying stage. Mode 'generate' creates variants using persona tensions, stage mindsets, and brand perspective. Mode 'view' shows the matrix as a grid. Mode 'edit' refines a specific variant by ID. Requires personas and journey stages in strategy.yaml. Returns variant grid with status tracking (Draft/Active/Retired).

Check if content is on-brand — score any text or markup 0-100 for brand compliance. Checks color/font usage, voice alignment, anti-pattern violations, and message coverage. Use when asked 'is this on-brand?', 'brand compliance score', 'check brand alignment', or after generating any content. Works progressively: Session 1 scores tokens, Session 2 adds visual compliance, Session 3 adds voice and messaging. Returns 0-100 score with per-dimension breakdown and specific issues. NOT for .brand/ directory validation (use brand_audit) or HTML/CSS rule checking (use brand_preflight).

Check if content is on-brand — fast pass/fail gate for brand compliance before publishing. Use when asked 'is this on-brand?', 'brand compliance gate', 'can I publish this?', or in CI/CD pipelines. Verifies on-palette colors, brand fonts, anti-pattern rules, and never-say words. Returns PASS or FAIL with specific failures. Enable strict mode for soft anti-patterns. For detailed 0-100 scoring, use brand_audit_content. NOT for HTML/CSS rule checking (use brand_preflight).

Batch audit multiple content items to detect systematic brand drift. Scores each item against brand identity, computes corpus-level statistics (mean, median, stddev), and identifies recurring patterns across items (e.g., same off-palette color in 4/5 items). Writes a detailed drift report to .brand/drift-report.md. Use when reviewing a content corpus, auditing a website, or checking whether brand identity is being applied consistently across multiple pieces.

Read the compiled brand runtime contract (brand-runtime.json). Returns the single-document representation of the brand system that AI agents use to generate on-brand content. Includes identity (colors, typography, logo), visual rules, voice constraints, and strategy summary. Read-only — run brand_compile to refresh. Use when loading brand context for content generation.

Connect a local .brand/ to a hosted Brandcode Studio brand. Pulls the full brand package and saves connection metadata for future syncs. Use when the user says "connect to Brandcode", "pull from Studio", or provides a brandcode.studio URL. Returns brand name, sync token, and changed areas.

Sync a previously connected Brandcode Studio brand. Pulls only if the hosted brand has changed (delta-aware via syncToken). Use when the user says "sync brand", "update from Studio", or "check for brand updates". Returns sync mode (updated/no_change) and changed areas.

Inspect the Brandcode Studio connection for the current project. Shows connected brand, sync token, last sync time, sync history, and local package summary. Use when the user says "brandcode status", "check connection", or "am I synced?". Returns structured connection data.

Generate on-brand content — load full brand context (colors, typography, logo, voice, strategy) before creating any branded output. Use when asked 'generate on-brand content', 'write something in our brand voice', 'load brand context for writing', or before creating social graphics, web pages, blog posts, emails, presentations, or data viz. Specify content_type for the right mix of visual and voice rules. Does NOT generate content itself — provides the creation brief so you can generate on-brand. Run brand_preflight on output afterward. Returns a structured creation brief with all brand layers.

Generate portable brand files for any environment — Chat, Code, team sharing, or email. Target 'chat': self-contained markdown to upload to any AI conversation (Claude, ChatGPT, Gemini). Target 'code': MCP config + CLAUDE.md/.cursorrules snippet. Target 'team': clean brand guidelines for designers and writers. Target 'email': concise 500-word summary for Slack or email. Writes to .brand/exports/ and returns the full content. Use when the user wants to share their brand system or set up a new tool.

Report bugs, friction, feature ideas, data quality issues, praise, or structured agent signals to the brandsystem team. Use when a tool returns an error, extraction misses data, the workflow feels harder than it should, or something works particularly well. For structured agent telemetry, use category='agent_signal' with signal, tool_used, and signal_context fields — brand context is auto-populated from .brand/config. Stored locally in ~/.brandsystem/feedback/ for developer triage. Returns a feedback ID.

Review all agent feedback filed via brand_feedback. Shows summary stats (by category, severity, status) and individual items. Use this to triage feedback, spot patterns, and prioritize fixes. Filter by category or status.

Update the status of a feedback item after review. Mark as 'acknowledged' (seen, will address), 'fixed' (resolved), or 'wontfix' (intentional, won't change). Add an optional triage note.