BrandKit MCP
BrandKit MCP
Give every AI tool access to your company's complete design system via the Model Context Protocol.
BrandKit MCP is an open-source MCP server that makes your design system natively accessible to Claude, Cursor, and any MCP-compatible AI tool. Drop your brand files in, connect once, and every AI session has access to your exact colors, typography, components, guidelines, and more.
Features
Zero-config ingestion -- drop in CSS files, markdown docs, PDFs, SVGs, and fonts. No YAML token files to write.
Context-aware -- separate marketing site and product app design systems in one project, with shared defaults.
Full MCP capability surface -- 12 tools, 16+ resources (under the
brandkit://URI scheme), and 4 reusable prompts (design-with-brand,audit-brand-compliance,generate-tailwind-theme,explain-brand-decision).Three transports -- stdio (Claude Desktop), SSE (legacy HTTP), and Streamable HTTP (current MCP spec).
5 token output formats -- CSS custom properties, SCSS variables, Tailwind config, W3C Design Tokens, and flat JSON.
Local preview server -- visual design system browser at localhost:3000.
Multiple deployment options -- local stdio, SSE over HTTP, Docker, Vercel, Cloudflare Workers.
Full-text search across your entire design system.
Hot reload -- file changes automatically re-index in under 1 second.
Project doc injection -- auto-generates CLAUDE.md, AGENTS.md, SKILLS.md, and DESIGN.md for your repository.
Related MCP server: guardrails-mcp-server
Quick Start (30 seconds)
# 1. Clone and install
git clone https://github.com/ejwhite7/brandkit-mcp
cd brandkit-mcp
npm install
npm run build
# 2. Initialize your brand directory
node dist/cli/index.js init --name "YourBrand"
# Or install globally with npm link
npm link
brandkit-mcp init --name "YourBrand"
# 3. Add your design files to the brand/ directory
# Drop CSS files, markdown docs, logos, fonts, PDFs...
# 4. Start the MCP server
node dist/cli/index.js serve
# 5. Or start the preview server to browse visually
node dist/cli/index.js preview --openNote: Once the package is published to npm,
npx brandkit-mcp@latest initwill work directly without cloning.
Claude Desktop Setup
Add BrandKit MCP to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
stdio Transport (recommended)
{
"mcpServers": {
"brandkit": {
"command": "node",
"args": ["/path/to/brandkit-mcp/dist/cli/index.js", "serve"],
"env": {}
}
}
}SSE Transport (for HTTP-based clients)
{
"mcpServers": {
"brandkit": {
"transport": "sse",
"url": "http://localhost:3001/sse"
}
}
}Start the SSE server first:
node dist/cli/index.js serve --transport sse --port 3001Supported File Types
File Type | Extensions | What BrandKit MCP Extracts |
CSS |
| Color tokens, typography tokens, custom properties, media queries |
Markdown |
| Component docs, brand guidelines, voice & tone, color palettes |
| Brand guidelines, usage rules, text content | |
SVG |
| Logo variants, icons, textures/patterns |
Images |
| Logo variants with dimensions, textures/patterns |
Fonts |
| Font family, weight, style metadata |
Design System Directory Structure
BrandKit MCP scans a brand/ directory with three context levels:
brand/
shared/ # Tokens and assets shared across all contexts
colors/
colors.css # CSS custom properties for color tokens
typography/
typography.css # Font families, sizes, weights, line heights
logos/
logo-primary.svg # Primary logo
logo-mark.svg # Logo mark / icon
logo-wordmark.svg # Text-only logo
usage-guidelines.md # Logo usage rules
voice/
brand-voice.md # Brand personality, tone, writing principles
guidelines/
accessibility.md # WCAG compliance, contrast ratios
spacing.md # Spacing system documentation
marketing/ # Marketing-site-specific overrides and assets
colors/
marketing-overrides.css # Warmer accent tones for landing pages
components/
hero-section.md # Hero section specs and examples
feature-card.md # Feature card component docs
guidelines/
marketing-writing.md # Headline and CTA guidelines
product/ # Product-app-specific overrides and assets
colors/
product-overrides.css # Subdued accent tones for the app UI
components/
data-table.md # Data table component specs
sidebar-nav.md # Navigation component docs
guidelines/
ui-patterns.md # Loading states, empty states, formsConvention: Subdirectory names (colors/, typography/, logos/, components/, guidelines/, voice/, textures/) determine how files are parsed. Place files in the matching directory for automatic classification.
MCP Tools Reference
BrandKit MCP exposes 12 tools to AI assistants:
# | Tool | Description | Key Parameters |
1 |
| High-level summary of the entire design system | (none) |
2 |
| All color tokens with hex values, roles, and usage |
|
3 |
| Font families, sizes, weights, and line heights |
|
4 |
| Logo variants with metadata and usage guidelines |
|
5 |
| Component documentation, specs, and code examples |
|
6 |
| Brand voice, accessibility, and design guidelines |
|
7 |
| Design tokens in any of 5 output formats |
|
8 |
| Background textures and patterns |
|
9 |
| Raw parsed CSS with all custom properties |
|
10 |
| Full-text search across the entire design system |
|
11 |
| Differences between marketing and product contexts |
|
12 |
| Validate color/typography usage against the system |
|
Tool Usage Examples
Get all colors for the marketing context:
{
"tool": "get_colors",
"arguments": {
"context": "marketing",
"role": "accent"
}
}Response:
## Colors (marketing context, role: accent)
| Token | Name | Hex | Role | Usage |
|-------|------|-----|------|-------|
| --color-accent | Accent | #ff6b6b | accent | Primary accent for CTAs |
| --color-accent-light | Accent Light | #ff8787 | accent | Hover states |
| --color-accent-dark | Accent Dark | #e63946 | accent | Active/pressed states |Search across the design system:
{
"tool": "search_brand",
"arguments": {
"query": "button hover state",
"context": "all",
"limit": 5
}
}Export tokens as Tailwind config:
{
"tool": "get_tokens",
"arguments": {
"format": "tailwind",
"context": "product",
"category": "colors"
}
}Compare marketing vs product design systems:
{
"tool": "get_context_diff",
"arguments": {
"aspect": "colors"
}
}Validate that your code uses approved colors:
{
"tool": "validate_usage",
"arguments": {
"colors": ["#1a1a2e", "#ff0000", "#e94560"],
"context": "marketing"
}
}Context System: Marketing vs Product
BrandKit MCP supports three directory-level contexts that model how real design systems work:
Context | Directory | Purpose |
shared |
| Tokens and guidelines common to both contexts. Acts as the default layer. |
marketing |
| Overrides and additions for the public-facing marketing website. |
product |
| Overrides and additions for the SaaS product application. |
How Context Resolution Works
Shared is the base. Every token and guideline in
shared/is available to both contexts.Context-specific values override shared values. If
shared/colors/colors.cssdefines--color-accent: #e94560andmarketing/colors/overrides.cssdefines--color-accent: #ff6b6b, then marketing context returns#ff6b6b.Context-specific additions are kept separate. A component defined only in
product/components/won't appear in marketing results.The "all" view is the union. Querying with
context: "all"returns every asset from all three directories.
When to Use Each Context
Use
context: "marketing"when generating landing pages, marketing emails, blog posts, or ad copy.Use
context: "product"when building app features, dashboards, settings pages, or in-app messaging.Use
context: "all"when you need a complete inventory or are searching broadly.Omit
context(defaults to "all") for general exploration.
Token Output Formats
The get_tokens tool supports 5 output formats:
CSS Custom Properties
:root {
--color-primary: #1a1a2e;
--color-secondary: #0f3460;
--color-accent: #e94560;
--font-family-primary: 'Inter', sans-serif;
--font-size-base: 1rem;
}SCSS Variables
$color-primary: #1a1a2e;
$color-secondary: #0f3460;
$color-accent: #e94560;
$font-family-primary: 'Inter', sans-serif;
$font-size-base: 1rem;Tailwind Config
module.exports = {
theme: {
extend: {
colors: {
primary: '#1a1a2e',
secondary: '#0f3460',
accent: '#e94560',
},
fontFamily: {
primary: ["'Inter'", 'sans-serif'],
},
fontSize: {
base: '1rem',
},
},
},
};W3C Design Tokens
{
"$schema": "https://design-tokens.github.io/community-group/format/",
"color": {
"primary": { "$type": "color", "$value": "#1a1a2e" },
"secondary": { "$type": "color", "$value": "#0f3460" },
"accent": { "$type": "color", "$value": "#e94560" }
}
}JSON Tokens
{
"colors": {
"--color-primary": { "value": "#1a1a2e", "name": "Primary" },
"--color-secondary": { "value": "#0f3460", "name": "Secondary" },
"--color-accent": { "value": "#e94560", "name": "Accent" }
}
}Project Documentation Files
BrandKit MCP can auto-generate project documentation files that give AI tools persistent context about your design system. Run:
node dist/cli/index.js docsThis generates four files:
File | Purpose |
CLAUDE.md | Project overview with tool usage instructions for Claude |
AGENTS.md | Multi-agent workflow context with design system summary |
SKILLS.md | Reusable skill definitions for design token lookup |
DESIGN.md | Complete design system reference document |
Delimiter System
Each generated file uses a clearly marked section that BrandKit MCP owns:
<!-- BRANDKIT:START -->
(auto-generated content here)
<!-- BRANDKIT:END -->Content outside these delimiters is preserved when you regenerate. This lets you add custom notes above or below the auto-generated section.
Preview Server
The preview server provides a visual browser for your design system at http://localhost:3000.
node dist/cli/index.js preview --port 3000 --watch --openPages
Page | URL | Description |
Dashboard |
| Overview with asset counts and quick links |
Colors |
| Color palette with swatches, hex values, and roles |
Typography |
| Font specimens with all sizes and weights |
Logos |
| Logo variants grid with download metadata |
Components |
| Component documentation with code examples |
Guidelines |
| Brand voice, accessibility, and design guidelines |
Textures |
| Background textures and patterns gallery |
Tokens |
| Token export in all 5 formats with copy-to-clipboard |
CSS |
| Raw parsed CSS custom properties |
Search |
| Full-text search across the design system |
The --watch flag enables hot reload: edit a brand file and the preview updates automatically.
Deployment
Local (stdio) -- Recommended for Claude Desktop
The simplest setup. The MCP server communicates over stdin/stdout:
node dist/cli/index.js serveConfigure Claude Desktop to launch the server automatically (see Claude Desktop Setup).
Local (SSE) -- For HTTP-based MCP Clients
Starts an HTTP server with Server-Sent Events transport:
node dist/cli/index.js serve --transport sse --port 3001 --watchConnect any MCP client to http://localhost:3001/sse.
Docker
Build and run with Docker:
docker build -t brandkit-mcp .
docker run -p 3001:3001 -v $(pwd)/brand:/app/brand:ro brandkit-mcpOr use Docker Compose:
docker-compose upThis starts both the MCP server (port 3001) and the preview server (port 3000).
Vercel
Deploy as a Vercel serverless function:
Install the Vercel CLI:
npm i -g vercelDeploy:
vercel --prodConnect to the SSE endpoint:
https://your-project.vercel.app/api/sse
The vercel.json configuration routes /api/sse and /api/messages to the adapter.
Cloudflare Workers
Deploy to Cloudflare Workers:
Install Wrangler:
npm i -g wranglerConfigure
wrangler.tomlwith your account detailsBundle your design system data at build time (Workers don't have filesystem access)
Deploy:
wrangler deploy
Standalone HTTP Server
Run a plain Node.js HTTP server without Express:
node dist/adapters/standalone.jsOr programmatically:
import { startStandaloneServer } from 'brandkit-mcp/adapters/standalone';
await startStandaloneServer(3001, './brandkit.config.yaml');CLI Reference
brandkit-mcp <command> [options]
Commands:
init [directory] Initialize a new brand directory with starter files
validate [config] Validate configuration and scan for issues
serve Start the MCP server
preview Start the local preview server
docs Generate project documentation files
Global Options:
--version Show version number
--help Show helpinit [directory]
Create a new brand directory with starter configuration and example files.
brandkit-mcp init .
brandkit-mcp init ./my-brand --name "Acme Corp"
brandkit-mcp init . --force # Overwrite existing filesOption | Description |
| Brand name for the config file |
| Overwrite existing files without prompting |
validate [config-path]
Validate the design system configuration and report any issues.
brandkit-mcp validate
brandkit-mcp validate ./brandkit.config.yamlChecks:
Config file exists and is valid YAML
All referenced directories exist
CSS files parse without errors
Markdown frontmatter is well-formed
No orphaned files outside recognized directories
serve
Start the MCP server for AI tool connections.
brandkit-mcp serve
brandkit-mcp serve --transport sse --port 3001
brandkit-mcp serve --config ./custom-config.yaml --watchOption | Description | Default |
| Transport: |
|
| Port for SSE transport |
|
| Path to config file | auto-detect |
| Enable hot reload |
|
preview
Launch the visual preview server.
brandkit-mcp preview
brandkit-mcp preview --port 8080 --watch --openOption | Description | Default |
| Preview server port |
|
| Path to config file | auto-detect |
| Enable hot reload |
|
| Open browser automatically |
|
docs
Generate project documentation files for AI tools.
brandkit-mcp docs
brandkit-mcp docs --output ./docs --config ./brandkit.config.yamlOption | Description | Default |
| Path to config file | auto-detect |
| Output directory for generated files |
|
Generates: CLAUDE.md, AGENTS.md, SKILLS.md, DESIGN.md
Configuration Reference
The brandkit.config.yaml file controls all aspects of BrandKit MCP:
# Required: your brand name
name: "Acme Corp"
# Optional: description shown in MCP server metadata
description: "Design system for Acme Corporation"
# Semantic version of your design system
version: "2.0.0"
# Context configuration
contexts:
marketing:
enabled: true
label: "Marketing Website"
description: "Public-facing marketing site (acme.com)"
product:
enabled: true
label: "Product App"
description: "SaaS application (app.acme.com)"
# Directory path overrides (relative to config file)
paths:
brand: "./brand"
shared: "./brand/shared"
marketing: "./brand/marketing"
product: "./brand/product"
# Preview server settings
preview:
port: 3000
host: localhost
# MCP server settings
server:
transport: stdio # "stdio" or "sse"
port: 3001 # Used when transport is "sse"
host: localhostThe only required field is name. Everything else has sensible defaults.
Contributing
Contributions are welcome! Here's how to get started:
Development Setup
git clone https://github.com/anthropics/brandkit-mcp.git
cd brandkit-mcp
npm install
npm run build
npm run dev # Watch modeHow to Add a New Parser
Create
src/parsers/your-parser.tsExport a parse function that accepts a file path and context
Return typed data matching the interfaces in
src/types/design-system.tsAdd the file type to
classifyFileType()insrc/scanner/directory-scanner.tsAdd a processing case in
processFile()insrc/indexer/index.tsWrite tests in
src/tests/parsers.test.ts
How to Add a New MCP Tool
Create
src/tools/your-tool.tsExport
TOOL_NAME,TOOL_DESCRIPTION,INPUT_SCHEMA, andhandler()Add the argument interface to
src/types/mcp.tsImport and register the tool in
src/tools/index.tsAdd the tool to the switch statement in the tools/call handler
Update the README tools reference table
Code Style
TypeScript strict mode enabled
ESM imports with
.jsextensionsNo
anytypes -- use proper interfacesAll public functions have JSDoc comments
Tests use Vitest
Running Tests
npm test # Run all tests
npm run test:watch # Watch mode
npx vitest run src/tests/parsers.test.ts # Single fileExamples
Acme Corp
A complete example design system is included at examples/acme-corp/. It demonstrates:
Shared color palette with neutral and semantic colors
Typography system with three font families
Logo usage guidelines
Brand voice and tone documentation
Accessibility standards
Marketing-specific color overrides and components (Hero Section, Feature Card)
Product-specific color overrides and components (Data Table, Sidebar Navigation)
Context-specific writing and UI pattern guidelines
To try it:
cd examples/acme-corp
node dist/cli/index.js preview --openStarter Template
A minimal starter template is available at templates/starter/. Use it as a starting point:
cp -r templates/starter/* .
node dist/cli/index.js validateLicense
MIT -- see LICENSE for details.
Built with the Model Context Protocol by Anthropic.
Available Tools
12 toolsget_brand_overviewA
Get a high-level overview of the design system: brand name, active contexts, asset inventory counts, and available design system sections.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden. It discloses that the tool returns brand name, active contexts, inventory counts, and sections. It does not mention side effects or permissions, but as a read-only overview, the absence is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence with no superfluous words. It front-loads the purpose and lists contents concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and low complexity, the description adequately covers what the tool returns. It could mention read-only nature or response format, but is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter documentation is needed. A baseline of 4 is appropriate as the description adds no parameter info but does not need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('high-level overview of the design system'), listing exact contents: brand name, active contexts, asset inventory counts, and sections. This clearly differentiates from sibling tools that focus on specific aspects (e.g., get_colors, get_components).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when a summary is needed before diving into specific design system elements, but lacks explicit when-not-to-use or alternative guidance. It is still clear enough for an AI to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_colorsA
Get the color palette with hex values, RGB values, usage guidelines, and semantic roles. Supports context filtering (marketing vs product) and output format selection.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Design context to query | all |
| role | No | Filter by semantic role: primary, secondary, accent, neutral, error, success, warning, info | |
| format | No | Output format | json |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses basic return contents (hex, RGB, guidelines, roles) and filtering options, but does not mention any behavioral traits like data source, caching, read-only semantics, or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with core purpose, then additional capabilities. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no required parameters, no output schema, and no annotations, the description adequately covers the tool's output and filtering options. It lacks details on return structure or error handling, but is sufficient for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds context about filtering ('marketing vs product') and output format selection, but does not significantly enhance meaning beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the color palette with specific elements (hex, RGB, usage guidelines, semantic roles). It distinguishes from siblings like get_tokens and get_typography by focusing on color-specific data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving color palette with optional filtering, but does not explicitly mention when to use this over alternatives (e.g., get_tokens) or provide 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_componentsA
Get component specifications, variants, CSS properties, and usage guidelines. Filter by context (marketing vs product) or category.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Design context to query | all |
| category | No | Filter by category: button, form, navigation, layout, card, modal, etc. | |
| name | No | Search by component name (partial match, case-insensitive) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like read-only nature, authentication needs, or rate limits, leaving the agent without necessary context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and filtering options without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lists what the tool returns (specifications, variants, CSS, guidelines) and filtering options, making it reasonably complete for a read-only tool with optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with parameter descriptions, so the baseline is 3. The description adds context about component content but doesn't enhance parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool retrieves component specifications, variants, CSS properties, and usage guidelines, distinguishing it from siblings like get_css and get_guidelines by combining multiple aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filtering by context and category, implying usage scenarios, but does not explicitly state when to use this tool versus alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_context_diffA
Compare marketing site vs product app design systems side-by-side, highlighting differences in colors, typography, and components.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Category to compare | all |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the core behavior (comparing and highlighting differences), but it does not disclose the output format, potential side effects, permissions, or rate limits. The behavior is simple and likely read-only, but the lack of output description is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence (18 words) that conveys the entire purpose without any fluff. Every word earns its place, making it highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no nested objects, no output schema), the description covers the main intent well. However, it does not describe the output format (e.g., what a 'highlight' looks like). Nonetheless, the context of sibling tools and the clear purpose makes it reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema coverage is 100% for the single parameter, and the schema description covers the enum values. The tool description mentions 'colors, typography, and components,' which aligns with the enum, adding marginal context. Since schema already provides good coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two specific design systems (marketing site vs product app) side-by-side, focusing on differences in colors, typography, and components. This specific verb-resource combination distinguishes it from sibling tools that retrieve individual elements or overviews.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing a side-by-side comparison of the two design systems. It provides clear context but does not explicitly state when not to use or mention alternatives, such as using individual get_* tools for a single system. Since siblings are listed, the context is fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_cssB
Get raw CSS file contents and extracted custom property definitions from the design system.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Design context to query | all |
| includeRaw | No | Include full raw CSS file contents (can be large) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should disclose behavioral traits. It does not warn that includeRaw=true can return large data, nor explain what 'extracted custom property definitions' means in terms of output structure. No details on performance or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded with the action 'Get'. However, it could benefit from more details without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is insufficient. It does not mention return structure, error conditions, or scope limitations. For a tool with moderate complexity, this leaves gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; it implies inclusion of raw CSS and custom properties but does not explicitly map to parameters or clarify the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves raw CSS file contents and custom property definitions from the design system. This specific verb-resource combination distinguishes it from sibling tools like get_tokens or get_colors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_tokens or get_typography. The description does not mention scenarios suited for raw CSS retrieval or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_guidelinesA
Get brand guidelines, voice and tone documentation, accessibility rules, and usage policies. Returns full markdown content.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Design context to query | all |
| section | No | Filter by section: brand-voice, accessibility, logo-usage, typography, colors, general |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing behavior. It states that the tool returns 'full markdown content', which is informative but does not mention whether the operation is read-only (likely), requires authentication, or has any side effects. The behavior is minimally disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the core purpose. Every sentence provides necessary information without extraneous content. It is appropriately concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters, no output schema, and no annotations. The description explains the purpose and output format adequately, but does not clarify how the 'context' and 'section' parameters interact (e.g., are they combined or exclusive?), nor does it detail the structure of the returned markdown. Given the simplicity, it is minimally complete but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters with descriptions and an enum for 'context'. The description adds that the output is 'full markdown content', but does not add specific meaning to the parameters beyond what the schema already covers. Since schema description coverage is 100%, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves brand guidelines, voice and tone documentation, accessibility rules, and usage policies. It uses a specific verb ('Get') and resource, and distinguishes itself from sibling tools like get_colors or get_logos by being the comprehensive guidelines tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for obtaining a broad set of guidelines, but it does not provide explicit guidance on when to use this tool versus the many sibling tools (e.g., get_brand_overview, get_colors). An agent would benefit from knowing that this returns a broader document, while other tools return specific subsets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_logosA
Get logo variants (primary, mark, wordmark, monochrome) with usage guidelines, minimum sizes, clear space rules, and forbidden uses. Optionally returns base64-encoded image data.
| Name | Required | Description | Default |
|---|---|---|---|
| variant | No | Filter by variant name (e.g., 'primary', 'mark', 'wordmark') | |
| format | No | Whether to include base64 data | metadata |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral aspects. It discloses optional base64 data return but omits details on rate limits, authentication requirements, or whether the data is cached. The description is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that quickly conveys the tool's purpose and key features. Every part is relevant and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description covers the main functionality well. It specifies what is returned (variants, guidelines, base64). A small gap is that it doesn't describe the output format for metadata, but it is relatively complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema: it repeats the variant filtering and format options. It mentions usage guidelines but these are not parameters. No significant extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves logo variants with specific features like usage guidelines and minimum sizes. It distinguishes itself from sibling tools such as get_colors and get_typography by focusing on logos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining logos but lacks explicit guidance on when to use it versus alternatives like search_brand or get_brand_overview. No when-not or exclusion criteria are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_texturesA
Get texture and pattern assets with usage context. Returns metadata and optionally base64-encoded image data.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Design context to query | all |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description indicates a read operation and mentions optional base64 data, but lacks details on permissions, side effects, or exact metadata structure, making it moderately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no superfluous information, efficiently covering the tool's purpose and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter retrieval tool with full schema coverage, the description adequately covers functionality and output, though it could mention default behavior or filtering options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds only 'with usage context' which aligns with the 'context' parameter, but does not enhance understanding beyond the schema's enum descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves texture and pattern assets with usage context, and specifies it returns metadata and optionally base64 image data, distinctly differentiating it from sibling tools like get_colors and get_logos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context for querying textures but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it, relying on the tool name and context parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_tokensA
Export design tokens in a specific format: CSS custom properties, SCSS variables, Tailwind config, W3C Design Tokens format, or JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Design context to query | all |
| format | Yes | Output format (required) | |
| category | No | Token category to export | all |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It implies a read-only export but does not explicitly state side effects, permissions, or rate limits. The behavior is adequately suggested but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose and key options. However, it is somewhat dense and could benefit from slight restructuring for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the input parameters but fails to describe the output format or response structure, especially given the absence of an output schema. For a simple export tool, it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal new meaning beyond the parameter descriptions. It repeats the format options but does not clarify when each is appropriate or how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports design tokens and lists the supported output formats (CSS, SCSS, Tailwind, W3C, JSON). This distinguishes it from sibling tools like get_css or get_colors, which focus on specific subsets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives, nor does it explain which format to choose or any prerequisites. The agent receives no usage context beyond the format list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_typographyB
Get typography specifications: font families, sizes, weights, line heights, and usage guidelines per context.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Design context to query | all |
| format | No | Output format | json |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description offers no behavioral details beyond indicating it retrieves data. It does not mention authentication, rate limits, or data freshness, leaving the agent with minimal insight into side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 11 words that immediately conveys the tool's purpose and scope. No superfluous words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two enum parameters and no output schema. The description lists the returned data types and mentions 'per context', which is adequate. It might briefly note default parameter values, but overall it is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with descriptions (100% coverage). The description adds context by listing the spec elements retrieved (e.g., font families, sizes) and mentions 'per context', which ties to the context parameter. However, it does not enhance the format parameter, so the added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves typography specifications, listing font families, sizes, weights, line heights, and usage guidelines per context. It distinguishes itself from siblings like get_colors or get_logos by specifying typography-specific content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get_css or get_tokens. The description implies context-based usage but does not elaborate on selecting between contexts or other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_brandA
Full-text search across all design system content: guidelines, component specs, color names, typography definitions, and brand documentation.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| context | No | Design context to search within | all |
| limit | No | Maximum number of results to return |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only mentions 'full-text search' without detailing any behavioral traits such as pagination, error handling, rate limits, or what happens when no results are found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the purpose and lists key content categories. Every word adds value, and there is no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has multiple parameters and no output schema, the description is somewhat complete in defining the search scope, but it lacks details about output format, ordering, or limits on search behavior, which weakens completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds context about the search scope (design system content) but does not provide additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Full-text search across all design system content' and enumerates specific content types (guidelines, component specs, color names, etc.), making the tool's purpose explicit and distinguishing it from the many get_* sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for broad search across all design system content, in contrast to sibling tools like get_colors which retrieve specific items, but it does not explicitly state when to use this versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_usageA
Validate whether a specific color, font, or logo usage complies with the brand guidelines. Returns pass/fail with specific guidance.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | What to validate | |
| value | Yes | The color hex/name, font name, or logo variant to validate | |
| context | No | Context to validate against | |
| useCase | No | Description of how it's being used |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states the tool returns 'pass/fail with specific guidance', which is transparent about output. However, it does not explicitly state that the tool is read-only or has no side effects, but the word 'validate' implies a safe operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded with the tool's purpose. It contains no unnecessary words and clearly communicates the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description is fairly complete: it explains the validation logic and the return format (pass/fail with guidance). However, it could include more detail on the 'specific guidance' or edge cases, but overall it provides sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for parameter descriptions, so the description adds little beyond summarizing the types ('color, font, or logo'). It does not provide additional context or usage examples for the parameters, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it validates compliance for color, font, or logo usage against brand guidelines. It distinguishes itself from sibling tools (which are retrieval-focused like 'get_colors' or 'search_brand') by being a validation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (for checking compliance) but does not mention when not to use it or suggest alternative tools. Since siblings are mostly read tools, a brief note about using this for validation vs. retrieval would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
12 tool updates
v0.1.0- First observed
get_brand_overview - First observed
get_colors - First observed
get_components - First observed
get_context_diff - First observed
get_css - First observed
get_guidelines - First observed
get_logos - First observed
get_textures - First observed
get_tokens - First observed
get_typography - First observed
search_brand - First observed
validate_usage
TDQS
Scored across 12 tools
Each tool targets a distinct aspect of the brand/design system: overview, colors, components, context diff, CSS, guidelines, logos, textures, tokens, typography, search, and validation. No two tools have overlapping purposes.
10 of 12 tools follow the 'get_' verb_noun pattern (e.g., get_colors, get_components). However, 'search_brand' and 'validate_usage' break this pattern by using different verbs, introducing slight inconsistency.
With 12 tools, the count is well within the optimal 3-15 range. Each tool represents a meaningful and distinct function for managing a brand kit, neither too few nor too many.
The set covers core retrieval and validation operations for brand assets (colors, typography, logos, etc.) and includes search and diff capabilities. The absence of mutation tools (create/update/delete) is a minor gap, but likely intentional for a read-only inspection server.
Maintenance
Related MCP Connectors
Brand-safe MCP for AI agents to create editable, on-brand graphics and automate variants.
Enterprise AI Control Plane: governance, guardrails, spend tracking, compliance & smart routing.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
MCP-Native LLM Orchestration Agent
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP Guard Server - Budget control, approval workflows and audit logging for AI agents (Claude Code, Cursor, ChatGPT)MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for AI agent security guardrails. Provides input validation, prompt injection detection, PII redaction, output filtering, policy enforcement, rate limiting, and comprehensive audit logging.31 npm1MIT

OnBrand by SlideSpeakofficial
AlicenseNot gradedqualityCmaintenanceAn MCP server that feeds AI agents your brand's real logos, colors, fonts, and approved slide layouts, so every deck and document comes out on brand the first time.7MIT- AlicenseNot gradedqualityBmaintenanceMCP server that exposes brand identity guidelines (visual look and voice) as markdown, enabling LLMs to produce on-brand content.24 npmMIT