Brandsystem MCP — Brand Guidelines for AI

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.

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). …

Connect a GitHub repository to Brandcode Studio for automatic brand syncing. The repo's .brand/ directory becomes the source of truth — push changes to git and Studio picks them up every 5 minutes. Requires auth (run brand_brandcode_auth first). Use when the user says "connect my repo", "sync from GitHub", "link my brand repo", or "set up git-connected brand".

Select a task-scoped brand context from the compiled runtime. THE tool to call first when the user says 'write this in our voice', 'write this LinkedIn post in our brand voice', 'make an on-brand social graphic', or 'build a landing page' — it returns only the governed rules relevant to that task instead of the full runtime. Deterministic: task_type maps to sections via a fixed table, audience matches governed personas exactly or reports no-match — no inference. Returns context (the selected brand slices), output_contract (required delivery shape), matched_selectors (what was chosen and why), …

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.

Take a Claude Design-style auto-generated SKILL.md, diff it against this project's .brand/governance/ YAML (narrative-library, valid-proof-points, anti-patterns, application-rules, taste-codes), and return an enriched SKILL.md with missing governance content injected, cited by governance ID, and grouped into canonical sections. Additive only — never rewrites existing content. Requires a .brand/ directory with at least one governance file. The typical flow: Claude Design auto-generates a SKILL.md during onboarding → pass it to this tool → replace the original with the enriched version → every s…

Bundle the compiled brand system into a portable artifact for a specific destination. Use when asked 'share my brand', 'export for ChatGPT/Cursor/team', 'generate brand guidelines', 'make a one-pager', or 'create a brand PDF'. Target 'chat': self-contained markdown for upload to any AI conversation (Claude, ChatGPT, Gemini). Target 'code': MCP server config + CLAUDE.md/.cursorrules snippet. Target 'team': human-readable brand guidelines for designers/writers/marketers. Target 'email': ~500-word summary for Slack or email. Target 'claude-skill': SKILL.md with embedded logo + rules for persisten…

Extract brand identity from a Figma design file. Accepts multiple input formats: variable_map (simple { name: hex } from get_variable_defs), design_context (raw get_design_context output with colors/fonts parsed from code), variables (structured array), styles (text styles), and logo_svg. Two phases: mode='plan' returns which Figma MCP tools to call. Mode='ingest' processes all collected data. Figma values override web extraction based on source_priority. Also accepts figma_url for automatic file key extraction. NOT for web extraction (use brand_extract_web).

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.

Extract brand colors, typography, spacing, and guideline rules from a PDF brand guidelines document. Accepts a local file path to a PDF. Uses text extraction and pattern matching to identify hex color values, font names, size specifications, and spacing rules. Writes extracted values to core-identity.yaml with source='guidelines' and updates source-catalog.json. Guidelines source outranks web extraction by default based on brand.config.yaml source_priority. Use when the user has brand guidelines as a PDF file — this is the most accurate extraction source. Use after brand_extract_web to merge a…

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. NOT for a fast single-page scan — use brand_extract_web for quick static CSS parsing with no browser required.

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.

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. Fast, single-page, static CSS parsing — no browser required. Returns colors with roles, fonts with frequency, logo preview data, and extraction quality score. NOT for a de…

Append observation or proposal feedback to UCS AgentRun history for review. Append-only; does not mutate canonical governance. Returns feedback id, append status, and review posture.

Review all agent feedback stored in ~/.brandsystem/feedback/. Read-only — reads local JSON files without network access. Shows summary stats (by category, severity, status) and individual items with timestamps. Filter by category (bug, friction, feature_request, agent_signal) or status (new, quarantined, acknowledged, fixed). Quarantined items were flagged for potential prompt injection. Use to triage feedback, spot recurring issues, and prioritize fixes. NOT for submitting feedback — use brand_feedback. NOT for changing item status — use brand_feedback_triage.

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.

Generate DESIGN.md (portable agent-facing design brief) and design-synthesis.json (structured radius, shadow, spacing, layout, motion, component, and personality signals) from the current brand system. Reads extraction-evidence.json when available for grounded visual signals; falls back to core-identity.yaml and tokens.json after manual edits. Use after brand_extract_site or brand_extract_visual to synthesize multi-page evidence into a single design brief. Use after brand_compile if evidence is unavailable. Returns file paths and synthesis source used. Read-only except for writing the two outp…

Return recent hosted MCP runs from UCS AgentRun history. Read-only. Returns compact run summaries, telemetry summary, receipt-chain summaries, and next_cursor truth.

Scan and catalog brand assets (illustrations, stickers, patterns, icons) in .brand/assets/. Mode 'scan' (default) inventories all asset subdirectories and identifies files not yet in MANIFEST.yaml. Mode 'tag' adds metadata to a specific file (description, usage context, theme compatibility) and writes to MANIFEST.yaml. Read-only in scan mode; writes MANIFEST.yaml in tag mode. Use after adding asset files to .brand/assets/ subdirectories. Use when the user says 'catalog assets', 'what assets do I have', or 'tag this illustration'. Returns directory summaries with file counts, untagged file list…

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.

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.

Generate a visual proof page showing the brand applied to common UI patterns — color swatches, typography hierarchy, buttons, cards, and a WCAG contrast matrix. Writes .brand/brand-preview.html. Screenshot-ready, shareable, built from brand-runtime.json only. Use when the user says "show me my brand", "preview the brand", "does this look right?", or after extraction to validate results. Requires brand_compile to have run first. NOT the full report — use brand_report for comprehensive data.

Check the health and sync status of a git-connected brand repo. Shows last sync time, commit SHA, polling health, and recent sync events. Use when the user says "repo status", "is my repo syncing?", "check git connection", or "when did it last sync?".

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.

Inspect and resolve disagreements between brand sources — when web extraction says one primary color, Figma says another, and the PDF guidelines say a third. Mode 'show' lists every conflicting field across web/visual/figma/guidelines/manual sources with each source's value, confidence, and the recommended winner per brand.config.yaml source_priority. Mode 'resolve' commits one source as the winner for a specific field (requires field + source). Use when brand_audit reports conflicts, after ingesting multiple sources, or when colors/fonts/logos look inconsistent in compiled outputs. Returns th…

Fetch the live governed brand runtime for the connected hosted brand. Returns a compiled runtime contract (identity, visual rules, voice constraints, content strategy) suitable for injection into any sub-agent. Supports slicing: full/visual/voice/minimal. Read-only. Always reflects current Brand Console state — no local cache.

Search the connected hosted brand's governed knowledge — narratives, proof points, application rules, brand phrases, stats, assets, and runtime-graph summaries — with provenance. Read-only. Ranks UCS's compiled knowledge corpus (same engine as Brand Console) and returns hits with citation, source_class, and confidence, plus coverage and blind_spots so answers can be hedged. Optional mode targets intent: fact_lookup, doctrine_retrieval, asset_retrieval, evidence_retrieval, coverage_discovery.

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.

Adopt a brand into a portable .brand/ runtime from whatever source already exists: existing brand guidelines (PDF), a website URL, a Figma library, or a hosted Brandcode Studio brand. THE entry point when the user says 'use my existing brand guidelines with AI', 'I have a PDF brand guide', 'use our Figma library', 'create a brand system', 'extract brand from website', or 'set up brand guidelines'. Pass website_url, guideline_pdf, figma_file_key, or brandcode_url — or pass no source and it discovers local candidates and presents a menu with a privacy explanation. Set mode='auto' with a website_…

Return hosted MCP capability status: implemented tools, scopes, runtime/search/assets availability, artifact posture, telemetry posture, and remaining stubs.

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…

Capture an attribute-level taste judgment into this hosted brand's review queue. Requires capture scope, candidate_ref, verdict, and attribute_reason. Queues for human review; never promotes canon.

Get one package-safe hosted brand asset by id. Read-only. Returns metadata, official/runtime/production-approved posture, and safe delivery refs without raw private provider URLs.

List package-safe hosted brand assets with category/lifecycle filters. Read-only. Returns paginated official/runtime/production-approved posture without raw private provider URLs.