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

package/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/basic-worker-deploy.md

@@ -0,0 +1,82 @@
+---
+name: basic-worker-deploy
+reference: deploy-to-cloudflare
+level: basic
+description: 'Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.'
+tags: [deployment, cloudflare, transport, local, worker]
+features:
+  - 'A minimal FrontMCP server configured for Cloudflare Workers with SSE transport'
+  - 'The `wrangler.toml` configuration with `main` pointing to the build output'
+  - 'Using `wrangler dev` for local testing before deploying with `wrangler deploy`'
+---
+
+# Basic Cloudflare Workers Deployment
+
+Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'echo',
+  description: 'Echo back the input',
+  inputSchema: { message: z.string() },
+})
+class EchoTool extends ToolContext<{ message: string }> {
+  async execute(input: { message: string }) {
+    return { content: [{ type: 'text' as const, text: input.message }] };
+  }
+}
+
+@App({ name: 'MyApp', tools: [EchoTool] })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-worker', version: '1.0.0' },
+  apps: [MyApp],
+  transport: {
+    protocol: 'legacy',
+  },
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+```toml
+# wrangler.toml
+name = "frontmcp-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[vars]
+NODE_ENV = "production"
+```
+
+```bash
+# Build for Cloudflare Workers
+frontmcp build --target cloudflare
+
+# Preview locally
+wrangler dev
+
+# Deploy to production
+wrangler deploy
+
+# Verify
+curl https://frontmcp-worker.your-subdomain.workers.dev/health
+```
+
+## What This Demonstrates
+
+- A minimal FrontMCP server configured for Cloudflare Workers with SSE transport
+- The `wrangler.toml` configuration with `main` pointing to the build output
+- Using `wrangler dev` for local testing before deploying with `wrangler deploy`
+
+## Related
+
+- See `deploy-to-cloudflare` for KV storage, D1, bundle size limits, and troubleshooting

package/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-custom-domain.md

@@ -0,0 +1,97 @@
+---
+name: worker-custom-domain
+reference: deploy-to-cloudflare
+level: advanced
+description: 'Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment.'
+tags: [deployment, json-rpc, cloudflare, worker, custom, domain]
+features:
+  - 'Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts'
+  - 'Adding a custom domain with `wrangler domains add` for production-ready URLs'
+  - 'End-to-end verification of both the health check and MCP JSON-RPC endpoint'
+---
+
+# Cloudflare Worker with Custom Domain and Project Scaffold
+
+Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment.
+
+## Code
+
+```bash
+# Scaffold a new project targeting Cloudflare
+npx frontmcp create my-app --target cloudflare
+cd my-app
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'translate',
+  description: 'Translate text',
+  inputSchema: { text: z.string(), lang: z.string() },
+})
+class TranslateTool extends ToolContext<{ text: string; lang: string }> {
+  async execute(input: { text: string; lang: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `[${input.lang}] ${input.text}` }],
+    };
+  }
+}
+
+@App({ name: 'TranslateApp', tools: [TranslateTool] })
+class TranslateApp {}
+
+@FrontMcp({
+  info: { name: 'translate-worker', version: '1.0.0' },
+  apps: [TranslateApp],
+  transport: {
+    type: 'sse',
+  },
+})
+class TranslateServer {}
+
+export default TranslateServer;
+```
+
+```toml
+# wrangler.toml
+name = "translate-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[[kv_namespaces]]
+binding = "FRONTMCP_KV"
+id = "your-kv-namespace-id"
+
+[vars]
+NODE_ENV = "production"
+```
+
+```bash
+# Build and deploy
+frontmcp build --target cloudflare
+wrangler deploy
+
+# Add a custom domain
+wrangler domains add mcp.example.com
+
+# Verify health endpoint
+curl https://mcp.example.com/health
+
+# Test MCP endpoint
+curl -X POST https://mcp.example.com/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+## What This Demonstrates
+
+- Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts
+- Adding a custom domain with `wrangler domains add` for production-ready URLs
+- End-to-end verification of both the health check and MCP JSON-RPC endpoint
+
+## Related
+
+- See `deploy-to-cloudflare` for bundle size limits, CPU time constraints, and the full storage options table

package/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-with-kv-storage.md

@@ -0,0 +1,92 @@
+---
+name: worker-with-kv-storage
+reference: deploy-to-cloudflare
+level: intermediate
+description: 'Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.'
+tags: [deployment, cloudflare, cli, session, worker, kv]
+features:
+  - 'Binding a KV namespace in `wrangler.toml` with `[[kv_namespaces]]`'
+  - 'Using `wrangler secret put` for sensitive values instead of `[vars]` (which are visible in plaintext)'
+  - 'Creating the KV namespace via CLI and copying the ID into the configuration'
+---
+
+# Cloudflare Worker with KV Storage
+
+Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'store_value',
+  description: 'Store a value by key',
+  inputSchema: { key: z.string(), value: z.string() },
+})
+class StoreValueTool extends ToolContext<{ key: string; value: string }> {
+  async execute(input: { key: string; value: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `Stored: ${input.key}` }],
+    };
+  }
+}
+
+@App({ name: 'StorageApp', tools: [StoreValueTool] })
+class StorageApp {}
+
+@FrontMcp({
+  info: { name: 'my-worker', version: '1.0.0' },
+  apps: [StorageApp],
+  transport: {
+    type: 'sse',
+  },
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+```toml
+# wrangler.toml
+name = "frontmcp-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[[kv_namespaces]]
+binding = "FRONTMCP_KV"
+id = "your-kv-namespace-id"
+
+[vars]
+NODE_ENV = "production"
+```
+
+```bash
+# Create the KV namespace
+wrangler kv:namespace create FRONTMCP_KV
+# Copy the returned id into wrangler.toml
+
+# Store secrets securely (not in [vars])
+wrangler secret put MY_API_KEY
+
+# Build and deploy
+frontmcp build --target cloudflare
+wrangler deploy
+
+# Verify
+curl -X POST https://frontmcp-worker.your-subdomain.workers.dev/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+## What This Demonstrates
+
+- Binding a KV namespace in `wrangler.toml` with `[[kv_namespaces]]`
+- Using `wrangler secret put` for sensitive values instead of `[vars]` (which are visible in plaintext)
+- Creating the KV namespace via CLI and copying the ID into the configuration
+
+## Related
+
+- See `deploy-to-cloudflare` for D1, Durable Objects, bundle size limits, and storage comparison table

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