308 lines
9.5 KiB
Markdown
308 lines
9.5 KiB
Markdown
# 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.
|