@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-production-readiness/examples/production-node-sdk/package-json-config.md

@@ -0,0 +1,107 @@
+---
+name: package-json-config
+reference: production-node-sdk
+level: intermediate
+description: 'Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.'
+tags: [production, sdk, readme, node, package, json]
+features:
+  - 'Correct `main`, `module`, `types`, and `exports` fields for CJS + ESM'
+  - 'Using `files` to include only `dist/`, `README.md`, and `LICENSE` in the published package'
+  - 'Declaring `zod` as a `peerDependency` for shared packages'
+  - 'The `prepublishOnly` script ensuring build and tests pass before publishing'
+  - 'Integration test verifying the full lifecycle with proper cleanup'
+---
+
+# npm Package Configuration for SDK Publishing
+
+Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.
+
+## Code
+
+```jsonc
+// package.json
+{
+  "name": "my-mcp-sdk",
+  "version": "1.0.0",
+  "description": "MCP SDK for task management with type-safe tool invocations",
+  "keywords": ["mcp", "sdk", "task-management", "frontmcp"],
+  "license": "MIT",
+
+  // CJS + ESM entry points
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts",
+    },
+  },
+
+  // Only ship what consumers need
+  "files": ["dist/", "README.md", "LICENSE"],
+
+  // Required Node.js version
+  "engines": {
+    "node": ">=18.0.0",
+  },
+
+  // Shared dependencies as peerDependencies
+  "peerDependencies": {
+    "zod": "^4.0.0",
+  },
+
+  "dependencies": {
+    "@frontmcp/sdk": "^1.0.0",
+  },
+
+  "devDependencies": {
+    "@frontmcp/testing": "^1.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.4.0",
+    "zod": "^4.0.0",
+  },
+
+  "scripts": {
+    "build": "frontmcp build",
+    "test": "jest --coverage",
+    "prepublishOnly": "npm run build && npm test",
+  },
+}
+```
+
+```typescript
+// test/lifecycle.spec.ts — Integration test for the full lifecycle
+import { create } from '../src/index';
+
+describe('SDK lifecycle', () => {
+  it('should complete create -> connect -> callTool -> close -> dispose', async () => {
+    const server = await create();
+    const client = await server.connect();
+
+    const { tools } = await client.listTools();
+    expect(tools.length).toBeGreaterThan(0);
+
+    const result = await client.callTool('my_tool', { input: 'test' });
+    expect(result).toBeDefined();
+
+    // Always clean up — tests must not leak resources
+    await client.close();
+    await server.dispose();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Correct `main`, `module`, `types`, and `exports` fields for CJS + ESM
+- Using `files` to include only `dist/`, `README.md`, and `LICENSE` in the published package
+- Declaring `zod` as a `peerDependency` for shared packages
+- The `prepublishOnly` script ensuring build and tests pass before publishing
+- Integration test verifying the full lifecycle with proper cleanup
+
+## Related
+
+- See `production-node-sdk` for the full npm publishing and testing checklist

package/catalog/frontmcp-production-readiness/examples/production-node-server/docker-multi-stage.md

@@ -0,0 +1,103 @@
+---
+name: docker-multi-stage
+reference: production-node-server
+level: basic
+description: 'Shows a production-ready Dockerfile with multi-stage build, non-root user, and container health check for a FrontMCP Node.js server.'
+tags: [production, dockerfile, docker, security, node, multi]
+features:
+  - 'Multi-stage Docker build separating build dependencies from runtime'
+  - 'Using `node:24-slim` as a minimal base image'
+  - 'Running as non-root user (`USER node`) for security'
+  - 'Container health check for orchestrator-aware restarts'
+  - 'Resource limits (memory, CPU) in docker-compose'
+---
+
+# Multi-Stage Dockerfile with Health Check
+
+Shows a production-ready Dockerfile with multi-stage build, non-root user, and container health check for a FrontMCP Node.js server.
+
+## Code
+
+```dockerfile
+# Dockerfile
+# Stage 1: Build
+FROM node:24-slim AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY tsconfig.json ./
+COPY src ./src
+RUN npx frontmcp build
+
+# Stage 2: Runtime (minimal image)
+FROM node:24-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile --production && yarn cache clean
+COPY --from=builder /app/dist ./dist
+
+# Non-root user for security
+USER node
+
+# Health check for container orchestration
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:3000/health', (res) => process.exit(res.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"
+
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+```
+
+```text
+# .dockerignore
+node_modules
+.git
+.env
+.env.*
+dist
+coverage
+*.md
+.cache
+```
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  mcp-server:
+    build: .
+    ports:
+      - '3000:3000'
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - REDIS_HOST=redis
+    depends_on:
+      - redis
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '1.0'
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis-data:/data
+
+volumes:
+  redis-data:
+```
+
+## What This Demonstrates
+
+- Multi-stage Docker build separating build dependencies from runtime
+- Using `node:24-slim` as a minimal base image
+- Running as non-root user (`USER node`) for security
+- Container health check for orchestrator-aware restarts
+- Resource limits (memory, CPU) in docker-compose
+
+## Related
+
+- See `production-node-server` for the full Node.js/Docker checklist

package/catalog/frontmcp-production-readiness/examples/production-node-server/graceful-shutdown.md

@@ -0,0 +1,87 @@
+---
+name: graceful-shutdown
+reference: production-node-server
+level: intermediate
+description: 'Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.'
+tags: [production, redis, database, node, graceful, shutdown]
+features:
+  - 'Handling SIGTERM for graceful shutdown in containerized environments'
+  - 'Draining in-flight requests before exiting with a timeout safety net'
+  - 'Disposing all resources (Redis, database) via `server.dispose()`'
+  - 'Returning unhealthy during shutdown so load balancers redirect traffic'
+---
+
+# Graceful Shutdown with SIGTERM Handling
+
+Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'resilient-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: 6379,
+  },
+})
+export default class ResilientServer {}
+```
+
+```typescript
+// src/lifecycle/shutdown.ts
+// Graceful shutdown handler — wire this in your entry point
+
+let isShuttingDown = false;
+
+export function setupGracefulShutdown(server: { close: () => Promise<void>; dispose: () => Promise<void> }): void {
+  const shutdown = async (signal: string) => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+
+    console.log(`Received ${signal}. Starting graceful shutdown...`);
+
+    // 1. Stop accepting new connections
+    await server.close();
+    console.log('Server closed — no new connections accepted.');
+
+    // 2. Wait for in-flight requests to complete (with timeout)
+    const drainTimeout = setTimeout(() => {
+      console.error('Drain timeout reached. Forcing exit.');
+      process.exit(1);
+    }, 30_000); // 30 second drain period
+
+    // 3. Dispose all resources (Redis, DB connections, providers)
+    await server.dispose();
+    clearTimeout(drainTimeout);
+    console.log('All resources disposed. Exiting.');
+
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+
+export function isHealthy(): boolean {
+  // Return unhealthy during shutdown drain so load balancers stop sending traffic
+  return !isShuttingDown;
+}
+```
+
+## What This Demonstrates
+
+- Handling SIGTERM for graceful shutdown in containerized environments
+- Draining in-flight requests before exiting with a timeout safety net
+- Disposing all resources (Redis, database) via `server.dispose()`
+- Returning unhealthy during shutdown so load balancers redirect traffic
+
+## Related
+
+- See `production-node-server` for the full process management and scaling checklist

package/catalog/frontmcp-production-readiness/examples/production-node-server/redis-session-scaling.md

@@ -0,0 +1,97 @@
+---
+name: redis-session-scaling
+reference: production-node-server
+level: advanced
+description: 'Shows how to configure Redis-backed session storage, connection pooling, and stateless server design for horizontal scaling behind a load balancer.'
+tags: [production, redis, session, node, scaling]
+features:
+  - 'Configuring Redis for session storage so all instances share state'
+  - 'Using key prefixes to namespace Redis keys and avoid collisions'
+  - 'Setting session TTL to prevent unbounded storage growth'
+  - 'Configuring Redis-backed job store for multi-instance job processing'
+  - 'Validating required environment variables at startup (fail fast)'
+---
+
+# Redis Session Storage for Multi-Instance Scaling
+
+Shows how to configure Redis-backed session storage, connection pooling, and stateless server design for horizontal scaling behind a load balancer.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'scalable-server', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Redis for all shared state — sessions, cache, jobs
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: Number(process.env.REDIS_PORT ?? 6379),
+    password: process.env.REDIS_PASSWORD,
+    keyPrefix: 'mcp:', // Namespace keys to avoid collisions
+  },
+
+  // Session configuration
+  session: {
+    ttl: 3600_000, // 1 hour session TTL
+  },
+
+  // Jobs use Redis store for multi-instance consistency
+  jobs: {
+    enabled: true,
+    store: {
+      redis: {
+        provider: 'redis',
+        host: process.env.REDIS_HOST ?? 'localhost',
+        port: Number(process.env.REDIS_PORT ?? 6379),
+      },
+    },
+    retry: {
+      maxAttempts: 3,
+      maxBackoffMs: 30_000,
+    },
+  },
+})
+export default class ScalableServer {}
+```
+
+```typescript
+// src/providers/env-validation.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const ENV_VALIDATOR = Symbol('EnvValidator');
+
+@Provider({ token: ENV_VALIDATOR, scope: ProviderScope.GLOBAL })
+export class EnvValidationProvider {
+  async onInit(): Promise<void> {
+    // Fail fast on missing config — don't discover in production at runtime
+    const required = ['REDIS_HOST', 'NODE_ENV'];
+    const missing = required.filter((key) => !process.env[key]);
+
+    if (missing.length > 0) {
+      throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+    }
+
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn('WARNING: NODE_ENV is not set to "production"');
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- Configuring Redis for session storage so all instances share state
+- Using key prefixes to namespace Redis keys and avoid collisions
+- Setting session TTL to prevent unbounded storage growth
+- Configuring Redis-backed job store for multi-instance job processing
+- Validating required environment variables at startup (fail fast)
+
+## Related
+
+- See `production-node-server` for the full storage and scaling checklist

package/catalog/frontmcp-production-readiness/examples/production-vercel/cold-start-optimization.md

@@ -0,0 +1,104 @@
+---
+name: cold-start-optimization
+reference: production-vercel
+level: intermediate
+description: 'Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.'
+tags: [production, vercel, openapi, performance, cold, start]
+features:
+  - 'Lazy-loading heavy dependencies via dynamic `import()` in `onInit()` instead of module scope'
+  - 'Caching expensive fetches (e.g., OpenAPI specs) across warm invocations'
+  - 'Keeping the module scope lightweight with no side effects'
+  - 'No `top-level await`, no global state, no network calls at import time'
+---
+
+# Cold Start Optimization for Serverless
+
+Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.
+
+## Code
+
+```typescript
+// src/providers/lazy-api-client.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const API_CLIENT = Symbol('ApiClient');
+
+@Provider({ token: API_CLIENT, scope: ProviderScope.GLOBAL })
+export class LazyApiClientProvider {
+  // Lazy-loaded — not imported at module scope
+  private client: unknown;
+
+  async onInit(): Promise<void> {
+    // Lazy-load heavy dependencies to reduce cold start time
+    // The import only happens when the provider is first used
+    const { HeavySDK } = await import('heavy-third-party-sdk');
+    this.client = new HeavySDK({
+      apiKey: process.env.API_KEY,
+    });
+  }
+
+  getClient() {
+    return this.client;
+  }
+}
+```
+
+```typescript
+// src/tools/cached-lookup.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Cache OpenAPI spec in module scope — survives warm invocations
+let cachedSpec: unknown | undefined;
+
+@Tool({
+  name: 'lookup',
+  description: 'Look up data using a cached API spec',
+  inputSchema: {
+    query: z.string().min(1).describe('Lookup query'),
+  },
+  outputSchema: {
+    result: z.string(),
+  },
+})
+export class CachedLookupTool extends ToolContext {
+  async execute(input: { query: string }) {
+    // Cache the spec — not fetched on every invocation
+    if (!cachedSpec) {
+      const response = await this.fetch('https://api.example.com/openapi.json');
+      cachedSpec = await response.json();
+    }
+
+    // Use cached spec for the lookup
+    return { result: `Found: ${input.query}` };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+// Only import lightweight modules at the top level
+import { MyApp } from './my.app';
+
+// No heavy initialization here — this runs on every cold start
+// No top-level await, no global state, no network calls
+
+@FrontMcp({
+  info: { name: 'fast-start', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { provider: 'vercel-kv' },
+})
+export default class FastStartServer {}
+```
+
+## What This Demonstrates
+
+- Lazy-loading heavy dependencies via dynamic `import()` in `onInit()` instead of module scope
+- Caching expensive fetches (e.g., OpenAPI specs) across warm invocations
+- Keeping the module scope lightweight with no side effects
+- No `top-level await`, no global state, no network calls at import time
+
+## Related
+
+- See `production-vercel` for the full cold start and edge runtime checklist

package/catalog/frontmcp-production-readiness/examples/production-vercel/stateless-serverless-design.md

@@ -0,0 +1,91 @@
+---
+name: stateless-serverless-design
+reference: production-vercel
+level: advanced
+description: 'Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto.'
+tags: [production, vercel, serverless, node, stateless, design]
+features:
+  - 'Using `@frontmcp/utils` (`sha256Hex`, `randomUUID`) instead of `node:crypto` for edge compatibility'
+  - 'Fully stateless design with no in-memory state between invocations'
+  - 'Using `this.fetch()` instead of Node.js `http`/`https` modules'
+  - 'No file system access (serverless is ephemeral)'
+---
+
+# Stateless Serverless Design with Edge Compatibility
+
+Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto.
+
+## Code
+
+```typescript
+// src/tools/edge-safe-tool.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+// Use @frontmcp/utils for cross-platform crypto — not node:crypto
+import { sha256Hex, randomUUID } from '@frontmcp/utils';
+
+@Tool({
+  name: 'process_request',
+  description: 'Process a request in an edge-safe, stateless manner',
+  inputSchema: {
+    data: z.string().min(1).describe('Request data'),
+  },
+  outputSchema: {
+    requestId: z.string(),
+    hash: z.string(),
+    processed: z.boolean(),
+  },
+})
+export class ProcessRequestTool extends ToolContext {
+  async execute(input: { data: string }) {
+    // Cross-platform crypto — works on edge runtime
+    const requestId = randomUUID();
+    const hash = sha256Hex(input.data);
+
+    // No file system access — serverless is ephemeral
+    // No in-memory state — each invocation is independent
+    // Use this.fetch() for external calls (not node http/https)
+    const response = await this.fetch('https://api.example.com/process', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ requestId, hash, data: input.data }),
+    });
+
+    const result = await response.json();
+    return { requestId, hash, processed: result.ok };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { EdgeApp } from './edge.app';
+
+@FrontMcp({
+  info: { name: 'edge-server', version: '1.0.0' },
+  apps: [EdgeApp],
+
+  // Vercel KV for all shared state
+  redis: { provider: 'vercel-kv' },
+
+  // CORS restricted to production domain
+  cors: {
+    origin: ['https://app.example.com'],
+  },
+
+  // Stateless: no file system, no SQLite, no in-memory sessions
+})
+export default class EdgeServer {}
+```
+
+## What This Demonstrates
+
+- Using `@frontmcp/utils` (`sha256Hex`, `randomUUID`) instead of `node:crypto` for edge compatibility
+- Fully stateless design with no in-memory state between invocations
+- Using `this.fetch()` instead of Node.js `http`/`https` modules
+- No file system access (serverless is ephemeral)
+
+## Related
+
+- See `production-vercel` for the full edge runtime and scaling checklist

package/catalog/frontmcp-production-readiness/examples/production-vercel/vercel-edge-config.md

@@ -0,0 +1,78 @@
+---
+name: vercel-edge-config
+reference: production-vercel
+level: basic
+description: 'Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.'
+tags: [production, vercel-kv, vercel, session, serverless, edge]
+features:
+  - 'Correct `vercel.json` with function routes, memory limits, and max duration'
+  - "Using Vercel KV (`provider: 'vercel-kv'`) for session storage instead of in-memory"
+  - 'Setting CORS origins dynamically using `VERCEL_URL`'
+  - 'Serverless function entry point via `createVercelHandler`'
+---
+
+# Vercel Configuration with Edge-Compatible Storage
+
+Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.
+
+## Code
+
+```jsonc
+// vercel.json
+{
+  "version": 2,
+  "builds": [{ "src": "api/**/*.ts", "use": "@vercel/node" }],
+  "routes": [{ "src": "/mcp/(.*)", "dest": "/api/mcp" }],
+  "functions": {
+    "api/mcp.ts": {
+      "memory": 256,
+      "maxDuration": 30,
+    },
+  },
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'vercel-mcp', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Vercel KV for session storage (not in-memory, not Redis directly)
+  redis: {
+    provider: 'vercel-kv', // Uses Vercel KV (Redis-compatible, managed)
+  },
+
+  // CORS: use VERCEL_URL or custom domain
+  cors: {
+    origin: [
+      process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : 'http://localhost:3000',
+      'https://app.example.com',
+    ],
+  },
+})
+export default class VercelMcpServer {}
+```
+
+```typescript
+// api/mcp.ts — Vercel serverless function entry point
+import Server from '../src/main';
+
+// Export the server class directly — FrontMCP handles
+// the Vercel serverless function lifecycle automatically.
+export default Server;
+```
+
+## What This Demonstrates
+
+- Correct `vercel.json` with function routes, memory limits, and max duration
+- Using Vercel KV (`provider: 'vercel-kv'`) for session storage instead of in-memory
+- Setting CORS origins dynamically using `VERCEL_URL`
+- Serverless function entry point via `createVercelHandler`
+
+## Related
+
+- See `production-vercel` for the full Vercel deployment checklist