# A2P AutoPilot MCP Server — Deployment Guide

## ✅ What Was Built

A complete, production-ready MCP Server with 4 interactive UI apps for managing A2P registrations in Claude Desktop.

### 📁 File Structure

```
a2p-autopilot/mcp-app/
├── server.ts                    # Main MCP server (stdio transport)
├── package.json                 # Dependencies & scripts
├── tsconfig.json               # TypeScript config
├── build-all.js                # Build script for all apps
├── README.md                   # Documentation
├── .gitignore                  # Git ignore patterns
│
├── src/                        # Core server logic
│   ├── tools.ts                # All 9 MCP tool definitions
│   ├── handlers.ts             # Tool execution handlers
│   ├── resources.ts            # UI resource registration
│   └── mock-data.ts            # Realistic test data (10 submissions)
│
├── apps/                       # 4 React apps (Vite)
│   ├── registration-wizard/
│   │   ├── App.tsx             # Multi-step registration form
│   │   ├── main.tsx            # React entry point
│   │   ├── index.html          # HTML template
│   │   └── vite.config.ts      # Vite single-file build config
│   ├── dashboard/
│   │   ├── App.tsx             # Submissions list with filters
│   │   ├── main.tsx
│   │   ├── index.html
│   │   └── vite.config.ts
│   ├── submission-detail/
│   │   ├── App.tsx             # Deep dive: SID chain, timeline, details
│   │   ├── main.tsx
│   │   ├── index.html
│   │   └── vite.config.ts
│   └── landing-preview/
│       ├── App.tsx             # Preview opt-in/privacy/terms pages
│       ├── main.tsx
│       ├── index.html
│       └── vite.config.ts
│
├── components/                 # Shared React components
│   ├── layout/
│   │   ├── PageHeader.tsx      # App header with title & actions
│   │   ├── Card.tsx            # Card container
│   │   ├── StepProgress.tsx    # Multi-step progress indicator
│   │   └── Section.tsx         # Content section
│   ├── data/
│   │   ├── StatusBadge.tsx     # Color-coded status badges
│   │   ├── DataTable.tsx       # Generic sortable table
│   │   ├── MetricCard.tsx      # Dashboard metric cards
│   │   ├── Timeline.tsx        # Event timeline
│   │   └── SidChainTracker.tsx # Visual SID chain progress
│   ├── forms/
│   │   ├── FormField.tsx       # Text input with validation
│   │   ├── SelectField.tsx     # Dropdown select
│   │   ├── PhoneInput.tsx      # Phone number input with formatting
│   │   ├── EINInput.tsx        # EIN input with XX-XXXXXXX formatting
│   │   └── FormSection.tsx     # Form section container
│   └── shared/
│       ├── Button.tsx          # Button with variants & loading state
│       ├── Modal.tsx           # Modal dialog
│       ├── Toast.tsx           # Toast notifications
│       └── ComplianceChecklist.tsx # Checkbox list for compliance
│
├── hooks/
│   ├── useMCPApp.ts            # Hook to access MCP context data
│   └── useSmartAction.ts       # Hook to call MCP tools from apps
│
└── styles/
    └── base.css                # Global CSS variables & utilities
```

## 🛠️ Setup Instructions

### 1. Install Dependencies

```bash
cd a2p-autopilot/mcp-app
npm install
```

### 2. Build UI Apps

```bash
npm run build:ui
```

This runs `build-all.js`, which builds all 4 apps as single-file HTML bundles:
- `dist/app-ui/registration-wizard.html`
- `dist/app-ui/dashboard.html`
- `dist/app-ui/submission-detail.html`
- `dist/app-ui/landing-preview.html`

### 3. Test the Server

```bash
npm run serve
```

The server runs on stdio. Test by piping JSON-RPC commands:

```bash
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npm run serve
```

### 4. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "a2p-autopilot": {
      "command": "node",
      "args": [
        "/Users/jakeshore/.clawdbot/workspace/a2p-autopilot/mcp-app/server.ts"
      ],
      "env": {
        "A2P_API_URL": "http://localhost:3100",
        "USE_MOCK_DATA": "true"
      }
    }
  }
}
```

Restart Claude Desktop.

## 🧪 Testing

### Using Mock Data (Default)

The server defaults to `USE_MOCK_DATA=true`, which uses the 10 realistic mock submissions in `src/mock-data.ts`.

### Using Live API

Set `USE_MOCK_DATA=false` and ensure the A2P AutoPilot backend is running on `localhost:3100`.

### Test Commands in Claude

```
Open the A2P registration wizard
Show me the A2P dashboard
View submission sub_1
Preview landing pages for sub_1
```

## 📊 MCP Tools

### UI Tools (Model + App Visible)

1. **a2p_registration_wizard** — Opens multi-step registration form
   - Optional: `externalId` to pre-fill data
   - Returns: `ui://a2p/registration-wizard`

2. **a2p_dashboard** — Opens submissions dashboard
   - Optional: `status` filter
   - Returns: `ui://a2p/dashboard` with submissions & stats

3. **a2p_view_submission** — Opens detailed submission view
   - Required: `submissionId`
   - Returns: `ui://a2p/submission-detail` with full data

4. **a2p_preview_landing** — Previews landing pages
   - Required: `submissionId`
   - Returns: `ui://a2p/landing-preview` with page URLs

### Backend Tools (App-Only Visibility)

5. **a2p_submit_registration** — Submit new registration
   - Takes full `RegistrationInput` object
   - Returns: submission ID & status

6. **a2p_retry_submission** — Retry failed submission
   - Required: `submissionId`

7. **a2p_cancel_submission** — Cancel pending submission
   - Required: `submissionId`

8. **a2p_check_status** — Refresh submission status
   - Required: `submissionId`

9. **a2p_get_stats** — Get dashboard statistics
   - Returns: counts by status, success rate

## 🎨 UI Features

### Registration Wizard
- 5-step form: Business Info → Authorized Rep → Address → Campaign → Review
- Form validation with real-time feedback
- Pre-fill support via `externalId`
- EIN & phone number formatting
- Industry & use case dropdowns

### Dashboard
- Metric cards: Total, Completed, Pending, Success Rate
- Status filter buttons
- Sortable submissions table
- Click any row to view details

### Submission Detail
- Current status with badge
- Failure reason display (if applicable)
- Full SID chain tracker (10 Twilio SIDs)
- Activity timeline with timestamps
- Retry/Cancel/Refresh actions
- Business & campaign details
- Remediation history

### Landing Preview
- 3-page preview: Landing, Privacy Policy, Terms
- Tab navigation
- Generated content based on campaign data
- Sample messages display
- Opt-in/opt-out instructions

## 🔧 Development

### Run Single App in Dev Mode

```bash
cd apps/registration-wizard
npx vite
```

Opens on `http://localhost:5173` with hot reload.

### Rebuild After Changes

```bash
npm run build:ui
```

### Add New Component

1. Create in `components/{category}/`
2. Import in app: `import { MyComponent } from '../../components/{category}/MyComponent'`
3. Use Tailwind classes for styling

## 📝 Type Safety

All types are imported from `../src/types.ts`:
- `RegistrationInput`
- `SubmissionRecord`
- `SubmissionStatus`
- `SidChain`
- Business/Campaign enums

## 🚀 Next Steps

1. **Connect to Real API**: Set `USE_MOCK_DATA=false` and test with live backend
2. **Add More Tools**: 
   - `a2p_bulk_import` for CSV imports
   - `a2p_export_report` for analytics
3. **Enhance UI**:
   - Add charts to dashboard (success rate over time)
   - Add search/sort to table
   - Add bulk actions (retry multiple submissions)
4. **Add Notifications**: Show real-time status updates via webhooks

## 🐛 Troubleshooting

### "Resource not found" error
- Run `npm run build:ui` to generate HTML bundles
- Check `dist/app-ui/` contains 4 HTML files

### Server won't start
- Verify `node` and `tsx` are installed: `npm install -g tsx`
- Check logs: `npm run serve 2>&1 | tee server.log`

### UI doesn't show data
- Verify `window.mcpContext` is set (check browser console)
- Check mock data in `src/mock-data.ts`

## 📦 Production Checklist

- [ ] Build all apps: `npm run build:ui`
- [ ] Set `USE_MOCK_DATA=false`
- [ ] Configure `A2P_API_URL` to production endpoint
- [ ] Test all 9 tools in Claude Desktop
- [ ] Verify error handling (network failures, validation errors)
- [ ] Check mobile responsiveness (Tailwind is mobile-first)
- [ ] Add logging/monitoring for tool calls

---

**Built by**: Subagent (a2p-mcp-server)  
**Date**: February 3, 2026  
**Status**: ✅ Ready for testing