BrandKit MCP

BrandKit MCP

Model Context Protocol を通じて、あらゆる AI ツールから自社の完全なブランド・アトミックシステムにアクセスできるようにします。

BrandKit MCP v2 は、企業の完全なブランド・アトミックシステム（言語的アイデンティティ（ポジショニング、オーディエンス、メッセージング、差別化、コンセプト、ボイス）とビジュアルアイデンティティ（カラー、タイポグラフィ、コンポーネント、トークン、モーション、アセット））を、Model Context Protocol (MCP) を通じて Claude やその他の AI ツールに公開するオープンソースの MCP サーバーです。読み取り専用ツール18個、ローカル書き込みツール1個、リソース14個を提供します。LLM がウェブサイト、アプリ、マーケティング用アセットの構築を支援する際、必要な正確なブランド表現やビジュアルルールに、構造化された形式で即座にアクセスできます。仕様だけでなく、ブランドの感覚を伝える、人が作成したテイストプリマーも含まれています。

クイックスタート

# 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"]
#        }
#      }
#    }

init は、--force が明示されていない限り、既存の 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

human/ ディレクトリは、意図的に MCP サーバーの対象外となっています。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	ロゴとブランドアセット
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	base、web、product の差分

stdio トランスポートでは、brandkit.config.yaml、DESIGN.md、PRODUCT.md を更新する sync_brand_docs も公開されます。ネットワークトランスポートでは、デフォルトでこの書き込み可能なツールは非表示になり、実行も拒否されます。

テイストプリマー

7つのクリエイティブ／言語系ツール（get_brand_overview、get_positioning、get_audience、get_messaging、get_differentiation、get_concepts、get_voice）は、magic_trick.md の内容をそのまま含む _taste_primer フィールドを挿入します。get_magic_trick は、ラップせずにプリマーを直接返します。

MCP リソース

BrandKit MCP は、MCP リソースとして 14 個の brand:// URI を公開します。

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 倍という上限があります。そのため、空または未対応のエントリーが並ぶツリーによって、ファイル数を数える前に処理が無制限に増えることはありません。ルート内のシンボリックリンクおよびハードリンクのエイリアスは、正規のファイル ID に基づいて 1 件として数えられます。エイリアスを使って、ルート内であることの確認や上限を回避することはできません。上限と同じ値までは許可されますが、次のバイト、ファイル、またはパスセグメントを超えると、ブランドからの相対パスを含むエラーが発生し、起動に失敗します。大規模なブランドでは、型付けされた ingestion の各値を、組み込みの安全上限（ファイルあたり 64 MiB、合計 512 MiB、ファイル数 10,000 件、パスセグメント数 64 個）まで引き上げることができます。maxTotalBytes は maxFileBytes 以上である必要があります。

version: 2 は必須です。このフィールドがない設定ファイル、または version: 1 を宣言している設定ファイルでは、起動時にサーバーが BrandkitV1ConfigError をスローします。

コンテキストシステム

BrandKit v2 は、3 つのコンテキストをサポートしています。

コンテキスト	目的
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 が書き込むことはありません。テイストの指針はブランドの感性を表すものです。必ず人が作成したままにしてください。

トークンの出力形式。 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 を指定すると、そのホスト名に対する信頼が設定されます。ワイルドカードバインド（0.0.0.0 または ::）は、server.allowedHosts が明示されていない場合、起動時に失敗します。

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) オリジンです。リストが空の場合、Origin ヘッダーのないリクエストは MCP クライアント向けとして引き続き有効ですが、Origin が指定されている場合は、信頼された Host のホスト名を使用する必要があります。ブラウザーアプリケーションが別のオリジンでホストされている場合は、allowedOrigins を明示的に設定してください。allowedHosts の IPv6 項目には角括弧を使用します。例：[2001:db8::10]。

プレビュー UI は意図的にループバック専用となっており、ワイルドカード、LAN、パブリックのバインドホストを拒否します。また、すべてのページと静的アセットに同じ Host および Origin の検証を適用します。ローカルマシンの外部でデータを利用できるようにするには、認証済みの MCP HTTP トランスポートを使用してください。

Docker Compose

デフォルトの Compose サービスは、サポート対象の Streamable HTTP トランスポートを http://127.0.0.1:3001/mcp で実行します。バンドル済みの Acme のサンプルを使用するため、新しくチェックアウトした場合でも、ホスト側にブランドファイルを用意する必要はありません。起動前にベアラートークンを設定してください。

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 に 1 つ含まれています。すべての 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 のランタイムファイルは不変です。そのため、この Function が 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 の strict モード
• .js 拡張子を付けた ESM インポート
• any 型は使用しないでください。適切なインターフェースを使用してください
• テストには Vitest を使用します

ライセンス

MIT -- 詳細は LICENSE を参照してください。

---

Anthropic が Model Context Protocol を使用して構築しました。