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

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

package/catalog/frontmcp-production-readiness/examples/production-cli-binary/stdio-transport-error-handling.md

@@ -0,0 +1,132 @@
+---
+name: stdio-transport-error-handling
+reference: production-cli-binary
+level: intermediate
+description: 'Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.'
+tags: [production, json-rpc, cli, transport, binary, stdio]
+features:
+  - 'Exit code conventions: 0 (success), 1 (user error), 2 (internal error)'
+  - 'Using stderr for all logging since stdout is the MCP JSON-RPC channel'
+  - 'Handling EOF on stdin and broken pipe on stdout gracefully'
+  - 'Showing helpful error messages for unknown flags instead of stack traces'
+  - 'Validating file paths to prevent writes to unexpected locations'
+---
+
+# Stdio Transport with Error Handling and Exit Codes
+
+Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.
+
+## Code
+
+```typescript
+#!/usr/bin/env node
+// src/cli.ts
+
+// Handle flags early — before any heavy imports
+const args = process.argv.slice(2);
+const unknownFlags = args.filter((a) => a.startsWith('-') && !['--version', '--help'].includes(a));
+
+if (unknownFlags.length > 0) {
+  // User error: unknown flags — show helpful message, not stack trace
+  console.error(`Error: Unknown flag(s): ${unknownFlags.join(', ')}`);
+  console.error('Run "my-mcp-cli --help" for usage.');
+  process.exit(1); // Exit code 1: user error
+}
+
+if (args.includes('--version')) {
+  console.error('my-mcp-cli v1.0.0');
+  process.exit(0);
+}
+
+async function main() {
+  try {
+    // Lazy-load to keep startup fast
+    const { FrontMcp } = await import('@frontmcp/sdk');
+    const { MyApp } = await import('./my.app');
+
+    // stderr for all logging — stdout is the MCP JSON-RPC channel
+    console.error('[my-mcp-cli] Starting MCP server via stdio...');
+
+    // Handle EOF on stdin gracefully
+    process.stdin.on('end', () => {
+      console.error('[my-mcp-cli] stdin closed. Exiting.');
+      process.exit(0);
+    });
+
+    // Handle broken pipe on stdout gracefully
+    process.stdout.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EPIPE') {
+        console.error('[my-mcp-cli] stdout pipe broken. Exiting.');
+        process.exit(0);
+      }
+      console.error('[my-mcp-cli] stdout error:', err.message);
+      process.exit(2); // Exit code 2: internal error
+    });
+
+    // Start the server (stdio transport)
+    @FrontMcp({
+      info: { name: 'my-mcp-cli', version: '1.0.0' },
+      apps: [MyApp],
+    })
+    class CliServer {}
+  } catch (err) {
+    // Internal error: log to stderr, exit with code 2
+    console.error('[my-mcp-cli] Fatal error:', err instanceof Error ? err.message : String(err));
+    process.exit(2);
+  }
+}
+
+main();
+```
+
+```typescript
+// src/tools/safe-tool.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'process_file',
+  description: 'Process a file path safely',
+  inputSchema: {
+    path: z.string().min(1).describe('File path to process'),
+  },
+  outputSchema: {
+    result: z.string(),
+    path: z.string(),
+  },
+})
+export class SafeFileTool extends ToolContext {
+  async execute(input: { path: string }) {
+    // Use os.homedir() and os.tmpdir() — no hardcoded paths
+    const os = await import('os');
+    const pathMod = await import('path');
+
+    // Ensure we only read from safe locations
+    const resolved = pathMod.resolve(input.path);
+    const home = os.homedir();
+    const tmp = os.tmpdir();
+
+    const relToHome = pathMod.relative(home, resolved);
+    const relToTmp = pathMod.relative(tmp, resolved);
+    const isInHome = !relToHome.startsWith('..') && !pathMod.isAbsolute(relToHome);
+    const isInTmp = !relToTmp.startsWith('..') && !pathMod.isAbsolute(relToTmp);
+    if (!isInHome && !isInTmp) {
+      this.fail(new Error('Path must be within home directory or temp directory'));
+    }
+
+    return { result: 'processed', path: resolved };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Exit code conventions: 0 (success), 1 (user error), 2 (internal error)
+- Using stderr for all logging since stdout is the MCP JSON-RPC channel
+- Handling EOF on stdin and broken pipe on stdout gracefully
+- Showing helpful error messages for unknown flags instead of stack traces
+- Validating file paths to prevent writes to unexpected locations
+
+## Related
+
+- See `production-cli-binary` for the full stdin/stdout transport and exit behavior checklist

package/catalog/frontmcp-production-readiness/examples/production-cli-daemon/daemon-socket-config.md

@@ -0,0 +1,82 @@
+---
+name: daemon-socket-config
+reference: production-cli-daemon
+level: basic
+description: 'Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.'
+tags: [production, unix-socket, sqlite, cli, transport, performance]
+features:
+  - 'Configuring Unix socket transport for local-only communication'
+  - 'Using SQLite with WAL mode for concurrent read/write performance'
+  - 'Storing data in user-specific config directory (`~/.config/`)'
+  - 'Process management with `frontmcp start/stop/restart/status/logs`'
+  - 'System service registration for auto-start on boot'
+---
+
+# Daemon Process with Unix Socket Transport
+
+Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'my-daemon', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Unix socket transport — no network exposure
+  http: {
+    socketPath: '/tmp/my-daemon.sock',
+  },
+
+  // SQLite for local persistence (sessions, cache)
+  sqlite: {
+    path: `${process.env.HOME}/.config/my-daemon/data.db`,
+    wal: true, // WAL mode for concurrent reads
+  },
+})
+export default class MyDaemonServer {}
+```
+
+```bash
+# Process management commands
+
+# Start the daemon
+frontmcp start my-daemon --entry ./src/main.ts
+
+# Check status
+frontmcp status
+# Output: my-daemon  running  pid:12345  socket:/tmp/my-daemon.sock
+
+# View logs
+frontmcp logs my-daemon --follow
+
+# Restart without orphaned processes
+frontmcp restart my-daemon
+
+# Stop cleanly
+frontmcp stop my-daemon
+```
+
+```bash
+# Register as a system service (auto-start on boot)
+frontmcp service install my-daemon
+
+# Verify system health
+frontmcp doctor
+```
+
+## What This Demonstrates
+
+- Configuring Unix socket transport for local-only communication
+- Using SQLite with WAL mode for concurrent read/write performance
+- Storing data in user-specific config directory (`~/.config/`)
+- Process management with `frontmcp start/stop/restart/status/logs`
+- System service registration for auto-start on boot
+
+## Related
+
+- See `production-cli-daemon` for the full daemon process management checklist

package/catalog/frontmcp-production-readiness/examples/production-cli-daemon/graceful-shutdown-cleanup.md

@@ -0,0 +1,107 @@
+---
+name: graceful-shutdown-cleanup
+reference: production-cli-daemon
+level: intermediate
+description: 'Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file.'
+tags: [production, unix-socket, cli, database, daemon, graceful]
+features:
+  - 'SIGTERM handler that completes in-flight requests before exiting'
+  - 'Removing the Unix socket file to prevent stale `.sock` files on restart'
+  - 'Cleaning up the PID file on shutdown'
+  - 'Using `@frontmcp/utils` (`unlink`, `fileExists`, `ensureDir`) for file operations'
+  - 'Implementing `onDestroy()` to close database connections'
+---
+
+# Daemon Graceful Shutdown with Socket Cleanup
+
+Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file.
+
+## Code
+
+```typescript
+// src/lifecycle/daemon-shutdown.ts
+import { unlink, fileExists } from '@frontmcp/utils';
+
+export function setupDaemonShutdown(server: { close: () => Promise<void>; dispose: () => Promise<void> }): void {
+  const socketPath = '/tmp/my-daemon.sock';
+  const pidFile = `${process.env.HOME}/.config/my-daemon/daemon.pid`;
+
+  const shutdown = async (signal: string) => {
+    console.log(`[daemon] Received ${signal}. Shutting down...`);
+
+    // 1. Stop accepting new connections
+    await server.close();
+    console.log('[daemon] Server closed.');
+
+    // 2. Dispose all resources (SQLite, providers)
+    await server.dispose();
+    console.log('[daemon] Resources disposed.');
+
+    // 3. Remove socket file (prevent stale .sock files)
+    if (await fileExists(socketPath)) {
+      await unlink(socketPath);
+      console.log(`[daemon] Socket removed: ${socketPath}`);
+    }
+
+    // 4. Clean up PID file
+    if (await fileExists(pidFile)) {
+      await unlink(pidFile);
+      console.log(`[daemon] PID file removed: ${pidFile}`);
+    }
+
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+```
+
+```typescript
+// src/providers/sqlite-store.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const LOCAL_STORE = Symbol('LocalStore');
+
+@Provider({ token: LOCAL_STORE, scope: ProviderScope.GLOBAL })
+export class SqliteStoreProvider {
+  private db!: { close: () => void; exec: (sql: string) => void };
+
+  async onInit(): Promise<void> {
+    // Database path is configurable, not hardcoded
+    const dbPath = process.env.DB_PATH ?? `${process.env.HOME}/.config/my-daemon/data.db`;
+
+    // Ensure directory exists
+    const { ensureDir } = await import('@frontmcp/utils');
+    const path = await import('path');
+    await ensureDir(path.dirname(dbPath));
+
+    // Initialize with WAL mode for concurrent reads
+    // Auto-migrate on startup
+    this.db = await this.openDatabase(dbPath);
+    this.db.exec('PRAGMA journal_mode=WAL');
+  }
+
+  async onDestroy(): Promise<void> {
+    // Close database connection on shutdown
+    this.db.close();
+  }
+
+  private async openDatabase(path: string) {
+    // Replace with your SQLite driver (e.g., better-sqlite3)
+    throw new Error('Implement with your SQLite driver');
+  }
+}
+```
+
+## What This Demonstrates
+
+- SIGTERM handler that completes in-flight requests before exiting
+- Removing the Unix socket file to prevent stale `.sock` files on restart
+- Cleaning up the PID file on shutdown
+- Using `@frontmcp/utils` (`unlink`, `fileExists`, `ensureDir`) for file operations
+- Implementing `onDestroy()` to close database connections
+
+## Related
+
+- See `production-cli-daemon` for the full graceful shutdown and security checklist

package/catalog/frontmcp-production-readiness/examples/production-cli-daemon/security-and-permissions.md

@@ -0,0 +1,119 @@
+---
+name: security-and-permissions
+reference: production-cli-daemon
+level: advanced
+description: 'Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.'
+tags: [production, cli, transport, security, local, node]
+features:
+  - 'XDG Base Directory compliance for config and data storage'
+  - 'Restrictive file permissions: config at `700`, secrets at `600`'
+  - 'Verifying secret file permissions before reading (fail if insecure)'
+  - 'Socket-only transport with no TCP network exposure'
+  - 'Using `@frontmcp/utils` for file operations instead of `node:fs`'
+---
+
+# Daemon Security: Socket Permissions, Config Storage, and Secret Management
+
+Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.
+
+## Code
+
+```typescript
+// src/lifecycle/daemon-security.ts
+import { stat, writeFile, fileExists, ensureDir, readFile } from '@frontmcp/utils';
+import { chmod } from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+
+// XDG Base Directory compliance
+function getConfigDir(appName: string): string {
+  return process.env.XDG_CONFIG_HOME
+    ? path.join(process.env.XDG_CONFIG_HOME, appName)
+    : path.join(os.homedir(), '.config', appName);
+}
+
+function getDataDir(appName: string): string {
+  return process.env.XDG_DATA_HOME
+    ? path.join(process.env.XDG_DATA_HOME, appName)
+    : path.join(os.homedir(), '.local', 'share', appName);
+}
+
+export async function ensureSecureSetup(appName: string): Promise<{
+  configDir: string;
+  dataDir: string;
+}> {
+  const configDir = getConfigDir(appName);
+  const dataDir = getDataDir(appName);
+
+  // Create directories with restrictive permissions
+  await ensureDir(configDir);
+  await ensureDir(dataDir);
+
+  // Config directory: owner-only access (700)
+  await chmod(configDir, 0o700);
+
+  // Secrets file: owner-only read/write (600)
+  const secretsFile = path.join(configDir, 'secrets.json');
+  if (await fileExists(secretsFile)) {
+    await chmod(secretsFile, 0o600);
+  }
+
+  return { configDir, dataDir };
+}
+
+export async function loadSecrets(configDir: string): Promise<Record<string, string>> {
+  const secretsFile = path.join(configDir, 'secrets.json');
+
+  if (!(await fileExists(secretsFile))) {
+    return {};
+  }
+
+  // Verify permissions before reading
+  const fileStat = await stat(secretsFile);
+  const mode = fileStat.mode & 0o777;
+  if (mode !== 0o600) {
+    throw new Error(
+      `Secrets file has insecure permissions: ${mode.toString(8)}. Expected 600. ` +
+        `Fix with: chmod 600 ${secretsFile}`,
+    );
+  }
+
+  const content = await readFile(secretsFile);
+  return JSON.parse(content);
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'secure-daemon', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Socket-only — no TCP network exposure
+  http: {
+    socketPath: '/tmp/secure-daemon.sock',
+  },
+
+  // SQLite in the data directory (persistent, writable)
+  sqlite: {
+    path: `${process.env.XDG_DATA_HOME ?? process.env.HOME + '/.local/share'}/secure-daemon/data.db`,
+    wal: true,
+  },
+})
+export default class SecureDaemonServer {}
+```
+
+## What This Demonstrates
+
+- XDG Base Directory compliance for config and data storage
+- Restrictive file permissions: config at `700`, secrets at `600`
+- Verifying secret file permissions before reading (fail if insecure)
+- Socket-only transport with no TCP network exposure
+- Using `@frontmcp/utils` for file operations instead of `node:fs`
+
+## Related
+
+- See `production-cli-daemon` for the full security and storage checklist