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

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

package/catalog/frontmcp-config/examples/configure-throttle/per-tool-rate-limit.md

@@ -0,0 +1,92 @@
+---
+name: per-tool-rate-limit
+reference: configure-throttle
+level: intermediate
+description: 'Override server defaults with per-tool rate limits and concurrency caps.'
+tags: [config, session, throttle, per, tool, rate]
+features:
+  - 'Setting per-tool `rateLimit`, `concurrency`, and `timeout` on the `@Tool` decorator'
+  - "Using `partitionBy: 'session'` for per-user fairness on expensive tools"
+  - 'Setting `queueTimeoutMs` to briefly queue excess requests instead of rejecting immediately'
+  - 'Tools without overrides (`QuickLookupTool`) inherit server defaults'
+---
+
+# Per-Tool Rate Limiting
+
+Override server defaults with per-tool rate limits and concurrency caps.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'expensive_query',
+  description: 'Run an expensive database query',
+  inputSchema: { query: z.string() },
+  outputSchema: { rows: z.array(z.record(z.unknown())), rowCount: z.number() },
+  rateLimit: {
+    maxRequests: 10,
+    windowMs: 60000,
+    partitionBy: 'session', // per-session rate limit
+  },
+  concurrency: {
+    maxConcurrent: 3,
+    queueTimeoutMs: 5000, // wait up to 5s for a slot
+    partitionBy: 'session',
+  },
+  timeout: {
+    executeMs: 60000, // 60 second timeout for this tool
+  },
+})
+class ExpensiveQueryTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return { rows: [{ id: 1 }], rowCount: 1 };
+  }
+}
+
+@Tool({
+  name: 'quick_lookup',
+  description: 'Fast key-value lookup',
+  inputSchema: { key: z.string() },
+  outputSchema: { value: z.string().nullable() },
+  // No overrides -- uses server defaults
+})
+class QuickLookupTool extends ToolContext {
+  async execute(input: { key: string }) {
+    return { value: 'cached-value' };
+  }
+}
+
+@App({
+  name: 'data-api',
+  tools: [ExpensiveQueryTool, QuickLookupTool],
+})
+class DataApp {}
+
+@FrontMcp({
+  info: { name: 'data-server', version: '1.0.0' },
+  apps: [DataApp],
+  throttle: {
+    enabled: true,
+    defaultRateLimit: { maxRequests: 100, windowMs: 60000 },
+    defaultConcurrency: { maxConcurrent: 10 },
+    defaultTimeout: { executeMs: 30000 },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Setting per-tool `rateLimit`, `concurrency`, and `timeout` on the `@Tool` decorator
+- Using `partitionBy: 'session'` for per-user fairness on expensive tools
+- Setting `queueTimeoutMs` to briefly queue excess requests instead of rejecting immediately
+- Tools without overrides (`QuickLookupTool`) inherit server defaults
+
+## Related
+
+- See `configure-throttle` for the full throttle configuration reference
+- See `configure-throttle-guard-config` for the complete GuardConfig interface

package/catalog/frontmcp-config/examples/configure-throttle/server-level-rate-limit.md

@@ -0,0 +1,83 @@
+---
+name: server-level-rate-limit
+reference: configure-throttle
+level: basic
+description: 'Configure global rate limits and IP filtering at the server level.'
+tags: [config, throttle, level, rate, limit]
+features:
+  - 'Enabling throttle with `throttle: { enabled: true }`'
+  - 'Setting `global` rate limit shared across all clients'
+  - 'Configuring `globalConcurrency` to cap simultaneous executions'
+  - 'Setting `defaultTimeout` to prevent runaway tool executions'
+  - 'Using `ipFilter` with deny-by-default posture and an explicit allow list'
+---
+
+# Server-Level Rate Limiting
+
+Configure global rate limits and IP filtering at the server level.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'search',
+  description: 'Search records',
+  inputSchema: { query: z.string() },
+  outputSchema: { results: z.array(z.string()) },
+})
+class SearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return { results: [`Result for: ${input.query}`] };
+  }
+}
+
+@App({
+  name: 'api',
+  tools: [SearchTool],
+})
+class ApiApp {}
+
+@FrontMcp({
+  info: { name: 'throttled-server', version: '1.0.0' },
+  apps: [ApiApp],
+  throttle: {
+    enabled: true,
+    global: {
+      maxRequests: 1000,
+      windowMs: 60000, // 1 minute window
+      partitionBy: 'global',
+    },
+    globalConcurrency: {
+      maxConcurrent: 50,
+      partitionBy: 'global',
+    },
+    defaultTimeout: {
+      executeMs: 30000, // 30 second timeout
+    },
+    ipFilter: {
+      allowList: ['10.0.0.0/8'],
+      defaultAction: 'deny',
+      trustProxy: true,
+      trustedProxyDepth: 1,
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Enabling throttle with `throttle: { enabled: true }`
+- Setting `global` rate limit shared across all clients
+- Configuring `globalConcurrency` to cap simultaneous executions
+- Setting `defaultTimeout` to prevent runaway tool executions
+- Using `ipFilter` with deny-by-default posture and an explicit allow list
+
+## Related
+
+- See `configure-throttle` for the full throttle configuration reference
+- See `configure-throttle-guard-config` for the complete GuardConfig interface