@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-deployment/examples/deploy-to-lambda/cdk-deployment.md

@@ -0,0 +1,92 @@
+---
+name: cdk-deployment
+reference: deploy-to-lambda
+level: advanced
+description: 'Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management.'
+tags: [deployment, lambda, performance, cdk]
+features:
+  - 'Using AWS CDK instead of SAM for infrastructure-as-code deployment'
+  - 'Provisioned concurrency via a Lambda alias to eliminate cold starts on critical endpoints'
+  - 'Referencing secrets from SSM Parameter Store with `{{resolve:ssm:...}}` instead of hardcoding'
+---
+
+# CDK Deployment with Provisioned Concurrency
+
+Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management.
+
+## Code
+
+```typescript
+// lib/frontmcp-stack.ts
+import * as cdk from 'aws-cdk-lib';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as apigw from 'aws-cdk-lib/aws-apigatewayv2';
+import * as integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import { Construct } from 'constructs';
+
+export class FrontMcpStack extends cdk.Stack {
+  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    const fn = new lambda.Function(this, 'FrontMcpHandler', {
+      runtime: lambda.Runtime.NODEJS_24_X,
+      handler: 'handler.handler',
+      code: lambda.Code.fromAsset('.'),
+      memorySize: 512,
+      timeout: cdk.Duration.seconds(30),
+      architecture: lambda.Architecture.ARM_64,
+      environment: {
+        NODE_ENV: 'production',
+        LOG_LEVEL: 'info',
+        // Use SSM for secrets instead of plaintext
+        FRONTMCP_AUTH_SECRET: cdk.Fn.sub('{{resolve:ssm-secure:/frontmcp/auth-secret}}'),
+      },
+    });
+
+    // Provisioned concurrency for predictable latency
+    const alias = new lambda.Alias(this, 'ProdAlias', {
+      aliasName: 'prod',
+      version: fn.currentVersion,
+      provisionedConcurrentExecutions: 5,
+    });
+
+    const api = new apigw.HttpApi(this, 'FrontMcpApi', {
+      defaultIntegration: new integrations.HttpLambdaIntegration(
+        'LambdaIntegration',
+        alias, // Route traffic to the alias with provisioned concurrency
+      ),
+    });
+
+    new cdk.CfnOutput(this, 'ApiEndpoint', {
+      value: api.apiEndpoint,
+    });
+  }
+}
+```
+
+```bash
+# Build the FrontMCP server
+frontmcp build --target lambda
+
+# Store secrets in SSM Parameter Store
+aws ssm put-parameter \
+  --name "/frontmcp/auth-secret" \
+  --type "SecureString" \
+  --value "your-secret-value"
+
+# Deploy with CDK
+cdk deploy
+
+# Verify
+curl https://abc123.execute-api.us-east-1.amazonaws.com/health
+```
+
+## What This Demonstrates
+
+- Using AWS CDK instead of SAM for infrastructure-as-code deployment
+- Provisioned concurrency via a Lambda alias to eliminate cold starts on critical endpoints
+- Referencing secrets from SSM Parameter Store with `{{resolve:ssm:...}}` instead of hardcoding
+
+## Related
+
+- See `deploy-to-lambda` for the SAM alternative, cold start benchmarks, and VPC configuration for ElastiCache

package/catalog/frontmcp-deployment/examples/deploy-to-lambda/lambda-handler-with-cors.md

@@ -0,0 +1,113 @@
+---
+name: lambda-handler-with-cors
+reference: deploy-to-lambda
+level: intermediate
+description: 'Create a custom Lambda handler with an explicit API Gateway definition for CORS support.'
+tags: [deployment, lambda, handler, cors]
+features:
+  - 'Creating a custom Lambda handler with `createLambdaHandler()` from `@frontmcp/adapters/lambda`'
+  - 'Defining an explicit HTTP API resource with CORS configuration for cross-origin requests'
+  - 'Linking the function events to the explicit API via `ApiId: !Ref`'
+---
+
+# Lambda Handler with CORS and API Gateway
+
+Create a custom Lambda handler with an explicit API Gateway definition for CORS support.
+
+## Code
+
+```typescript
+// src/lambda.ts
+import { createLambdaHandler } from '@frontmcp/adapters/lambda';
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'analyze',
+  description: 'Analyze text content',
+  inputSchema: { text: z.string() },
+})
+class AnalyzeTool extends ToolContext<{ text: string }> {
+  async execute(input: { text: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `Analysis of: ${input.text}` }],
+    };
+  }
+}
+
+@App({ name: 'AnalyzerApp', tools: [AnalyzeTool] })
+class AnalyzerApp {}
+
+@FrontMcp({
+  info: { name: 'analyzer', version: '1.0.0' },
+  apps: [AnalyzerApp],
+})
+class AnalyzerServer {}
+
+export const handler = createLambdaHandler(AnalyzerServer, {
+  streaming: false,
+});
+```
+
+```yaml
+# template.yaml - with explicit API Gateway and CORS
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: FrontMCP server with CORS
+
+Globals:
+  Function:
+    Timeout: 30
+    Runtime: nodejs24.x
+    MemorySize: 512
+
+Resources:
+  FrontMcpApi:
+    Type: AWS::Serverless::HttpApi
+    Properties:
+      StageName: prod
+      CorsConfiguration:
+        AllowOrigins:
+          - 'https://your-domain.com'
+        AllowMethods:
+          - GET
+          - POST
+          - OPTIONS
+        AllowHeaders:
+          - Content-Type
+          - Authorization
+
+  FrontMcpFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: handler.handler
+      CodeUri: .
+      Architectures:
+        - arm64
+      Environment:
+        Variables:
+          NODE_ENV: production
+      Events:
+        McpApi:
+          Type: HttpApi
+          Properties:
+            ApiId: !Ref FrontMcpApi
+            Path: /{proxy+}
+            Method: ANY
+```
+
+```bash
+# Build and deploy
+frontmcp build --target lambda
+sam build && sam deploy
+```
+
+## What This Demonstrates
+
+- Creating a custom Lambda handler with `createLambdaHandler()` from `@frontmcp/adapters/lambda`
+- Defining an explicit HTTP API resource with CORS configuration for cross-origin requests
+- Linking the function events to the explicit API via `ApiId: !Ref`
+
+## Related
+
+- See `deploy-to-lambda` for secrets management, provisioned concurrency, and CDK deployment

package/catalog/frontmcp-deployment/examples/deploy-to-lambda/sam-template-basic.md

@@ -0,0 +1,100 @@
+---
+name: sam-template-basic
+reference: deploy-to-lambda
+level: basic
+description: 'Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.'
+tags: [deployment, lambda, performance, sam, template]
+features:
+  - 'A minimal SAM template with ARM64 architecture for faster cold starts and lower cost'
+  - "The `/{proxy+}` catch-all route that forwards all requests to FrontMCP's internal router"
+  - 'CloudWatch log group with 14-day retention'
+---
+
+# Basic SAM Template for Lambda
+
+Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.
+
+## Code
+
+```yaml
+# template.yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: FrontMCP server on AWS Lambda
+
+Globals:
+  Function:
+    Timeout: 30
+    Runtime: nodejs24.x
+    MemorySize: 512
+    Environment:
+      Variables:
+        NODE_ENV: production
+        LOG_LEVEL: info
+
+Resources:
+  FrontMcpFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: handler.handler
+      CodeUri: .
+      Description: FrontMCP MCP server
+      Architectures:
+        - arm64
+      Events:
+        McpApi:
+          Type: HttpApi
+          Properties:
+            Path: /{proxy+}
+            Method: ANY
+        HealthCheck:
+          Type: HttpApi
+          Properties:
+            Path: /health
+            Method: GET
+
+  FrontMcpLogGroup:
+    Type: AWS::Logs::LogGroup
+    Properties:
+      LogGroupName: !Sub /aws/lambda/${FrontMcpFunction}
+      RetentionInDays: 14
+
+Outputs:
+  ApiEndpoint:
+    Description: API Gateway endpoint URL
+    Value: !Sub 'https://${ServerlessHttpApi}.execute-api.${AWS::Region}.amazonaws.com'
+  FunctionArn:
+    Description: Lambda function ARN
+    Value: !GetAtt FrontMcpFunction.Arn
+```
+
+```bash
+# Build for Lambda
+frontmcp build --target lambda
+
+# Deploy with guided prompts (first time)
+sam build
+sam deploy --guided
+
+# Subsequent deploys
+sam build && sam deploy
+
+# Get the endpoint URL
+aws cloudformation describe-stacks \
+  --stack-name frontmcp-prod \
+  --query "Stacks[0].Outputs[?OutputKey=='ApiEndpoint'].OutputValue" \
+  --output text
+
+# Verify
+curl https://abc123.execute-api.us-east-1.amazonaws.com/health
+```
+
+## What This Demonstrates
+
+- A minimal SAM template with ARM64 architecture for faster cold starts and lower cost
+- The `/{proxy+}` catch-all route that forwards all requests to FrontMCP's internal router
+- CloudWatch log group with 14-day retention
+
+## Related
+
+- See `deploy-to-lambda` for Redis/ElastiCache integration, CDK alternative, and provisioned concurrency

package/catalog/frontmcp-deployment/examples/deploy-to-node/docker-compose-with-redis.md

@@ -0,0 +1,101 @@
+---
+name: docker-compose-with-redis
+reference: deploy-to-node
+level: basic
+description: 'Deploy a FrontMCP server with Redis using Docker Compose for production.'
+tags: [deployment, docker-compose, redis, dockerfile, docker, session]
+features:
+  - 'Multi-stage Dockerfile that keeps the production image small and secure'
+  - 'Docker Compose configuration with Redis for session storage'
+  - 'Health checks on both the FrontMCP server and Redis, with `depends_on` ensuring Redis starts first'
+---
+
+# Docker Compose with Redis
+
+Deploy a FrontMCP server with Redis using Docker Compose for production.
+
+## Code
+
+```yaml
+# docker-compose.yml
+version: '3.9'
+
+services:
+  frontmcp:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - '${PORT:-3000}:3000'
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - REDIS_URL=redis://redis:6379
+      - LOG_LEVEL=info
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test: ['CMD', 'wget', '-qO-', 'http://localhost:3000/health']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 10s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  redis-data:
+```
+
+```dockerfile
+# Dockerfile
+FROM node:24-alpine AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN npx frontmcp build --target node
+
+FROM node:24-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/yarn.lock ./
+RUN yarn install --frozen-lockfile --production && yarn cache clean
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
+  CMD wget -qO- http://localhost:3000/health || exit 1
+CMD ["node", "dist/main.js"]
+```
+
+```bash
+# Build and start
+docker compose up -d
+
+# Verify
+docker compose ps
+curl http://localhost:3000/health
+# {"status":"ok","uptime":12345}
+```
+
+## What This Demonstrates
+
+- Multi-stage Dockerfile that keeps the production image small and secure
+- Docker Compose configuration with Redis for session storage
+- Health checks on both the FrontMCP server and Redis, with `depends_on` ensuring Redis starts first
+
+## Related
+
+- See `deploy-to-node` for PM2 process management, NGINX reverse proxy, and environment variable configuration

package/catalog/frontmcp-deployment/examples/deploy-to-node/pm2-with-nginx.md

@@ -0,0 +1,79 @@
+---
+name: pm2-with-nginx
+reference: deploy-to-node
+level: intermediate
+description: 'Deploy a FrontMCP server on bare metal using PM2 for process management and NGINX for TLS termination.'
+tags: [deployment, nx, node, pm2, nginx]
+features:
+  - 'Using PM2 with `-i max` for multi-core clustering and automatic restarts'
+  - 'Configuring NGINX as a reverse proxy for TLS termination in front of the FrontMCP server'
+  - 'Setting environment variables via `.env` for production configuration'
+---
+
+# PM2 Process Manager with NGINX Reverse Proxy
+
+Deploy a FrontMCP server on bare metal using PM2 for process management and NGINX for TLS termination.
+
+## Code
+
+```bash
+# Build the server
+frontmcp build --target node
+
+# Install PM2 globally
+npm install -g pm2
+
+# Start with cluster mode (one instance per CPU core)
+pm2 start dist/main.js --name frontmcp-server -i max
+
+# Save the process list for auto-restart on reboot
+pm2 save
+pm2 startup
+```
+
+```nginx
+# /etc/nginx/sites-available/mcp.example.com
+server {
+    listen 443 ssl;
+    server_name mcp.example.com;
+
+    ssl_certificate     /etc/ssl/certs/mcp.example.com.pem;
+    ssl_certificate_key /etc/ssl/private/mcp.example.com.key;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+```bash
+# .env
+PORT=3000
+NODE_ENV=production
+HOST=0.0.0.0
+REDIS_URL=redis://localhost:6379
+LOG_LEVEL=info
+```
+
+```bash
+# Enable the NGINX site and reload
+sudo ln -s /etc/nginx/sites-available/mcp.example.com /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+
+# Verify
+curl https://mcp.example.com/health
+```
+
+## What This Demonstrates
+
+- Using PM2 with `-i max` for multi-core clustering and automatic restarts
+- Configuring NGINX as a reverse proxy for TLS termination in front of the FrontMCP server
+- Setting environment variables via `.env` for production configuration
+
+## Related
+
+- See `deploy-to-node` for Docker Compose deployment, resource limits, and the full environment variable reference

package/catalog/frontmcp-deployment/examples/deploy-to-node/resource-limits.md

@@ -0,0 +1,92 @@
+---
+name: resource-limits
+reference: deploy-to-node
+level: advanced
+description: 'Configure resource limits, health checks, and environment variables for a production FrontMCP deployment.'
+tags: [deployment, docker-compose, docker, node, resource, limits]
+features:
+  - 'Setting CPU and memory limits/reservations in Docker Compose to prevent OOM kills'
+  - 'Using `NODE_OPTIONS=--max-old-space-size` to align the V8 heap limit with the container memory'
+  - 'Configuring health checks with appropriate `start_period` to allow the server time to initialize'
+---
+
+# Production Resource Limits and Health Checks
+
+Configure resource limits, health checks, and environment variables for a production FrontMCP deployment.
+
+## Code
+
+```yaml
+# docker-compose.yml with resource limits
+version: '3.9'
+
+services:
+  frontmcp:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - '${PORT:-3000}:3000'
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - REDIS_URL=redis://redis:6379
+      - LOG_LEVEL=info
+      - NODE_OPTIONS=--max-old-space-size=384
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '1.0'
+        reservations:
+          memory: 256M
+          cpus: '0.5'
+    healthcheck:
+      test: ['CMD', 'wget', '-qO-', 'http://localhost:3000/health']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis-data:/data
+    deploy:
+      resources:
+        limits:
+          memory: 128M
+          cpus: '0.5'
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 10s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  redis-data:
+```
+
+```bash
+# Verify health check endpoint
+curl http://localhost:3000/health
+# {"status":"ok","uptime":12345}
+
+# Monitor resource usage
+docker stats --no-stream
+```
+
+## What This Demonstrates
+
+- Setting CPU and memory limits/reservations in Docker Compose to prevent OOM kills
+- Using `NODE_OPTIONS=--max-old-space-size` to align the V8 heap limit with the container memory
+- Configuring health checks with appropriate `start_period` to allow the server time to initialize
+
+## Related
+
+- See `deploy-to-node` for the full deployment guide including Dockerfile, PM2, and NGINX setup

package/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/basic-multistage-dockerfile.md

@@ -0,0 +1,63 @@
+---
+name: basic-multistage-dockerfile
+reference: deploy-to-node-dockerfile
+level: basic
+description: 'A minimal multi-stage Dockerfile for building and running a FrontMCP server in production.'
+tags: [deployment, dockerfile, docker, node, multistage]
+features:
+  - 'Two-stage build: the first stage installs all dependencies and builds; the second copies only production artifacts'
+  - 'Using `yarn install --production` in the production stage to exclude dev dependencies'
+  - 'A health check that verifies the server is responding'
+---
+
+# Basic Multi-Stage Dockerfile
+
+A minimal multi-stage Dockerfile for building and running a FrontMCP server in production.
+
+## Code
+
+```dockerfile
+# Dockerfile
+
+# ---- Build Stage ----
+FROM node:24-alpine AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN yarn frontmcp build --target node
+
+# ---- Production Stage ----
+FROM node:24-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+ENV PORT=3000
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/yarn.lock ./
+RUN yarn install --frozen-lockfile --production && \
+    yarn cache clean
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+CMD ["node", "dist/main.js"]
+```
+
+```bash
+# Build and run the container
+docker build -t my-frontmcp-server .
+docker run -p 3000:3000 -e NODE_ENV=production my-frontmcp-server
+
+# Verify
+curl http://localhost:3000/health
+```
+
+## What This Demonstrates
+
+- Two-stage build: the first stage installs all dependencies and builds; the second copies only production artifacts
+- Using `yarn install --production` in the production stage to exclude dev dependencies
+- A health check that verifies the server is responding
+
+## Related
+
+- See `deploy-to-node-dockerfile` for the complete reference Dockerfile with security hardening