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

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

package/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/secure-nonroot-dockerfile.md

@@ -0,0 +1,89 @@
+---
+name: secure-nonroot-dockerfile
+reference: deploy-to-node-dockerfile
+level: advanced
+description: 'A production Dockerfile with a non-root user, proper ownership, and security hardening.'
+tags: [deployment, dockerfile, docker, security, node, secure]
+features:
+  - 'Creating a dedicated non-root user (`frontmcp`) and switching to it with `USER`'
+  - 'Setting file ownership before switching users so the process can read its own files'
+  - 'Combining the Dockerfile with runtime resource limits (`--memory`, `--cpus`)'
+---
+
+# Secure Non-Root Dockerfile
+
+A production Dockerfile with a non-root user, proper ownership, and security hardening.
+
+## 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
+
+# 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 to non-root user
+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"]
+```
+
+```bash
+# Build
+docker build -t my-frontmcp-server:secure .
+
+# Run with resource limits
+docker run -p 3000:3000 \
+  --memory=512m \
+  --cpus=1.0 \
+  -e NODE_ENV=production \
+  -e REDIS_URL=redis://redis:6379 \
+  my-frontmcp-server:secure
+
+# Verify the process runs as non-root
+docker exec $(docker ps -q -f ancestor=my-frontmcp-server:secure) whoami
+# frontmcp
+```
+
+## What This Demonstrates
+
+- Creating a dedicated non-root user (`frontmcp`) and switching to it with `USER`
+- Setting file ownership before switching users so the process can read its own files
+- Combining the Dockerfile with runtime resource limits (`--memory`, `--cpus`)
+
+## Related
+
+- See `deploy-to-node-dockerfile` for the complete reference Dockerfile
+- See `deploy-to-node` for Docker Compose, PM2, and NGINX deployment patterns

package/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-mcp-endpoint-test.md

@@ -0,0 +1,69 @@
+---
+name: vercel-mcp-endpoint-test
+reference: deploy-to-vercel
+level: advanced
+description: 'Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation.'
+tags: [deployment, json-rpc, vercel, mcp, endpoint]
+features:
+  - 'Testing the health endpoint and MCP JSON-RPC API of a deployed Vercel function'
+  - 'Using preview deployments to validate changes before promoting to production'
+  - 'Setting `maxDuration` according to your Vercel plan (Hobby: 10s, Pro: 60s, Enterprise: 900s)'
+---
+
+# Testing a Vercel MCP Endpoint
+
+Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation.
+
+## Code
+
+```bash
+# Health check
+curl https://your-project.vercel.app/health
+# {"status":"ok"}
+
+# List tools via JSON-RPC
+curl -X POST https://your-project.vercel.app/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+
+# Call a tool via JSON-RPC
+curl -X POST https://your-project.vercel.app/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greet","arguments":{"name":"World"}},"id":2}'
+```
+
+```bash
+# Preview deployment for PR testing
+vercel
+# Creates a unique preview URL: https://my-project-abc123.vercel.app
+
+# Test the preview before promoting to production
+curl https://my-project-abc123.vercel.app/health
+
+# Promote to production
+vercel --prod
+```
+
+```json
+// vercel.json - with maxDuration matching your plan
+{
+  "rewrites": [{ "source": "/(.*)", "destination": "/api/frontmcp" }],
+  "functions": {
+    "api/frontmcp.ts": {
+      "memory": 1024,
+      "maxDuration": 10
+    }
+  },
+  "regions": ["iad1"]
+}
+```
+
+## What This Demonstrates
+
+- Testing the health endpoint and MCP JSON-RPC API of a deployed Vercel function
+- Using preview deployments to validate changes before promoting to production
+- Setting `maxDuration` according to your Vercel plan (Hobby: 10s, Pro: 60s, Enterprise: 900s)
+
+## Related
+
+- See `deploy-to-vercel` for the full deployment, KV storage, and cold start optimization guide

package/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-kv.md

@@ -0,0 +1,82 @@
+---
+name: vercel-with-kv
+reference: deploy-to-vercel
+level: basic
+description: 'Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence.'
+tags: [deployment, vercel-kv, vercel, session, performance, serverless]
+features:
+  - "Configuring `{ provider: 'vercel-kv' }` for automatic Vercel KV session storage"
+  - 'The `vercel.json` catch-all rewrite that routes all requests to the single FrontMCP handler'
+  - 'Setting function memory to 1024 MB for faster cold starts'
+---
+
+# Deploy to Vercel with KV Storage
+
+Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'greet',
+  description: 'Greet a user',
+  inputSchema: { name: z.string() },
+})
+class GreetTool extends ToolContext<{ name: string }> {
+  async execute(input: { name: string }) {
+    return { content: [{ type: 'text' as const, text: `Hello, ${input.name}!` }] };
+  }
+}
+
+@App({ name: 'MyApp', tools: [GreetTool] })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { provider: 'vercel-kv' },
+})
+class MyServer {}
+```
+
+```json
+// vercel.json
+{
+  "rewrites": [{ "source": "/(.*)", "destination": "/api/frontmcp" }],
+  "functions": {
+    "api/frontmcp.ts": {
+      "memory": 1024,
+      "maxDuration": 60
+    }
+  },
+  "regions": ["iad1"]
+}
+```
+
+```bash
+# Build for Vercel
+frontmcp build --target vercel
+
+# Preview deployment
+vercel
+
+# Production deployment
+vercel --prod
+
+# Verify
+curl https://your-project.vercel.app/health
+```
+
+## What This Demonstrates
+
+- Configuring `{ provider: 'vercel-kv' }` for automatic Vercel KV session storage
+- The `vercel.json` catch-all rewrite that routes all requests to the single FrontMCP handler
+- Setting function memory to 1024 MB for faster cold starts
+
+## Related
+
+- See `deploy-to-vercel` for KV provisioning, environment variables, and cold start optimization

package/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-skills-cache.md

@@ -0,0 +1,90 @@
+---
+name: vercel-with-skills-cache
+reference: deploy-to-vercel
+level: intermediate
+description: 'Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching.'
+tags: [deployment, vercel-kv, vercel, cache, security, skills]
+features:
+  - 'Enabling skills cache backed by Vercel KV with a 60-second TTL'
+  - 'Setting environment variables via `vercel env add` instead of hardcoding in source'
+  - 'Adding security headers (`X-Content-Type-Options`, `X-Frame-Options`) in `vercel.json`'
+---
+
+# Vercel Deployment with Skills Cache
+
+Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'MyApp' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { provider: 'vercel-kv' },
+  skillsConfig: {
+    enabled: true,
+    cache: {
+      enabled: true,
+      redis: { provider: 'vercel-kv' },
+      ttlMs: 60000,
+    },
+  },
+})
+class MyServer {}
+```
+
+```bash
+# Set environment variables via Vercel CLI
+vercel env add KV_REST_API_URL "https://your-kv-store.kv.vercel-storage.com"
+vercel env add KV_REST_API_TOKEN "your-token"
+vercel env add NODE_ENV production
+vercel env add LOG_LEVEL info
+```
+
+```json
+// vercel.json
+{
+  "rewrites": [{ "source": "/(.*)", "destination": "/api/frontmcp" }],
+  "functions": {
+    "api/frontmcp.ts": {
+      "memory": 1024,
+      "maxDuration": 60
+    }
+  },
+  "regions": ["iad1"],
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "X-Content-Type-Options", "value": "nosniff" },
+        { "key": "X-Frame-Options", "value": "DENY" }
+      ]
+    }
+  ]
+}
+```
+
+```bash
+# Deploy to production
+frontmcp build --target vercel
+vercel --prod
+
+# Add a custom domain
+vercel domains add mcp.example.com
+```
+
+## What This Demonstrates
+
+- Enabling skills cache backed by Vercel KV with a 60-second TTL
+- Setting environment variables via `vercel env add` instead of hardcoding in source
+- Adding security headers (`X-Content-Type-Options`, `X-Frame-Options`) in `vercel.json`
+
+## Related
+
+- See `deploy-to-vercel` for the full deployment guide including cold start notes and execution limits

package/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/minimal-vercel-config.md

@@ -0,0 +1,49 @@
+---
+name: minimal-vercel-config
+reference: deploy-to-vercel-config
+level: basic
+description: 'The minimum `vercel.json` needed to deploy a FrontMCP server to Vercel.'
+tags: [deployment, vercel, serverless, config, minimal]
+features:
+  - 'The catch-all rewrite (`/(.*) -> /api/frontmcp`) routes all requests to the single FrontMCP handler'
+  - 'Setting `buildCommand` and `outputDirectory` so Vercel uses the FrontMCP build pipeline'
+  - 'Configuring function memory (512 MB) and max duration (30s) for the serverless function'
+---
+
+# Minimal vercel.json Configuration
+
+The minimum `vercel.json` needed to deploy a FrontMCP server to Vercel.
+
+## Code
+
+```json
+// vercel.json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "buildCommand": "frontmcp build --target vercel",
+  "outputDirectory": "dist",
+  "rewrites": [
+    {
+      "source": "/(.*)",
+      "destination": "/api/frontmcp"
+    }
+  ],
+  "functions": {
+    "api/frontmcp.js": {
+      "memory": 512,
+      "maxDuration": 30
+    }
+  },
+  "regions": ["iad1"]
+}
+```
+
+## What This Demonstrates
+
+- The catch-all rewrite (`/(.*) -> /api/frontmcp`) routes all requests to the single FrontMCP handler
+- Setting `buildCommand` and `outputDirectory` so Vercel uses the FrontMCP build pipeline
+- Configuring function memory (512 MB) and max duration (30s) for the serverless function
+
+## Related
+
+- See `deploy-to-vercel-config` for the full reference configuration with security headers