@frontmcp/skills 1.0.0-beta.13 → 1.0.0-beta.14

package/catalog/frontmcp-production-readiness/examples/production-node-sdk/basic-sdk-lifecycle.md

@@ -0,0 +1,85 @@
+---
+name: basic-sdk-lifecycle
+reference: production-node-sdk
+level: basic
+description: 'Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.'
+tags: [production, sdk, node, lifecycle]
+features:
+  - 'Exporting a `create()` function as the public API surface'
+  - 'No port binding in SDK mode (embedded, not standalone server)'
+  - 'The full lifecycle: `create()` -> `connect()` -> `callTool()` -> `close()` -> `dispose()`'
+  - 'Proper cleanup to prevent memory and connection leaks'
+---
+
+# Basic SDK Lifecycle: Create, Connect, Use, Dispose
+
+Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'my-mcp-package', version: '1.0.0' },
+  apps: [MyApp],
+  // SDK mode: no port binding, no HTTP server
+})
+export default class MyMcpServer {}
+```
+
+```typescript
+// src/index.ts — Public API surface
+// Export a clean create() function for consumers
+import MyMcpServer from './main';
+
+export async function create() {
+  // create() does not bind a port — SDK mode, not server mode
+  const server = await MyMcpServer.create();
+  return server;
+}
+
+export type { MyMcpServer };
+```
+
+```typescript
+// examples/usage.ts — How consumers use the SDK
+import { create } from 'my-mcp-package';
+
+async function main() {
+  // 1. Create the server (no port binding)
+  const server = await create();
+
+  // 2. Connect to get a typed client
+  const client = await server.connect();
+
+  // 3. Use the client
+  const tools = await client.listTools();
+  console.log(
+    'Available tools:',
+    tools.map((t) => t.name),
+  );
+
+  const result = await client.callTool('my_tool', { input: 'value' });
+  console.log('Result:', result);
+
+  // 4. Always clean up — prevents leaks
+  await client.close();
+  await server.dispose();
+}
+
+main().catch(console.error);
+```
+
+## What This Demonstrates
+
+- Exporting a `create()` function as the public API surface
+- No port binding in SDK mode (embedded, not standalone server)
+- The full lifecycle: `create()` -> `connect()` -> `callTool()` -> `close()` -> `dispose()`
+- Proper cleanup to prevent memory and connection leaks
+
+## Related
+
+- See `production-node-sdk` for the full SDK publishing checklist

package/catalog/frontmcp-production-readiness/examples/production-node-sdk/multi-instance-cleanup.md

@@ -0,0 +1,110 @@
+---
+name: multi-instance-cleanup
+reference: production-node-sdk
+level: advanced
+description: 'Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources.'
+tags: [production, sdk, node, multi, instance, cleanup]
+features:
+  - 'Implementing `onDestroy()` in providers to clean up timers and listeners'
+  - 'Ensuring multiple instances coexist without sharing global state'
+  - 'Testing that dispose removes all event listeners (no leaks)'
+  - 'Verifying one instance still works after another is disposed'
+---
+
+# Multi-Instance Coexistence and Cleanup
+
+Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources.
+
+## Code
+
+```typescript
+// src/providers/polling.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const POLLER = Symbol('Poller');
+
+@Provider({ token: POLLER, scope: ProviderScope.GLOBAL })
+export class PollingProvider {
+  private intervalId: ReturnType<typeof setInterval> | undefined;
+  private listeners: Array<() => void> = [];
+
+  async onInit(): Promise<void> {
+    // Start a polling interval
+    this.intervalId = setInterval(() => {
+      this.listeners.forEach((fn) => fn());
+    }, 10_000);
+  }
+
+  addListener(fn: () => void): void {
+    this.listeners.push(fn);
+  }
+
+  async onDestroy(): Promise<void> {
+    // Clean up timer — prevents dangling intervals after dispose
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+    }
+    // Remove all listener references — prevents memory leaks
+    this.listeners.length = 0;
+  }
+}
+```
+
+```typescript
+// test/multi-instance.spec.ts
+import { create } from '../src/index';
+
+describe('Multi-instance coexistence', () => {
+  it('should run two instances side by side without conflicts', async () => {
+    // Create two independent instances
+    const server1 = await create();
+    const server2 = await create();
+
+    const client1 = await server1.connect();
+    const client2 = await server2.connect();
+
+    // Both should work independently
+    const tools1 = await client1.listTools();
+    const tools2 = await client2.listTools();
+
+    expect(tools1.tools.length).toBeGreaterThan(0);
+    expect(tools2.tools.length).toBeGreaterThan(0);
+
+    // Clean up both — no shared global state
+    await client1.close();
+    await server1.dispose();
+
+    // Instance 2 still works after instance 1 is disposed
+    const result = await client2.callTool('my_tool', { input: 'still-alive' });
+    expect(result).toBeDefined();
+
+    await client2.close();
+    await server2.dispose();
+  });
+
+  it('should not leak event listeners after dispose', async () => {
+    const initialListeners = process.listenerCount('SIGTERM');
+
+    const server = await create();
+    const client = await server.connect();
+
+    await client.close();
+    await server.dispose();
+
+    // No dangling SIGTERM listeners after dispose
+    expect(process.listenerCount('SIGTERM')).toBe(initialListeners);
+  });
+});
+```
+
+## What This Demonstrates
+
+- Implementing `onDestroy()` in providers to clean up timers and listeners
+- Ensuring multiple instances coexist without sharing global state
+- Testing that dispose removes all event listeners (no leaks)
+- Verifying one instance still works after another is disposed
+
+## Related
+
+- See `production-node-sdk` for the full memory and cleanup checklist

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