clawdbot-workspace/a2p-autopilot/mcp-app/DEPLOYMENT.md

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

cd a2p-autopilot/mcp-app
npm install

2. Build UI Apps

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

npm run serve

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

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:

{
  "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

cd apps/registration-wizard
npx vite

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

Rebuild After Changes

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