@frontmcp/skills 1.0.0-beta.9 → 1.0.0

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

package/catalog/frontmcp-production-readiness/examples/production-cloudflare/durable-objects-state.md

@@ -0,0 +1,124 @@
+---
+name: durable-objects-state
+reference: production-cloudflare
+level: advanced
+description: 'Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage.'
+tags: [production, cloudflare, cache, throttle, durable, objects]
+features:
+  - 'Using Durable Objects for stateful coordination (rate limiting) in an ephemeral Workers runtime'
+  - 'Using R2 for blob/file storage since Workers have no filesystem'
+  - 'Combining KV (cache), R2 (files), and Durable Objects (state) in one deployment'
+  - 'Wrangler configuration with all three binding types'
+---
+
+# Stateful Coordination with Durable Objects
+
+Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage.
+
+## Code
+
+```toml
+# wrangler.toml — with Durable Objects and R2
+name = "stateful-mcp-worker"
+main = "dist/worker.js"
+compatibility_date = "2024-01-01"
+
+# KV for cache
+[[kv_namespaces]]
+binding = "CACHE"
+id = "cache-namespace-id"
+
+# R2 for blob/file storage
+[[r2_buckets]]
+binding = "FILES"
+bucket_name = "mcp-files"
+
+# Durable Objects for stateful coordination
+[durable_objects]
+bindings = [
+  { name = "RATE_LIMITER", class_name = "RateLimiterDO" }
+]
+
+[[migrations]]
+tag = "v1"
+new_classes = ["RateLimiterDO"]
+```
+
+```typescript
+// src/tools/rate-limited-action.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'rate_limited_action',
+  description: 'An action that uses Durable Objects for distributed rate limiting',
+  inputSchema: {
+    userId: z.string().min(1).describe('User identifier'),
+    action: z.string().min(1).describe('Action to perform'),
+  },
+  outputSchema: {
+    allowed: z.boolean(),
+    remaining: z.number(),
+    action: z.string(),
+  },
+})
+export class RateLimitedActionTool extends ToolContext {
+  async execute(input: { userId: string; action: string }) {
+    // Durable Objects provide stateful rate limiting across Workers instances
+    // Each user gets their own Durable Object instance for consistent state
+    const result = await this.fetch(`https://internal/rate-check/${input.userId}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: input.action }),
+    });
+
+    const { allowed, remaining } = await result.json();
+
+    if (!allowed) {
+      this.fail(new Error(`Rate limit exceeded for user ${input.userId}`));
+    }
+
+    return { allowed, remaining, action: input.action };
+  }
+}
+```
+
+```typescript
+// src/tools/file-upload.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'upload_file',
+  description: 'Upload a file to R2 object storage',
+  inputSchema: {
+    filename: z.string().min(1).describe('File name'),
+    content: z.string().min(1).describe('File content (base64 encoded)'),
+  },
+  outputSchema: {
+    key: z.string(),
+    url: z.string(),
+    size: z.number(),
+  },
+})
+export class FileUploadTool extends ToolContext {
+  async execute(input: { filename: string; content: string }) {
+    // R2 for blob/file storage — no filesystem in Workers
+    const key = `uploads/${Date.now()}-${input.filename}`;
+    const size = input.content.length;
+
+    return { key, url: `https://files.example.com/${key}`, size };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using Durable Objects for stateful coordination (rate limiting) in an ephemeral Workers runtime
+- Using R2 for blob/file storage since Workers have no filesystem
+- Combining KV (cache), R2 (files), and Durable Objects (state) in one deployment
+- Wrangler configuration with all three binding types
+
+## Related
+
+- See `production-cloudflare` for the full storage and scaling checklist

package/catalog/frontmcp-production-readiness/examples/production-cloudflare/workers-runtime-constraints.md

@@ -0,0 +1,103 @@
+---
+name: workers-runtime-constraints
+reference: production-cloudflare
+level: intermediate
+description: 'Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.'
+tags: [production, cloudflare, node, workers, runtime, constraints]
+features:
+  - 'Using `@frontmcp/utils` for crypto instead of `node:crypto` (Workers use V8 isolates, not Node)'
+  - 'All I/O is async (no synchronous blocking operations allowed in Workers)'
+  - 'No `eval()` or dynamic `Function()` (prohibited in Workers)'
+  - 'No filesystem access (Workers have no filesystem)'
+  - 'Using Fetch API via `this.fetch()` instead of Node.js `http`/`https`'
+---
+
+# Workers Runtime Constraints and Compatibility
+
+Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.
+
+## Code
+
+```typescript
+// src/tools/worker-safe.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+// Use @frontmcp/utils — wraps Web Crypto API, works in Workers
+import { sha256Hex, randomUUID, base64urlEncode } from '@frontmcp/utils';
+
+@Tool({
+  name: 'transform_data',
+  description: 'Transform and hash data in a Workers-compatible way',
+  inputSchema: {
+    payload: z.string().min(1).describe('Data to transform'),
+  },
+  outputSchema: {
+    id: z.string(),
+    hash: z.string(),
+    encoded: z.string(),
+    timestamp: z.string(),
+  },
+})
+export class TransformDataTool extends ToolContext {
+  async execute(input: { payload: string }) {
+    // All operations are async — no synchronous blocking
+
+    // Cross-platform crypto (Web Crypto under the hood)
+    const id = randomUUID();
+    const hash = sha256Hex(input.payload);
+    const encoded = base64urlEncode(input.payload);
+
+    // Use this.fetch() — standard Fetch API, not node http
+    const response = await this.fetch('https://api.example.com/transform', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id, payload: input.payload }),
+    });
+
+    if (!response.ok) {
+      this.fail(new Error(`Transform API error: ${response.status}`));
+    }
+
+    return {
+      id,
+      hash,
+      encoded,
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+```
+
+```typescript
+// src/providers/kv-store.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const KV_STORE = Symbol('KvStore');
+
+// Workers KV — no filesystem, no eval, no dynamic Function()
+@Provider({ token: KV_STORE, scope: ProviderScope.GLOBAL })
+export class KvStoreProvider {
+  // Workers KV is bound via wrangler.toml, accessed from env
+  async get(key: string): Promise<string | null> {
+    // In Workers, KV is available via the environment binding
+    // This is a pattern — actual binding depends on your worker setup
+    return null;
+  }
+
+  async put(key: string, value: string, ttlSeconds?: number): Promise<void> {
+    // KV put with optional TTL
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `@frontmcp/utils` for crypto instead of `node:crypto` (Workers use V8 isolates, not Node)
+- All I/O is async (no synchronous blocking operations allowed in Workers)
+- No `eval()` or dynamic `Function()` (prohibited in Workers)
+- No filesystem access (Workers have no filesystem)
+- Using Fetch API via `this.fetch()` instead of Node.js `http`/`https`
+
+## Related
+
+- See `production-cloudflare` for the full Workers runtime and performance checklist