@frontmcp/skills 1.0.0-beta.9 → 1.0.0

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

package/catalog/frontmcp-config/examples/configure-throttle-guard-config/full-guard-config.md

@@ -0,0 +1,99 @@
+---
+name: full-guard-config
+reference: configure-throttle-guard-config
+level: advanced
+description: 'Complete GuardConfig using every available field for maximum protection.'
+tags: [config, redis, session, throttle, guard, full]
+features:
+  - 'Every field in the `GuardConfig` interface used together'
+  - 'Priority order: IP filter -> global rate limit -> global concurrency -> per-tool limits'
+  - 'Redis `storage` for shared counters across instances'
+  - '`keyPrefix` to namespace guard keys in shared Redis'
+  - "Mixed `partitionBy` strategies: `'ip'` for global, `'session'` for per-tool"
+  - '`queueTimeoutMs` to briefly queue excess requests instead of rejecting'
+---
+
+# Full GuardConfig with All Options
+
+Complete GuardConfig using every available field for maximum protection.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'secure-app' })
+class SecureApp {}
+
+@FrontMcp({
+  info: { name: 'fully-guarded-server', version: '1.0.0' },
+  apps: [SecureApp],
+  throttle: {
+    enabled: true,
+
+    // Distributed storage for multi-instance deployments
+    storage: {
+      type: 'redis',
+      redis: {
+        config: {
+          host: process.env['REDIS_HOST'] ?? 'redis.internal',
+          port: 6379,
+        },
+      },
+    },
+    keyPrefix: 'myapp:guard:',
+
+    // Server-wide limits
+    global: {
+      maxRequests: 1000,
+      windowMs: 60000,
+      partitionBy: 'ip', // per-client IP rate limit
+    },
+    globalConcurrency: {
+      maxConcurrent: 50,
+      queueTimeoutMs: 2000,
+      partitionBy: 'global',
+    },
+
+    // Default per-tool limits
+    defaultRateLimit: {
+      maxRequests: 100,
+      windowMs: 60000,
+      partitionBy: 'session',
+    },
+    defaultConcurrency: {
+      maxConcurrent: 10,
+      queueTimeoutMs: 5000,
+      partitionBy: 'session',
+    },
+    defaultTimeout: {
+      executeMs: 30000,
+    },
+
+    // IP-based access control
+    ipFilter: {
+      allowList: ['10.0.0.0/8', '172.16.0.0/12'],
+      denyList: ['192.168.1.100'],
+      defaultAction: 'deny',
+      trustProxy: true,
+      trustedProxyDepth: 2,
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Every field in the `GuardConfig` interface used together
+- Priority order: IP filter -> global rate limit -> global concurrency -> per-tool limits
+- Redis `storage` for shared counters across instances
+- `keyPrefix` to namespace guard keys in shared Redis
+- Mixed `partitionBy` strategies: `'ip'` for global, `'session'` for per-tool
+- `queueTimeoutMs` to briefly queue excess requests instead of rejecting
+
+## Related
+
+- See `configure-throttle-guard-config` for the complete interface reference
+- See `configure-throttle` for practical throttle configuration patterns

package/catalog/frontmcp-config/examples/configure-throttle-guard-config/minimal-guard-config.md

@@ -0,0 +1,55 @@
+---
+name: minimal-guard-config
+reference: configure-throttle-guard-config
+level: basic
+description: 'Enable throttle with just a global rate limit and default timeout.'
+tags: [config, throttle, guard, minimal]
+features:
+  - 'The minimum fields needed to enable the guard: `enabled`, `global`, and `defaultTimeout`'
+  - "`partitionBy: 'global'` shares one counter across all clients"
+  - '`windowMs` defaults to 60000 (1 minute) if omitted'
+  - 'Other fields (`globalConcurrency`, `ipFilter`, `storage`) are optional'
+---
+
+# Minimal GuardConfig
+
+Enable throttle with just a global rate limit and default timeout.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'my-app' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'guarded-server', version: '1.0.0' },
+  apps: [MyApp],
+  throttle: {
+    enabled: true,
+    global: {
+      maxRequests: 1000,
+      windowMs: 60000,
+      partitionBy: 'global',
+    },
+    defaultTimeout: {
+      executeMs: 30000,
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- The minimum fields needed to enable the guard: `enabled`, `global`, and `defaultTimeout`
+- `partitionBy: 'global'` shares one counter across all clients
+- `windowMs` defaults to 60000 (1 minute) if omitted
+- Other fields (`globalConcurrency`, `ipFilter`, `storage`) are optional
+
+## Related
+
+- See `configure-throttle-guard-config` for the complete GuardConfig interface
+- See `configure-throttle` for practical throttle configuration patterns

package/catalog/frontmcp-config/examples/configure-transport/custom-protocol-flags.md

@@ -0,0 +1,74 @@
+---
+name: custom-protocol-flags
+reference: configure-transport
+level: advanced
+description: 'Override individual protocol flags instead of using a preset for fine-grained control.'
+tags: [config, redis, session, transport, custom, protocol]
+features:
+  - 'Passing an object to `protocol` instead of a preset string for fine-grained control'
+  - 'Enabling SSE, streamable HTTP, and JSON-only modes simultaneously'
+  - 'Setting `strictSession: true` to require `mcp-session-id` header on streamable HTTP'
+  - "Using `distributedMode: 'auto'` to auto-detect based on whether Redis is configured"
+  - 'Disabling `legacy` SSE while keeping modern SSE support'
+---
+
+# Custom Protocol Flags
+
+Override individual protocol flags instead of using a preset for fine-grained control.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'stream_logs',
+  description: 'Stream application logs',
+  inputSchema: { service: z.string(), lines: z.number().optional() },
+  outputSchema: { logs: z.array(z.string()) },
+})
+class StreamLogsTool extends ToolContext {
+  async execute(input: { service: string; lines?: number }) {
+    return { logs: ['[INFO] Service started', '[INFO] Healthy'] };
+  }
+}
+
+@App({
+  name: 'devtools',
+  tools: [StreamLogsTool],
+})
+class DevtoolsApp {}
+
+@FrontMcp({
+  info: { name: 'custom-protocol-server', version: '1.0.0' },
+  apps: [DevtoolsApp],
+  transport: {
+    sessionMode: 'stateful',
+    protocol: {
+      sse: true, // SSE endpoint enabled
+      streamable: true, // Streamable HTTP POST enabled
+      json: true, // JSON-only responses also available
+      stateless: false, // Sessions required
+      legacy: false, // No legacy SSE
+      strictSession: true, // Require mcp-session-id header
+    },
+    distributedMode: 'auto', // auto-detect based on Redis config
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Passing an object to `protocol` instead of a preset string for fine-grained control
+- Enabling SSE, streamable HTTP, and JSON-only modes simultaneously
+- Setting `strictSession: true` to require `mcp-session-id` header on streamable HTTP
+- Using `distributedMode: 'auto'` to auto-detect based on whether Redis is configured
+- Disabling `legacy` SSE while keeping modern SSE support
+
+## Related
+
+- See `configure-transport` for the full transport configuration reference
+- See `configure-transport-protocol-presets` for the built-in preset definitions

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

@@ -0,0 +1,86 @@
+---
+name: distributed-sessions-redis
+reference: configure-transport
+level: intermediate
+description: 'Configure transport with Redis persistence for multi-instance load-balanced deployments.'
+tags: [config, redis, session, transport, distributed, sessions]
+features:
+  - 'Using `distributedMode: true` for load-balanced multi-instance deployments'
+  - 'Redis `persistence` so sessions survive restarts and are shared across instances'
+  - 'Setting `defaultTtlMs` to prevent sessions from accumulating indefinitely'
+  - 'Redis-backed `eventStore` for SSE resumability across instances'
+  - "Using the `'modern'` preset (drops legacy SSE but keeps streamable HTTP)"
+---
+
+# Distributed Sessions with Redis
+
+Configure transport with Redis persistence for multi-instance load-balanced deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_report',
+  description: 'Generate a report',
+  inputSchema: { reportId: z.string() },
+  outputSchema: { data: z.string(), generatedAt: z.string() },
+})
+class GetReportTool extends ToolContext {
+  async execute(input: { reportId: string }) {
+    return { data: 'report-data', generatedAt: new Date().toISOString() };
+  }
+}
+
+@App({
+  name: 'reports',
+  tools: [GetReportTool],
+})
+class ReportsApp {}
+
+@FrontMcp({
+  info: { name: 'distributed-server', version: '1.0.0' },
+  apps: [ReportsApp],
+  transport: {
+    sessionMode: 'stateful',
+    protocol: 'modern',
+    distributedMode: true,
+    persistence: {
+      redis: {
+        provider: 'redis',
+        host: process.env['REDIS_HOST'] ?? 'redis.internal',
+        port: 6379,
+      },
+      defaultTtlMs: 3_600_000, // 1 hour session TTL
+    },
+    eventStore: {
+      enabled: true,
+      provider: 'redis',
+      maxEvents: 10000,
+      ttlMs: 300_000, // 5 minute event TTL
+      redis: {
+        provider: 'redis',
+        host: process.env['REDIS_HOST'] ?? 'redis.internal',
+      },
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `distributedMode: true` for load-balanced multi-instance deployments
+- Redis `persistence` so sessions survive restarts and are shared across instances
+- Setting `defaultTtlMs` to prevent sessions from accumulating indefinitely
+- Redis-backed `eventStore` for SSE resumability across instances
+- Using the `'modern'` preset (drops legacy SSE but keeps streamable HTTP)
+
+## Related
+
+- See `configure-transport` for the full transport configuration reference
+- See `configure-session` for session storage options
+- See `setup-redis` for Redis provisioning

package/catalog/frontmcp-config/examples/configure-transport/stateless-serverless.md

@@ -0,0 +1,69 @@
+---
+name: stateless-serverless
+reference: configure-transport
+level: basic
+description: 'Configure stateless transport for Vercel, Lambda, or Cloudflare deployments.'
+tags: [config, vercel, lambda, cloudflare, session, transport]
+features:
+  - "Using `sessionMode: 'stateless'` to disable session management"
+  - "Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response"
+  - 'Each request is standalone with no server-side state between invocations'
+  - 'Required for serverless targets (Vercel, Lambda, Cloudflare Workers)'
+---
+
+# Stateless Transport for Serverless
+
+Configure stateless transport for Vercel, Lambda, or Cloudflare deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'convert_currency',
+  description: 'Convert between currencies',
+  inputSchema: {
+    amount: z.number(),
+    from: z.string(),
+    to: z.string(),
+  },
+  outputSchema: { result: z.number(), rate: z.number() },
+})
+class ConvertCurrencyTool extends ToolContext {
+  async execute(input: { amount: number; from: string; to: string }) {
+    const rate = 1.1;
+    return { result: input.amount * rate, rate };
+  }
+}
+
+@App({
+  name: 'currency-api',
+  tools: [ConvertCurrencyTool],
+})
+class CurrencyApp {}
+
+@FrontMcp({
+  info: { name: 'serverless-server', version: '1.0.0' },
+  apps: [CurrencyApp],
+  transport: {
+    sessionMode: 'stateless',
+    protocol: 'stateless-api',
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `sessionMode: 'stateless'` to disable session management
+- Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response
+- Each request is standalone with no server-side state between invocations
+- Required for serverless targets (Vercel, Lambda, Cloudflare Workers)
+
+## Related
+
+- See `configure-transport` for the full transport configuration reference
+- See `configure-transport-protocol-presets` for all preset options

package/catalog/frontmcp-config/examples/configure-transport-protocol-presets/legacy-preset-nodejs.md

@@ -0,0 +1,65 @@
+---
+name: legacy-preset-nodejs
+reference: configure-transport-protocol-presets
+level: basic
+description: 'Use the default legacy preset for maximum compatibility with all MCP clients.'
+tags: [config, anthropic, session, transport, node, protocol]
+features:
+  - "The `'legacy'` preset is the default and can be omitted"
+  - 'Enables SSE, Streamable HTTP, and Legacy SSE for maximum client compatibility'
+  - '`strictSession: true` requires `mcp-session-id` header for streamable HTTP'
+  - 'Best for single-instance Node.js deployments (Claude Desktop, etc.)'
+---
+
+# Legacy Preset for Node.js
+
+Use the default legacy preset for maximum compatibility with all MCP clients.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'hello',
+  description: 'Say hello',
+  inputSchema: { name: z.string() },
+  outputSchema: { greeting: z.string() },
+})
+class HelloTool extends ToolContext {
+  async execute(input: { name: string }) {
+    return { greeting: `Hello, ${input.name}!` };
+  }
+}
+
+@App({
+  name: 'my-app',
+  tools: [HelloTool],
+})
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'legacy-server', version: '1.0.0' },
+  apps: [MyApp],
+  transport: {
+    protocol: 'legacy', // default -- can be omitted
+  },
+})
+class Server {}
+// Enables: SSE + Streamable HTTP + Legacy SSE
+// Flags: { sse: true, streamable: true, json: false, stateless: false, legacy: true, strictSession: true }
+```
+
+## What This Demonstrates
+
+- The `'legacy'` preset is the default and can be omitted
+- Enables SSE, Streamable HTTP, and Legacy SSE for maximum client compatibility
+- `strictSession: true` requires `mcp-session-id` header for streamable HTTP
+- Best for single-instance Node.js deployments (Claude Desktop, etc.)
+
+## Related
+
+- See `configure-transport-protocol-presets` for all preset definitions
+- See `configure-transport` for full transport configuration

package/catalog/frontmcp-config/examples/configure-transport-protocol-presets/stateless-api-serverless.md

@@ -0,0 +1,69 @@
+---
+name: stateless-api-serverless
+reference: configure-transport-protocol-presets
+level: intermediate
+description: 'Use the stateless-api preset for Vercel, Lambda, or Cloudflare Workers.'
+tags: [config, vercel, lambda, cloudflare, session, transport]
+features:
+  - "The `'stateless-api'` preset disables SSE, streaming, and sessions entirely"
+  - 'Each request is standalone with no server-side state'
+  - "Pair with `sessionMode: 'stateless'` for serverless execution"
+  - 'Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed'
+---
+
+# Stateless API Preset for Serverless
+
+Use the stateless-api preset for Vercel, Lambda, or Cloudflare Workers.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'translate',
+  description: 'Translate text between languages',
+  inputSchema: {
+    text: z.string(),
+    targetLang: z.string(),
+  },
+  outputSchema: { translated: z.string() },
+})
+class TranslateTool extends ToolContext {
+  async execute(input: { text: string; targetLang: string }) {
+    return { translated: `[${input.targetLang}] ${input.text}` };
+  }
+}
+
+@App({
+  name: 'translate-api',
+  tools: [TranslateTool],
+})
+class TranslateApp {}
+
+@FrontMcp({
+  info: { name: 'serverless-translate', version: '1.0.0' },
+  apps: [TranslateApp],
+  transport: {
+    sessionMode: 'stateless',
+    protocol: 'stateless-api',
+  },
+})
+class Server {}
+// Enables: Stateless HTTP only
+// Flags: { sse: false, streamable: false, json: false, stateless: true, legacy: false, strictSession: false }
+```
+
+## What This Demonstrates
+
+- The `'stateless-api'` preset disables SSE, streaming, and sessions entirely
+- Each request is standalone with no server-side state
+- Pair with `sessionMode: 'stateless'` for serverless execution
+- Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed
+
+## Related
+
+- See `configure-transport-protocol-presets` for all preset definitions
+- See `configure-transport` for full transport configuration