91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
# 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)
|