@brander/mcp-tools 0.2.0

package/README.md

@@ -0,0 +1,126 @@
+# @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 14 element types (charts, tables, grids, forms, etc.) with your brand's colors, fonts, and styling — directly inside Claude Desktop.
+
+## Quick Start
+
+```bash
+npm install @brander/mcp-tools
+```
+
+```typescript
+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.
+
+## 14 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 |
+
+## Configuration
+
+```typescript
+interface BranderToolsConfig {
+  /** BranderUX project ID */
+  projectId: string;
+
+  /** Beta design partner key (bux_dp_xxx) */
+  betaKey: string;
+
+  /** API base URL (defaults to https://app.branderux.com) */
+  apiBaseUrl?: string;
+
+  /** Path to local brandSettings.json for development */
+  brandSettingsPath?: string;
+}
+```
+
+## Claude Desktop Setup
+
+```json
+{
+  "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 14 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:
+
+```typescript
+// 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](https://github.com/BranderUX/mcp-demo) for a full reference implementation with a fake e-commerce dataset (TechStore Pro).
+
+## License
+
+MIT