@brander/mcp-tools

Add branded, interactive UI to any MCP server in one line.

@brander/mcp-tools registers a generate_screen tool on your MCP server that renders built-in and custom element types (charts, tables, grids, forms, and more) with your brand's colors, fonts, and styling — directly inside Claude Desktop.

Quick Start

npm install @brander/mcp-tools

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { registerBranderTools } from "@brander/mcp-tools";

const server = new McpServer({ name: "my-app", version: "1.0.0" });

// Register your own business tools...
// server.registerTool("search_products", { ... }, handler);

// One line — adds branded UI rendering
await registerBranderTools(server, {
  projectId: process.env.BRANDER_PROJECT_ID!,
  betaKey: process.env.BRANDER_BETA_KEY!,
});

await server.connect(new StdioServerTransport());

What It Does

When you call registerBranderTools(server, config), it adds:

1. generate_screen tool — Claude uses this to render branded UI instead of writing raw text. Accepts an array of elements with typed props.
2. MCP App resource — A self-contained HTML renderer (React + MUI) that Claude Desktop loads to display the elements.

Your brand settings (colors, fonts, layout, dark mode) are loaded from the BranderUX API at startup and applied to every rendered screen.

Built-in Element Types

| Element | Description | |---|---| | header | Page title with subtitle | | chat-bubble | Text/markdown response | | stats-grid | KPI cards with trends | | data-table | Sortable, filterable table | | line-chart | Time series chart | | pie-chart | Proportional data | | bar-chart | Category comparison | | item-grid | Product/item cards | | item-card | Single item detail card | | image | Image display | | details-data | Key-value detail sections | | form | Dynamic input form | | button | Action/link button | | alert | Notification banner |

You can also create custom element types through the BranderUX dashboard.

Configuration

interface BranderToolsConfig {
  /** BranderUX project ID */
  projectId: string;

  /** Beta design partner key (bux_dp_xxx) */
  betaKey: string;

  /** API base URL (defaults to https://branderux.com) */
  apiBaseUrl?: string;

  /** Path to local brandSettings.json for development */
  brandSettingsPath?: string;
}

Claude Desktop Setup

{
  "mcpServers": {
    "my-app": {
      "command": "node",
      "args": ["/path/to/your/dist/index.js"],
      "env": {
        "BRANDER_PROJECT_ID": "your_project_id",
        "BRANDER_BETA_KEY": "bux_dp_your_key"
      }
    }
  }
}

How It Works

1. At startup, registerBranderTools loads your project's brand settings from the BranderUX API
2. It registers the generate_screen tool with Zod schemas for all element types
3. It registers an MCP App resource — a single-file HTML bundle containing all React components
4. When Claude calls generate_screen, it returns structured data + a reference to the HTML resource
5. Claude Desktop loads the HTML resource and renders branded UI with your data

Interactive Elements

Elements support click interactions via clickQuery. When a user clicks a table row, chart segment, or card, the query is sent back to Claude to continue the conversation:

// Claude generates this tool call:
generate_screen({
  elements: [{
    elementType: "item-grid",
    props: { items: [...] },
    clickQuery: "Show details for [title] including specs and reviews"
  }]
})

Placeholders like [title], [id], [name] are filled with the clicked element's data.

Example

See BranderUX/mcp-demo for a full reference implementation with a fake e-commerce dataset (TechStore Pro).

License

MIT