Brick MCP Server

Overview

The Brick MCP Server is a Model Context Protocol (MCP) server that provides AI assistants (like Claude Code or Copilot) with direct access to the Brick design system. It enables accurate, context-aware assistance when developers implement Brick components by exposing component documentation, design tokens, and usage examples through standardized MCP tools.

Prerequisites

Follow the Amedia CLI guide available here

Usage

The Brick MCP server can be run in two modes:

Stdio Mode (for Claude Code)

The recommended way to use the MCP server with Claude Code is via npx:

# Add to Claude Code
claude mcp add --transport stdio Brick -- npx -y @amedia/brick-mcp@latest

HTTP Mode (for local development)

To run the MCP server as an HTTP service:

# Fetch data folder
npm run build
# Development with watch mode
npm run dev:http

The HTTP server exposes:

• http://localhost:3000/health - Health check endpoint
• http://localhost:3000/sse - SSE endpoint for MCP protocol communication
• http://localhost:3000/message - Message endpoint for client-to-server communication

To add to Claude run

claude mcp add Brick-http --transport sse --scope user -- http://0.0.0.0:3000/sse

Environment Variables

• PORT - Server port (default: 3000)
• HOST - Server host (default: 0.0.0.0)

What the MCP Server Provides

Once configured, you can ask Claude about Brick components, design tokens, and implementation patterns. The MCP server provides three main tools:

1. list-components: Discover all available Brick components with filtering by name, category, or tags
2. get-component-docs: Retrieve detailed documentation including MDX content, llm.txt summaries, examples, and Storybook links
3. get-design-tokens: Access design tokens filtered by category (colors, spacing, typography, shadows, borders) or theme, with available themes list and comprehensive documentation about the token system

Goals

1. Easy Discovery: Enable AI to quickly list and search available Brick components
2. Accurate Implementation: Provide detailed component documentation including props, events, and accessibility guidelines
3. Design Consistency: Make design tokens easily accessible for consistent styling
4. Best Practices: Include usage examples and patterns from Storybook
5. Developer Experience: Reduce friction when implementing Brick components through AI-assisted development

MCP Tools (Actions)

The MCP server exposes three tools that AI assistants can call to fetch information about the Brick design system. All data is pre-generated during the build process and bundled as JSON files, making the server fast and suitable for use as a standalone npm package.

1. list-components

List all available Brick components with optional filtering.

Input:

{
  filter?: string;  // Filter by name, category, or tag
}

Output:

{
  components: Array<{
    name: string; // e.g., "brick-button"
    version: string; // e.g., "9.0.0"
    selector: string; // e.g., "brick-button-v9"
    description?: string;
    category?: string; // Auto-categorized: Forms, Navigation, Layout, Feedback, Display, Utilities
    tags?: string[]; // Auto-generated tags
  }>;
}

Example: { "filter": "button" } returns all button-related components.

2. get-component-docs

Retrieve detailed documentation for one or more components.

Input:

{
  components: string[];  // e.g., ["brick-button", "brick-modal"]
}

Output:

{
  docs: Array<{
    name: string;
    version: string;
    selector: string;
    description?: string; // From llm.txt or MDX content
    examples: {
      webComponent?: string; // Extracted from MDX or auto-generated
      storybook?: string; // Link to Chromatic Storybook
    };
    cdnPath?: string; // Eik CDN URL for the component
  }>;
}

Data Sources:

• llm.txt: AI-friendly component summaries (if available)
• .mdx files: Full documentation from Storybook
• package.json: Version and description

3. get-design-tokens

Access design tokens from brick-tokens with filtering options.

Input:

{
  category?: 'colors' | 'spacing' | 'typography' | 'shadows' | 'borders';
  theme?: string;  // e.g., "bergen", "alfa", "bt"
}

Output:

{
  tokens: Array<{
    name: string;        // e.g., "color-primary"
    value: string;       // e.g., "#0066CC"
    type: string;        // Token type from Design Tokens spec
    description?: string;
    category?: string;
    theme?: string;
  }>;
  themes: string[];      // Available theme names (e.g., ["alfa", "bergen", "bt"])
  documentation: {
    anOverview?: string;  // Overview of the design token system
    formats?: string;     // Information about token formats
    naming?: string;      // Token naming conventions
    themes?: string;      // Theme documentation
    usage?: string;       // Usage guidelines
  };
}

Data Sources:

• Pre-built tokens from brick-tokens/publications/publication/*.json
• Documentation from tokens-documentation.json

Usage Example

Once configured, Claude Code can use the MCP tools to answer questions about Brick:

User: "I need to add a button to my app using Brick"

Claude: [Calls list-components with filter: "button"]
        [Calls get-component-docs with components: ["brick-button"]]

        "I can help you add a Brick button. Here's the brick-button-v9 component:

        <brick-button-v9>Click me</brick-button-v9>

        You can load it from the Eik CDN:
        https://assets.acdn.no/pkg/@amedia/brick-button/9.0.0/brick-button.js

        For detailed examples and variants, check the Storybook documentation:
        https://master--60060c41f82e040021133482.chromatic.com/?path=/docs/bricks-brick-button

        Would you like me to implement this in your file?"

Maintaining Component Documentation

The MCP server includes prompts to help maintain component documentation as components evolve.

Updating Component Docs

Use prompts/update-component-docs.md to check if component documentation needs updating based on version changes.

When to use:

• After component versions have been updated
• To audit which components have outdated documentation
• Before publishing a new version of the MCP server

What it does:

1. Compares versions in data/components/*.md frontmatter against packages/*/package.json
2. Identifies components with major or minor version changes (patch changes are skipped)
3. Generates updated documentation for components that need it
4. Provides a summary of what was updated

Example usage with Claude Code:

User: "Check if any component docs need updating using prompts/update-component-docs.md"

Claude: [Reads the prompt file and follows the instructions]
        [Checks all components in data/components/]
        [Identifies version mismatches]
        [Updates documentation for components with major/minor changes]

        ## Documentation Update Summary

        ### Components Checked: 45

        ### Updates Required:
        - brick-modal: 3.2.1 → 4.0.0 (major change)
        - brick-image: 6.0.5 → 6.1.0 (minor change)

        ### Up to Date: 42 components

        ### Skipped (patch changes only):
        - brick-button: 9.0.2 → 9.0.5

The prompt references prompts/generate-llm-docs.md for the documentation generation process.

Adding New Tools

To add a new MCP tool:

1. Create a new file in src/tools/yourTool.ts
2. Implement the tool function with input/output types using Zod
3. Register the tool in src/server.ts using server.registerTool()
4. Update this README with tool documentation

Publishing

The package is configured to publish to npm:

# From the Brick root
# 1. Make your changes and create a changeset
npx changeset
# 2. Create a PR - merging will trigger a "Version Packages" PR
# 3. Merge the "Version Packages" PR to publish to npm

For snapshot releases (testing pre-release versions):

1. Create a changeset and then run the snapshot GitHub action for your branch and this package.

After publishing, the package can be used via:

npx @amedia/brick-mcp           # Run the latest version
npm install @amedia/brick-mcp   # Install in your project

References

• MCP TypeScript SDK
• MCP Specification
• Brick Design System
• Chromatic Storybook