@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-production-readiness/references/common-checklist.md

@@ -0,0 +1,175 @@
+---
+name: common-checklist
+description: Security, performance, reliability, and observability checks for all deployment targets
+---
+
+# Common Production Readiness Checklist
+
+These checks apply to ALL deployment targets. Run them first, then proceed to your target-specific checklist.
+
+## Security
+
+### Authentication & Authorization
+
+- [ ] JWT_SECRET is set to a strong random value (not the default)
+- [ ] Authentication is enabled (`auth` config in `@FrontMcp` or `@frontmcp/auth`)
+- [ ] API keys/tokens are loaded from environment variables, never hardcoded
+- [ ] Session storage uses Redis or platform-native store (not in-memory) for multi-instance
+- [ ] Session TTL is configured appropriately (not infinite)
+- [ ] Tool-level authorization is enforced where needed (ApprovalPlugin or custom)
+- [ ] OAuth redirect URIs are restricted to known domains
+
+### CORS Configuration
+
+- [ ] CORS is NOT permissive (don't allow all origins in production)
+- [ ] Specific allowed origins are listed: `cors: { origin: ['https://your-app.com'] }`
+- [ ] Credentials mode is only enabled if cookies/sessions are needed
+- [ ] Preflight cache (`maxAge`) is set to reduce OPTIONS requests
+
+### Input Validation
+
+- [ ] All tool inputs use Zod schemas (never trust raw input)
+- [ ] All tool outputs use `outputSchema` to prevent data leaks
+- [ ] Path parameters and query params are validated
+- [ ] File paths are sanitized to prevent directory traversal
+- [ ] SQL queries use parameterized statements (never string interpolation)
+
+### Secrets Management
+
+- [ ] No secrets in source code or git history
+- [ ] `.env` files are in `.gitignore`
+- [ ] Production secrets are managed via secret manager (AWS SSM, Vault, etc.)
+- [ ] API keys have minimum required permissions
+- [ ] Secrets are rotated on a schedule
+
+### Rate Limiting
+
+- [ ] Rate limiting is configured for public-facing endpoints
+- [ ] Per-client/per-IP limits are set
+- [ ] Throttle configuration uses `@FrontMcp({ throttle: {...} })`
+- [ ] Large payload limits are set to prevent memory exhaustion
+
+### Dependencies
+
+- [ ] `npm audit` shows no high/critical vulnerabilities
+- [ ] Dependencies are pinned or use tilde ranges (not `*` or `latest`)
+- [ ] No unused dependencies in package.json
+
+## Performance
+
+### Caching
+
+- [ ] CachePlugin is configured for read-heavy tools
+- [ ] Cache TTL is tuned per tool (not one-size-fits-all)
+- [ ] Stale cache invalidation strategy is defined
+
+### Response Optimization
+
+- [ ] Large responses are paginated or streamed
+- [ ] Tools return only necessary data (no over-fetching)
+- [ ] Binary data uses proper encoding (base64 only when necessary)
+
+### Memory Management
+
+- [ ] No memory leaks from event listeners or unclosed connections
+- [ ] Large data processing uses streams instead of buffering
+- [ ] Provider lifecycle `dispose()` is implemented for cleanup
+- [ ] Session storage has TTL to prevent unbounded growth
+
+## Reliability
+
+### Error Handling
+
+- [ ] All tools use `this.fail()` with specific MCP error classes
+- [ ] Unknown errors are caught and wrapped (never expose stack traces)
+- [ ] Error responses include MCP error codes for client handling
+- [ ] Async errors are properly caught (no unhandled promise rejections)
+
+### Retry & Circuit Breaking
+
+- [ ] External API calls have retry logic with exponential backoff
+- [ ] Circuit breaker pattern for unreliable downstream services
+- [ ] Timeouts are set for all external calls
+- [ ] Job retries have maximum attempt limits
+
+## Observability
+
+### Logging
+
+- [ ] Logs use structured format (JSON in production)
+- [ ] Log levels are appropriate (info for normal, error for failures)
+- [ ] Sensitive data is redacted from logs (tokens, passwords, PII)
+- [ ] Request/response logging includes correlation IDs
+
+### Health & Readiness
+
+- [ ] `/healthz` endpoint is reachable from load balancer or orchestrator
+- [ ] `/readyz` endpoint is configured for Kubernetes readiness or similar
+- [ ] Custom probes added for external dependencies (databases, APIs, queues)
+- [ ] `includeDetails: false` in production to avoid leaking infrastructure topology
+- [ ] Probe timeout (`readyz.timeoutMs`) is lower than orchestrator probe timeout
+- [ ] `toolsHash` from `/readyz` is monitored for config drift across instances
+
+### Monitoring
+
+- [ ] Request count and latency metrics are exposed
+- [ ] Error rate metrics are tracked
+- [ ] Tool execution duration is measured
+- [ ] Error tracking service is integrated (Sentry, Datadog, etc.)
+
+## Jobs & Workflows (if enabled)
+
+- [ ] Jobs Redis store is configured for production (`jobs: { enabled: true, store: { redis } }`)
+- [ ] Job retry config has reasonable `maxAttempts` and `maxBackoffMs`
+- [ ] Workflow timeout is set to prevent runaway workflows
+- [ ] Job execution times are monitored (long-running jobs need alerting)
+- [ ] Workflow step `continueOnError` is only used for non-critical steps
+
+## Skills HTTP Endpoints (if enabled)
+
+- [ ] Skills HTTP auth is configured (`skillsConfig.auth: 'api-key'` or `'bearer'`)
+- [ ] Skills caching is enabled for production (`skillsConfig.cache: { enabled: true }`)
+- [ ] Cache TTL is tuned for skill instruction freshness requirements
+- [ ] `/llm.txt` and `/skills` endpoints are tested for correct responses
+
+## ExtApps / Widgets (if enabled)
+
+- [ ] Host capabilities are reviewed — only enable what widgets need
+- [ ] `serverToolProxy` is disabled if widgets should not call MCP tools
+- [ ] Widget session validation is active (default with HTTP transport)
+- [ ] CSP headers are configured for hosted widget origins
+
+## SQLite (if used)
+
+- [ ] WAL mode is enabled for concurrent read/write performance
+- [ ] Database file path is writable and persistent (not ephemeral storage)
+- [ ] Backup strategy is defined (periodic file copy or WAL checkpoint)
+- [ ] Database size is monitored to prevent disk exhaustion
+
+## Documentation
+
+- [ ] README.md is up-to-date for the deployment target (see `frontmcp-setup` → `references/readme-guide.md`)
+- [ ] API documentation covers all tools and resources
+- [ ] Environment variables are documented in `.env.example`
+
+## Common Anti-Patterns
+
+| Anti-Pattern              | Fix                                         |
+| ------------------------- | ------------------------------------------- |
+| Default JWT_SECRET        | Set a strong random secret                  |
+| In-memory session store   | Use Redis or platform-native storage        |
+| `cors: { origin: '*' }`   | Restrict to known origins                   |
+| No output schema on tools | Always define `outputSchema`                |
+| Synchronous file I/O      | Use async operations from `@frontmcp/utils` |
+| Hardcoded secrets         | Use environment variables                   |
+| Unbounded caching         | Set TTL on all caches                       |
+
+## Examples
+
+| Example                                                                              | Level        | Description                                                                                                                |
+| ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| [`caching-and-performance`](../examples/common-checklist/caching-and-performance.md) | Advanced     | Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.     |
+| [`observability-setup`](../examples/common-checklist/observability-setup.md)         | Intermediate | Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production. |
+| [`security-hardening`](../examples/common-checklist/security-hardening.md)           | Basic        | Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.         |
+
+> See all examples in [`examples/common-checklist/`](../examples/common-checklist/)

package/catalog/frontmcp-production-readiness/references/health-readiness-endpoints.md

@@ -0,0 +1,198 @@
+---
+name: health-readiness-endpoints
+description: Configure /healthz and /readyz endpoints with custom probes, runtime-aware readiness, and dependency health checks
+---
+
+# Health & Readiness Endpoints
+
+FrontMCP provides Kubernetes-style `/healthz` (liveness) and `/readyz` (readiness) endpoints with automatic dependency probing, catalog introspection, and runtime-aware behavior.
+
+## Runtime Availability
+
+| Runtime                    | `/healthz` | `/readyz` | Notes                              |
+| -------------------------- | ---------- | --------- | ---------------------------------- |
+| Node.js / Bun / Deno       | yes        | yes       | Full support                       |
+| Edge / Cloudflare / Vercel | yes        | no        | No persistent connections to probe |
+| CLI                        | yes        | no        | No HTTP server in stdio mode       |
+| Browser                    | yes        | yes       | Full support                       |
+
+## Default Behavior
+
+Health endpoints are **enabled by default** with zero configuration:
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  // health endpoints are auto-registered:
+  // GET /healthz  -> liveness probe
+  // GET /readyz   -> readiness probe (Node.js, Bun, Deno, Browser)
+  // GET /health   -> legacy alias for /healthz
+})
+export default class Server {}
+```
+
+## Endpoint Responses
+
+### `/healthz` (Liveness)
+
+Lightweight, no I/O. Returns server info, runtime context, and uptime.
+
+```json
+{
+  "status": "ok",
+  "server": { "name": "my-server", "version": "1.0.0" },
+  "runtime": { "platform": "linux", "runtime": "node", "deployment": "standalone", "env": "production" },
+  "uptime": 3600.5
+}
+```
+
+- **HTTP 200**: Server process is alive
+- **HTTP 503**: Server is in a degraded state
+
+### `/readyz` (Readiness)
+
+Deep check: probes all registered dependencies, returns catalog hash and registry counts.
+
+```json
+{
+  "status": "ready",
+  "totalLatencyMs": 45,
+  "catalog": {
+    "toolsHash": "a1b2c3d4e5f6...",
+    "toolCount": 12,
+    "resourceCount": 3,
+    "promptCount": 2,
+    "skillCount": 1,
+    "agentCount": 0
+  },
+  "probes": {
+    "session-store": { "status": "healthy", "latencyMs": 12 },
+    "remote:payment-svc": { "status": "healthy", "latencyMs": 25 }
+  }
+}
+```
+
+- **HTTP 200**: All probes pass (`status: "ready"`)
+- **HTTP 503**: At least one probe unhealthy (`status: "not_ready"`)
+
+## Auto-Discovered Probes
+
+The health service automatically registers probes for:
+
+- **Session store** (Redis/Vercel KV) via `TransportService.pingSessionStore()`
+- **Remote MCP apps** via the existing `HealthCheckManager` background checks
+
+## Custom Probes
+
+Add your own dependency checks via the `health.probes` config:
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { host: 'localhost' },
+  health: {
+    probes: [
+      {
+        name: 'postgres',
+        async check() {
+          const start = Date.now();
+          await pool.query('SELECT 1');
+          return { status: 'healthy', latencyMs: Date.now() - start };
+        },
+      },
+      {
+        name: 'external-api',
+        async check() {
+          const res = await fetch('https://api.example.com/ping');
+          return { status: res.ok ? 'healthy' : 'unhealthy' };
+        },
+      },
+    ],
+  },
+})
+```
+
+## Configuration Options
+
+```typescript
+health: {
+  enabled: true,              // default: true
+  healthzPath: '/healthz',    // default: '/healthz'
+  readyzPath: '/readyz',      // default: '/readyz'
+  includeDetails: false,      // default: true in dev, false in production
+  readyz: {
+    enabled: true,            // auto-determined by runtime when omitted
+    timeoutMs: 5000,          // per-probe timeout, default: 5000
+  },
+  probes: [],                 // custom user-defined probes
+}
+```
+
+### Probe Result Shape
+
+Each probe must return:
+
+```typescript
+interface HealthProbeResult {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  latencyMs?: number;
+  details?: Record<string, unknown>;
+  error?: string;
+}
+```
+
+## Production Recommendations
+
+- [ ] Set `includeDetails: false` in production to avoid leaking infrastructure topology
+- [ ] Set `readyz.timeoutMs` to a value lower than your orchestrator's probe timeout
+- [ ] Add custom probes for all external dependencies (databases, APIs, queues)
+- [ ] Use the `toolsHash` from `/readyz` to detect config drift across instances
+- [ ] Point Kubernetes liveness probe at `/healthz` and readiness probe at `/readyz`
+- [ ] Point load balancer health checks at `/health` or `/healthz`
+
+## Kubernetes Example
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: 3001
+  initialDelaySeconds: 5
+  periodSeconds: 10
+readinessProbe:
+  httpGet:
+    path: /readyz
+    port: 3001
+  initialDelaySeconds: 10
+  periodSeconds: 15
+  timeoutSeconds: 5
+```
+
+## Docker Example
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:3001/healthz || exit 1
+```
+
+## Disabling Health Endpoints
+
+```typescript
+@FrontMcp({
+  health: { enabled: false },
+})
+```
+
+## Examples
+
+| Example                                                                              | Level        | Description                                                                                |
+| ------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------ |
+| [`basic-health-setup`](../examples/health-readiness-endpoints/basic-health-setup.md) | Basic        | Default health endpoints with Redis session store, showing /healthz and /readyz responses. |
+| [`custom-probes`](../examples/health-readiness-endpoints/custom-probes.md)           | Intermediate | Custom database and API probes with Kubernetes deployment configuration.                   |
+
+## Reference
+
+- [Health Checks Documentation](https://docs.agentfront.dev/frontmcp/deployment/health-checks)
+- Related skills: `frontmcp-observability`, `frontmcp-deployment`, `frontmcp-config`

package/catalog/frontmcp-production-readiness/references/production-browser.md

@@ -0,0 +1,56 @@
+---
+name: production-browser
+description: Checklist for publishing FrontMCP as a browser-compatible SDK bundle
+---
+
+# Production Readiness: Browser SDK
+
+Target-specific checklist for publishing FrontMCP as a browser-compatible SDK.
+
+> Run the `common-checklist` first, then use this checklist for browser-specific items.
+
+## Build
+
+- [ ] `frontmcp build --target browser` produces a correct ESM/UMD bundle
+- [ ] Bundle size is acceptable (check with `npx bundlesize` or similar)
+- [ ] Tree-shaking works (no unnecessary code in final bundle)
+- [ ] Source maps are generated for debugging (but not shipped to production CDN)
+
+## Browser Compatibility
+
+- [ ] No Node.js-only APIs (`fs`, `path`, `child_process`, `net`, `crypto`)
+- [ ] All crypto uses `@frontmcp/utils` (wraps Web Crypto API)
+- [ ] All file operations removed or polyfilled
+- [ ] Fetch API used instead of Node http/https modules
+- [ ] Works in major browsers (Chrome, Firefox, Safari, Edge)
+
+## Security
+
+- [ ] No secrets bundled in the client-side code
+- [ ] API keys are NOT in the browser bundle (use server-side proxy)
+- [ ] CORS is configured on the server to accept browser origins
+- [ ] Content Security Policy (CSP) headers are compatible
+
+## Distribution
+
+- [ ] Package exports both ESM and CJS: `"module"` and `"main"` in package.json
+- [ ] `"browser"` field in package.json points to the browser build
+- [ ] TypeScript declarations (`.d.ts`) are included
+- [ ] CDN-friendly: works via `<script>` tag or `import` from CDN
+
+## Performance
+
+- [ ] Bundle is minified for production
+- [ ] Code splitting is used for large optional features
+- [ ] No synchronous operations that block the main thread
+- [ ] WebSocket/SSE connections handle reconnection gracefully
+
+## Examples
+
+| Example                                                                                  | Level        | Description                                                                                                                                                |
+| ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`browser-bundle-config`](../examples/production-browser/browser-bundle-config.md)       | Basic        | Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.       |
+| [`cross-platform-crypto`](../examples/production-browser/cross-platform-crypto.md)       | Intermediate | Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.         |
+| [`security-and-performance`](../examples/production-browser/security-and-performance.md) | Advanced     | Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread. |
+
+> See all examples in [`examples/production-browser/`](../examples/production-browser/)

package/catalog/frontmcp-production-readiness/references/production-cli-binary.md

@@ -0,0 +1,71 @@
+---
+name: production-cli-binary
+description: Checklist for publishing FrontMCP as a one-shot CLI binary with stdin/stdout transport
+---
+
+# Production Readiness: CLI Binary (One-Shot Execution)
+
+Checklist for publishing FrontMCP as a one-shot CLI binary — runs a command, processes input, exits. Not a long-running server.
+
+> Run the `common-checklist` first, then use this checklist for binary-specific items.
+
+## Build
+
+- [ ] `frontmcp build --target cli` produces a working binary
+- [ ] Binary starts and responds to `--help` within 500ms
+- [ ] `package.json` has correct `bin` field pointing to the built output
+- [ ] Shebang line is correct: `#!/usr/bin/env node`
+- [ ] Binary file has execute permissions (`chmod +x`)
+
+## Startup Performance
+
+- [ ] Cold start time is under 1 second
+- [ ] No heavy initialization at module scope (lazy-load dependencies)
+- [ ] No network calls during startup (model downloads, API fetches)
+- [ ] No async initialization that blocks first output
+
+## stdin/stdout Transport
+
+- [ ] MCP stdio transport works: reads JSON-RPC from stdin, writes to stdout
+- [ ] stderr is used for logging (not stdout — that's the MCP channel)
+- [ ] Handles EOF on stdin gracefully (clean exit)
+- [ ] Handles broken pipe on stdout gracefully (no crash)
+
+## Exit Behavior
+
+- [ ] Exit code 0 on success
+- [ ] Exit code 1 on user error (bad input, missing args)
+- [ ] Exit code 2 on internal error
+- [ ] No hanging — process exits promptly after work is done
+- [ ] All async operations complete before exit (no dangling promises)
+
+## npm Distribution
+
+- [ ] Package name is available on npm
+- [ ] `package.json` has `name`, `version`, `description`, `keywords`, `license`
+- [ ] `files` field includes only: `dist/`, `README.md`, `LICENSE`
+- [ ] `.npmignore` or `files` excludes: `src/`, `e2e/`, `.env`, `coverage/`
+- [ ] `README.md` has: `npm install -g <name>` and usage examples
+
+## Error Messages
+
+- [ ] User errors show helpful messages (not stack traces)
+- [ ] `--version` flag works correctly
+- [ ] Unknown flags produce a helpful error
+- [ ] Missing required arguments show usage hint
+
+## Security
+
+- [ ] No secrets bundled in the binary
+- [ ] No secrets logged to stderr
+- [ ] No hardcoded paths (use `os.homedir()`, `os.tmpdir()`)
+- [ ] No writes to unexpected locations
+
+## Examples
+
+| Example                                                                                                 | Level        | Description                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`binary-build-config`](../examples/production-cli-binary/binary-build-config.md)                       | Basic        | Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings. |
+| [`stdio-transport-error-handling`](../examples/production-cli-binary/stdio-transport-error-handling.md) | Intermediate | Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.          |
+
+> See all examples in [`examples/production-cli-binary/`](../examples/production-cli-binary/)

package/catalog/frontmcp-production-readiness/references/production-cli-daemon.md

@@ -0,0 +1,71 @@
+---
+name: production-cli-daemon
+description: Checklist for deploying FrontMCP as a long-running local daemon with socket transport
+---
+
+# Production Readiness: CLI Daemon (Local MCP Server)
+
+Checklist for deploying FrontMCP as a long-running local MCP server managed by the FrontMCP process manager (`frontmcp start/stop/restart`).
+
+> Run the `common-checklist` first, then use this checklist for daemon-specific items.
+
+## Process Management
+
+- [ ] Server starts via `frontmcp start <name> --entry ./src/main.ts`
+- [ ] `frontmcp stop <name>` cleanly shuts down the daemon
+- [ ] `frontmcp restart <name>` works without orphaned processes
+- [ ] `frontmcp status` shows the daemon as running
+- [ ] `frontmcp logs <name> --follow` streams daemon output
+
+## Socket / Transport
+
+- [ ] Unix socket path is configured: `http: { socketPath: '/tmp/my-app.sock' }`
+- [ ] Socket file is cleaned up on shutdown (no stale `.sock` files)
+- [ ] Stdio transport works as fallback: `frontmcp socket ./src/main.ts`
+- [ ] Socket permissions are restrictive (only the owning user can connect)
+
+## Service Registration
+
+- [ ] `frontmcp service install <name>` registers as a system service (launchd/systemd)
+- [ ] Service starts automatically on boot (if desired)
+- [ ] Service restarts on crash with backoff
+- [ ] Logs are captured by the system journal / log file
+
+## Storage
+
+- [ ] SQLite used for local persistence (session, cache)
+- [ ] Database file location is configurable (not hardcoded)
+- [ ] WAL mode enabled for concurrent reads
+- [ ] Automatic migration on startup (if schema changes)
+- [ ] Redis optional (only if shared state is needed between instances)
+
+## Graceful Shutdown
+
+- [ ] SIGTERM handler completes in-flight requests
+- [ ] Database connections are closed
+- [ ] Socket file is removed
+- [ ] PID file is cleaned up
+
+## Health & Monitoring
+
+- [ ] `/health` endpoint responds on the socket
+- [ ] Startup errors are logged clearly (not swallowed)
+- [ ] `frontmcp doctor` passes all checks
+- [ ] Memory usage is stable over time (no leaks)
+
+## Security
+
+- [ ] Socket file has restrictive permissions
+- [ ] No network exposure (socket-only, not TCP)
+- [ ] Secrets stored in config file with `600` permissions
+- [ ] Config stored in `~/.config/<app>/` or XDG directories
+
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`daemon-socket-config`](../examples/production-cli-daemon/daemon-socket-config.md)           | Basic        | Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.                                                   |
+| [`graceful-shutdown-cleanup`](../examples/production-cli-daemon/graceful-shutdown-cleanup.md) | Intermediate | Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file. |
+| [`security-and-permissions`](../examples/production-cli-daemon/security-and-permissions.md)   | Advanced     | Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.                                                       |
+
+> See all examples in [`examples/production-cli-daemon/`](../examples/production-cli-daemon/)

package/catalog/frontmcp-production-readiness/references/production-cloudflare.md

@@ -0,0 +1,62 @@
+---
+name: production-cloudflare
+description: Checklist for deploying FrontMCP to Cloudflare Workers with KV and Durable Objects
+---
+
+# Production Readiness: Cloudflare Workers
+
+Target-specific checklist for deploying FrontMCP to Cloudflare Workers.
+
+> Run the `common-checklist` first, then use this checklist for Cloudflare-specific items.
+
+## Wrangler Configuration
+
+- [ ] `wrangler.toml` is configured with correct routes and bindings
+- [ ] `frontmcp build --target cloudflare` produces the correct output
+- [ ] Environment variables are set via `wrangler secret put` or dashboard
+- [ ] Custom domain or `*.workers.dev` subdomain is configured for CORS
+
+## Workers Runtime
+
+- [ ] No Node.js-only APIs used (Workers use V8 isolates, not Node)
+- [ ] No `node:crypto` or `node:fs` — use `@frontmcp/utils` or Web APIs
+- [ ] Bundle size is within Workers limits (< 10MB compressed)
+- [ ] No `eval()` or dynamic `Function()` (prohibited in Workers)
+- [ ] Async I/O only — no synchronous blocking operations
+
+## Storage
+
+- [ ] Session storage uses Workers KV, Durable Objects, or D1
+- [ ] Cache uses Workers KV or Cache API
+- [ ] No file system access (Workers have no filesystem)
+- [ ] R2 is used for blob/file storage if needed
+
+## Performance
+
+- [ ] Cold start time is within Workers limits (< 50ms)
+- [ ] No heavy initialization at module scope
+- [ ] Lazy-load dependencies
+- [ ] Request handling completes within CPU time limits
+
+## Scaling
+
+- [ ] Stateless design (Workers are ephemeral)
+- [ ] Durable Objects used for stateful coordination (if needed)
+- [ ] No in-memory caching between requests (use KV instead)
+
+## CI/CD
+
+- [ ] `wrangler.toml` environment configs for staging/production
+- [ ] Secrets set via `wrangler secret put`
+- [ ] Deploy with `wrangler deploy` (not manual upload)
+- [ ] Tail logs: `wrangler tail` for production debugging
+
+## Examples
+
+| Example                                                                                           | Level        | Description                                                                                                                                               |
+| ------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`durable-objects-state`](../examples/production-cloudflare/durable-objects-state.md)             | Advanced     | Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage. |
+| [`workers-runtime-constraints`](../examples/production-cloudflare/workers-runtime-constraints.md) | Intermediate | Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.           |
+| [`wrangler-config`](../examples/production-cloudflare/wrangler-config.md)                         | Basic        | Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.      |
+
+> See all examples in [`examples/production-cloudflare/`](../examples/production-cloudflare/)