Skip to main content
Glama

BrandKit MCP

Give every AI tool access to your company's complete design system via the Model Context Protocol.

npm version License: MIT Node 20+ TypeScript

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 --open

Note: Once the package is published to npm, npx brandkit-mcp@latest init will 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

{
  "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 3001

Supported File Types

File Type

Extensions

What BrandKit MCP Extracts

CSS

.css

Color tokens, typography tokens, custom properties, media queries

Markdown

.md

Component docs, brand guidelines, voice & tone, color palettes

PDF

.pdf

Brand guidelines, usage rules, text content

SVG

.svg

Logo variants, icons, textures/patterns

Images

.png, .jpg, .webp

Logo variants with dimensions, textures/patterns

Fonts

.woff2, .woff, .ttf, .otf

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, forms

Convention: 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

get_brand_overview

High-level summary of the entire design system

(none)

2

get_colors

All color tokens with hex values, roles, and usage

context, role

3

get_typography

Font families, sizes, weights, and line heights

context

4

get_logos

Logo variants with metadata and usage guidelines

context, variant, include_base64

5

get_components

Component documentation, specs, and code examples

context, category, name

6

get_guidelines

Brand voice, accessibility, and design guidelines

context, section

7

get_tokens

Design tokens in any of 5 output formats

context, format, category

8

get_textures

Background textures and patterns

context

9

get_css

Raw parsed CSS with all custom properties

context

10

search_brand

Full-text search across the entire design system

query, context, type, limit

11

get_context_diff

Differences between marketing and product contexts

aspect

12

validate_usage

Validate color/typography usage against the system

colors, fonts, context

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

brand/shared/

Tokens and guidelines common to both contexts. Acts as the default layer.

marketing

brand/marketing/

Overrides and additions for the public-facing marketing website.

product

brand/product/

Overrides and additions for the SaaS product application.

How Context Resolution Works

  1. Shared is the base. Every token and guideline in shared/ is available to both contexts.

  2. Context-specific values override shared values. If shared/colors/colors.css defines --color-accent: #e94560 and marketing/colors/overrides.css defines --color-accent: #ff6b6b, then marketing context returns #ff6b6b.

  3. Context-specific additions are kept separate. A component defined only in product/components/ won't appear in marketing results.

  4. 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 docs

This 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 --open

Pages

Page

URL

Description

Dashboard

/

Overview with asset counts and quick links

Colors

/colors

Color palette with swatches, hex values, and roles

Typography

/typography

Font specimens with all sizes and weights

Logos

/logos

Logo variants grid with download metadata

Components

/components

Component documentation with code examples

Guidelines

/guidelines

Brand voice, accessibility, and design guidelines

Textures

/textures

Background textures and patterns gallery

Tokens

/tokens

Token export in all 5 formats with copy-to-clipboard

CSS

/css

Raw parsed CSS custom properties

Search

/search

Full-text search across the design system

The --watch flag enables hot reload: edit a brand file and the preview updates automatically.

Deployment

The simplest setup. The MCP server communicates over stdin/stdout:

node dist/cli/index.js serve

Configure 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 --watch

Connect 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-mcp

Or use Docker Compose:

docker-compose up

This starts both the MCP server (port 3001) and the preview server (port 3000).

Vercel

Deploy as a Vercel serverless function:

  1. Install the Vercel CLI: npm i -g vercel

  2. Deploy: vercel --prod

  3. Connect 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:

  1. Install Wrangler: npm i -g wrangler

  2. Configure wrangler.toml with your account details

  3. Bundle your design system data at build time (Workers don't have filesystem access)

  4. Deploy: wrangler deploy

Standalone HTTP Server

Run a plain Node.js HTTP server without Express:

node dist/adapters/standalone.js

Or 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 help

init [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 files

Option

Description

--name <name>

Brand name for the config file

--force

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

Checks:

  • 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 --watch

Option

Description

Default

--transport <type>

Transport: stdio or sse

stdio

--port <number>

Port for SSE transport

3001

--config <path>

Path to config file

auto-detect

--watch

Enable hot reload

false

preview

Launch the visual preview server.

brandkit-mcp preview
brandkit-mcp preview --port 8080 --watch --open

Option

Description

Default

--port <number>

Preview server port

3000

--config <path>

Path to config file

auto-detect

--watch

Enable hot reload

false

--open

Open browser automatically

false

docs

Generate project documentation files for AI tools.

brandkit-mcp docs
brandkit-mcp docs --output ./docs --config ./brandkit.config.yaml

Option

Description

Default

--config <path>

Path to config file

auto-detect

--output <dir>

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: localhost

The 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 mode

How to Add a New Parser

  1. Create src/parsers/your-parser.ts

  2. Export a parse function that accepts a file path and context

  3. Return typed data matching the interfaces in src/types/design-system.ts

  4. Add the file type to classifyFileType() in src/scanner/directory-scanner.ts

  5. Add a processing case in processFile() in src/indexer/index.ts

  6. Write tests in src/tests/parsers.test.ts

How to Add a New MCP Tool

  1. Create src/tools/your-tool.ts

  2. Export TOOL_NAME, TOOL_DESCRIPTION, INPUT_SCHEMA, and handler()

  3. Add the argument interface to src/types/mcp.ts

  4. Import and register the tool in src/tools/index.ts

  5. Add the tool to the switch statement in the tools/call handler

  6. Update the README tools reference table

Code Style

  • TypeScript strict mode enabled

  • ESM imports with .js extensions

  • No any types -- use proper interfaces

  • All 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 file

Examples

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 --open

Starter 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 validate

License

MIT -- see LICENSE for details.


Built with the Model Context Protocol by Anthropic.

Available Tools

12 tools
get_brand_overviewA

Get a high-level overview of the design system: brand name, active contexts, asset inventory counts, and available design system sections.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoDesign context to queryall
roleNoFilter by semantic role: primary, secondary, accent, neutral, error, success, warning, info
formatNoOutput formatjson

TDQS

A3.6/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoDesign context to queryall
categoryNoFilter by category: button, form, navigation, layout, card, modal, etc.
nameNoSearch by component name (partial match, case-insensitive)

TDQS

A3.6/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryNoCategory to compareall

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoDesign context to queryall
includeRawNoInclude full raw CSS file contents (can be large)

TDQS

B3.1/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoDesign context to queryall
sectionNoFilter by section: brand-voice, accessibility, logo-usage, typography, colors, general

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
variantNoFilter by variant name (e.g., 'primary', 'mark', 'wordmark')
formatNoWhether to include base64 datametadata

TDQS

A3.8/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoDesign context to queryall

TDQS

A3.8/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoDesign context to queryall
formatYesOutput format (required)
categoryNoToken category to exportall

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoDesign context to queryall
formatNoOutput formatjson

TDQS

B3.4/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query
contextNoDesign context to search withinall
limitNoMaximum number of results to return

TDQS

A3.5/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeYesWhat to validate
valueYesThe color hex/name, font name, or logo variant to validate
contextNoContext to validate against
useCaseNoDescription of how it's being used

TDQS

A4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 12 tool updatesv0.1.0
    • First observedget_brand_overview
    • First observedget_colors
    • First observedget_components
    • First observedget_context_diff
    • First observedget_css
    • First observedget_guidelines
    • First observedget_logos
    • First observedget_textures
    • First observedget_tokens
    • First observedget_typography
    • First observedsearch_brand
    • First observedvalidate_usage

TDQS

A3.8/5.0

Scored across 12 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers