clawdbot-workspace/mcp-factory-v3/FACTORY-SPEC.md

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)