@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-production-readiness/examples/health-readiness-endpoints/custom-probes.md

@@ -0,0 +1,136 @@
+---
+name: custom-probes
+reference: health-readiness-endpoints
+level: intermediate
+description: 'Custom database and API probes with Kubernetes deployment configuration.'
+tags: [production, health, readiness, kubernetes, postgres, probes, custom]
+features:
+  - 'Custom health probes for PostgreSQL and external API dependencies'
+  - 'Kubernetes liveness and readiness probe configuration'
+  - 'Production includeDetails: false to hide infrastructure topology'
+  - 'Per-probe timeout to prevent slow dependencies from blocking readiness'
+---
+
+# Custom Health Probes with Kubernetes
+
+Custom database and API probes with Kubernetes deployment configuration.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { pool } from './db';
+import { MyApp } from './apps/my-app';
+
+@FrontMcp({
+  info: { name: 'api-server', version: '2.1.0' },
+  apps: [MyApp],
+  http: { port: 3001 },
+  redis: { host: process.env['REDIS_HOST'] ?? 'localhost' },
+  health: {
+    includeDetails: false, // don't leak infra topology in production
+    readyz: {
+      timeoutMs: 3000, // probes must respond within 3s
+    },
+    probes: [
+      {
+        name: 'postgres',
+        async check() {
+          const start = Date.now();
+          try {
+            await pool.query('SELECT 1');
+            return { status: 'healthy', latencyMs: Date.now() - start };
+          } catch (err) {
+            return {
+              status: 'unhealthy',
+              latencyMs: Date.now() - start,
+              error: err instanceof Error ? err.message : String(err),
+            };
+          }
+        },
+      },
+      {
+        name: 'payment-api',
+        async check() {
+          const start = Date.now();
+          const res = await fetch('https://api.payments.example.com/health', {
+            signal: AbortSignal.timeout(2000),
+          });
+          return {
+            status: res.ok ? 'healthy' : 'unhealthy',
+            latencyMs: Date.now() - start,
+          };
+        },
+      },
+    ],
+  },
+})
+export default class Server {}
+```
+
+```yaml
+# k8s/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api-server
+spec:
+  replicas: 3
+  template:
+    spec:
+      containers:
+        - name: api-server
+          image: my-registry/api-server:2.1.0
+          ports:
+            - containerPort: 3001
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: 3001
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: 3001
+            initialDelaySeconds: 10
+            periodSeconds: 15
+            timeoutSeconds: 5
+            failureThreshold: 2
+          env:
+            - name: REDIS_HOST
+              value: redis-service
+            - name: NODE_ENV
+              value: production
+```
+
+When `includeDetails: false`, the `/readyz` response omits per-probe details:
+
+```json
+{
+  "status": "ready",
+  "totalLatencyMs": 45,
+  "catalog": {
+    "toolsHash": "a1b2c3d4...",
+    "toolCount": 8,
+    "resourceCount": 2,
+    "promptCount": 1,
+    "skillCount": 0,
+    "agentCount": 0
+  }
+}
+```
+
+## What This Demonstrates
+
+- Custom health probes for PostgreSQL and external API dependencies
+- Kubernetes liveness and readiness probe configuration
+- Production includeDetails: false to hide infrastructure topology
+- Per-probe timeout to prevent slow dependencies from blocking readiness
+
+## Related
+
+- See `health-readiness-endpoints` for the full configuration reference
+- See `frontmcp-observability` for tracing and monitoring integration

package/catalog/frontmcp-production-readiness/examples/production-browser/browser-bundle-config.md

@@ -0,0 +1,93 @@
+---
+name: browser-bundle-config
+reference: production-browser
+level: basic
+description: 'Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.'
+tags: [production, browser, sdk, node, bundle, config]
+features:
+  - 'Correct `main`, `module`, `browser`, `types`, and `exports` fields for browser distribution'
+  - 'Using the `browser` field to point bundlers to the browser-specific build'
+  - 'Browser-safe imports with no Node.js-only APIs'
+  - 'CDN-friendly distribution that works via `<script type="module">`'
+---
+
+# Browser SDK Bundle Configuration
+
+Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.
+
+## Code
+
+```jsonc
+// package.json
+{
+  "name": "my-mcp-browser-sdk",
+  "version": "1.0.0",
+  "description": "Browser-compatible MCP SDK",
+  "license": "MIT",
+
+  // CJS entry
+  "main": "./dist/cjs/index.js",
+  // ESM entry
+  "module": "./dist/esm/index.js",
+  // Browser-specific entry
+  "browser": "./dist/browser/index.js",
+  // TypeScript declarations
+  "types": "./dist/types/index.d.ts",
+
+  // Conditional exports for bundlers
+  "exports": {
+    ".": {
+      "browser": "./dist/browser/index.js",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts",
+    },
+  },
+
+  "files": ["dist/", "README.md", "LICENSE"],
+
+  "scripts": {
+    "build": "frontmcp build --target browser",
+    "analyze": "npx bundlesize",
+    "test": "jest --coverage",
+  },
+}
+```
+
+```typescript
+// src/index.ts — Browser-safe public API
+// No Node.js-only imports (fs, path, child_process, net, crypto)
+// All crypto uses @frontmcp/utils (wraps Web Crypto API)
+import { sha256Hex, randomUUID, base64urlEncode } from '@frontmcp/utils';
+
+export { create } from './client';
+export type { McpBrowserClient, McpToolResult } from './types';
+
+// Re-export utilities that work in the browser
+export { sha256Hex, randomUUID, base64urlEncode };
+```
+
+```html
+<!-- CDN usage via script tag -->
+<script type="module">
+  import { create } from 'https://cdn.example.com/my-mcp-browser-sdk@1.0.0/dist/browser/index.js';
+
+  const client = await create({
+    baseUrl: 'https://mcp-api.example.com',
+  });
+
+  const tools = await client.listTools();
+  console.log('Available tools:', tools);
+</script>
+```
+
+## What This Demonstrates
+
+- Correct `main`, `module`, `browser`, `types`, and `exports` fields for browser distribution
+- Using the `browser` field to point bundlers to the browser-specific build
+- Browser-safe imports with no Node.js-only APIs
+- CDN-friendly distribution that works via `<script type="module">`
+
+## Related
+
+- See `production-browser` for the full browser compatibility and distribution checklist

package/catalog/frontmcp-production-readiness/examples/production-browser/cross-platform-crypto.md

@@ -0,0 +1,116 @@
+---
+name: cross-platform-crypto
+reference: production-browser
+level: intermediate
+description: 'Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.'
+tags: [production, browser, node, cross, platform, crypto]
+features:
+  - 'Using `@frontmcp/utils` for crypto instead of `node:crypto` (wraps Web Crypto API)'
+  - 'Using Fetch API for HTTP calls instead of Node.js `http`/`https`'
+  - 'Using `crypto.randomUUID()` from the Web Crypto API in browser code'
+  - 'WebSocket connection with automatic reconnection for streaming'
+  - 'No Node.js-only APIs (`fs`, `path`, `child_process`, `net`)'
+---
+
+# Cross-Platform Crypto and Browser Compatibility
+
+Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.
+
+## Code
+
+```typescript
+// src/tools/browser-safe-hash.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+// @frontmcp/utils wraps Web Crypto API — works in browsers
+import { sha256Hex, sha256Base64url, randomUUID } from '@frontmcp/utils';
+
+@Tool({
+  name: 'hash_data',
+  description: 'Hash data using browser-compatible crypto',
+  inputSchema: {
+    data: z.string().min(1).describe('Data to hash'),
+    format: z.enum(['hex', 'base64url']).default('hex').describe('Output format'),
+  },
+  outputSchema: {
+    hash: z.string(),
+    format: z.string(),
+    id: z.string(),
+  },
+})
+export class HashDataTool extends ToolContext {
+  async execute(input: { data: string; format: 'hex' | 'base64url' }) {
+    // Cross-platform: works in browser (Web Crypto) and Node.js
+    const hash = input.format === 'hex' ? sha256Hex(input.data) : sha256Base64url(input.data);
+    const id = randomUUID();
+
+    return { hash, format: input.format, id };
+  }
+}
+```
+
+```typescript
+// src/client/browser-client.ts
+// Browser-compatible MCP client — no Node.js APIs
+
+export class BrowserMcpClient {
+  private baseUrl: string;
+
+  constructor(config: { baseUrl: string }) {
+    this.baseUrl = config.baseUrl;
+  }
+
+  // Use Fetch API — not Node.js http/https
+  async callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+    const response = await fetch(`${this.baseUrl}/mcp`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: { name, arguments: args },
+        id: crypto.randomUUID(), // Web Crypto API
+      }),
+    });
+
+    const result = await response.json();
+    return result;
+  }
+
+  // WebSocket with reconnection for SSE/streaming
+  connectStream(onMessage: (data: unknown) => void): { close: () => void } {
+    let ws: WebSocket;
+    let reconnectTimer: ReturnType<typeof setTimeout>;
+
+    const connect = () => {
+      ws = new WebSocket(this.baseUrl.replace('http', 'ws') + '/mcp/stream');
+      ws.onmessage = (event) => onMessage(JSON.parse(event.data));
+      ws.onclose = () => {
+        // Reconnect gracefully
+        reconnectTimer = setTimeout(connect, 1000);
+      };
+    };
+
+    connect();
+
+    return {
+      close: () => {
+        clearTimeout(reconnectTimer);
+        ws?.close();
+      },
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `@frontmcp/utils` for crypto instead of `node:crypto` (wraps Web Crypto API)
+- Using Fetch API for HTTP calls instead of Node.js `http`/`https`
+- Using `crypto.randomUUID()` from the Web Crypto API in browser code
+- WebSocket connection with automatic reconnection for streaming
+- No Node.js-only APIs (`fs`, `path`, `child_process`, `net`)
+
+## Related
+
+- See `production-browser` for the full browser compatibility and security checklist

package/catalog/frontmcp-production-readiness/examples/production-browser/security-and-performance.md

@@ -0,0 +1,128 @@
+---
+name: security-and-performance
+reference: production-browser
+level: advanced
+description: 'Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread.'
+tags: [production, auth, browser, security, performance]
+features:
+  - 'No secrets (API keys, tokens) in the browser bundle -- using server-side proxy'
+  - 'CORS configured on the server to accept specific browser origins'
+  - 'Code splitting with dynamic `import()` for large optional features'
+  - 'Yielding to the event loop during large data processing to avoid blocking the main thread'
+  - 'Auth tokens obtained from the auth flow, never hardcoded'
+---
+
+# Browser SDK Security and Performance Optimization
+
+Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread.
+
+## Code
+
+```typescript
+// src/main.ts — Server-side: configure CORS and CSP for browser clients
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'browser-api', version: '1.0.0' },
+  apps: [MyApp],
+
+  // CORS configured for browser origins
+  cors: {
+    origin: ['https://app.example.com', 'https://admin.example.com'],
+    credentials: true,
+    maxAge: 86400,
+  },
+
+  // API keys stay server-side — browser clients use session tokens
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env.AUTH_CLIENT_ID!,
+  },
+})
+export default class BrowserApiServer {}
+```
+
+```typescript
+// src/browser-sdk/index.ts — Browser SDK entry point
+// No secrets in this code — it ships to the browser!
+
+export async function createClient(config: { baseUrl: string; token: string }) {
+  // Token comes from the auth flow, not hardcoded
+  const headers = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${config.token}`,
+  };
+
+  return {
+    async callTool(name: string, args: Record<string, unknown>) {
+      const response = await fetch(`${config.baseUrl}/mcp`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'tools/call',
+          params: { name, arguments: args },
+          id: crypto.randomUUID(),
+        }),
+      });
+      return response.json();
+    },
+
+    async listTools() {
+      const response = await fetch(`${config.baseUrl}/mcp`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'tools/list',
+          id: crypto.randomUUID(),
+        }),
+      });
+      return response.json();
+    },
+  };
+}
+```
+
+```typescript
+// src/browser-sdk/lazy-features.ts — Code splitting for large optional features
+
+// Lazy-load heavy features — don't include in the main bundle
+export async function loadVectorSearch() {
+  const { TFIDFVectoria } = await import('vectoriadb');
+  return new TFIDFVectoria({ defaultTopK: 10 });
+}
+
+// Use in a non-blocking way
+export async function processLargeDataset(data: string[]): Promise<string[]> {
+  // Don't block the main thread — yield periodically
+  const results: string[] = [];
+  const BATCH_SIZE = 100;
+
+  for (let i = 0; i < data.length; i += BATCH_SIZE) {
+    const batch = data.slice(i, i + BATCH_SIZE);
+    results.push(...batch.map((item) => item.toUpperCase()));
+
+    // Yield to the event loop between batches
+    if (i + BATCH_SIZE < data.length) {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+
+  return results;
+}
+```
+
+## What This Demonstrates
+
+- No secrets (API keys, tokens) in the browser bundle -- using server-side proxy
+- CORS configured on the server to accept specific browser origins
+- Code splitting with dynamic `import()` for large optional features
+- Yielding to the event loop during large data processing to avoid blocking the main thread
+- Auth tokens obtained from the auth flow, never hardcoded
+
+## Related
+
+- See `production-browser` for the full security, distribution, and performance checklist

package/catalog/frontmcp-production-readiness/examples/production-cli-binary/binary-build-config.md

@@ -0,0 +1,109 @@
+---
+name: binary-build-config
+reference: production-cli-binary
+level: basic
+description: 'Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings.'
+tags: [production, cli, transport, node, binary, config]
+features:
+  - 'Correct `bin` field in package.json pointing to the built output'
+  - 'Shebang line (`#!/usr/bin/env node`) for direct execution'
+  - 'Handling `--version` and `--help` flags before server initialization'
+  - 'Using stderr for logging (stdout is the MCP channel)'
+  - '`files` field excluding source, tests, and config from the published package'
+---
+
+# CLI Binary Build and Package Configuration
+
+Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings.
+
+## Code
+
+```jsonc
+// package.json
+{
+  "name": "my-mcp-cli",
+  "version": "1.0.0",
+  "description": "MCP CLI tool for data processing",
+  "keywords": ["mcp", "cli", "data-processing"],
+  "license": "MIT",
+
+  // Binary entry point
+  "bin": {
+    "my-mcp-cli": "./dist/cli.js",
+  },
+
+  // Only ship what users need
+  "files": ["dist/", "README.md", "LICENSE"],
+
+  // Required Node.js version
+  "engines": {
+    "node": ">=18.0.0",
+  },
+
+  "dependencies": {
+    "@frontmcp/sdk": "^1.0.0",
+    "zod": "^4.0.0",
+  },
+
+  "scripts": {
+    "build": "frontmcp build --target cli",
+    "test": "jest --coverage",
+    "prepublishOnly": "npm run build && npm test",
+  },
+}
+```
+
+```typescript
+#!/usr/bin/env node
+// src/cli.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+// Handle --version and --help before server initialization
+if (process.argv.includes('--version')) {
+  console.error('my-mcp-cli v1.0.0');
+  process.exit(0);
+}
+
+if (process.argv.includes('--help')) {
+  console.error('Usage: my-mcp-cli');
+  console.error('  Runs an MCP server via stdio transport.');
+  console.error('  Reads JSON-RPC from stdin, writes to stdout.');
+  console.error('');
+  console.error('Options:');
+  console.error('  --version  Show version');
+  console.error('  --help     Show this help');
+  process.exit(0);
+}
+
+@FrontMcp({
+  info: { name: 'my-mcp-cli', version: '1.0.0' },
+  apps: [MyApp],
+  // Stdio transport: reads JSON-RPC from stdin, writes to stdout
+})
+class CliServer {}
+```
+
+```bash
+# Build and verify
+frontmcp build --target cli
+
+# Verify binary starts quickly
+time my-mcp-cli --help    # Should complete in < 500ms
+time my-mcp-cli --version # Should complete in < 500ms
+
+# Test stdio transport
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | my-mcp-cli
+```
+
+## What This Demonstrates
+
+- Correct `bin` field in package.json pointing to the built output
+- Shebang line (`#!/usr/bin/env node`) for direct execution
+- Handling `--version` and `--help` flags before server initialization
+- Using stderr for logging (stdout is the MCP channel)
+- `files` field excluding source, tests, and config from the published package
+
+## Related
+
+- See `production-cli-binary` for the full build and distribution checklist