# MCP Factory V3 — Quality-First Build System

## Quality Standards (Feb 2026)

Every MCP server MUST include these features:

### Server Architecture
- **Lazy-loaded tool modules** — tools loaded on-demand, not all at startup
- **Dual transport** — HTTP (SSE) + stdio support
- **Graceful shutdown** — SIGINT/SIGTERM handlers, connection cleanup
- **Health endpoint** — `/health` for monitoring
- **Structured logging** — JSON logs with levels, request IDs
- **Environment validation** — fail fast on missing required env vars

### API Client
- **Retry with exponential backoff** — 3 retries, 1s/2s/4s delays
- **Rate limit awareness** — respect 429 headers, auto-throttle
- **Automatic pagination** — cursor/offset pagination abstracted away
- **Request/response interceptors** — logging, error normalization
- **Timeout handling** — 30s default, configurable per-request
- **Auth refresh** — auto-refresh OAuth tokens before expiry

### Tool Quality
- **Strict inputSchema** — Zod validation on all inputs
- **Typed outputs** — consistent response shapes
- **Error categorization** — user errors vs system errors vs auth errors
- **Pagination support** — limit/offset/cursor params where applicable
- **Bulk operations** — batch create/update/delete where API supports it
- **Search/filter** — rich query params, not just list-all

### React MCP Apps (UI Resources)
- **React 18+ with Suspense** — lazy loading components
- **Code splitting** — dynamic imports for heavy components
- **Error boundaries** — graceful error UI, not white screens
- **Loading skeletons** — shimmer/skeleton UI during data fetch
- **Dark theme** — CSS custom properties, #0f172a/#1e293b base
- **Responsive** — mobile-first, works on all screen sizes
- **Accessible** — ARIA labels, keyboard navigation, focus management
- **Optimistic UI** — instant feedback on user actions
- **Virtual scrolling** — for large lists (100+ items)
- **Toast notifications** — success/error feedback
- **Empty states** — helpful messaging when no data
- **Client-side search/filter** — instant filtering without API calls
- **Debounced inputs** — search inputs don't fire on every keystroke

### TypeScript
- **Strict mode** — `"strict": true` in tsconfig
- **No `any` types** — everything typed, use `unknown` if needed
- **Discriminated unions** — for API response variants
- **Branded types** — for IDs (CustomerId, OrderId, etc.)

### Documentation
- **README.md** — setup, env vars, examples, API reference
- **Tool catalog** — table of all tools with descriptions
- **App catalog** — table of all apps with screenshots descriptions

## Factory Pipeline

### Phase 1: Manifest Creation (Opus, 1 agent)
- Research API docs for each platform
- Create manifest.json with categories, endpoints, auth pattern
- Human review before proceeding

### Phase 2: Foundation Build (Sonnet, 1 agent per server)
- API client + types + server shell
- Scope: ~15 min per server
- Verify: TSC compiles, server starts

### Phase 3: Tool Build (Sonnet, 1 agent per server)
- All tool files based on manifest categories
- Scope: ~15 min per server
- Verify: TSC compiles, tool count matches manifest

### Phase 4: App Build (Sonnet, 1 agent per server)
- All React apps
- Scope: ~15 min per server
- Verify: file count, each app has required files

### Phase 5: Quality Pass (Sonnet, 1 agent per batch)
- TSC strict mode check
- Verify lazy loading patterns
- Check error boundaries exist
- Verify loading skeletons
- Fix any issues

### Phase 6: Git + Deploy
- Commit each server individually
- Push to monorepo
- Sync to individual repos
- All done via bash script (zero tokens)
