@frontmcp/skills 0.0.1

package/catalog/deployment/deploy-to-lambda/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: deploy-to-lambda
+description: Deploy a FrontMCP server to AWS Lambda with API Gateway. Use when deploying to AWS, setting up SAM or CDK, or configuring Lambda handlers.
+tags:
+  - deployment
+  - lambda
+  - aws
+  - serverless
+parameters:
+  - name: runtime
+    description: AWS Lambda runtime version
+    type: string
+    required: false
+    default: nodejs22.x
+  - name: memory
+    description: Lambda function memory in MB
+    type: number
+    required: false
+    default: 512
+  - name: timeout
+    description: Lambda function timeout in seconds
+    type: number
+    required: false
+    default: 30
+  - name: region
+    description: AWS region for deployment
+    type: string
+    required: false
+    default: us-east-1
+examples:
+  - scenario: Deploy with SAM
+    parameters:
+      memory: 512
+      timeout: 30
+      region: us-east-1
+    expected-outcome: A FrontMCP server deployed as an AWS Lambda function behind API Gateway, managed by SAM.
+  - scenario: Deploy with CDK
+    parameters:
+      memory: 1024
+      timeout: 60
+      region: eu-west-1
+    expected-outcome: A FrontMCP server deployed via AWS CDK with API Gateway and Lambda.
+compatibility: AWS CLI and SAM CLI required
+license: Apache-2.0
+visibility: both
+priority: 10
+metadata:
+  category: deployment
+  difficulty: advanced
+  platform: aws
+  docs: https://docs.agentfront.dev/frontmcp/deployment/serverless
+---
+
+# Deploy a FrontMCP Server to AWS Lambda
+
+This skill walks you through deploying a FrontMCP server to AWS Lambda with API Gateway using SAM or CDK.
+
+## Prerequisites
+
+- AWS account with appropriate IAM permissions
+- AWS CLI configured: `aws configure`
+- SAM CLI installed: `brew install aws-sam-cli` (macOS) or see AWS docs
+- Node.js 22 or later
+- A FrontMCP project ready to build
+
+## Step 1: Build for Lambda
+
+```bash
+frontmcp build --target lambda
+```
+
+This produces a Lambda-compatible output with a single handler file optimized for cold-start performance, minimized bundle size with tree-shaking, and a `template.yaml` scaffold for SAM.
+
+## Step 2: SAM Template
+
+Create `template.yaml` in your project root:
+
+```yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: FrontMCP server on AWS Lambda
+
+Globals:
+  Function:
+    Timeout: 30
+    Runtime: nodejs22.x
+    MemorySize: 512
+    Environment:
+      Variables:
+        NODE_ENV: production
+        LOG_LEVEL: info
+
+Resources:
+  FrontMcpFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: dist/lambda.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
+      Environment:
+        Variables:
+          REDIS_URL: !If
+            - HasRedis
+            - !Ref RedisUrl
+            - ''
+      Policies:
+        - AWSLambdaBasicExecutionRole
+
+  FrontMcpLogGroup:
+    Type: AWS::Logs::LogGroup
+    Properties:
+      LogGroupName: !Sub /aws/lambda/${FrontMcpFunction}
+      RetentionInDays: 14
+
+Conditions:
+  HasRedis: !Not [!Equals [!Ref RedisUrl, '']]
+
+Parameters:
+  RedisUrl:
+    Type: String
+    Default: ''
+    Description: Redis connection URL for session storage
+
+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
+```
+
+## Step 3: API Gateway
+
+SAM automatically creates an HTTP API (API Gateway v2) from the `Events` block. The `/{proxy+}` route catches all paths and forwards them to FrontMCP's internal router.
+
+For more control, define the API explicitly:
+
+```yaml
+Resources:
+  FrontMcpApi:
+    Type: AWS::Serverless::HttpApi
+    Properties:
+      StageName: prod
+      CorsConfiguration:
+        AllowOrigins:
+          - 'https://your-domain.com'
+        AllowMethods:
+          - GET
+          - POST
+          - OPTIONS
+        AllowHeaders:
+          - Content-Type
+          - Authorization
+```
+
+## Step 4: Handler Configuration
+
+FrontMCP generates a Lambda handler at `dist/lambda.handler` during the build step. To customize the handler, create a `lambda.ts` entry point:
+
+```typescript
+import { createLambdaHandler } from '@frontmcp/adapters/lambda';
+import { AppModule } from './app.module';
+
+export const handler = createLambdaHandler(AppModule, {
+  streaming: false,
+});
+```
+
+## Step 5: Environment Variables
+
+Configure environment variables in the SAM template or set them after deployment:
+
+```bash
+aws lambda update-function-configuration \
+  --function-name FrontMcpFunction \
+  --environment "Variables={NODE_ENV=production,LOG_LEVEL=info,REDIS_URL=redis://your-redis:6379}"
+```
+
+| Variable               | Description                         | Required          |
+| ---------------------- | ----------------------------------- | ----------------- |
+| `NODE_ENV`             | Runtime environment                 | Yes               |
+| `REDIS_URL`            | Redis/ElastiCache connection string | If using sessions |
+| `LOG_LEVEL`            | Logging verbosity                   | No                |
+| `FRONTMCP_AUTH_SECRET` | Secret for signing auth tokens      | If using auth     |
+
+For sensitive values, use AWS Systems Manager Parameter Store or Secrets Manager:
+
+```yaml
+Environment:
+  Variables:
+    FRONTMCP_AUTH_SECRET: !Sub '{{resolve:ssm:/frontmcp/auth-secret}}'
+```
+
+## Step 6: Deploy
+
+### First Deployment (Guided)
+
+```bash
+sam build
+sam deploy --guided
+```
+
+The guided deployment prompts for stack name, region, and parameter overrides. Answers are saved in `samconfig.toml` for subsequent deploys.
+
+### Subsequent Deployments
+
+```bash
+sam build && sam deploy
+```
+
+### CDK Alternative
+
+If you prefer AWS CDK over SAM:
+
+```typescript
+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';
+
+const fn = new lambda.Function(this, 'FrontMcpHandler', {
+  runtime: lambda.Runtime.NODEJS_22_X,
+  handler: 'dist/lambda.handler',
+  code: lambda.Code.fromAsset('.'),
+  memorySize: 512,
+  timeout: cdk.Duration.seconds(30),
+  architecture: lambda.Architecture.ARM_64,
+  environment: {
+    NODE_ENV: 'production',
+    LOG_LEVEL: 'info',
+  },
+});
+
+const api = new apigw.HttpApi(this, 'FrontMcpApi', {
+  defaultIntegration: new integrations.HttpLambdaIntegration('LambdaIntegration', fn),
+});
+```
+
+Deploy with:
+
+```bash
+cdk deploy
+```
+
+## Step 7: Verify
+
+```bash
+# Get the endpoint from stack outputs
+aws cloudformation describe-stacks \
+  --stack-name frontmcp-prod \
+  --query "Stacks[0].Outputs[?OutputKey=='ApiEndpoint'].OutputValue" \
+  --output text
+
+# Health check
+curl https://abc123.execute-api.us-east-1.amazonaws.com/health
+```
+
+## Cold Start Mitigation
+
+Lambda cold starts occur when a new execution environment is initialized. Strategies to reduce their impact:
+
+1. **Provisioned Concurrency** -- pre-warms execution environments (incurs cost when idle):
+
+   ```yaml
+   FrontMcpFunction:
+     Properties:
+       ProvisionedConcurrencyConfig:
+         ProvisionedConcurrentExecutions: 5
+   ```
+
+2. **Small bundles** -- the `frontmcp build --target lambda` output is already optimized, but audit your dependencies.
+
+3. **ARM64 runtime** -- ARM functions initialize faster than x86. The template uses `arm64` by default.
+
+4. **Higher memory** -- CPU scales proportionally with memory. 512 MB or 1024 MB is a good starting point.
+
+### Typical Cold Start Times
+
+| Memory  | Cold Start (ARM64) | Cold Start (x86) |
+| ------- | ------------------ | ---------------- |
+| 256 MB  | ~800ms             | ~1000ms          |
+| 512 MB  | ~500ms             | ~700ms           |
+| 1024 MB | ~350ms             | ~500ms           |
+
+## Troubleshooting
+
+- **Timeout errors**: Increase `Timeout` in the SAM template. Check if the function is waiting on an unreachable resource.
+- **502 Bad Gateway**: Check CloudWatch logs. Common causes: handler path mismatch, missing environment variables, unhandled exceptions.
+- **Cold starts too slow**: Increase memory allocation, use ARM64, or enable provisioned concurrency.
+- **Redis from Lambda**: Place the Lambda function in the same VPC as your ElastiCache cluster with appropriate security groups.

package/catalog/deployment/deploy-to-node/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: deploy-to-node
+description: Deploy a FrontMCP server as a standalone Node.js application with Docker. Use when deploying to a VPS, Docker, or bare metal server.
+tags:
+  - deployment
+  - node
+  - docker
+  - production
+parameters:
+  - name: port
+    description: The port number the server will listen on
+    type: number
+    required: false
+    default: 3000
+examples:
+  - scenario: Deploy with Docker Compose
+    parameters:
+      port: 3000
+    expected-outcome: A FrontMCP server running inside a Docker container orchestrated by Docker Compose, with Redis for session storage and automatic restarts on failure.
+  - scenario: Deploy to bare metal with PM2
+    parameters:
+      port: 8080
+    expected-outcome: A FrontMCP server running directly on the host machine under PM2, listening on port 8080 with NGINX as a reverse proxy.
+compatibility: Node.js 22+, Docker recommended
+license: Apache-2.0
+visibility: both
+priority: 10
+metadata:
+  category: deployment
+  difficulty: intermediate
+  docs: https://docs.agentfront.dev/frontmcp/deployment/production-build
+---
+
+# Deploy a FrontMCP Server to Node.js
+
+This skill walks you through deploying a FrontMCP server as a standalone Node.js application, optionally containerized with Docker for production use.
+
+## Prerequisites
+
+- Node.js 22 or later
+- Docker and Docker Compose (recommended for production)
+- A FrontMCP project ready to build
+
+## Step 1: Build the Server
+
+```bash
+frontmcp build --target node
+```
+
+This compiles your TypeScript source, bundles dependencies, and produces a production-ready output in `dist/`. The build output includes compiled JavaScript optimized for Node.js, a `package.json` with production dependencies only, and any static assets.
+
+## Step 2: Dockerfile (Multi-Stage)
+
+Create a multi-stage `Dockerfile` in your project root:
+
+```dockerfile
+# Stage 1: Build
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN npx frontmcp build --target node
+
+# Stage 2: Production
+FROM node:22-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+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"]
+```
+
+The first stage installs all dependencies and builds the project. The second stage copies only the compiled output and production dependencies into a slim image.
+
+## Step 3: Docker Compose with Redis
+
+Create a `docker-compose.yml` for a complete deployment with Redis:
+
+```yaml
+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:
+```
+
+Deploy with:
+
+```bash
+docker compose up -d
+```
+
+## Step 4: Environment Variables
+
+Create a `.env` file or set variables in your deployment environment:
+
+```bash
+# Server
+PORT=3000
+NODE_ENV=production
+HOST=0.0.0.0
+
+# Redis (required for session storage in production)
+REDIS_URL=redis://localhost:6379
+
+# Logging
+LOG_LEVEL=info
+```
+
+| Variable    | Description                         | Default       |
+| ----------- | ----------------------------------- | ------------- |
+| `PORT`      | HTTP port for the server            | `3000`        |
+| `NODE_ENV`  | Runtime environment                 | `development` |
+| `REDIS_URL` | Redis connection string for storage | (none)        |
+| `HOST`      | Network interface to bind           | `0.0.0.0`     |
+| `LOG_LEVEL` | Logging verbosity                   | `info`        |
+
+## Step 5: Health Checks
+
+FrontMCP servers expose a `/health` endpoint by default:
+
+```bash
+curl http://localhost:3000/health
+# Response: { "status": "ok", "uptime": 12345 }
+```
+
+For Docker, the `HEALTHCHECK` directive in the Dockerfile and the `healthcheck` block in Compose handle this automatically. Point your load balancer or orchestrator at this endpoint for liveness checks.
+
+## Step 6: PM2 for Bare Metal
+
+When running without Docker, use PM2 as a process manager:
+
+```bash
+# Install PM2 globally
+npm install -g pm2
+
+# Start the server 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
+```
+
+The `-i max` flag runs one instance per CPU core for optimal throughput.
+
+## Step 7: NGINX Reverse Proxy
+
+Place NGINX in front of the server for TLS termination:
+
+```nginx
+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;
+    }
+}
+```
+
+## Resource Limits
+
+Set appropriate limits in Docker Compose for production:
+
+```yaml
+services:
+  frontmcp:
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '1.0'
+        reservations:
+          memory: 256M
+          cpus: '0.5'
+```
+
+## Troubleshooting
+
+- **Port already in use**: Change the `PORT` environment variable or stop the conflicting process.
+- **Redis connection refused**: Verify Redis is running and `REDIS_URL` is correct. In Docker Compose, use the service name (`redis`) as the hostname.
+- **Health check failing**: Increase `start_period` in the health check configuration to give the server more startup time.
+- **Out of memory**: Increase the memory limit in Docker or use `NODE_OPTIONS="--max-old-space-size=1024" node dist/main.js`.

package/catalog/deployment/deploy-to-node/references/Dockerfile.example

@@ -0,0 +1,45 @@
+# ---- Build Stage ----
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Install dependencies first for better layer caching
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+
+# Copy source and build
+COPY . .
+RUN yarn frontmcp build --target node
+
+# ---- Production Stage ----
+FROM node:22-alpine AS production
+
+WORKDIR /app
+
+# Create non-root user for security
+RUN addgroup -S frontmcp && adduser -S frontmcp -G frontmcp
+
+# Copy only production artifacts
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/yarn.lock ./
+
+# Install production dependencies only
+RUN yarn install --frozen-lockfile --production && \
+    yarn cache clean
+
+# Set ownership
+RUN chown -R frontmcp:frontmcp /app
+
+USER frontmcp
+
+# Environment defaults
+ENV NODE_ENV=production
+ENV PORT=3000
+
+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"]