@compono-public/ui-mcp

MCP (Model Context Protocol) server for the Compono UI library. This server provides AI coding agents with access to component information, props, and usage examples.

Features

• List Components: Get all available Compono UI components
• Get Component Props: Retrieve prop types, descriptions, and default values
• Get Component Examples: Access usage examples with full code and imports
• List Icons: Discover available icons with search and filtering capabilities

Quick Start

npx @compono-public/ui-mcp

Configure Your AI Tool

The MCP server communicates via stdio. Configure your AI tool to run the server.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "compono-ui": {
      "command": "npx",
      "args": ["@compono-public/ui-mcp"]
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "compono-ui": {
      "command": "npx",
      "args": ["@compono-public/ui-mcp"]
    }
  }
}

OpenCode

Edit opencode.json in your project root:

{
  "mcp": {
    "compono-ui": {
      "type": "local",
      "command": ["npx", "@compono-public/ui-mcp"]
    }
  }
}

Using Local Build

For local development within this repo (no build required):

yarn pkg-mcp start

Configure your AI tool:

{
  "command": "yarn",
  "args": ["pkg-mcp", "start"]
}

After updating the configuration, restart your AI tool to load the MCP server.

Available Tools

list_components

List all available Compono UI components with descriptions and alternatives.

Input: None

Output:

{
  "components": [
    {
      "name": "Button",
      "description": "A semantic button for triggering actions.\nUse Button for clickable actions like form submissions, confirmations, or navigation.",
      "category": "Actions",
      "tags": ["button", "action", "click", "submit"],
      "alternatives": [
        {
          "name": "IconButton",
          "path": "/docs/components-iconbutton--interactive",
          "description": "For buttons containing only an icon."
        },
        {
          "name": "LinkButton",
          "path": "/docs/components-link-linkbutton--page",
          "description": "For a semantic link that looks like a button."
        }
      ]
    },
    {
      "name": "DeprecatedComponent",
      "description": "An old component.",
      "category": "Components",
      "alternatives": [],
      "deprecated": true,
      "deprecationMessage": "Use NewComponent instead."
    }
  ],
  "count": 76,
  "dataVersion": "0.1.0"
}

Note: The tags, deprecated, and deprecationMessage fields are only included when specified, to reduce payload size.

get_component_props

Get props and type information for a specific component.

Input:

{
  "component": "Button"
}

Output:

{
  "name": "Button",
  "description": "A semantic button for triggering actions.",
  "deprecated": false,
  "deprecationMessage": null,
  "category": "Actions",
  "tags": ["button", "action", "click", "submit"],
  "props": {
    "look": {
      "type": "string",
      "isRequired": false,
      "description": "Visual style: \"primary\" | \"secondary\" | \"tertiary\" | \"naked\" | \"link\"",
      "defaultValue": null,
      "enumValues": ["primary", "secondary", "tertiary", "link", "naked"]
    },
    "tone": {
      "type": "string",
      "isRequired": false,
      "description": "Color scheme: \"primary\" | \"critical\" | \"white\"",
      "defaultValue": null,
      "enumValues": [
        "primary",
        "secondary",
        "success",
        "warning",
        "critical",
        "inherit",
        "white"
      ]
    },
    "size": {
      "type": "string",
      "isRequired": false,
      "description": "Button size: \"xs\" | \"sm\" | \"md\" | \"lg\"",
      "defaultValue": null,
      "enumValues": ["xs", "sm", "md", "lg", "inherit"]
    }
  }
}

Note: The enumValues field shows valid values for props that accept theme variants. For components with subcomponents (e.g., Card), a subcomponents object is included with their props.

get_component_examples

Get usage examples for a specific component.

Input:

{
  "component": "Button"
}

Output:

{
  "name": "Button",
  "description": "A semantic button for triggering actions.\nUse Button for clickable actions like form submissions, confirmations, or navigation.",
  "install": "import { Button, ButtonProps } from \"@compono/ui\";",
  "alternatives": [
    {
      "name": "IconButton",
      "path": "/docs/components-iconbutton--interactive",
      "description": "For buttons containing only an icon."
    }
  ],
  "examples": [
    {
      "name": "Looks",
      "description": "Available button styles",
      "code": "import { Inline } from \"../../\";\nimport { Button } from \"../\";\n\nexport const Looks = () => (\n  <Inline gap=\"3\">\n    <Button>Primary</Button>\n    <Button look=\"secondary\">Secondary</Button>\n  </Inline>\n);"
    }
  ],
  "exampleCount": 4
}

list_icons

List all available Compono UI icons with search and filtering capabilities. Use this tool to discover available icons and avoid guessing icon names.

Input (all optional):

{
  "variant": "Solid",
  "search": "arrow"
}

Parameters:

• variant (optional): Filter by icon variant (e.g., "Solid", "Outline", "Logomark")
• search (optional): Search icons by name (case-insensitive)

Output:

{
  "icons": [
    {
      "name": "ArrowLeftSolidIcon",
      "variant": "Solid"
    },
    {
      "name": "ArrowRightSolidIcon",
      "variant": "Solid"
    }
  ],
  "count": 2,
  "dataVersion": "1.0.0",
  "availableVariants": [
    "CircleColorLogomark",
    "CircleLogomark",
    "ColorLogomark",
    "Logomark",
    "Outline",
    "OutlineAnimated",
    "RectangleColorLogomark",
    "RectangleLogomark",
    "Solid"
  ]
}

Usage example:

import { CheckCircleSolidIcon } from "@compono/ui-icons";

function SuccessMessage() {
  return (
    <div>
      <CheckCircleSolidIcon />
      <span>Success!</span>
    </div>
  );
}

Development

Scripts

All scripts below should be run from the packages/mcp directory:

# Generate static data files from UI components
yarn generate

# Generate for specific components only
yarn generate Button Alert

# Generate for all components (not just initial scope)
yarn generate --all

# Build the MCP server
yarn build

# Watch mode for development
yarn dev

# Run the server
yarn start

# Run tests
yarn test

# Clean build artifacts
yarn clean

Individual Generation Scripts

# Generate only component list
yarn generate:components

# Generate only type definitions
yarn generate:types
yarn generate:types Button Card  # Specific components
yarn generate:types --all        # All components

# Generate only examples
yarn generate:examples
yarn generate:examples Button Card  # Specific components
yarn generate:examples --all        # All components

# Generate only icon metadata
yarn generate:icons

Tagging Components for MCP

Use JSDoc tags to control which components and stories are included in MCP data. See TAGGING.md for full documentation.

| Tag | Purpose | | ---------------- | ------------------------------------------ | | @mcpComponent | Component description for AI | | @mcpCategory | Component category (default: "Components") | | @mcpTags | Searchable keywords (comma-separated) | | @mcpDeprecated | Deprecation notice | | @mcpExample | Story example description |

Architecture

packages/mcp/
├── src/
│   ├── index.ts                    # Entry point (stdio transport)
│   ├── lib/
│   │   ├── types.ts                # Shared TypeScript types
│   │   └── data.ts                 # Load & filter JSON data
│   └── tools/
│       ├── index.ts                # Tool registration
│       ├── list-components.ts      # list_components tool
│       ├── get-component-props.ts  # get_component_props tool
│       └── get-component-examples.ts # get_component_examples tool
├── scripts/
│   ├── generate.ts                 # Main generation entry point
│   ├── generate-components.ts      # Generate components.json
│   ├── generate-types.ts           # Generate types/*.json
│   ├── generate-examples.ts        # Generate examples/*.json
│   ├── __tests__/                  # Unit and integration tests
│   │   ├── fixtures/               # Test fixtures (DummyButton, etc.)
│   │   ├── generate.test.ts        # Integration tests
│   │   ├── extract-types.test.ts   # Type extraction tests
│   │   ├── parse-mdx.test.ts       # MDX parsing tests
│   │   ├── parse-stories.test.ts   # Story parsing tests
│   │   └── parse-theme.test.ts     # Theme variant extraction tests
│   └── utils/
│       ├── extract-types.ts        # TypeScript AST parsing for props
│       ├── get-component-list.ts   # Scan component directories
│       ├── parse-mdx.ts            # Parse MDX metadata
│       ├── parse-stories.ts        # Parse @mcpExample stories
│       └── parse-theme.ts          # Extract theme variant values
├── data/                           # Generated JSON (committed to git)
│   ├── components.json             # Component list with metadata
│   ├── types/
│   │   ├── Button.json
│   │   ├── Alert.json
│   │   └── ...
│   └── examples/
│       ├── Button.json
│       ├── Alert.json
│       └── ...
├── package.json
├── tsconfig.json
├── tsconfig.scripts.json
└── plan.md                         # Implementation plan

Data Files

The data/ directory contains generated JSON files that are committed to git:

| File | Description | | ----------------- | -------------------------------------------------------------------------- | | components.json | List of all components with name, description, category, deprecated status | | types/*.json | Props for each component (only those with @mcpComponent tag) | | examples/*.json | Usage examples for each component (only those with @mcpExample tags) |

Initial Scope

By default, type and example generation is limited to these components:

• Button
• Alert
• Checkbox
• Card

Use --all flag or pass specific component names to generate for additional components.

Generation Logic

For detailed documentation on how components are discovered and data is generated, see GENERATION.md.

Internal Component Detection

The following patterns are automatically detected as internal/subcomponents and excluded from public API:

| Pattern | Examples | Reason | | -------------- | ------------------------- | ----------------------- | | *Base | ButtonBase, AlertBase | Base primitives | | *Body | ButtonBody | Subcomponents | | *Content | AlertContent | Subcomponents | | *Input | CheckboxInput | Low-level inputs | | *CloseButton | AlertCloseButton | Utility subcomponents | | *Internal | MenuInternal | Explicitly internal | | *Provider | ThemeProvider | Context providers | | *Context | MenuContext | Context objects | | _* | _InternalComponent | Convention for internal | | use* | useTheme | Hooks |

Related

• Compono UI Documentation
• MCP Protocol Specification
• Implementation Plan