# MCP UI Kit — React Rewrite Plan

## Vision
Build a **generic, reusable MCP UI component library** using React + ext-apps SDK. Any MCP server (GHL, HubSpot, Salesforce, etc.) can use this component kit to render AI-generated interactive UIs. GHL is the first implementation. The library is CRM-agnostic — interactive components accept tool names as props so each server configures its own tool mappings.

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│ Goose / Claude Desktop (MCP Host)                       │
│                                                          │
│   tools/call → GHL MCP Server → GHL API                │
│        ↑           ↓                                     │
│   tools/call   structuredContent (JSON UI tree)         │
│        ↑           ↓                                     │
│   ┌─────────────────────────────────────────────┐       │
│   │  React App (iframe via ext-apps SDK)         │       │
│   │                                              │       │
│   │  useApp() hook ← ontoolresult (UI tree)     │       │
│   │       ↓                                      │       │
│   │  MCPAppProvider (React Context)              │       │
│   │    - uiTree state                            │       │
│   │    - formState (inputs, selections)          │       │
│   │    - callTool(name, args) → MCP server      │       │
│   │       ↓                                      │       │
│   │  <UITreeRenderer tree={uiTree} />            │       │
│   │    - Looks up component by type              │       │
│   │    - Renders React component with props      │       │
│   │    - Recursively renders children            │       │
│   │       ↓                                      │       │
│   │  42 Display Components (pure, CRM-agnostic)  │       │
│   │  + 8 Interactive Components (tool-configurable)│     │
│   │    - ContactPicker(searchTool="search_contacts")│    │
│   │    - InvoiceBuilder(createTool="create_invoice")│    │
│   │    - KanbanBoard(onMoveTool="update_opportunity")│   │
│   │    - EditableField(saveTool=props.saveTool)  │       │
│   └─────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────┘
```

## File Structure (New)

```
src/ui/react-app/                  # GENERIC MCP UI KIT (no GHL references)
├── package.json                   # React + ext-apps SDK deps
├── vite.config.ts                 # Vite + singlefile + React
├── tsconfig.json
├── index.html                     # Entry point
├── src/
│   ├── App.tsx                    # Root — useApp hook, MCPAppProvider
│   ├── types.ts                   # UITree, UIElement, component prop interfaces
│   ├── context/
│   │   └── MCPAppContext.tsx      # React Context — uiTree, formState, callTool
│   ├── hooks/
│   │   ├── useCallTool.ts        # Hook wrapping app.callServerTool
│   │   ├── useFormState.ts       # Shared form state management
│   │   └── useSizeReporter.ts    # Auto-report content size to host
│   ├── renderer/
│   │   ├── UITreeRenderer.tsx    # Recursive tree → React component resolver
│   │   └── registry.ts           # Component name → React component map
│   ├── components/
│   │   ├── layout/               # PageHeader, Card, SplitLayout, Section, StatsGrid
│   │   ├── data/                 # DataTable, KanbanBoard, MetricCard, StatusBadge,
│   │   │                         # Timeline, ProgressBar, KeyValueList, etc.
│   │   ├── charts/               # BarChart, LineChart, PieChart, FunnelChart, Sparkline
│   │   ├── comms/                # ChatThread, EmailPreview, TranscriptView, etc.
│   │   ├── viz/                  # CalendarView, FlowDiagram, TreeView, MediaGallery, etc.
│   │   ├── interactive/          # ContactPicker, InvoiceBuilder, EditableField, etc.
│   │   │                         # All accept tool names as PROPS (CRM-agnostic)
│   │   └── shared/               # ActionButton, Toast, Modal (React portals)
│   └── styles/
│       ├── base.css              # Reset, variables, typography
│       ├── components.css        # Component-specific styles (compact for chat)
│       └── interactive.css       # Drag/drop, modals, toasts, form styles
```

### CRM-Agnostic Design Principle
- NO component imports GHL types or references GHL tool names
- Interactive components receive tool names via props:
  - `ContactPicker` → `searchTool="search_contacts"` (GHL) or `"hubspot_search_contacts"` (HubSpot)
  - `KanbanBoard` → `moveTool="update_opportunity"` (GHL) or `"move_deal"` (Pipedrive)
  - `InvoiceBuilder` → `createTool="create_invoice"` (any billing system)
- The MCP server's AI prompt tells Claude which tool names to use in the UI tree
- Components call `callTool(props.toolName, args)` — they don't know or care what CRM is behind it

## Component Inventory

### Existing 42 (string → React conversion)

**Layout (5):** PageHeader, Card, StatsGrid, SplitLayout, Section
**Data Display (10):** DataTable, KanbanBoard, MetricCard, StatusBadge, Timeline, ProgressBar, DetailHeader, KeyValueList, LineItemsTable, InfoBlock
**Navigation (3):** SearchBar, FilterChips, TabGroup
**Actions (2):** ActionButton, ActionBar
**Extended Data (6):** CurrencyDisplay, TagList, CardGrid, AvatarGroup, StarRating, StockIndicator
**Communications (6):** ChatThread, EmailPreview, ContentPreview, TranscriptView, AudioPlayer, ChecklistView
**Visualization (5):** CalendarView, FlowDiagram, TreeView, MediaGallery, DuplicateCompare
**Charts (5):** BarChart, LineChart, PieChart, FunnelChart, SparklineChart

### New Interactive Components (8)

| Component | Purpose | MCP Tools Used |
|-----------|---------|----------------|
| **ContactPicker** | Searchable dropdown, fetches contacts on type | `search_contacts` |
| **InvoiceBuilder** | Line items, totals, contact auto-fill | `create_invoice`, `get_contact` |
| **OpportunityEditor** | Inline edit deal name/value/status/stage | `update_opportunity` |
| **AppointmentBooker** | Calendar slot picker + booking form | `get_calendar`, `create_appointment` |
| **EditableField** | Click-to-edit any text/number field | varies (generic) |
| **SelectDropdown** | Generic select with async option loading | varies |
| **FormGroup** | Group of form fields with validation | varies |
| **AmountInput** | Currency-formatted number input | — (local state) |

---

## Agent Team Plan

### Phase 1: Foundation (Sequential — 1 agent)

**Agent Alpha — Project Scaffold + App Shell**
- Create `src/ui/react-app/` with package.json, vite.config, tsconfig
- Install deps: react, react-dom, @modelcontextprotocol/ext-apps, @vitejs/plugin-react, vite-plugin-singlefile
- Build `App.tsx` with `useApp` hook — handles ontoolresult, ontoolinput, host context
- Build `GHLContext.tsx` — React context providing uiTree, formState, callTool
- Build `useCallTool.ts` — wrapper around `app.callServerTool` with loading/error states
- Build `useFormState.ts` — shared form state hook
- Build `useSizeReporter.ts` — auto-measures content, sends `ui/notifications/size-changed`
- Build `UITreeRenderer.tsx` — recursive renderer that resolves component types from registry
- Build `registry.ts` — component map (stubs for now, filled by other agents)
- Build `types.ts` — UITree, UIElement, all component prop interfaces
- Build base CSS (`base.css`) — reset, variables, compact typography
- Update outer build pipeline in GoHighLevel-MCP `package.json` to build React app
- **Output:** Working scaffold that renders a loading state, connects to host via ext-apps

### Phase 2: Components (Parallel — 4 agents)

**Agent Bravo — Layout + Core Data Components (15)**
Files: `components/layout/`, `components/data/` (first half)
- PageHeader, Card, StatsGrid, SplitLayout, Section
- DataTable (with clickable rows, sortable columns)
- KanbanBoard (with FULL drag-and-drop via React state — no DOM hacking)
- MetricCard, StatusBadge, Timeline
- Register all in registry.ts
- Component CSS in `components.css`

**Agent Charlie — Data Display + Navigation + Actions (15)**
Files: `components/data/` (second half), `components/shared/`
- ProgressBar, DetailHeader, KeyValueList, LineItemsTable, InfoBlock
- SearchBar, FilterChips, TabGroup
- ActionButton, ActionBar
- CurrencyDisplay, TagList, CardGrid, AvatarGroup, StarRating, StockIndicator
- Register all in registry.ts

**Agent Delta — Comms + Viz + Charts (16)**
Files: `components/comms/`, `components/viz/`, `components/charts/`
- ChatThread, EmailPreview, ContentPreview, TranscriptView, AudioPlayer, ChecklistView
- CalendarView, FlowDiagram, TreeView, MediaGallery, DuplicateCompare
- BarChart, LineChart, PieChart, FunnelChart, SparklineChart
- All chart components use inline SVG (same approach, just JSX)
- Register all in registry.ts

**Agent Echo — Interactive Components + Forms (8)**
Files: `components/interactive/`, `hooks/`
- ContactPicker — searchable dropdown, calls `search_contacts` on keystroke with debounce
- InvoiceBuilder — line items table + contact selection + auto-total
- OpportunityEditor — inline edit form for deal fields, saves via `update_opportunity`
- AppointmentBooker — date/time picker + contact + calendar selection
- EditableField — click-to-edit wrapper for any field
- SelectDropdown — generic async select
- FormGroup — form layout with labels + validation
- AmountInput — formatted currency input
- Shared: Toast component, Modal component (proper React portals)
- Integrate with GHLContext for tool calling

### Phase 3: Integration (Sequential — 1 agent)

**Agent Foxtrot — Wire Everything Together**
- Merge all component registrations into `registry.ts`
- Update `src/apps/index.ts`:
  - Add new tool definitions for interactive components (`create_invoice`, `create_appointment`)
  - Update resource handler for `ui://ghl/dynamic-view` to serve React build
  - Add new resource URIs if needed
- Update `src/server.ts` if new tools need routing
- Update system prompt: add new interactive component catalog entries
- Update Goose config `available_tools` if needed
- Full build: React app → singlefile HTML → server TypeScript
- Test: verify JSON UI trees render correctly, interactive components call tools, drag-and-drop works
- Write brief README for the new architecture

---

## Key Technical Decisions

### State Management
- **React Context** (not Redux) — app is small enough, context + useReducer is perfect
- `GHLContext` holds: current UITree, form values, loading states, selected entities
- Any component can `const { callTool } = useGHL()` to interact with the MCP server

### Tool Calling Pattern
```tsx
// Any component can call MCP tools:
const { callTool, isLoading } = useCallTool();

const handleDrop = async (cardId: string, newStageId: string) => {
  await callTool('update_opportunity', {
    opportunityId: cardId,
    pipelineStageId: newStageId,
  });
};
```

### Drag & Drop (KanbanBoard)
- Pure React state — no global DOM event handlers
- `onDragStart`, `onDragOver`, `onDrop` on React elements
- Optimistic UI update (move card immediately, revert on error)

### Dynamic Sizing
- `useSizeReporter` hook — ResizeObserver on `#app`
- Sends `ui/notifications/size-changed` on every size change
- Caps at 600px height

### CSS Strategy
- Plain CSS files (not CSS modules, not Tailwind) — keeps bundle simple
- Same compact sizing as current (12px base, tight padding)
- All in `styles/` directory, imported in App.tsx
- Interactive styles (drag states, modals, toasts) in separate file

### Build Pipeline
```bash
# In src/ui/react-app/
npm run build
# → Vite builds React app → vite-plugin-singlefile → single HTML file
# → Output: ../../dist/app-ui/dynamic-view.html

# In GoHighLevel-MCP root
npm run build
# → Builds React UI first, then compiles TypeScript server
```

---

## Timeline Estimate

| Phase | Agents | Est. Time | Depends On |
|-------|--------|-----------|------------|
| Phase 1: Foundation | Alpha (1) | ~20 min | — |
| Phase 2: Components | Bravo, Charlie, Delta, Echo (4 parallel) | ~25 min | Phase 1 |
| Phase 3: Integration | Foxtrot (1) | ~15 min | Phase 2 |
| **Total** | **6 agents** | **~60 min** | |

---

## Success Criteria
1. ✅ All 42 existing components render identically to current version
2. ✅ JSON UI trees from Claude work without any format changes
3. ✅ KanbanBoard drag-and-drop moves deals and persists via `update_opportunity`
4. ✅ ContactPicker fetches real contacts from GHL on keystroke
5. ✅ InvoiceBuilder creates invoices with real contact data
6. ✅ EditableField saves changes via appropriate MCP tool
7. ✅ Dynamic sizing works — views fit in chat
8. ✅ Single HTML file output (vite-plugin-singlefile)
9. ✅ ext-apps handshake completes with Goose
10. ✅ All existing `view_*` tools still work alongside `generate_ghl_view`