Brandsystem MCP — Brand Guidelines for AI

使用 AI 落实品牌指南

**@brandsystem/mcp 可将你现有的品牌资料转化为 AI Agent 可用的上下文。**提供网站、PDF 指南、Figma 库、本地文件或 Brandcode Studio 品牌。它会生成可移植的 .brand/ 运行时，其中包含设计令牌、语调规则、来源信息和合规性检查。

本地优先，无需账户。默认的 Core 配置提供 12 个工具，涵盖完整的采用 → 使用 → 检查流程。

从这里开始

为你的 Agent 安装，然后询问：“如何使用 AI 落实品牌指南？”

# 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

**Claude Desktop（一键安装）：**从最新 GitHub 版本下载 brandsystem-mcp-<version>.mcpb，然后双击（或将其拖到 Settings > Extensions 中）。Claude Desktop 会询问存放 .brand/ 目录的文件夹——无需安装 Node 或编辑 JSON。

除非传入 --write，否则 install 只会进行试运行。根据需要将 claude-code 替换为 cline、cursor、windsurf 或 claude-desktop。JSON 文件目标会保留现有设置；Cline 和 Codex 的配置会委托给其官方 MCP 命令，以确保其当前架构保持权威。Agent 可以参考精简的安装指南，无需通读整篇 README。

已经完成配置？告诉你的 Agent：

使用我现有的品牌指南和 AI 协作。从这个网站/PDF/Figma 库开始，告诉我哪些内容需要人工确认。

它解决的问题

AI 工具默认生成类别平均水平的内容，因为它们不了解品牌背景。品牌指南存在于 PDF、Figma 文件和人们的脑海中——AI 工具在生成内容时都无法读取这些信息。最常见的问题不是“输出有误”，而是“正确但平庸”——输出通过了机械检查，却像是任何称职的通才都能做出来的。

这个 MCP 服务是 “两个 MCP，一个品牌” 模式中的创作部分。它从实时来源提取品牌识别信息，并将其编译到 .brand/ 目录中，其中包含结构化治理内容（反模式、依据状态、语调规则、应用规则），以及 DTCG 令牌、brand-runtime.json 和 interaction-policy.json。该目录就是可移植的品牌运行时——它是一份能伴随品牌在不同界面间流转的产物。

• Claude Design 在连接到受治理的代码库时，会原生读取 .brand/ 目录
• Claude Code、Claude Desktop、Cursor 和 Windsurf 可通过 stdio 直接连接到此服务，并在生成时加载 brand-runtime.json
• ChatGPT 和其他远程优先客户端可将同一运行时作为上传的产物（brand-report.html / brand-runtime.json）或通过远程 MCP 连接使用——参见兼容性一览
• @brandcode/mcp（托管的 Use MCP）通过 HTTP 在 mcp.brandcode.studio/{slug} 提供同一运行时，适合需要经过身份验证的实时读取的团队

加载 brand-runtime.json 后，Agent 提示词中的品牌上下文会从 200-400 个令牌的内嵌内容缩减为仅包含差异的内容。首次输出即符合品牌风格。无需通过评审来消除瓶颈。

---

快速开始

1. 添加到 MCP 配置

将以下内容复制到 .mcp.json（Claude Code）、.cursor/mcp.json（Cursor）或 Windsurf MCP 设置中。Codex 用户可以改为运行 npx @brandsystem/mcp install --client codex --write：

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

对于提交到代码库的项目级配置，请固定版本（"@brandsystem/mcp@<version>"），以免协作者自动运行未经审核的版本；npx @brandsystem/mcp install 会为你写入固定版本的规范。

2. 创建你的品牌系统

告诉你的 AI 工具：

运行 brand_start，参数为 client_name="Acme Corp"、website_url="https://acme.com" 和 mode="auto"

这条命令会从网站提取颜色、字体和徽标；如果基础提取效果不佳，则会升级为渲染提取或更深入的多页面提取；然后编译 DTCG 令牌、生成 design-synthesis.json 和 DESIGN.md，并生成可移植的 HTML 品牌报告——整个过程不到 60 秒。

3. 你将获得

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

将 brand-runtime.json 加载到任意子 Agent 的上下文中。首次输出就符合品牌规范。无需在每条提示词中重复编写样板内容。

4. 开始使用

运行 brand_write，为“Q3 产品发布”制作社交媒体图

AI 现在拥有完整的品牌上下文——颜色、字体排版、徽标、反模式和语气规则——并能生成符合品牌规范的内容。

导出为各工具的原生格式

只需编码一次品牌信息，即可按每种工具原生支持的格式导入。brand_export 会将文件写入 .brand/exports/：

目标	输出	存放位置
agents-md	AGENTS.md 片段（位于 brandsystem:start/end 标记之间）	项目根目录的 AGENTS.md——供 Codex、Cursor 和其他支持 AGENTS.md 的 Agent 读取
cursor-rules	带有 description / globs / alwaysApply: false 前置内容的 brand.mdc	.cursor/rules/brand.mdc——自动附加到 UI 文件
css-variables	:root { --brand-color-*; --brand-font-* }，如果品牌有深色调色板，还会添加 [data-theme="dark"] / prefers-color-scheme: dark 区块	任意样式表
tailwind	Tailwind CSS v4 @theme { --color-brand-*; --font-brand-*; --radius-brand-* }	放在 @import "tailwindcss"; 之后
shadcn	从品牌角色映射而来的 shadcn/ui :root + .dark 变量（--background、--primary、--ring、--radius …）	shadcn/ui 项目中的 globals.css
claude-skill、chat、code、team、email、pdf	技能文件、聊天上传文件、CLAUDE.md 片段、指南、摘要、PDF 指南	Claude 技能、AI 聊天、团队成员

运行 brand_export，参数为 target="tailwind"

CSS 目标格式根据编译后的 DTCG 令牌生成；品牌字符串经过验证（十六进制颜色、合理的字体名称、带引号的字体系列），确保提取的内容不会突破声明边界。指令类目标（agents-md、cursor-rules）会附带来源说明，并将品牌值保留在带围栏的数据块中。

5. 深入探索（可选）

会话	新增内容	命令
1. 核心标识	颜色、字体、徽标、令牌	brand_start（已完成）
2. 视觉标识	构图、反模式、插画风格	brand_deepen_identity
3. 品牌沟通	品牌声音、语气、禁用词、品牌故事	brand_compile_messaging
4. 内容策略	用户画像、旅程阶段、主题	brand_build_personas

每个会话都会丰富 brand-runtime.json。你可以随时停止——仅会话 1 就很有价值。

6. 与团队分享

运行 brand_brandcode_connect，保存到 Brandcode Studio

你的品牌会保存在 brandcode.studio。团队成员可以将同一品牌导入各自的工具。一个唯一可信来源。

---

功能介绍

会话 1：核心身份 —— 从网站或 Figma 文件中提取颜色、字体和 Logo。将其整理为 DTCG 令牌、结构化设计综合层、可移植的 DESIGN.md 和 HTML 报告。

会话 2：视觉身份 —— 通过引导式访谈定义构图规则、图案语言、插画风格和反模式。反模式会转化为可强制执行的合规规则。

会话 3：品牌信息 —— 审核现有网站的品牌语气，然后通过引导式访谈定义视角、语气规范（语调、词汇、AI 习惯用语检测）和品牌故事。

会话 4：内容策略 —— 构建买家角色、旅程阶段、编辑主题，以及角色 × 阶段信息矩阵。

每个会话都会基于前一个会话继续构建。可随时停止——立即获得价值。

两种使用方式

本地优先的 MCP 流程 —— 从网站或 Figma 文件开始，在本地构建 .brand/ 目录，并立即在聊天或代码工具中使用，无需账号。

连接 Brandcode Studio 的流程 —— 连接 Brandcode Studio 中已有的托管品牌，将打包后的品牌拉取到 .brand/，并随时间保持同步。

两个 MCP，一个品牌

.brand 运行时就是产品。两个 MCP 为其提供服务：

@brandsystem/mcp — 构建（此软件包）。 在本地创建并编译 .brand 运行时。从网站、Figma 和 PDF 中提取内容。将治理规则（反模式、事实依据状态、品牌语气规则、应用规则）与 DTCG 令牌、brand-runtime.json 和 interaction-policy.json 编译到单个 .brand/ 目录中。可移植、可版本管理，可随时提交到任何代码仓库。

@brandcode/mcp — 使用（托管）。 使用 Brandcode bearer-key 身份验证，将已授权的 MCP 客户端连接到实时 Full Brand Runtime：https://mcp.brandcode.studio/{slug}。Agent 可获取当前运行时、搜索已批准的知识、检查草稿、检索可安全打包的资源、追加审核反馈，并在明确授予 capture 范围后，将风格捕捉排入队列以供人工审核——无需为每个工具复制指南，没有过时快照，也不会通过 MCP 修改规范内容。标语：“让你的品牌在每个 AI 工具中实时呈现。”

同一个 .brand 运行时产物，两种使用路径。Build 负责创建，Use 负责提供服务。

Brandcode MCP 的阶段 0 已在 specs/brandcode-mcp-phase-0-lock.md 中锁定，定义了最初的 8 个只读／仅追加工具。当前托管实现新增了 capture_taste，作为范围受限的贡献层工具：它需要明确授予 capture 范围，会将审核候选项排入队列供人工审核，且绝不会将其提升为规范内容。

托管服务可用性： Brandcode MCP 处于预发布阶段，仅向获批客户端开放——尚未公开发布，也未列入注册表。托管服务上的品牌数据归客户端所有；反馈仅支持追加；Agent 历史记录经过范围限制和脱敏处理。删除和导出请求通过你的 Brandcode Studio 联系人处理。在公开发布之前，请使用 @brandsystem/mcp 进行本地构建／同步，并使用 Live Mode（brand_brandcode_live）读取连接数据；该模式会在较短的缓存 TTL 内从托管运行时刷新数据。

维护者可以使用冒烟测试工具（设置 BRANDCODE_MCP_SMOKE_URL 和范围受限的测试密钥后运行 npm run smoke:hosted-mcp），端到端验证托管部署。该工具会验证 MCP initialize、tools/list、已锁定的托管工具顺序、核心托管工具调用，以及只读模式下权限范围不足时的行为。它绝不会将密钥硬编码；缺少验证输入时会报告为 blocked 或 skipped。

Claude Design 集成

.brand/ 目录专为 Claude Design 设计，作为一等输入。将包含 .brand/ 的代码库交给 Claude Design——其中有治理 YAML、叙事库、证明要点文件、品味说明和 DTCG 令牌——它便会以受治理的品牌为依据，而不是根据上传的素材即兴发挥。这就是 Deploy 路径：使用 @brandsystem/mcp 编写一次，然后所有 Anthropic 界面（Claude Design、Claude Code、通过编译包使用的 Chat）都使用相同的运行时。

---

工具参考

工具配置（0.10+）

默认情况下，服务会注册 Core 配置——包含 12 个工具，覆盖完整流程：采用 → 运行时/上下文 → 创建 → 检查 → 导出，此外还包括 Studio 连接器入口以及澄清/提升路径。这有助于 Agent 准确选择首个工具。

Core 还会在发生故障后自动提供 brand_feedback。在会话中的工具出错、必须删减超大响应，或报告 LOW 或空提取结果之前，它不会出现在工具列表中。之后，服务会将其列入工具列表（通过 notifications/tools/list_changed），并在失败响应的 next_steps 中指向该工具，供不会刷新工具列表的客户端使用。不会自动发送任何内容：只有 Agent 调用 brand_feedback 后，报告才会发送给 Brandcode 团队；报告仅包含 Agent 撰写的说明，不包含 .brand/ 文件。请参阅 docs/DATA-FLOWS.md。

full 配置会注册整个创作系统（下方所有工具）。可通过环境变量或参数启用：

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

或者设置 BRANDSYSTEM_PROFILE=full。Core 工具：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。

入口

工具	功能
brand_start	**从这里开始。**根据网站 URL，在不到 60 秒内创建品牌系统。对于 JavaScript 渲染效果较弱的网站，使用 mode='auto' 可通过一次调用完成设置，并在渲染和深度网站分析之间回退。
brand_status	查看进度、获取后续步骤；如果尚无品牌，还可查看入门指南。

会话 1：核心身份

工具	功能
brand_extract_web	从任意网站 URL 提取徽标（SVG/PNG）、颜色和字体。
brand_extract_visual	在无头 Chrome 中截取渲染页面，并从 JavaScript 密集型网站提取计算后的颜色、字体和视觉上下文。
brand_extract_site	发现具有代表性的页面，在桌面端和移动端渲染，截取截图，对多个组件进行采样，并保存 extraction-evidence.json。
brand_generate_designmd	根据提取的证据或当前品牌状态生成 design-synthesis.json 和 DESIGN.md。
brand_extract_figma	从 Figma 设计文件中提取内容（准确度更高）。分为两个阶段：规划，然后导入。
brand_set_logo	通过 SVG 标记、URL 或数据 URI 添加或替换徽标。
brand_compile	根据提取的数据生成 DTCG 设计令牌、品牌运行时契约和交互策略。
brand_clarify	通过交互方式消除有歧义的品牌值（颜色角色、字体确认）。
brand_audit	验证 .brand/ 目录的完整性和正确性。
brand_report	生成可移植的 HTML 品牌报告。上传到任意 AI 聊天，即可作为即时指南。
brand_init	底层目录搭建。建议改用 brand_start。

会话 2：视觉识别

工具	功能
brand_deepen_identity	定义构图规则、图案、插画风格和反模式（6 个访谈环节）。
brand_ingest_assets	扫描并编目品牌素材，附带 MANIFEST.yaml 元数据。
brand_preflight	检查 HTML/CSS 是否符合品牌规则——检测不符合品牌规范的颜色、错误字体和反模式违规。添加 render: true，在沙盒化的无头 Chrome 中验证计算结果（参见检查构建结果）。

会话 3：品牌信息

工具	功能
brand_extract_messaging	审核现有网站的品牌表达——识别特征、词汇、主张、AI 风格用语和缺口。
brand_compile_messaging	定义观点、品牌表达规范（语气、词汇、AI 风格用语检测）和品牌故事。

会话 4：内容策略

工具	功能
brand_build_personas	通过 7 个问题的引导式访谈，建立买家画像。
brand_build_journey	定义买家旅程阶段（内置 4 个经过验证的默认阶段）。
brand_build_themes	定义编辑内容主题，并在认知、互动和转化阶段之间取得平衡。
brand_build_matrix	为每种买家画像与旅程阶段组合生成不同版本的品牌信息。

内容评分

工具	功能
brand_audit_content	从多个维度按照品牌规则为内容评分（0-100）。
brand_check_compliance	发布前快速进行通过/不通过合规检查。
brand_audit_drift	检测多篇内容中系统性的品牌偏移。

运行时与实用工具

工具	功能
brand_runtime	读取已编译的品牌运行时契约（为 AI Agent 提供单文档品牌上下文）。
brand_context	确定性地选择运行时中与任务相关的部分（task_type → 对应章节，audience → 匹配画像，紧凑预算）。返回匹配的选择器和明确的无匹配结果，不会静默回退。
brand_write	加载完整品牌上下文（视觉、品牌表达和策略），用于内容生成。
brand_export	以各工具的原生格式导出品牌：AGENTS.md、Cursor 规则、CSS 变量、Tailwind v4 主题、shadcn/ui 主题、Claude 技能、聊天/团队/电子邮件 Markdown 或 PDF。
brand_feedback	向 brandsystem 团队报告错误、使用阻碍或功能想法。

Brandcode Studio 连接器

工具	功能
brand_brandcode_connect	将本地 .brand/ 目录连接到托管的 Brandcode Studio 品牌并拉取当前软件包。
brand_brandcode_sync	使用支持同步令牌的增量行为，从之前连接的托管品牌拉取更新。
brand_brandcode_status	检查当前的 Brandcode Studio 连接、同步历史记录和本地软件包摘要。
brand_brandcode_live	切换已连接的读取工具，使其在较短的缓存 TTL 内从托管运行时刷新。

工具流程

工具会自动串联——每个工具的响应都会告知 LLM 接下来要运行什么：

Session 1: brand_start → brand_extract_web or brand_extract_visual or brand_extract_site → brand_generate_designmd → brand_compile → brand_clarify → brand_report
Session 2: brand_deepen_identity (interview x 6) → brand_compile (generates VIM)
Session 3: brand_extract_messaging → brand_compile_messaging (interview x 3) → brand_write
Session 4: brand_build_personas → brand_build_journey → brand_build_themes → brand_build_matrix

brand_status 可在任何时候调用。任何内容生成后都会运行 brand_preflight。

检查构建结果

静态检查会读取源代码。页面可以声明品牌字体，但仍以回退字体渲染；也可以在背景上使用正确的十六进制颜色值，却让文字难以辨认。使用 render: true 的 brand_preflight 会在真实浏览器中检查计算后的结果：

{ "html": "site/index.html", "render": true, "viewport": "mobile", "screenshot": true }

• 输入： HTML 字符串，或工作目录内 .html 文件的路径（会检查符号链接是否越界）。渲染前会内联工作目录中的样式表、@import、脚本、字体和图片。
• 沙箱： 页面会在与提取功能相同的受限无头 Chrome 中渲染（启用 Chromium 沙箱，绕过 Service Worker），并禁止所有网络出站连接。出站代理会拒绝所有连接，请求拦截器会中止所有非 data:、blob: 或 about: 请求。远程字体和 CDN 样式表不会加载。响应会列出被拦截的内容，方便你改用本地副本。
• 测量内容： 对每个可见元素测量计算后的文字、背景和边框颜色（经过 Alpha 合成）、实际渲染的字体（字体栈中第一个可用的字体）、字号和字重，以及 Logo 是否渲染。
• 检查内容：
  • R-COLOR：与最近品牌颜色的 CIEDE2000 色差。≤2.3 表示匹配，≤6 会作为信息提示（“使用准确值”），超过该值会产生警告，超过 15 则为错误。低色度中性色始终允许。在 clarify-primary 未关闭时，颜色错误仅作提示。
  • R-FONT：渲染的字体必须是品牌字体。品牌字体之后的一般字体和系统回退字体均可接受。若品牌字体位于字体栈首位但无法加载，则会作为信息提示。
  • R-CONTRAST：WCAG AA（4.5:1，大号文字为 3:1），根据实际前景色和背景色测量。图片或渐变上的文字会标记为无法确定。
  • R-LOGO：品牌名称以文字形式渲染，但未渲染任何 Logo SVG 或图片。
• 输出： overall（PASS/WARN/FAIL）、0–100 的 score（颜色 40 / 字体排版 30 / 对比度 30），以及按严重程度排序的问题。每个问题都包含定位信息、测量值、最近的品牌值或要求阈值，以及出现次数；问题数量最多为 max_findings。响应还包含测得的配色方案和字体比例、精简的 static_preflight 摘要；设置 screenshot: true 时，还会提供 .brand/checks/ 下的 PNG 路径，供你向用户展示。静态规则中发现的严重反模式也会导致渲染检查失败。

需要本地安装 Chrome 或 Chromium。如果未安装，工具会告知你，并引导你返回静态检查。

CLI 命令

npm 包提供了一个 CLI 入口点，用于设置、诊断和托管品牌连接器：

npx @brandsystem/mcp doctor                      # local checkup: Node, profile, .brand/ state, credential permissions, client configs
npx @brandsystem/mcp install --client claude-code # write MCP config (dry-run by default; add --write to apply, existing config backed up)
npx @brandsystem/mcp install --client cline --write
npx @brandsystem/mcp install --client cursor --profile full
npx @brandsystem/mcp inspect                     # version, profile, tool list, .brand/ artifact inventory

npx @brandsystem/mcp brandcode connect https://brandcode.studio/start/brands/pendium
npx @brandsystem/mcp brandcode sync
npx @brandsystem/mcp brandcode status

install 不会覆盖其他服务的条目：它会进行深度合并，先备份现有文件，并拒绝无效的 JSON。它会将规范固定为你运行时的版本（@brandsystem/mcp@<version>），Codex 和 Cline 也一样；传入 --unpinned 可改为写入浮动版本 @brandsystem/mcp。对于受保护的托管品牌，请添加 --share-token=TOKEN。

受信任的 Studio 来源。 凭据（会话、管理员和共享令牌）只会发送到受信任的 Brandcode Studio 来源——默认是 https://www.brandcode.studio 和 https://brandcode.studio——并且只有来自受信任来源的软件包声明的批准，才能将品牌标记为 production_approved。其他主机仍可用于读取公开软件包（仅限 https、受 SSRF 防护，不发送凭据），但其批准声明会被忽略。对于本地开发或暂存环境，可使用 BRANDCODE_STUDIO_TRUSTED_ORIGINS 添加来源（以逗号分隔；必须使用 https，但明确列出的 http://localhost、http://127.0.0.1 或 http://[::1] 除外）。

签名软件包。 Brandcode Studio 为软件包签名时（Ed25519，密钥固定在 src/connectors/brandcode/signing-keys.ts 中），连接器会验证签名，并将其存储为 .brand/brandcode-package.sig.json。有效签名可使任意来源的软件包获得 production_approved，因此复制的软件包仍可验证。无效签名绝不会获得批准：包括正文遭篡改、密钥未知或密钥错误的情况。brand_brandcode_connect 和 brand_brandcode_sync 会将 package_signature 报告为 signed/verified、signed/invalid 或 unsigned；brand_audit 则会标记拉取后被修改的已签名软件包。将 BRANDCODE_REQUIRE_SIGNED_APPROVAL=true 设为拒绝未签名软件包的批准。请参阅 docs/SIGNED-PACKAGES.md。

---

.brand/ 目录

运行完整流水线后，你的 .brand/ 目录如下所示：

.brand/
  brand.config.yaml              # Client name, industry, source URLs, session state
  core-identity.yaml             # Colors, typography, logos with confidence scores
  extraction-evidence.json       # Multi-page rendered evidence bundle (optional)
  design-synthesis.json          # Structured design synthesis (radius, shadow, layout, personality)
  DESIGN.md                      # Portable agent-facing design brief
  tokens.json                    # DTCG design tokens (compiled output)
  brand-runtime.json             # Compiled runtime contract (single-doc brand context)
  interaction-policy.json        # Enforceable rules (anti-patterns, voice, claims)
  needs-clarification.yaml       # Items requiring human review
  brand-report.html              # Portable HTML brand report
  visual-identity.yaml           # Session 2: composition, patterns, anti-patterns
  visual-identity-manifest.md    # Session 2: compiled VIM document
  system-integration.md          # Session 2: CLAUDE.md / .cursorrules setup guide
  messaging.yaml                 # Session 3: perspective, voice, brand story
  messaging-audit.md             # Session 3: voice fingerprint analysis
  brand-story.md                 # Session 3: compiled brand narrative
  assets/
    logo/
      logo-wordmark.svg          # Extracted logo files
    illustrations/               # Brand illustrations with MANIFEST.yaml
    stickers/                    # Brand stickers with MANIFEST.yaml
    patterns/                    # Brand patterns with MANIFEST.yaml
  checks/                        # Rendered-check screenshots (brand_preflight render=true, screenshot=true)

文件详情

文件	格式	用途
brand.config.yaml	YAML	项目元数据：客户端名称、行业、网站 URL、Figma 文件密钥、会话编号、架构版本
core-identity.yaml	YAML	所有提取的品牌数据：颜色（含角色和置信度）、字体排版（含字体系列和字重）、徽标规范（含内联 SVG 和数据 URI）、间距
extraction-evidence.json	JSON	从有代表性的页面和视口捕获的多页面渲染证据。包含用于支撑综合分析的屏幕截图、计算所得元素和 CSS 自定义属性
design-synthesis.json	JSON	对品牌进行结构化设计解读。包含根据证据和当前品牌身份推导出的圆角、阴影、间距、布局、组件、动效和个性特征
DESIGN.md	Markdown	根据证据包和当前品牌状态综合整理的便携式 Agent 设计简介
tokens.json	JSON	DTCG 设计令牌。包含颜色和字体排版，以及可用时由综合分析驱动的圆角、阴影、布局、间距和动效分组
brand-runtime.json	JSON	面向 AI Agent 的单文档品牌契约。将全部 4 个会话 YAML 合并为扁平、便于快速访问的格式。仅包含中等及以上置信度的值。由 brand_compile 编译，由 brand_runtime 读取
interaction-policy.json	JSON	可执行的规则引擎。包含视觉反模式、语气限制（禁用表达、AI 腔模式）和内容声明政策。供预检和评分工具使用
needs-clarification.yaml	YAML	按优先级排列的待确认事项列表：系统无法有把握地确定的内容，例如缺失的主色、低置信度值、未分配的角色
brand-report.html	HTML	独立的品牌报告。可离线使用，所有资源均内嵌。可粘贴到任意 AI 工具中作为品牌指南
assets/logo/	SVG/PNG	提取的徽标文件。SVG 的路径数据内嵌在 core-identity.yaml 中，以便移植

---

平台设置

Codex

使用软件包安装程序，它会调用 Codex 官方 MCP 配置命令：

npx @brandsystem/mcp install --client codex --write

安装后启动新的 Codex 任务。Codex CLI、Codex 应用和 IDE 扩展共享相同的 MCP 配置。

Cline

使用软件包安装程序，它会调用 Cline 官方的非交互式 MCP 命令：

npx @brandsystem/mcp install --client cline --write

启动新的 Cline 任务，然后询问：“如何将品牌指南用于 AI？” Cline CLI 和 IDE 扩展共享位于 ~/.cline/data/settings/cline_mcp_settings.json 的全局配置。

Claude Code

在项目根目录中创建 .mcp.json：

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

Cursor

在项目根目录中创建 .cursor/mcp.json：

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

Windsurf

创建 ~/.codeium/windsurf/mcp_config.json：

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

Claude Desktop

**一键安装：**安装 MCP Bundle — 从最新的 GitHub 发布版本下载 brandsystem-mcp-<version>.mcpb，并使用 Claude Desktop 打开。在安装对话框中选择品牌项目文件夹（.brand/ 所在位置）和工具配置（core 或 full）。维护者使用 npm run build:mcpb 构建该 Bundle（→ build/brandsystem-mcp-<version>.mcpb）；其清单根据 package.json 和已注册的 Core 工具生成。

**手动配置：**打开 Settings > Developer > Edit Config（claude_desktop_config.json）。Claude Desktop 不会在项目文件夹中启动服务，因此请将 BRANDSYSTEM_PROJECT_DIR 设置为存放（或将存放）.brand/ 的文件夹：

{
  "mcpServers": {
    "brandsystem": {
      "command": "npx",
      "args": ["-y", "@brandsystem/mcp"],
      "env": { "BRANDSYSTEM_PROJECT_DIR": "/absolute/path/to/your/brand-project" }
    }
  }
}

兼容性一览

将品牌接入 AI 工具有三种截然不同的方式——不要混为一谈：

方式	客户端	所需条件
本地直连 MCP（stdio）	Claude Code、Claude Desktop、Cursor、Windsurf	上方的 .mcp.json 配置——服务在你的机器上运行
远程托管 MCP	ChatGPT（开发者模式）及其他远程 MCP 客户端	已获批准的 Brandcode Studio 品牌和 bearer 密钥（预发布阶段，仅限获批客户端）。ChatGPT 连接的是远程 MCP 服务，而非本地 stdio 进程；OpenAI 记录了为私有服务使用安全隧道的选项
运行时文件复制	任意 AI 工具	将 brand-report.html 或 brand-runtime.json 上传到对话中——无需 MCP 连接

Claude Chat（不使用 MCP）

如果你使用的 Claude Chat 不支持 MCP：

1. 先在代码环境中运行流水线，生成 brand-report.html
2. 将 HTML 文件上传到 Claude Chat 对话中
3. 说：“将此内容用作我们创建所有内容时的品牌指南”

报告 HTML 是独立文件，可在任何 AI 工具中作为独立品牌参考使用。

---

故障排查

“找不到 .brand/ 目录”

除 brand_start、brand_init 和 brand_feedback 外，每个工具都需要 .brand/ 目录。请先运行 brand_start。

如果你使用的是托管品牌流程，而非本地提取，brand_brandcode_connect 也会在首次连接时自动创建 .brand/ 目录。

提取结果为空（未找到颜色或字体）

这通常表示网站通过 JavaScript 动态加载 CSS。brand_extract_web 只解析 <style> 块和链接样式表中的静态 CSS。解决方法：

• 运行 brand_extract_visual，使用无头 Chrome 和计算后的样式分析单个渲染页面
• 运行 brand_extract_site，在桌面和移动端采集有代表性的页面，并保存 extraction-evidence.json
• 提取后或手动编辑后运行 brand_generate_designmd，重新生成 design-synthesis.json 和 DESIGN.md
• 尝试其他页面，例如使用了更多内联或链接 CSS 的页面（如首页、博客文章）
• 使用 Figma 提取（brand_extract_figma）以获得更高准确度
• 提取后使用 brand_clarify 手动设置值

当 mode='auto' 时，如果提取质量较低且 Chrome/Chromium 可用，brand_start 已会尝试这种视觉回退方式，然后根据最佳可用证据生成 design-synthesis.json 和 DESIGN.md。

Figma 提取失败

brand_extract_figma 不会直接连接到 Figma。它分两个阶段运行：

1. 规划：返回要获取的数据（变量、样式、徽标）相关说明
2. 导入：处理你从 Figma MCP 工具传回的数据

请确保已连接单独的 Figma MCP 服务（例如 @anthropics/figma-mcp），并在导入模式下将获取的数据传递给 brand_extract_figma。

未检测到徽标

网页提取会查找 <img>、<svg> 和 <link rel="icon"> 元素。如果你的徽标通过 JavaScript 渲染或嵌入为 CSS 背景，请使用 brand_set_logo 手动添加，可使用 SVG 标记、URL 或数据 URI。

“响应大小超过 5K 目标”（控制台警告）

这只是一个提示性警告，并非错误。一些工具（brand_write、brand_deepen_identity）会返回内容丰富的对话指南，超过 5K 个字符。硬性上限为 50K，超过后会触发截断。

服务无法启动

# Verify Node.js >= 22.13.0
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

提交反馈

使用 brand_feedback 报告错误、使用障碍或想法：

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"

对于 Agent 遥测，请使用 category="agent_signal"，并提供 signal、tool_used 和 signal_context。品牌上下文会从 .brand/config 自动填充。

---

工作原理

置信度评分

每个提取的值都带有一个置信度等级：

等级	含义	令牌行为
confirmed	经人工验证	纳入令牌
high	强信号（例如 Figma 变量、名为 --brand-primary 的 CSS 自定义属性）	纳入令牌
medium	合理推断（例如 CSS 中出现频率最高的彩色颜色）	纳入令牌
low	弱信号（例如颜色仅在通用属性中出现一次）	从令牌中排除，并添加到 needs-clarification.yaml

来源优先级

在多个来源中发现相同的品牌元素时，优先级较高的来源胜出：

figma > manual > web

从 Figma 提取的主色会替换从网页提取的主色。人工确认的值会覆盖这两个自动化来源。在同一来源内，置信度较高的值优先。

网页提取

brand_extract_web 会获取目标 URL，并：

1. 解析所有 <style> 块和最多 5 个链接样式表
2. 从 CSS 属性和自定义属性中提取颜色值
3. 根据属性名称推断颜色角色（例如 --primary、--brand-accent）
4. 如果未找到明确指定的主色，则将出现频率最高的彩色颜色提升为“主色”
5. 提取字体系列并按出现频率排序
6. 从 <img>、<svg> 和 <link rel="icon"> 元素中查找徽标候选项
7. 将徽标下载并嵌入为内联 SVG 或 base64 数据 URI

视觉提取

brand_extract_visual 会启动无头 Chrome，访问目标 URL，并：

1. 捕获渲染页面的 2x DPR 截图
2. 从 body、header、hero、链接、卡片和按钮等语义元素中提取计算后的样式
3. 读取 :root 中的 CSS 自定义属性
4. 根据视觉上下文推断可能的颜色角色（例如，按钮背景 → 主色）
5. 将截图作为 MCP 图像块返回，以便调用方 Agent 进行定性视觉分析

对于 JS 渲染的应用和页面构建器，如果静态 CSS 解析无法捕获关键品牌信号，此路径可作为后备方案。

深度站点提取

brand_extract_site 将渲染路径扩展到首页之外：

1. 在同一域名下发现具有代表性的页面
2. 为每个选定页面捕获桌面端和移动端截图
3. 对多个按钮、卡片、链接、输入框、区域和其他组件实例进行采样
4. 将结果保存到 .brand/extraction-evidence.json
5. 将这些证据提供给 brand_generate_designmd / brand_compile，以生成 .brand/design-synthesis.json 和 .brand/DESIGN.md
6. 在 merge=true 时，将额外的颜色和字体合并回 core-identity.yaml

当首页不足以了解品牌系统，或你希望在编译令牌前收集更丰富的证据时，请使用此功能。

Figma 提取

brand_extract_figma 分两步衔接 Figma MCP 和 brandsystem：

1. 计划模式 -- 返回从 Figma 获取数据（变量、文本样式、徽标组件）的具体说明
2. 导入模式 -- 处理收集到的 Figma 数据，将变量名称映射到相应角色，并以 high 置信度合并到 core-identity.yaml

DTCG 令牌编译

brand_compile 会将 core-identity.yaml 转换为 Design Tokens Community Group 格式：

• 颜色会成为按角色命名的 $type: "color" 令牌。当网站在同一主题下，同一角色存在两种合理颜色时（例如页面表面和弱化面板表面），会将次要颜色保留为角色变体（surface-alt、text-secondary、neutral-alt、border-alt、accent-alt、action-alt），并编译为同级令牌（如 color.surface-alt），在其扩展中包含 variantOf。变体至少需要达到 medium 置信度，与基础颜色来自同一来源层级，并且与基础颜色有明显差异。每个基础角色在每个主题中最多有一个变体
• 排版会成为分组令牌，包含 fontFamily、dimension（尺寸）和 fontWeight 条目
• 间距会成为带比例值的 dimension 令牌
• 每个令牌都包含 $extensions["com.brandsystem"]，其中含有来源和置信度元数据
• 仅包含置信度达到 medium 或更高的值

---

更大的图景

四个动词层层递进——Build、Use、Evolve、Deploy。@brandsystem/mcp 负责 Build。.brand 运行时负责在各阶段之间流转。

 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 — 本软件包。提取品牌识别。编译治理规范。生成 .brand/ 目录。

Use — 托管于 mcp.brandcode.studio/{slug} 的 @brandcode/mcp。授权的 MCP 客户端默认会获取实时的完整品牌运行时。

Evolve — Brandcode Studio。品味笔记从记忆沉淀为正式治理规范。反模式不断累积。运行时随每个生产周期持续完善。

Deploy — 受治理的 .brand 仓库随你同行。将 Claude Design 指向它。为 Claude Code、Chat、Gemini、NotebookLM 编译资源包。所有界面都使用同一运行时。

渐进式深入

每个阶段都建立在前一阶段之上。可随时停止——每一步都能立即发挥作用。

阶段	可获得内容	方式
1. 免费扫描	品牌令牌 + DESIGN.md + 含平台设置指南的 HTML 报告	brand_start（自动），或 brand_extract_web / brand_extract_visual / brand_extract_site → brand_generate_designmd → brand_compile → brand_report
2. MCP 深入探索	Figma 提取、澄清、完整审计	第 1 次会话：使用 brand_extract_figma + brand_clarify
3. 视觉识别	构图规则、模式、反模式、VIM	第 2 次会话：brand_deepen_identity → brand_compile
4. 核心信息	品牌声音档案、观点、品牌故事	第 3 次会话：brand_extract_messaging → brand_compile_messaging
5. Studio 同步	拉取托管软件包、同步历史、共享分发	brand_brandcode_connect → brand_brandcode_sync → brand_brandcode_live，用于实时模式读取
6. 实时使用 MCP	授权 Agent 访问 mcp.brandcode.studio/{slug}，获取当前运行时、搜索知识、检查草稿、获取资源	@brandcode/mcp 使用 Bearer 密钥身份验证连接一次；跨 Agent 会话读取的内容始终保持最新
7. 部署到 Claude Design	Claude Design 原生读取 .brand/ 目录中的治理规范、叙事、证明要点和品味笔记，无需转换	将 Claude Design 指向包含 .brand/ 的仓库；从第一次生成开始，输出就符合品牌规范

第 1–4 阶段是独立的本地 MCP 工作流。开源、完全可移植、无需账户。

第 5–7 阶段是 Deploy 路径——.brand 运行时由此变为共享、实时提供，并由每个生成界面使用。可通过 Brandcode Studio 和 Column Five Media 获取。

可移植内容

工件	可移植？	归属方
@brandsystem/mcp（创作工具）	完全可移植 — 开源，适用于任何品牌	MIT 许可证
.brand/ 目录（运行时）	完全可移植 — 随品牌一起迁移的可移植工件	客户端
Brandcode 框架（架构 + 立场 + U-mech）	完全可移植 — 由每个品牌实例导入的通用层	开放
客户端主张、叙述、规则（I-content）	按实例区分 — 每个品牌独有	客户端
@brandcode/mcp（托管的 Use MCP）	提供运行时服务 — 经授权的 MCP 客户端可连接	Brandcode

---

开发

# 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

项目结构

src/
  index.ts              # Entry point -- stdio transport
  cli.ts                # CLI entry point for brandcode connect/sync/status
  server.ts             # MCP server creation and tool registration (all tools, priority order)
  tools/                # One file per tool
    brand-start.ts              # Entry point (Session 1)
    brand-status.ts             # Progress dashboard
    brand-extract-web.ts        # Website extraction
    brand-extract-figma.ts      # Figma extraction (plan/ingest)
    brand-set-logo.ts           # Manual logo add/replace
    brand-compile.ts            # Token + VIM + runtime compilation
    brand-clarify.ts            # Interactive clarification
    brand-audit.ts              # Schema validation
    brand-report.ts             # HTML report generation
    brand-init.ts               # Low-level directory scaffolding
    brand-deepen-identity.ts    # Session 2: visual identity interview
    brand-ingest-assets.ts      # Session 2: asset cataloging
    brand-preflight.ts          # Session 2: HTML compliance checking
    brand-extract-messaging.ts  # Session 3: voice/messaging audit
    brand-compile-messaging.ts  # Session 3: perspective + voice interview
    brand-build-personas.ts     # Session 4: buyer personas
    brand-build-journey.ts      # Session 4: buyer journey stages
    brand-build-themes.ts       # Session 4: editorial themes
    brand-build-matrix.ts       # Session 4: messaging matrix
    brand-audit-content.ts      # Content scoring (0-100)
    brand-check-compliance.ts   # Binary pass/fail compliance gate
    brand-audit-drift.ts        # Batch drift detection
    brand-runtime.ts            # Read compiled brand runtime contract
    brand-brandcode-connect.ts  # Hosted brand connect
    brand-brandcode-sync.ts     # Hosted brand sync
    brand-brandcode-status.ts   # Hosted brand status
    brand-write.ts              # Content generation context loader
    brand-export.ts             # Portable brand file export
    brand-feedback.ts           # Bug reports + feedback
  connectors/
    brandcode/                  # Hosted brand client, persistence, and URL resolution
  lib/                  # Shared utilities
    brand-dir.ts        # .brand/ directory I/O (YAML, JSON, markdown, assets)
    confidence.ts       # Confidence scoring and source precedence
    css-parser.ts       # CSS color and font extraction
    dtcg-compiler.ts    # DTCG token compilation
    color-namer.ts      # Human-readable color name generation
    content-scorer.ts   # Brand compliance scoring engine
    logo-extractor.ts   # Logo candidate detection
    svg-resolver.ts     # SVG inlining and base64 encoding
    report-html.ts      # HTML report generation
    vim-generator.ts    # Visual Identity Manifest + system integration markdown
    runtime-compiler.ts # Compile brand-runtime.json from 4 source YAMLs
    interaction-policy-compiler.ts  # Compile interaction-policy.json (enforceable rules)
    response.ts         # Structured MCP response builder
    version.ts          # Package version reader
  types/
    index.ts            # TypeScript type definitions
  schemas/
    index.ts            # Zod schemas for validation (7 schema files)
bin/
  brandsystem-mcp.mjs   # CLI entry point
specs/
  brand-runtime-schema.md         # Runtime contract documentation
  interaction-policy-schema.md    # Interaction policy documentation
test/
  lib/                  # Library unit tests (9 files)
  tools/                # Tool tests (2 files: export + smoke)
  server.test.ts        # Server creation smoke test

---

Agent 评估套件

eval/ 目录提供固定测试数据、方法论和可运行的测试框架，用于衡量对 Agent 来说重要的指标：真实提示词下的首个工具选择、响应 Token 预算、信封格式符合性、针对已标注案例的合规检查准确率，以及第二个 Agent 能否在没有任何说明的情况下使用生成的运行时。运行确定性测试层，请使用 npm run eval；依赖模型的测试层（首个工具选择）可通过 ANTHROPIC_API_KEY 选择性启用。结果仅发布自实际运行，并注明模型版本和日期 — 该仓库提供的是证据工具，而非未经验证的说法。请参阅 eval/README.md。

安全

• 请通过仓库的 Security 页面 → Advisories →“Report a vulnerability”私下报告漏洞。 请参阅 SECURITY.md。请勿为疑似漏洞公开提交问题。
• 设计上以本地运行优先。 提取和编译在你的计算机上运行。网络活动仅限于：获取你指定工具使用的来源（网站、通过你自己的 Figma MCP 获取的 Figma 内容）、连接托管品牌时可选的 Brandcode Studio 连接器调用，以及可选的 brand_feedback 报告。
• 本地写入的内容： 所有内容都写入工作目录中的 .brand/。连接器凭据存储在 .brand/brandcode-auth.json 中（已加入 gitignore）。

许可证

MIT