@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-config/examples/configure-elicitation/basic-confirmation-gate.md

@@ -0,0 +1,83 @@
+---
+name: basic-confirmation-gate
+reference: configure-elicitation
+level: basic
+description: 'Request user confirmation before executing a destructive action.'
+tags: [config, elicitation, confirmation, gate]
+features:
+  - 'Enabling elicitation with `elicitation: { enabled: true }` in the `@FrontMcp` decorator'
+  - 'Using `this.elicit()` to pause tool execution and request user confirmation'
+  - 'Handling the case where the client does not support elicitation (`!confirmation`)'
+  - 'Using a boolean `requestedSchema` for simple yes/no confirmations'
+---
+
+# Basic Confirmation Gate
+
+Request user confirmation before executing a destructive action.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'delete_records',
+  description: 'Delete records from the database',
+  inputSchema: {
+    table: z.string(),
+    filter: z.string(),
+  },
+  outputSchema: { deleted: z.number() },
+})
+class DeleteRecordsTool extends ToolContext {
+  async execute(input: { table: string; filter: string }) {
+    const count = 42; // simulate counting matching records
+
+    const confirmation = await this.elicit({
+      message: `This will delete ${count} records from ${input.table}. Are you sure?`,
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          confirmed: { type: 'boolean', description: 'Confirm deletion' },
+        },
+        required: ['confirmed'],
+      },
+    });
+
+    if (!confirmation || !confirmation.confirmed) {
+      return { deleted: 0 };
+    }
+
+    return { deleted: count };
+  }
+}
+
+@App({
+  name: 'db-tools',
+  tools: [DeleteRecordsTool],
+})
+class DbApp {}
+
+@FrontMcp({
+  info: { name: 'elicit-server', version: '1.0.0' },
+  apps: [DbApp],
+  elicitation: {
+    enabled: true,
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Enabling elicitation with `elicitation: { enabled: true }` in the `@FrontMcp` decorator
+- Using `this.elicit()` to pause tool execution and request user confirmation
+- Handling the case where the client does not support elicitation (`!confirmation`)
+- Using a boolean `requestedSchema` for simple yes/no confirmations
+
+## Related
+
+- See `configure-elicitation` for the full elicitation configuration reference
+- See `setup-redis` for distributed elicitation state

package/catalog/frontmcp-config/examples/configure-elicitation/distributed-elicitation-redis.md

@@ -0,0 +1,87 @@
+---
+name: distributed-elicitation-redis
+reference: configure-elicitation
+level: intermediate
+description: 'Configure elicitation with Redis storage for multi-instance production deployments.'
+tags: [config, redis, elicitation, distributed]
+features:
+  - 'Configuring Redis-backed elicitation state for multi-instance deployments'
+  - 'Using a `requestedSchema` with both required and optional fields'
+  - 'Elicitation state is shared across server instances so the response can arrive at any replica'
+  - 'Loading Redis connection details from environment variables'
+---
+
+# Distributed Elicitation with Redis
+
+Configure elicitation with Redis storage for multi-instance production deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'deploy_service',
+  description: 'Deploy a service to production',
+  inputSchema: {
+    service: z.string(),
+    version: z.string(),
+  },
+  outputSchema: { deploymentId: z.string(), status: z.string() },
+})
+class DeployServiceTool extends ToolContext {
+  async execute(input: { service: string; version: string }) {
+    const confirmation = await this.elicit({
+      message: `Deploy ${input.service}@${input.version} to production?`,
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          confirmed: { type: 'boolean', description: 'Confirm deployment' },
+          reason: { type: 'string', description: 'Deployment reason (optional)' },
+        },
+        required: ['confirmed'],
+      },
+    });
+
+    if (!confirmation || !confirmation.confirmed) {
+      return { deploymentId: '', status: 'cancelled' };
+    }
+
+    return { deploymentId: 'deploy-abc123', status: 'started' };
+  }
+}
+
+@App({
+  name: 'deploy-tools',
+  tools: [DeployServiceTool],
+})
+class DeployApp {}
+
+@FrontMcp({
+  info: { name: 'deploy-server', version: '1.0.0' },
+  apps: [DeployApp],
+  elicitation: {
+    enabled: true,
+    redis: {
+      provider: 'redis',
+      host: process.env['REDIS_HOST'] ?? 'localhost',
+      port: Number(process.env['REDIS_PORT'] ?? 6379),
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring Redis-backed elicitation state for multi-instance deployments
+- Using a `requestedSchema` with both required and optional fields
+- Elicitation state is shared across server instances so the response can arrive at any replica
+- Loading Redis connection details from environment variables
+
+## Related
+
+- See `configure-elicitation` for the full elicitation configuration reference
+- See `configure-session` for session storage with Redis

package/catalog/frontmcp-config/examples/configure-http/cors-restricted-origins.md

@@ -0,0 +1,52 @@
+---
+name: cors-restricted-origins
+reference: configure-http
+level: basic
+description: 'Configure CORS to allow only specific frontend origins with credentials.'
+tags: [config, browser, http, cors, restricted, origins]
+features:
+  - 'Restricting CORS to explicit origins instead of the permissive default'
+  - 'Enabling `credentials: true` with specific origins (required -- browsers reject `*` with credentials)'
+  - 'Setting `maxAge` to reduce preflight request overhead'
+  - 'Reading port from an environment variable with a fallback'
+---
+
+# CORS with Restricted Origins
+
+Configure CORS to allow only specific frontend origins with credentials.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'my-app' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'cors-server', version: '1.0.0' },
+  apps: [MyApp],
+  http: {
+    port: Number(process.env['PORT']) || 3001,
+    cors: {
+      origin: ['https://myapp.com', 'https://staging.myapp.com'],
+      credentials: true,
+      maxAge: 86400, // cache preflight for 24 hours
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Restricting CORS to explicit origins instead of the permissive default
+- Enabling `credentials: true` with specific origins (required -- browsers reject `*` with credentials)
+- Setting `maxAge` to reduce preflight request overhead
+- Reading port from an environment variable with a fallback
+
+## Related
+
+- See `configure-http` for the full HTTP configuration reference
+- See `configure-throttle` for rate limiting and IP filtering

package/catalog/frontmcp-config/examples/configure-http/entry-path-reverse-proxy.md

@@ -0,0 +1,72 @@
+---
+name: entry-path-reverse-proxy
+reference: configure-http
+level: intermediate
+description: 'Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.'
+tags: [config, nx, http, entry, path, reverse]
+features:
+  - 'Using `entryPath` to mount the server under a URL prefix (no trailing slash)'
+  - 'All MCP endpoints are prefixed: `/api/mcp/sse`, `/api/mcp/`, etc.'
+  - 'Using a dynamic CORS origin function to allow wildcard subdomains'
+  - 'Suitable for running behind nginx, Caddy, or other reverse proxies'
+---
+
+# Entry Path Prefix Behind a Reverse Proxy
+
+Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'health_check',
+  description: 'Check service health',
+  inputSchema: {},
+  outputSchema: { status: z.string() },
+})
+class HealthCheckTool extends ToolContext {
+  async execute() {
+    return { status: 'ok' };
+  }
+}
+
+@App({
+  name: 'api',
+  tools: [HealthCheckTool],
+})
+class ApiApp {}
+
+@FrontMcp({
+  info: { name: 'proxy-server', version: '1.0.0' },
+  apps: [ApiApp],
+  http: {
+    port: 3001,
+    entryPath: '/api/mcp', // no trailing slash
+    cors: {
+      origin: (origin: string) => {
+        // allow any *.myapp.com subdomain
+        return origin.endsWith('.myapp.com');
+      },
+      credentials: true,
+    },
+  },
+})
+class Server {}
+// Endpoints become: /api/mcp/sse, /api/mcp/, etc.
+```
+
+## What This Demonstrates
+
+- Using `entryPath` to mount the server under a URL prefix (no trailing slash)
+- All MCP endpoints are prefixed: `/api/mcp/sse`, `/api/mcp/`, etc.
+- Using a dynamic CORS origin function to allow wildcard subdomains
+- Suitable for running behind nginx, Caddy, or other reverse proxies
+
+## Related
+
+- See `configure-http` for the full HTTP configuration reference
+- See `configure-transport` for protocol options behind a proxy

package/catalog/frontmcp-config/examples/configure-http/unix-socket-local.md

@@ -0,0 +1,64 @@
+---
+name: unix-socket-local
+reference: configure-http
+level: intermediate
+description: 'Bind the server to a unix socket instead of a TCP port for local-only communication.'
+tags: [config, unix-socket, cli, local, http, unix]
+features:
+  - 'Using `socketPath` to bind to a unix socket instead of a TCP port'
+  - 'When `socketPath` is set, the `port` field is ignored'
+  - 'Disabling CORS with `cors: false` since unix sockets are local-only'
+  - 'Suitable for CLI tools, daemons, and process manager integrations'
+---
+
+# Unix Socket for Local Access
+
+Bind the server to a unix socket instead of a TCP port for local-only communication.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'system_status',
+  description: 'Get system status',
+  inputSchema: {},
+  outputSchema: { uptime: z.number(), healthy: z.boolean() },
+})
+class SystemStatusTool extends ToolContext {
+  async execute() {
+    return { uptime: process.uptime(), healthy: true };
+  }
+}
+
+@App({
+  name: 'daemon',
+  tools: [SystemStatusTool],
+})
+class DaemonApp {}
+
+@FrontMcp({
+  info: { name: 'daemon-server', version: '1.0.0' },
+  apps: [DaemonApp],
+  http: {
+    socketPath: '/tmp/my-mcp-server.sock',
+    cors: false, // no CORS needed for local socket
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `socketPath` to bind to a unix socket instead of a TCP port
+- When `socketPath` is set, the `port` field is ignored
+- Disabling CORS with `cors: false` since unix sockets are local-only
+- Suitable for CLI tools, daemons, and process manager integrations
+
+## Related
+
+- See `configure-http` for the full HTTP configuration reference
+- See `configure-transport` for transport protocol options

package/catalog/frontmcp-config/examples/configure-session/multi-server-key-prefix.md

@@ -0,0 +1,68 @@
+---
+name: multi-server-key-prefix
+reference: configure-session
+level: intermediate
+description: 'Use unique key prefixes when multiple FrontMCP servers share one Redis instance.'
+tags: [config, redis, session, multi, key, prefix]
+features:
+  - 'Using unique `keyPrefix` values per server to avoid session key collisions'
+  - 'Both servers share the same Redis instance but have isolated session namespaces'
+  - 'Tuning `defaultTtlMs` per server based on workload pattern'
+  - '`billing-mcp:session:` vs `analytics-mcp:session:` prevents cross-contamination'
+---
+
+# Multi-Server Key Prefix Isolation
+
+Use unique key prefixes when multiple FrontMCP servers share one Redis instance.
+
+## Code
+
+```typescript
+// src/billing-server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'billing-app' })
+class BillingApp {}
+
+@FrontMcp({
+  info: { name: 'billing-server', version: '1.0.0' },
+  apps: [BillingApp],
+  redis: {
+    provider: 'redis',
+    host: 'shared-redis.internal',
+    port: 6379,
+    keyPrefix: 'billing-mcp:session:',
+    defaultTtlMs: 86_400_000, // 24 hours for long-running agent workflows
+  },
+})
+class BillingServer {}
+
+// src/analytics-server.ts
+@App({ name: 'analytics-app' })
+class AnalyticsApp {}
+
+@FrontMcp({
+  info: { name: 'analytics-server', version: '1.0.0' },
+  apps: [AnalyticsApp],
+  redis: {
+    provider: 'redis',
+    host: 'shared-redis.internal',
+    port: 6379,
+    keyPrefix: 'analytics-mcp:session:',
+    defaultTtlMs: 600_000, // 10 minutes for short CI/CD operations
+  },
+})
+class AnalyticsServer {}
+```
+
+## What This Demonstrates
+
+- Using unique `keyPrefix` values per server to avoid session key collisions
+- Both servers share the same Redis instance but have isolated session namespaces
+- Tuning `defaultTtlMs` per server based on workload pattern
+- `billing-mcp:session:` vs `analytics-mcp:session:` prevents cross-contamination
+
+## Related
+
+- See `configure-session` for the full session configuration reference
+- See `setup-redis` for Redis provisioning details

package/catalog/frontmcp-config/examples/configure-session/redis-session-store.md

@@ -0,0 +1,52 @@
+---
+name: redis-session-store
+reference: configure-session
+level: basic
+description: 'Configure Redis-backed session storage for production deployments.'
+tags: [config, redis, session, store]
+features:
+  - 'Configuring Redis as the session storage provider for production persistence'
+  - 'Using `keyPrefix` to namespace session keys and prevent collisions with other servers'
+  - 'Setting `defaultTtlMs` to control session lifetime (1 hour for interactive use)'
+  - 'Loading Redis connection details from environment variables'
+---
+
+# Redis Session Store
+
+Configure Redis-backed session storage for production deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'my-app' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'prod-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: Number(process.env['REDIS_PORT'] ?? 6379),
+    password: process.env['REDIS_PASSWORD'],
+    keyPrefix: 'myapp-mcp:session:',
+    defaultTtlMs: 3_600_000, // 1 hour for interactive sessions
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring Redis as the session storage provider for production persistence
+- Using `keyPrefix` to namespace session keys and prevent collisions with other servers
+- Setting `defaultTtlMs` to control session lifetime (1 hour for interactive use)
+- Loading Redis connection details from environment variables
+
+## Related
+
+- See `configure-session` for all session storage options
+- See `setup-redis` for Redis provisioning details

package/catalog/frontmcp-config/examples/configure-session/vercel-kv-session.md

@@ -0,0 +1,52 @@
+---
+name: vercel-kv-session
+reference: configure-session
+level: intermediate
+description: 'Configure Vercel KV for session storage in serverless Vercel deployments.'
+tags: [config, vercel-kv, vercel, session, transport, serverless]
+features:
+  - "Using `provider: 'vercel-kv'` for Vercel platform deployments"
+  - 'Vercel automatically injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` environment variables'
+  - 'Combining with `stateless-api` transport preset for serverless execution'
+  - 'No explicit host/port needed -- Vercel KV uses REST API under the hood'
+---
+
+# Vercel KV Session Store
+
+Configure Vercel KV for session storage in serverless Vercel deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'my-app' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'vercel-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'vercel-kv',
+    // KV_REST_API_URL and KV_REST_API_TOKEN are auto-injected by Vercel
+  },
+  transport: {
+    protocol: 'stateless-api',
+    sessionMode: 'stateless',
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `provider: 'vercel-kv'` for Vercel platform deployments
+- Vercel automatically injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` environment variables
+- Combining with `stateless-api` transport preset for serverless execution
+- No explicit host/port needed -- Vercel KV uses REST API under the hood
+
+## Related
+
+- See `configure-session` for all session storage options
+- See `configure-transport` for transport protocol configuration

package/catalog/frontmcp-config/examples/configure-throttle/distributed-redis-throttle.md

@@ -0,0 +1,94 @@
+---
+name: distributed-redis-throttle
+reference: configure-throttle
+level: advanced
+description: 'Configure Redis-backed rate limiting for multi-instance deployments behind a load balancer.'
+tags: [config, redis, session, throttle, distributed]
+features:
+  - "Configuring `storage: { type: 'redis' }` so rate limit counters are shared across instances"
+  - 'Using `keyPrefix` to namespace guard keys in a shared Redis instance'
+  - "Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool"
+  - 'In-memory counters are per-process and would allow N times the intended rate with N instances'
+---
+
+# Distributed Rate Limiting with Redis
+
+Configure Redis-backed rate limiting for multi-instance deployments behind a load balancer.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'process_payment',
+  description: 'Process a payment transaction',
+  inputSchema: {
+    amount: z.number(),
+    currency: z.string(),
+  },
+  outputSchema: { transactionId: z.string(), status: z.string() },
+  rateLimit: {
+    maxRequests: 5,
+    windowMs: 60000,
+    partitionBy: 'session',
+  },
+  concurrency: {
+    maxConcurrent: 1,
+    partitionBy: 'session',
+  },
+})
+class ProcessPaymentTool extends ToolContext {
+  async execute(input: { amount: number; currency: string }) {
+    return { transactionId: 'txn-abc123', status: 'completed' };
+  }
+}
+
+@App({
+  name: 'payments',
+  tools: [ProcessPaymentTool],
+})
+class PaymentsApp {}
+
+@FrontMcp({
+  info: { name: 'payment-server', version: '1.0.0' },
+  apps: [PaymentsApp],
+  throttle: {
+    enabled: true,
+    storage: {
+      type: 'redis',
+      redis: {
+        config: {
+          host: process.env['REDIS_HOST'] ?? 'redis.internal',
+          port: Number(process.env['REDIS_PORT'] ?? 6379),
+        },
+      },
+    },
+    keyPrefix: 'payments:guard:',
+    global: {
+      maxRequests: 500,
+      windowMs: 60000,
+      partitionBy: 'ip',
+    },
+    globalConcurrency: {
+      maxConcurrent: 20,
+      partitionBy: 'global',
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring `storage: { type: 'redis' }` so rate limit counters are shared across instances
+- Using `keyPrefix` to namespace guard keys in a shared Redis instance
+- Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool
+- In-memory counters are per-process and would allow N times the intended rate with N instances
+
+## Related
+
+- See `configure-throttle` for the full throttle configuration reference
+- See `setup-redis` for Redis provisioning details