brand-os-mcp-server

Brand-OS tools for AI-powered UI generation with strict brand enforcement.

For Claude Code & Cursor Users

Claude Code Setup

1. Add CLAUDE.md to your project root:

curl -O https://raw.githubusercontent.com/brand-os/core/main/CLAUDE.md

2. Claude Code will automatically follow Brand-OS rules for component generation

Cursor IDE Setup

1. Add .cursorrules to your project root:

curl -O https://raw.githubusercontent.com/brand-os/core/main/.cursorrules

2. Cursor will enforce Brand-OS patterns in all UI generation

Installation

npm install @brand-os/core

For MCP-Compatible Tools (Claude Desktop)

1. Install the MCP Server

npm install -g brand-os-mcp-server

2. Configure Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "brand-os": {
      "command": "node",
      "args": ["/usr/local/lib/node_modules/brand-os-mcp-server/dist/index.js"]
    }
  }
}

Note: The path may vary based on your npm global installation directory. Find it with:

npm root -g

3. Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the Brand-OS MCP server.

Available Tools

Once configured, Claude will have access to these Brand-OS tools:

compose

Create UI by composing pre-built blocks from the Brand-OS gallery.

Example:

// Request
{
  "requirements": "Show sales metrics with chart and AI insights"
}

// Returns JSX/TSX snippet

scaffold

Create new components using Brand-OS primitives (CardShell, Panel, Stack, Grid, etc.).

Example:

// Request
{
  "name": "CustomMetric",
  "description": "Special metric display",
  "code": "export function CustomMetric({value, label}) { ... }"
}

// Returns validated JSX/TSX

discover

Find components by natural language query.

Example:

// Request
{
  "query": "charts for time series data"
}

// Returns matching components

gallery

Browse all available pre-built blocks (379 total).

Example:

// Request
{
  "category": "metrics" // optional filter
}

// Returns block catalog

Usage in Your App

1. Install Core Package

npm install @brand-os/core

2. Setup Provider

import { BrandOSProvider } from '@brand-os/core';

export default function App() {
  return (
    <BrandOSProvider config={{
      nano: {
        // Your brand tokens
        '--brand-primary': '#3B82F6',
        '--glass-bg': 'rgba(255, 255, 255, 0.6)',
        '--glass-blur': '40px'
      }
    }}>
      {/* Your app */}
    </BrandOSProvider>
  );
}

3. Use Generated Components

When Claude generates components using the MCP tools, they'll return JSX/TSX snippets you can use directly:

import { Resolved } from '@brand-os/core';

// Component generated by Claude's compose tool
<Resolved intent={{
  type: "stat-card",
  data: {
    title: "Revenue",
    value: 125000,
    change: 12.5
  }
}} />

Brand Enforcement

The MCP server ensures all generated UI:

• ✅ Only uses CSS variables (no hardcoded colors)
• ✅ Follows glass morphism aesthetic
• ✅ Maintains exact typography system
• ✅ Respects spacing/density settings
• ✅ Bundle size < 2KB per component

Development

Running Locally

# Clone and install
git clone https://github.com/your-org/brand-os
cd brand-os/packages/brand-os-mcp-server
npm install

# Build
npm run build

# Test locally with Claude
node dist/index.js

Testing Tools

The MCP server can be tested using the MCP Inspector:

npx @modelcontextprotocol/inspector dist/index.js

Support

• Issues: https://github.com/your-org/brand-os/issues
• Docs: https://brand-os.dev/docs
• Discord: https://discord.gg/brand-os

License

MIT