# MCP Factory V2 — GHL-Quality Standard

## Quality Bar (The GHL Standard)

Every MCP server must match GoHighLevel's quality:

### Architecture
```
src/
├── server.ts              # MCP server setup (HTTP + stdio)
├── main.ts                # Entry point with transport selection
├── clients/               # API client classes (one per service)
│   └── {service}.ts       # Auth, request handling, error mapping
├── tools/                 # Tool definitions (one file per domain)
│   ├── contacts-tools.ts
│   ├── deals-tools.ts
│   └── ...
├── types/                 # TypeScript interfaces
│   └── index.ts
├── apps/                  # structuredContent HTML templates (legacy)
│   └── templates/
├── ui/                    # MCP Apps (React + Vite, per-app bundled)
│   └── react-app/
│       ├── src/
│       │   ├── apps/      # One dir per app (App.tsx + index.html + vite.config.ts)
│       │   ├── components/ # Shared component library
│       │   ├── hooks/     # Shared hooks (useCallTool, useDirtyState, etc.)
│       │   └── styles/    # Shared CSS
│       └── package.json
├── package.json
└── tsconfig.json
tests/
├── tools/
├── clients/
└── mocks/
```

### Minimum Requirements
- **Tools:** Comprehensive API coverage (30-100+ tools depending on API surface)
  - Organized into domain files (contacts, deals, campaigns, etc.)
  - Full CRUD for every major entity
  - Search/filter/list with pagination
  - Proper input schemas with descriptions
- **MCP Apps:** 10-65 React apps depending on platform complexity
  - Dashboards, detail views, list/grid views, form builders
  - Shared component library across apps
  - Client-side interactivity (sorting, filtering, drag-drop)
  - Proper text fallbacks for non-UI hosts
- **API Client:** Proper auth handling (OAuth2/API key), error mapping, rate limiting
- **Types:** Full TypeScript types for all API responses
- **Tests:** Unit tests for tools and clients
- **README:** Comprehensive setup, tool reference, app showcase
- **Package:** bin entry, prepublishOnly, npm pack clean
- **Dual Transport:** Both HTTP and stdio support

### MCP Apps Quality Standard
- Use `@modelcontextprotocol/ext-apps` SDK
- `registerAppTool()` + `registerAppResource()` pattern
- Each app is a standalone Vite-bundled HTML file
- Client-side state first (Pattern 1), callServerTool as enhancement
- Host CSS variable integration
- Graceful degradation with 5s timeout
- ALWAYS provide text content fallback

## Build Process (Per MCP)

### Phase 1: API Research (30 min)
- Map complete API surface (endpoints, entities, auth)
- Identify all CRUD operations per entity
- Note auth flow (OAuth2, API key, Bearer)
- List all entities and relationships

### Phase 2: Architecture (15 min)
- Design tool groupings (one file per domain)
- Plan API client structure
- Identify app opportunities (dashboards, detail views, forms)
- Estimate tool count and app count

### Phase 3: Build Server (2-4 hours)
- Implement API client with proper auth
- Build all tools organized by domain
- TypeScript types for all responses
- Compile clean, proper error handling

### Phase 4: Build MCP Apps (2-4 hours)
- Shared component library (or import from existing)
- React apps per the patterns catalog
- Vite single-file bundling
- Register tools + resources in server

### Phase 5: Quality Check (30 min)
- TypeScript compiles clean
- npm pack works
- README complete
- Tests pass
- Push to mcpengine-repo AND individual GitHub repo

## Parallelization Strategy

Build 3-5 MCPs simultaneously using sub-agents:
- Each sub-agent gets one MCP to build end-to-end
- Sub-agents follow this exact spec
- Main agent reviews output and commits

## Priority Order (by market value)

### Tier 1 — High Value (Build First)
1. Zendesk (huge market, 100k+ customers)
2. Mailchimp (email marketing leader)
3. Pipedrive (popular CRM)
4. ClickUp (project management)
5. Trello (project management)
6. Calendly (scheduling leader)

### Tier 2 — Strong Market
7. BigCommerce (ecommerce)
8. FreshBooks (accounting)
9. Keap (CRM + automation)
10. Wrike (project management)
11. Zendesk (support)
12. Constant Contact (email marketing)

### Tier 3 — Niche but Solid
13. BambooHR (HR)
14. Gusto (payroll)
15. Rippling (HR platform)
16. Basecamp (project management)
17. ServiceTitan (field service)
18. Housecall Pro (field service)
19. Jobber (field service)

### Tier 4 — Specialized
20. Acuity Scheduling
21. Clover (POS)
22. FieldEdge (field service)
23. Lightspeed (POS/ecommerce)
24. Squarespace (website builder)
25. Toast (restaurant POS)
26. TouchBistro (restaurant POS)
27. Wave (accounting)

### Already Built (need apps added)
28. Brevo — needs full rebuild (tools + apps)
29. Close CRM — needs full rebuild (tools + apps)
30. FreshDesk — needs full rebuild (tools + apps)
31. HelpScout — needs full rebuild (tools + apps)
32. Compliance GRC — needs apps
33. Product Analytics — needs apps

### Already Good
34. GoHighLevel — 474 tools, 65 apps ✅
35. CloseBot — 119 tools, 6 apps ✅
36. Meta Ads — 55 tools, 11 apps ✅
37. Twilio — 54 tools, 19 apps ✅
38. Google Console — 22 tools, 5 apps ✅
39. n8n — 8 apps ✅