# A2P AutoPilot MCP Apps

Professional React UI apps for the A2P AutoPilot MCP server. These apps run inside MCP hosts like Claude Desktop and provide interactive interfaces for A2P brand and campaign registration.

## 🎯 Overview

Four standalone, production-ready apps:

1. **Registration Wizard** — Multi-step form for creating A2P registrations
2. **Dashboard** — Overview of all submissions with metrics and filtering
3. **Submission Detail** — Deep dive into individual submission status and history
4. **Landing Preview** — TCPA-compliant landing page preview with compliance checklist

## 🏗️ Architecture

- **Framework**: React 18 + TypeScript
- **Build**: Vite with `vite-plugin-singlefile` (single HTML output per app)
- **MCP Integration**: `@modelcontextprotocol/ext-apps` SDK
- **Styling**: CSS with host theme variables (Claude Desktop compatible)
- **State**: Client-side React state + MCP tool results

## 📦 Installation

```bash
npm install
```

## 🚀 Development

Run individual apps in dev mode:

```bash
npm run dev:wizard      # Registration Wizard
npm run dev:dashboard   # Dashboard
npm run dev:detail      # Submission Detail
npm run dev:preview     # Landing Preview
```

Each dev server runs on a separate port with hot module replacement.

## 🏭 Production Build

Build all apps to single HTML files:

```bash
npm run build
```

Output: `dist/app-ui/*.html` (one file per app, fully self-contained)

Build individual apps:

```bash
npm run build:wizard
npm run build:dashboard
npm run build:detail
npm run build:preview
```

## 📁 Project Structure

```
mcp-app/
├── apps/                      # 4 standalone apps
│   ├── registration-wizard/   # Multi-step registration form
│   ├── dashboard/             # Submissions overview
│   ├── submission-detail/     # Individual submission view
│   └── landing-preview/       # Landing page preview
├── components/                # Shared React components
│   ├── layout/               # PageHeader, Card, StepProgress, Section
│   ├── data/                 # StatusBadge, DataTable, MetricCard, Timeline, SidChainTracker
│   ├── forms/                # FormField, SelectField, PhoneInput, EINInput
│   └── shared/               # Button, Modal, Toast, ComplianceChecklist
├── hooks/                    # Custom React hooks
│   ├── useMCPApp.ts         # MCP connection + host styles
│   └── useSmartAction.ts    # callServerTool with fallback
├── styles/                   # Global CSS
│   └── base.css             # Host CSS variables + utilities
├── dist/app-ui/             # Build output (single HTML files)
├── package.json
└── README.md
```

## 🎨 Design System

Uses Claude Desktop host CSS variables for seamless theme integration:

- `--color-background-primary`, `--color-text-primary`, etc.
- `--font-family`, `--font-size-*`
- `--border-radius-*`, `--spacing-*`, `--shadow-*`

Fallback values provided for standalone testing.

## 🔌 MCP Integration

### Critical Rules (from MCP Apps SDK)

1. **Register handlers BEFORE `app.connect()`**
2. **Send all data upfront via `ontoolresult`** — use client-side state for interactivity
3. **Use `callServerTool` only when fresh server data is needed**
4. **Use `updateModelContext` to inform the model of user actions**
5. **Apply host styles with `useHostStyles()`**

### Data Flow

```
MCP Server (tool call) 
  → Tool Result (JSON data) 
    → App receives via `ontoolresult` 
      → React state updates 
        → UI renders
```

User interactions → `callServerTool` or `sendMessage` → Server processes → New tool result → UI updates

## 📱 Apps

### 1. Registration Wizard

**Purpose**: Complete A2P registration flow in 5 steps

**Steps**:
1. Business Information (name, type, industry, EIN, etc.)
2. Authorized Representative (contact person)
3. Business Address (physical location)
4. Campaign Details (use case, messages, opt-in/out)
5. Review & Submit (full summary + compliance check)

**Features**:
- Real-time validation on each step
- Auto-formatted inputs (EIN, phone numbers)
- Multi-select regions of operation
- Sample messages with character count
- Compliance checklist on review step
- Edit any step from review

**Tool Calls**:
- `a2p_submit_registration` (final submit)

---

### 2. Dashboard

**Purpose**: Overview of all A2P submissions

**Features**:
- 5 metric cards (Total, Pending, Approved, Failed, Success Rate)
- Sortable, filterable data table
- Status badge for each submission
- Brand trust score display
- Auto-refresh every 60 seconds
- Click row to view details

**Tool Calls**:
- `a2p_get_stats` (metrics + submissions list)
- `sendMessage` to open detail view

---

### 3. Submission Detail

**Purpose**: Deep dive into individual submission

**Features**:
- Status badge + brand trust score
- SID chain progress tracker (12 Twilio steps)
- Business info summary
- Remediation history timeline
- Audit log timeline
- Action buttons (Retry, Cancel, Refresh, View Landing Page)
- Cancel confirmation modal

**Tool Calls**:
- `a2p_retry_submission` (retry failed)
- `a2p_cancel_submission` (cancel pending)
- `a2p_check_status` (refresh)
- `sendMessage` to open landing preview

---

### 4. Landing Preview

**Purpose**: Preview TCPA-compliant landing pages

**Features**:
- Tabbed interface (Opt-In Page, Privacy Policy, Terms)
- Live HTML preview in iframe
- Compliance checklist sidebar (9 TCPA elements)
- Auto-detection of compliance elements
- View HTML source (collapsible)
- Page URLs display

**Tool Calls**:
- None (displays data from tool result)

---

## 🧩 Shared Components

### Layout
- **PageHeader**: App title bar with optional subtitle, back button, action slot
- **Card**: Elevated container with optional header/footer
- **StepProgress**: Horizontal step indicator with labels and completion state
- **Section**: Collapsible section with title

### Data Display
- **StatusBadge**: Colored badge for submission statuses (13 status types)
- **DataTable**: Sortable, filterable table with column definitions
- **MetricCard**: Stat card with value, label, optional trend
- **Timeline**: Vertical timeline for events with timestamps
- **SidChainTracker**: Visual 12-step progress tracker for Twilio SID chain

### Forms
- **FormField**: Text input with label, error, help text
- **SelectField**: Dropdown with options
- **PhoneInput**: Phone input with auto-formatting to E.164
- **EINInput**: EIN input with auto-formatting (XX-XXXXXXX)
- **FormSection**: Group of form fields with section title

### Shared UI
- **Button**: Primary/secondary/danger variants, loading state
- **Modal**: Overlay modal for confirmations
- **Toast**: Success/error/info/warning toast notifications
- **ComplianceChecklist**: Green checkmark list with progress bar

## 🎣 Custom Hooks

### `useMCPApp()`

Wrapper around `useApp` that:
- Registers `ontoolresult` and `ontoolinput` handlers
- Applies host styles with `useHostStyles()`
- Connects to MCP host
- Provides app instance + tool result data

```tsx
const { app, toolResult, isConnected } = useMCPApp();
```

### `useSmartAction()`

Capability detection for `callServerTool`:
- Calls server tool if available
- Falls back to `sendMessage` if not
- Updates model context after action
- Returns loading state and error

```tsx
const { execute, isLoading, error } = useSmartAction(app);
await execute('a2p_submit_registration', { ...args });
```

## 🎨 Theming

All apps use host CSS variables for seamless integration with Claude Desktop's theme. Fallback values ensure apps work standalone.

**Colors**: `--color-background-primary`, `--color-text-primary`, `--color-accent-primary`, etc.
**Typography**: `--font-family`, `--font-size-base`, etc.
**Spacing**: `--spacing-1` through `--spacing-12`
**Border Radius**: `--border-radius-sm`, `--border-radius-md`, `--border-radius-lg`
**Shadows**: `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`

## 📊 Data Types

All data types are defined in `/Users/jakeshore/.clawdbot/workspace/a2p-autopilot/src/types.ts`:

- `RegistrationInput` (full registration data)
- `SubmissionRecord` (submission state + history)
- `SidChain` (12 Twilio SIDs)
- `RemediationEntry` (auto-fix history)
- `LandingPageConfig` (landing page data)
- Plus 13 enums (BusinessType, BusinessIndustry, CampaignUseCase, etc.)

## 🚀 Deployment

Built apps are single HTML files (via `vite-plugin-singlefile`). Each file is ~200-400KB and fully self-contained (no external dependencies).

**Output files**:
- `dist/app-ui/registration-wizard.html`
- `dist/app-ui/dashboard.html`
- `dist/app-ui/submission-detail.html`
- `dist/app-ui/landing-preview.html`

These files can be served statically or embedded directly in the MCP server.

## 🧪 Testing

Open individual apps in Claude Desktop by:
1. Building the app
2. Registering the app HTML in your MCP server config
3. Calling the MCP tool that returns the app

Or test standalone by opening the built HTML files directly in a browser (limited MCP functionality).

## 🎯 Key Features

✅ **Production-ready** — Clean TypeScript, proper error handling, loading states  
✅ **Beautiful UI** — Professional design using host theme variables  
✅ **MCP-native** — Follows all MCP Apps SDK best practices  
✅ **Single-file builds** — No external dependencies, easy to deploy  
✅ **Accessible** — Semantic HTML, keyboard navigation, ARIA labels  
✅ **Responsive** — Works on all screen sizes  
✅ **Type-safe** — Full TypeScript coverage  

## 📝 License

Part of the A2P AutoPilot project.
