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

package/catalog/frontmcp-production-readiness/examples/production-cloudflare/durable-objects-state.md

@@ -0,0 +1,124 @@
+---
+name: durable-objects-state
+reference: production-cloudflare
+level: advanced
+description: 'Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage.'
+tags: [production, cloudflare, cache, throttle, durable, objects]
+features:
+  - 'Using Durable Objects for stateful coordination (rate limiting) in an ephemeral Workers runtime'
+  - 'Using R2 for blob/file storage since Workers have no filesystem'
+  - 'Combining KV (cache), R2 (files), and Durable Objects (state) in one deployment'
+  - 'Wrangler configuration with all three binding types'
+---
+
+# Stateful Coordination with Durable Objects
+
+Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage.
+
+## Code
+
+```toml
+# wrangler.toml — with Durable Objects and R2
+name = "stateful-mcp-worker"
+main = "dist/worker.js"
+compatibility_date = "2024-01-01"
+
+# KV for cache
+[[kv_namespaces]]
+binding = "CACHE"
+id = "cache-namespace-id"
+
+# R2 for blob/file storage
+[[r2_buckets]]
+binding = "FILES"
+bucket_name = "mcp-files"
+
+# Durable Objects for stateful coordination
+[durable_objects]
+bindings = [
+  { name = "RATE_LIMITER", class_name = "RateLimiterDO" }
+]
+
+[[migrations]]
+tag = "v1"
+new_classes = ["RateLimiterDO"]
+```
+
+```typescript
+// src/tools/rate-limited-action.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'rate_limited_action',
+  description: 'An action that uses Durable Objects for distributed rate limiting',
+  inputSchema: {
+    userId: z.string().min(1).describe('User identifier'),
+    action: z.string().min(1).describe('Action to perform'),
+  },
+  outputSchema: {
+    allowed: z.boolean(),
+    remaining: z.number(),
+    action: z.string(),
+  },
+})
+export class RateLimitedActionTool extends ToolContext {
+  async execute(input: { userId: string; action: string }) {
+    // Durable Objects provide stateful rate limiting across Workers instances
+    // Each user gets their own Durable Object instance for consistent state
+    const result = await this.fetch(`https://internal/rate-check/${input.userId}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: input.action }),
+    });
+
+    const { allowed, remaining } = await result.json();
+
+    if (!allowed) {
+      this.fail(new Error(`Rate limit exceeded for user ${input.userId}`));
+    }
+
+    return { allowed, remaining, action: input.action };
+  }
+}
+```
+
+```typescript
+// src/tools/file-upload.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'upload_file',
+  description: 'Upload a file to R2 object storage',
+  inputSchema: {
+    filename: z.string().min(1).describe('File name'),
+    content: z.string().min(1).describe('File content (base64 encoded)'),
+  },
+  outputSchema: {
+    key: z.string(),
+    url: z.string(),
+    size: z.number(),
+  },
+})
+export class FileUploadTool extends ToolContext {
+  async execute(input: { filename: string; content: string }) {
+    // R2 for blob/file storage — no filesystem in Workers
+    const key = `uploads/${Date.now()}-${input.filename}`;
+    const size = input.content.length;
+
+    return { key, url: `https://files.example.com/${key}`, size };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using Durable Objects for stateful coordination (rate limiting) in an ephemeral Workers runtime
+- Using R2 for blob/file storage since Workers have no filesystem
+- Combining KV (cache), R2 (files), and Durable Objects (state) in one deployment
+- Wrangler configuration with all three binding types
+
+## Related
+
+- See `production-cloudflare` for the full storage and scaling checklist

package/catalog/frontmcp-production-readiness/examples/production-cloudflare/workers-runtime-constraints.md

@@ -0,0 +1,103 @@
+---
+name: workers-runtime-constraints
+reference: production-cloudflare
+level: intermediate
+description: '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.'
+tags: [production, cloudflare, node, workers, runtime, constraints]
+features:
+  - 'Using `@frontmcp/utils` for crypto instead of `node:crypto` (Workers use V8 isolates, not Node)'
+  - 'All I/O is async (no synchronous blocking operations allowed in Workers)'
+  - 'No `eval()` or dynamic `Function()` (prohibited in Workers)'
+  - 'No filesystem access (Workers have no filesystem)'
+  - 'Using Fetch API via `this.fetch()` instead of Node.js `http`/`https`'
+---
+
+# Workers Runtime Constraints and Compatibility
+
+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.
+
+## Code
+
+```typescript
+// src/tools/worker-safe.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+// Use @frontmcp/utils — wraps Web Crypto API, works in Workers
+import { sha256Hex, randomUUID, base64urlEncode } from '@frontmcp/utils';
+
+@Tool({
+  name: 'transform_data',
+  description: 'Transform and hash data in a Workers-compatible way',
+  inputSchema: {
+    payload: z.string().min(1).describe('Data to transform'),
+  },
+  outputSchema: {
+    id: z.string(),
+    hash: z.string(),
+    encoded: z.string(),
+    timestamp: z.string(),
+  },
+})
+export class TransformDataTool extends ToolContext {
+  async execute(input: { payload: string }) {
+    // All operations are async — no synchronous blocking
+
+    // Cross-platform crypto (Web Crypto under the hood)
+    const id = randomUUID();
+    const hash = sha256Hex(input.payload);
+    const encoded = base64urlEncode(input.payload);
+
+    // Use this.fetch() — standard Fetch API, not node http
+    const response = await this.fetch('https://api.example.com/transform', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id, payload: input.payload }),
+    });
+
+    if (!response.ok) {
+      this.fail(new Error(`Transform API error: ${response.status}`));
+    }
+
+    return {
+      id,
+      hash,
+      encoded,
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+```
+
+```typescript
+// src/providers/kv-store.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const KV_STORE = Symbol('KvStore');
+
+// Workers KV — no filesystem, no eval, no dynamic Function()
+@Provider({ token: KV_STORE, scope: ProviderScope.GLOBAL })
+export class KvStoreProvider {
+  // Workers KV is bound via wrangler.toml, accessed from env
+  async get(key: string): Promise<string | null> {
+    // In Workers, KV is available via the environment binding
+    // This is a pattern — actual binding depends on your worker setup
+    return null;
+  }
+
+  async put(key: string, value: string, ttlSeconds?: number): Promise<void> {
+    // KV put with optional TTL
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `@frontmcp/utils` for crypto instead of `node:crypto` (Workers use V8 isolates, not Node)
+- All I/O is async (no synchronous blocking operations allowed in Workers)
+- No `eval()` or dynamic `Function()` (prohibited in Workers)
+- No filesystem access (Workers have no filesystem)
+- Using Fetch API via `this.fetch()` instead of Node.js `http`/`https`
+
+## Related
+
+- See `production-cloudflare` for the full Workers runtime and performance checklist

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