brandsystem-mcp

Purpose

Without brand context, AI tools default to "category-average" output. Brand guidelines are usually scattered across PDFs, Figma files, and people's heads, unreadable by AI at creation time. The core problem brandsystem-mcp solves is not "broken output" but "correct but generic"—it passes mechanical checks yet looks like something any competent generic writer could produce.

This MCP server is the authoring half of the "Two MCPs, One Brand" model. It extracts brand identity from live sources and compiles it into a .brand/ directory with structured governance, containing DTCG tokens, brand-runtime.json, interaction-policy.json, plus governance content such as anti-patterns, evidence point status, voice rules, and application rules. The .brand/ directory is a portable brand runtime that travels with the brand across touchpoints.

Main Capabilities

According to the materials, the server offers two tool configurations:

• Default Core configuration: registers 12 tools, covering the complete loop: adopt → runtime/context → create → check → export, plus the Studio connector entry point and the clarify/promote paths. Core tools include 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.
• full configuration: registers the complete authoring system (all tools). It can be selected via environment variables or arguments, for example setting BRANDSYSTEM_PROFILE=full.

Capabilities divided by session:

• Session 1 Core Identity: extracts colors, fonts, and logo from a website or Figma file, compiles them into DTCG tokens, a structured design synthesis layer, a portable DESIGN.md, and an HTML report.
• Session 2 Visual Identity: through guidedinterview, defines composition rules, pattern language, illustration style, and anti-patterns. Anti-patterns become executable compliance rules.
• Session 3 Messaging: audits the existing website voice, then through a guided interview defines perspective, a voice codex (tone, vocabulary, AI-speak detection), and brand story.
• Session 4 Content Strategy: builds buyer personas, journey stages, editorial themes, and a persona × stage message matrix.

Each session builds on the previous one, and you can stop at any stage; Session 1 is valuable on its own.

Other capabilities include:

• Content scoring and checking: tools such as brand_check, brand_preflight; brand_preflight runs after any content generation.
• Runtime and utility tools: brand_runtime, brand_context, brand_export, etc.
• Brandcode Studio connector: brand_brandcode_connect can save a brand to Brandcode Studio, and team members can pull the same brand into their own tools.

Tools chain automatically: each tool's response tells the LLM what to run next. brand_status can be called at any time.

Usage

The materials provide multiple installation and usage paths:

1. Add to the MCP configuration. Copy it into .mcp.json (Claude Code), .cursor/mcp.json (Cursor), or the Windsurf MCP settings. Codex users can run npx @brandsystem/mcp install --client codex --write.
2. Create a brand system. Tell the AI tool to run brand_start, for example client_name="Acme Corp", website_url="https://acme.com"、mode="auto"。该命令从网站提取颜色、字体和 Logo, when the initial extraction quality is weak, it escalates to rendering or multi-page deep extraction, compiles DTCG tokens, generates design-synthesis.json + DESIGN.md, and produces a portable HTML brand report, all within 60 seconds.
3. Load brand-runtime.json into the context of any sub-agent, and the first output conforms to the brand, with no per-prompt boilerplate needed. Run brand_write to generate social graphics for the "Q3 Product Launch".
4. Each session enriches brand-runtime.json, and can be stopped at any point.
5. Save to Brandcode Studio via brand_brandcode_connect, the brand persists, and team members pull the same brand from their respective tools.

The CLI entry point is used for setup, diagnostics, and hosting the brand connector. Installation does not overwrite entries from other servers: it deep merges, backs up existing files first, and rejects invalid JSON. For protected hosted brands, add --share-token=TOKEN.

Installation methods for each client (listed in the materials):

• Codex: Use the package installer, which delegates to the official Codex MCP configuration command; after installation, start a new Codex task. Codex CLI, the Codex app, and the IDE extension share the same MCP configuration.
• Cline: Use the package installer, which delegates to the official Cline non-interactive MCP command; after starting a new Cline task, ask "How do I use my brand guidelines with AI?". Cline CLI and the IDE extension share the global configuration at ~/.cline/data/settings/cline_mcp_settings.json.
• Claude Code: Create .mcp.json in the project root directory.
• Cursor: Create .cursor/mcp.json in the project root directory.
• Windsurf: Create ~/.codeium/windsurf/mcp_config.json.
• Claude Desktop: Open Settings > Developer > Edit Config (claude_desktop_config.json).

Claude Chat (no MCP) path: First run the pipeline in a code environment to generate brand-report.html, upload the HTML file to the Claude Chat conversation, then say "Use this as my brand guidelines for everything we create". The report HTML is self-contained and can serve as a standalone brand reference.

Applicable Scenarios

• Design, marketing, and content teams that want AI-generated content to conform to brand specifications.
• Scenarios that need to build a portable brand runtime from websites, PDFs, Figma libraries, or local files.
• Teams that want to inject brand guidelines as context into tools such as Claude Code, Claude Desktop, Cursor, Windsurf, Cline, and Codex.
• Scenarios that need content compliance scoring and checks.
• Team collaboration, sharing a single source of brand truth through Brandcode Studio.

Claude Design integration: The .brand/ directory is designed as a first-class input for Claude Design. Point Claude Design at a repository containing .brand/ (governance YAML, narrative library, evidence point files, taste notes, DTCG tokens), and it will improvise based on the governed brand rather than uploaded assets. This is the Deploy path: author once with @brandsystem/mcp, then every Anthropic touchpoint (Claude Design, Claude Code, Chat via the compiled package) consumes the same runtime.

Limitations

• Figma extraction does not connect directly to Figma. It has two phases: Plan returns instructions on which data to fetch (variables, styles, Logo); Ingest processes the data passed back from the Figma MCP tool. A separate Figma MCP server (such as @anthropics/figma-mcp) needs to be connected, and the fetched data passed to brand_extract_figma in ingest mode.
• brand_extract_web only parses static CSS in <style> blocks and up to 5 linked stylesheets. If a website loads CSS dynamically via JavaScript, it may extractFetch as empty.
• Website extraction looks for <img>, <svg>, and <link rel="icon"> elements. If a Logo is rendered via JavaScript or embedded as a CSS background, it must be added manually with brand_set_logo (SVG markup, URL, or data URI).
• Every extracted value carries a confidence level; when the same brand element appears in multiple sources, the source with higher priority wins. Primary colors from Figma sources replace those extracted from the web. Manually confirmed values override both. Within the same source, the higher-confidence one wins.
• Except for brand_start, brand_init, and brand_feedback, every tool requires the .brand/ directory.
• Some tools (brand_write, brand_deepen_identity) return rich conversation guidance exceeding 5K characters, which is a soft warning; the hard limit is 50K, which triggers truncation.
• Brandcode MCP is in pre-release status, offered only to approved customers, and has not yet been publicly released or listed in a registry. Brand data on the hosted service belongs to the customer; feedback is append-only; agent history is restricted and redacted. Deletion and export requests are handled through the Brandcode Studio contact. Before public release, local build/sync uses @brandsystem/mcp, and connection reads use Live Mode (brand_brandcode_live), which refreshes from the hosted runtime within a short cache TTL.
• Details such as client-specific installation commands, code snippets, the HTML structure of brand reports, and the complete file list of the .brand/ directory are not fully given one by one in the materials and are not provided for now.