@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-production-readiness/examples/production-cloudflare/wrangler-config.md

@@ -0,0 +1,89 @@
+---
+name: wrangler-config
+reference: production-cloudflare
+level: basic
+description: 'Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.'
+tags: [production, cloudflare, cache, session, wrangler, config]
+features:
+  - 'Complete `wrangler.toml` with KV bindings for sessions and cache'
+  - 'Separate staging/production environment configs'
+  - 'Cloudflare Worker entry point via `createCloudflareHandler`'
+  - 'Secrets managed via `wrangler secret put` (not in config files)'
+---
+
+# Wrangler Configuration with KV Bindings
+
+Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.
+
+## Code
+
+```toml
+# wrangler.toml
+name = "my-mcp-worker"
+main = "dist/worker.js"
+compatibility_date = "2024-01-01"
+
+# Custom domain routing
+routes = [
+  { pattern = "mcp.example.com/*", zone_name = "example.com" }
+]
+
+# KV namespace for session storage
+[[kv_namespaces]]
+binding = "MCP_SESSIONS"
+id = "abc123def456"
+
+# KV namespace for cache
+[[kv_namespaces]]
+binding = "MCP_CACHE"
+id = "def456ghi789"
+
+# Environment-specific config
+[env.staging]
+name = "my-mcp-worker-staging"
+routes = [
+  { pattern = "mcp-staging.example.com/*", zone_name = "example.com" }
+]
+
+[env.production]
+name = "my-mcp-worker-production"
+routes = [
+  { pattern = "mcp.example.com/*", zone_name = "example.com" }
+]
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'cf-mcp', version: '1.0.0' },
+  apps: [MyApp],
+
+  // CORS: use the workers.dev or custom domain
+  cors: {
+    origin: ['https://app.example.com'],
+  },
+})
+export default class CloudflareMcpServer {}
+```
+
+```typescript
+// src/worker.ts — Cloudflare Worker entry point
+import { createCloudflareHandler } from '@frontmcp/adapters/cloudflare';
+import Server from './main';
+
+export default createCloudflareHandler(Server);
+```
+
+## What This Demonstrates
+
+- Complete `wrangler.toml` with KV bindings for sessions and cache
+- Separate staging/production environment configs
+- Cloudflare Worker entry point via `createCloudflareHandler`
+- Secrets managed via `wrangler secret put` (not in config files)
+
+## Related
+
+- See `production-cloudflare` for the full Cloudflare Workers checklist

package/catalog/frontmcp-production-readiness/examples/production-lambda/cold-start-connection-reuse.md

@@ -0,0 +1,122 @@
+---
+name: cold-start-connection-reuse
+reference: production-lambda
+level: intermediate
+description: 'Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.'
+tags: [production, lambda, performance, cold, start, connection]
+features:
+  - 'Connection reuse pattern: caching connections in module scope across warm invocations'
+  - 'Lazy-loading heavy dependencies (`pg`) via dynamic `import()` to reduce cold start'
+  - 'Not closing connections in `onDestroy()` for Lambda (they survive freeze/thaw)'
+  - 'Keeping module scope lightweight with no heavy initialization'
+---
+
+# Cold Start Optimization and Connection Reuse
+
+Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.
+
+## Code
+
+```typescript
+// src/providers/db-connection.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const DB_CLIENT = Symbol('DbClient');
+
+// Connection reuse pattern: connections survive between warm invocations
+// but must handle cold starts and reconnection gracefully
+let cachedConnection: unknown | undefined;
+
+@Provider({ token: DB_CLIENT, scope: ProviderScope.GLOBAL })
+export class DbConnectionProvider {
+  private connection: unknown;
+
+  async onInit(): Promise<void> {
+    // Reuse connection across warm invocations
+    if (cachedConnection) {
+      this.connection = cachedConnection;
+      return;
+    }
+
+    // Lazy-load the database driver — reduces cold start time
+    const { Client } = await import('pg');
+    this.connection = new Client({
+      host: process.env.DB_HOST,
+      connectionTimeoutMillis: 5000, // Don't hang on connection attempts
+    });
+    await (this.connection as { connect: () => Promise<void> }).connect();
+
+    // Cache for warm invocations
+    cachedConnection = this.connection;
+  }
+
+  getConnection() {
+    return this.connection;
+  }
+
+  // Note: Don't close in onDestroy for Lambda — connection survives freeze/thaw
+}
+```
+
+```typescript
+// src/tools/optimized-query.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { DB_CLIENT } from '../providers/db-connection.provider';
+
+@Tool({
+  name: 'query_data',
+  description: 'Query data with connection reuse',
+  inputSchema: {
+    id: z.string().min(1).describe('Record ID'),
+  },
+  outputSchema: {
+    id: z.string(),
+    data: z.string(),
+  },
+})
+export class OptimizedQueryTool extends ToolContext {
+  async execute(input: { id: string }) {
+    const db = this.get(DB_CLIENT);
+
+    // Parameterized query — prevents SQL injection
+    const result = await (db as { getConnection: () => { query: Function } })
+      .getConnection()
+      .query('SELECT * FROM records WHERE id = $1', [input.id]);
+
+    if (!result.rows[0]) {
+      this.fail(new Error(`Record not found: ${input.id}`));
+    }
+
+    return { id: input.id, data: JSON.stringify(result.rows[0]) };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+// Only import lightweight modules at the top level
+// Heavy imports happen lazily in providers
+import { MyApp } from './my.app';
+
+// No heavy initialization at module scope
+// No network calls, no database connections here
+
+@FrontMcp({
+  info: { name: 'fast-lambda', version: '1.0.0' },
+  apps: [MyApp],
+})
+export default class FastLambdaServer {}
+```
+
+## What This Demonstrates
+
+- Connection reuse pattern: caching connections in module scope across warm invocations
+- Lazy-loading heavy dependencies (`pg`) via dynamic `import()` to reduce cold start
+- Not closing connections in `onDestroy()` for Lambda (they survive freeze/thaw)
+- Keeping module scope lightweight with no heavy initialization
+
+## Related
+
+- See `production-lambda` for the full cold start and scaling checklist

package/catalog/frontmcp-production-readiness/examples/production-lambda/sam-template.md

@@ -0,0 +1,107 @@
+---
+name: sam-template
+reference: production-lambda
+level: basic
+description: 'Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration.'
+tags: [production, lambda, session, sam, template]
+features:
+  - 'Complete SAM template with API Gateway, Lambda function, and DynamoDB table'
+  - 'DynamoDB for session storage with TTL-based automatic cleanup'
+  - 'Lambda handler entry point via `createLambdaHandler`'
+  - 'Pay-per-request billing for cost-effective scaling'
+  - 'IAM policies scoped to the specific DynamoDB table'
+---
+
+# SAM Template with API Gateway and DynamoDB
+
+Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration.
+
+## Code
+
+```yaml
+# ci/template.yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: FrontMCP Lambda deployment
+
+Globals:
+  Function:
+    Runtime: nodejs20.x
+    Timeout: 30
+    MemorySize: 256
+    Environment:
+      Variables:
+        NODE_ENV: production
+        SESSION_TABLE: !Ref SessionTable
+
+Resources:
+  McpFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: dist/lambda.handler
+      CodeUri: .
+      Events:
+        McpApi:
+          Type: Api
+          Properties:
+            Path: /mcp/{proxy+}
+            Method: ANY
+      Policies:
+        - DynamoDBCrudPolicy:
+            TableName: !Ref SessionTable
+
+  SessionTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      TableName: mcp-sessions
+      BillingMode: PAY_PER_REQUEST
+      AttributeDefinitions:
+        - AttributeName: sessionId
+          AttributeType: S
+      KeySchema:
+        - AttributeName: sessionId
+          KeyType: HASH
+      TimeToLiveSpecification:
+        AttributeName: ttl
+        Enabled: true
+
+Outputs:
+  ApiEndpoint:
+    Description: API Gateway endpoint URL
+    Value: !Sub 'https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/mcp/'
+```
+
+```typescript
+// src/lambda.ts — Lambda handler entry point
+import { createLambdaHandler } from '@frontmcp/adapters/lambda';
+import Server from './main';
+
+export const handler = createLambdaHandler(Server);
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'lambda-mcp', version: '1.0.0' },
+  apps: [MyApp],
+  cors: {
+    origin: ['https://app.example.com'],
+  },
+})
+export default class LambdaMcpServer {}
+```
+
+## What This Demonstrates
+
+- Complete SAM template with API Gateway, Lambda function, and DynamoDB table
+- DynamoDB for session storage with TTL-based automatic cleanup
+- Lambda handler entry point via `createLambdaHandler`
+- Pay-per-request billing for cost-effective scaling
+- IAM policies scoped to the specific DynamoDB table
+
+## Related
+
+- See `production-lambda` for the full SAM/CloudFormation and Lambda runtime checklist

package/catalog/frontmcp-production-readiness/examples/production-lambda/scaling-and-monitoring.md

@@ -0,0 +1,138 @@
+---
+name: scaling-and-monitoring
+reference: production-lambda
+level: advanced
+description: 'Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.'
+tags: [production, lambda, performance, scaling, monitoring]
+features:
+  - 'Reserved concurrency to prevent downstream service overload'
+  - 'Provisioned concurrency for latency-sensitive endpoints (reduces cold starts)'
+  - 'Dead letter queue (DLQ) for capturing failed invocations'
+  - 'CloudWatch alarms for error rate and throttling detection'
+  - 'Loading secrets from AWS SSM Parameter Store instead of environment variables'
+---
+
+# Lambda Scaling, Concurrency Limits, and CloudWatch Monitoring
+
+Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.
+
+## Code
+
+```yaml
+# ci/template.yaml — scaling and monitoring additions
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+
+Resources:
+  McpFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: dist/lambda.handler
+      CodeUri: .
+      Runtime: nodejs20.x
+      Timeout: 30
+      MemorySize: 512
+      # Reserved concurrency prevents downstream overload
+      ReservedConcurrentExecutions: 100
+      # Provisioned concurrency for latency-sensitive endpoints
+      AutoPublishAlias: live
+      ProvisionedConcurrencyConfig:
+        ProvisionedConcurrentExecutions: 5
+      # Dead letter queue for failed invocations
+      DeadLetterQueue:
+        Type: SQS
+        TargetArn: !GetAtt DeadLetterQueue.Arn
+      Environment:
+        Variables:
+          NODE_ENV: production
+          SECRETS_PATH: /mcp/production/
+
+  DeadLetterQueue:
+    Type: AWS::SQS::Queue
+    Properties:
+      QueueName: mcp-dlq
+      MessageRetentionPeriod: 1209600 # 14 days
+
+  # CloudWatch alarm: error rate
+  ErrorAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: mcp-lambda-errors
+      MetricName: Errors
+      Namespace: AWS/Lambda
+      Statistic: Sum
+      Period: 300
+      EvaluationPeriods: 1
+      Threshold: 5
+      ComparisonOperator: GreaterThanThreshold
+      Dimensions:
+        - Name: FunctionName
+          Value: !Ref McpFunction
+
+  # CloudWatch alarm: throttling
+  ThrottleAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: mcp-lambda-throttles
+      MetricName: Throttles
+      Namespace: AWS/Lambda
+      Statistic: Sum
+      Period: 300
+      EvaluationPeriods: 1
+      Threshold: 1
+      ComparisonOperator: GreaterThanThreshold
+      Dimensions:
+        - Name: FunctionName
+          Value: !Ref McpFunction
+```
+
+```typescript
+// src/providers/secrets.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const SECRETS = Symbol('Secrets');
+
+@Provider({ token: SECRETS, scope: ProviderScope.GLOBAL })
+export class SecretsProvider {
+  private cache = new Map<string, string>();
+
+  async onInit(): Promise<void> {
+    // Load secrets from AWS SSM Parameter Store (not env vars for sensitive data)
+    const { SSMClient, GetParametersByPathCommand } = await import('@aws-sdk/client-ssm');
+    const ssm = new SSMClient({});
+    const path = process.env.SECRETS_PATH ?? '/mcp/production/';
+
+    const result = await ssm.send(
+      new GetParametersByPathCommand({
+        Path: path,
+        WithDecryption: true,
+      }),
+    );
+
+    for (const param of result.Parameters ?? []) {
+      const key = param.Name?.replace(path, '') ?? '';
+      this.cache.set(key, param.Value ?? '');
+    }
+  }
+
+  get(key: string): string {
+    const value = this.cache.get(key);
+    if (!value) {
+      throw new Error(`Secret not found: ${key}`);
+    }
+    return value;
+  }
+}
+```
+
+## What This Demonstrates
+
+- Reserved concurrency to prevent downstream service overload
+- Provisioned concurrency for latency-sensitive endpoints (reduces cold starts)
+- Dead letter queue (DLQ) for capturing failed invocations
+- CloudWatch alarms for error rate and throttling detection
+- Loading secrets from AWS SSM Parameter Store instead of environment variables
+
+## Related
+
+- See `production-lambda` for the full CI/CD and scaling checklist

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