BrandKit MCP

BrandKit MCP

通过 Model Context Protocol，让每个 AI 工具都能访问公司的完整品牌原子系统。

BrandKit MCP v2 是一个开源 MCP 服务，可通过 Model Context Protocol（MCP），向 Claude 和其他 AI 工具提供公司的完整品牌原子系统——包括语言识别（定位、受众、信息传达、差异化、概念、品牌语调）和视觉识别（颜色、字体、组件、设计令牌、动效、资源）。它提供 18 个只读工具、一个本地写入工具和 14 项资源。当大模型协助构建网站、应用或营销素材时，可以即时、有序地访问所需的准确品牌语言和视觉规则——其中还包括由人工撰写的品味指南，传递品牌直觉，而不只是规格。

快速开始

# 1. Install
npm install -g brandkit-mcp

# 2. Scaffold a new brand atomic system from the starter template
brandkit-mcp init

# 3. Edit the scaffolded files with your brand content

# 4. Wire into Claude Desktop (or any MCP-compatible client)
#    Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
#    {
#      "mcpServers": {
#        "brandkit": {
#          "command": "brandkit-mcp",
#          "args": ["serve"]
#        }
#      }
#    }

除非明确指定 --force，否则 init 不会更改现有的 brandkit.config.yaml 或 brand_atomic_system/。使用强制选项时，只会对常规的单链接配置文件和真实目录进行干净替换； 符号链接、硬链接配置文件和特殊文件目标均会被拒绝。

仓库结构

品牌原子系统位于单个 <brand-root>/ 目录下（默认为 ./brand_atomic_system）：

<brand-root>/
├── readme.md
├── magic_trick.md               # human-authored taste primer
├── brandkit.config.yaml         # version: 2
├── human/                       # PDFs and human-only material (MCP ignores)
│   └── *.pdf
└── agent/
    ├── verbal/
    │   ├── positioning.md
    │   ├── audience.yaml
    │   ├── messaging.md
    │   ├── differentiation.md
    │   ├── concepts.md
    │   └── voice.md
    └── visual/
        ├── colors_and_type.css
        ├── fonts/
        ├── assets/
        ├── components/
        ├── tokens/
        ├── motion/
        │   ├── motion.json
        │   └── motion.css
        └── artifacts/
            ├── web/             # override layer
            └── product/         # override layer

MCP 服务会有意忽略 human/ 目录——可将 PDF、印刷规格或其他仅供人工使用的材料放在其中。agent/ 下的所有内容都会被索引并提供服务。

MCP 工具参考

BrandKit MCP 向 AI 助手提供 18 个工具：

工具	描述
get_brand_overview	高层概览 + 品味指南
get_magic_trick	原样返回 magic_trick.md
get_positioning	定位文档
get_audience	解析后的受众 YAML
get_messaging	信息传达文档
get_differentiation	差异化文档
get_concepts	创意概念/方向
get_voice	品牌语调文档
get_colors_and_type	颜色 + 字体自定义属性
get_assets	Logo + 品牌资源
get_fonts	字体字形
get_components	UI 基础组件
get_tokens	设计令牌示例
get_motion	动效系统（json + css）
get_css	colors_and_type.css + motion.css 文本
search_brand	全文搜索
validate_usage	验证品牌规范合规性
get_context_diff	比较基础版本、网页版本和产品版本

stdio 传输还会提供 sync_brand_docs，用于更新 brandkit.config.yaml、DESIGN.md 和 PRODUCT.md。默认情况下，网络传输会隐藏并拒绝此写入工具。

品味指南

七个创意/语言工具（get_brand_overview、get_positioning、get_audience、get_messaging、get_differentiation、get_concepts、get_voice）会注入 _taste_primer 字段，其中原样包含 magic_trick.md。get_magic_trick 直接返回该指南，不作包装。

MCP 资源

BrandKit MCP 将 14 个 brand:// URI 作为 MCP 资源公开：

URI	描述
brand://overview	品牌概览
brand://magic_trick	品味入门
brand://verbal/positioning	定位文档
brand://verbal/audience	受众 YAML
brand://verbal/messaging	信息传达文档
brand://verbal/differentiation	差异化文档
brand://verbal/concepts	创意概念
brand://verbal/voice	品牌语调文档
brand://visual/colors_and_type	色彩 + 字体排版 CSS
brand://visual/assets	资源索引
brand://visual/fonts	字体索引
brand://visual/components	组件索引
brand://visual/tokens	令牌示例
brand://visual/motion	动效系统

配置

项目根目录中的 brandkit.config.yaml 文件用于控制 BrandKit MCP：

version: 2
brand:
  name: Acme Corp
  description: Plumbing for builders.
  root: ./brand_atomic_system
contexts: [base, web, product]
ignore:
  - human/
ingestion:
  maxFileBytes: 16777216
  maxTotalBytes: 134217728
  maxFiles: 1000
  maxDepth: 16

忽略项是相对于 brand.root 的路径。它们会匹配指定路径及其目录边界内的后代路径，因此 human/ 不会匹配 humanity/。

品牌导入会在读取文件内容前受到限制。默认值允许每个文件最大为 16 MiB、所有唯一输入总计最大为 128 MiB、最多 1,000 个唯一文件，以及 brand.root 下最多 16 个路径段。固定文档、发现的组件和令牌、清单、字体及图像资源共用此预算。目录枚举也限制为配置文件数上限的 4 倍，因此空条目或不受支持的条目构成的目录树不会在文件计数前造成无界工作。根目录内的符号链接和硬链接别名会按规范文件身份计为一次；别名无法绕过目录包含范围检查或限制。达到上限时仍可接受，超过上限的下一个字节、文件或路径段会导致启动失败，并显示相对于品牌目录的错误。大型品牌可以将这些带类型的 ingestion 值提高到内置安全上限（每个文件 64 MiB、总计 512 MiB、10,000 个文件和 64 个路径段）；maxTotalBytes 必须至少等于 maxFileBytes。

必须设置 version: 2。缺少此字段或声明 version: 1 的配置文件会导致服务在启动时抛出 BrandkitV1ConfigError。

上下文系统

BrandKit v2 支持三种上下文：

上下文	用途
base	共享基础——字体、核心色彩、全局令牌
web	面向公众的网站覆盖项（agent/visual/artifacts/web/）
product	SaaS 应用覆盖项（agent/visual/artifacts/product/）

口头内容（agent/verbal/）没有上下文覆盖项——它全局适用。视觉内容可通过 artifacts/ 层按上下文覆盖。

从 v1 迁移

2.0.0 是一个破坏性版本。 目录布局、上下文词汇和工具接口都已更改。此版本不包含自动迁移功能——路径映射需要手动完成：

v1 路径	v2 路径
brand/shared/colors/*.css	agent/visual/colors_and_type.css
brand/shared/typography/*.css	agent/visual/colors_and_type.css
brand/shared/logos/*	agent/visual/assets/
brand/shared/components/*.md	agent/visual/components/*.md
brand/shared/voice/brand-voice.md	agent/verbal/voice.md
brand/shared/guidelines/*.md	agent/verbal/{positioning,messaging,differentiation,concepts}.md
brand/marketing/*	agent/visual/artifacts/web/*
brand/product/*	agent/visual/artifacts/product/*

还必须更新 brandkit.config.yaml，声明 version: 2 并使用新的 brand.root 字段。v1 配置会在启动时抛出 BrandkitV1ConfigError——更新配置前，服务无法启动。

约定

magic_trick.md 由人工编写。 MCP 会读取它，但 sync_brand_docs 绝不会写入它。品味指南体现了品牌的直觉——必须由人来维护。

Token 输出格式。 get_tokens 工具支持 CSS 自定义属性、SCSS 变量、Tailwind 配置、W3C Design Tokens 和扁平 JSON。

品牌文件必须保留在 brand.root 内。 每个固定和发现的品牌输入都会在配置的根目录下解析并打开。如果符号链接的最终目标仍位于该根目录内，则可以接受；会忽略逃逸出根目录的符号链接和清单路径，并发出警告，且绝不会通过工具、资源或预览页面索引或公开其内容。

配置必须是常规的单链接文件。 brandkit.config.yaml 不能是符号链接、硬链接、目录或其他非常规条目。服务端会将配置持久化操作绑定到启动时加载的文件；如果服务端运行期间该路径被替换，sync_brand_docs 会拒绝读取或覆盖替换后的文件。成功更新配置时会在同一目录中进行原子替换，并保留现有权限。

传输方式。 服务端支持 stdio（推荐用于 Claude Desktop）、SSE（旧版 HTTP）和 Streamable HTTP（当前 MCP 规范）。在本地开发时，网络传输绑定到环回地址仍无需身份验证。在将 SSE 或 HTTP 绑定到任何非环回主机之前，请设置 BRANDKIT_AUTH_TOKEN；客户端必须在每个请求中通过 Authorization: Bearer <token> 发送该令牌。

默认情况下，所有网络传输均为只读，包括环回地址、独立部署和 Vercel 部署。若要有意通过 SSE 或 Streamable HTTP 公开 sync_brand_docs，请使用 brandkit-mcp serve --transport http --allow-write-tools 启动 CLI（或在程序化 startServer 选项中设置 allowWriteTools: true）。请将此视为特权模式：绑定到非环回地址时仍必须进行身份验证。stdio 无需此标志即可保留预期的本地写入工作流。没有可写配置上下文的适配器绝不会公布该工具，即使启用了特权模式也不例外。

所有网络传输都会拒绝不受信任的 Host 和 Origin 标头，并返回 HTTP 403。环回监听器会自动信任环回主机名和来源，包括 IPv4、IPv6 和临时端口。指定非环回 server.host 时，系统会为该确切主机名建立信任。除非明确设置 server.allowedHosts，否则通配符绑定（0.0.0.0 或 ::）会在启动时失败：

server:
  transport: http
  host: 0.0.0.0
  port: 3001
  allowedHosts:
    - mcp.example.com       # hostname only; Host-header ports are ignored
  allowedOrigins:
    - https://app.example.com

allowedOrigins 条目必须是确切的 HTTP(S) 来源；如果端口不是默认端口，也必须包含端口。如果该列表为空，则对于 MCP 客户端，不带 Origin 标头的请求仍然有效；但如果提供了 Origin，其主机名必须使用受信任的 Host 主机名。当浏览器应用托管在不同来源时，请明确配置 allowedOrigins。allowedHosts 中的 IPv6 条目必须使用方括号，例如 [2001:db8::10]。

预览 UI 特意限制为仅环回地址，并拒绝任何通配符、局域网或 公共绑定主机。它还会对每个页面和静态资源应用相同的 Host 和 Origin 验证。 如果数据需要在本机之外使用，请使用经过身份验证的 MCP HTTP 传输。

Docker Compose

默认的 Compose 服务运行受支持的 Streamable HTTP 传输，地址为 http://127.0.0.1:3001/mcp。它使用随附的 Acme 示例，因此全新检出无需主机端品牌文件。启动前请设置 Bearer 令牌：

export BRANDKIT_AUTH_TOKEN="$(node -e "process.stdout.write(require('crypto').randomBytes(32).toString('hex'))")"
docker compose up --build --wait --wait-timeout 60
npm run test:docker-smoke

令牌会在运行时注入，经过身份验证的健康检查也需要该令牌。未设置令牌时，Compose 会拒绝启动。若要使用自己的品牌，请挂载常规配置文件和品牌目录，将 BRANDKIT_CONFIG 设置为该配置的容器路径，并将 server.allowedHosts 限定为客户端实际使用的主机名。请勿将令牌放入镜像或配置文件中。Compose 有意仅公开经过身份验证的 MCP 服务；请在可信的本地计算机上单独运行预览 CLI。现有的 stdio 容器集成可以通过覆盖镜像命令来使用 node /app/dist/cli/index.js serve --transport stdio --config <path>，且无需发布端口。

Vercel

该仓库包含一个无状态 Node.js Function，路径为 /api/mcp。请在每个 Vercel 环境中设置 BRANDKIT_AUTH_TOKEN，并将其作为 Bearer 令牌发送。 Vercel 的 VERCEL_URL 和 VERCEL_PROJECT_PRODUCTION_URL 会被自动信任。对于自定义域名，请将 BRANDKIT_ALLOWED_HOSTS 设置为以逗号分隔的主机名列表，不含协议或路径。

默认部署会显式打包 templates/starter/**，并以只读方式提供其中的数据。若要部署其他品牌，请将 BRANDKIT_CONFIG 设置为仓库相对的配置路径，并更新 vercel.json 中的 functions.api/mcp.js.includeFiles，以包含该配置及其完整的品牌根目录。Vercel 运行时文件不可变；该函数绝不会声明 sync_brand_docs。 每个请求都会创建并关闭自己的 MCP 服务和传输，因此请求不依赖预热实例或会话亲和性。

CLI 参考

brandkit-mcp <command> [options]

Commands:
  init [directory]      Scaffold a brand atomic system from the starter template
  validate [config]     Validate configuration and scan for issues
  serve                 Start the MCP server
  preview               Start the local preview UI for browsing the brand atomic system
  docs                  Generate project documentation files

Global Options:
  --version             Show version number
  --help                Show help

serve 接受 --transport <stdio|sse|http>、--host <host>、--port <number>、--config <path>、--watch 和特权网络选项 --allow-write-tools。

贡献

欢迎贡献。

git clone https://github.com/ejwhite7/brandkit-mcp
cd brandkit-mcp
npm install
npm run build
npm test

• TypeScript 严格模式
• 使用带 .js 扩展名的 ESM 导入
• 不使用 any 类型——请使用适当的接口
• 测试使用 Vitest

许可证

MIT——详情请参阅 LICENSE。

---

由 Anthropic 基于 Model Context Protocol 构建。