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

package/catalog/frontmcp-guides/examples/example-weather-api/weather-tool-with-schemas.md

@@ -0,0 +1,74 @@
+---
+name: weather-tool-with-schemas
+reference: example-weather-api
+level: basic
+description: 'Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`.'
+tags: [guides, weather, api, tool, schemas]
+features:
+  - 'Defining Zod `inputSchema` with validation (`.min(1)`, `.enum()`, `.default()`)'
+  - 'Defining `outputSchema` to prevent data leaks and ensure type safety'
+  - 'Using `this.fetch()` for HTTP calls within tools'
+  - 'Using `this.fail()` for business-logic error handling'
+  - 'Using `.describe()` on schema fields for LLM-friendly tool descriptions'
+---
+
+# Weather Tool with Zod Input/Output Schemas
+
+Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`.
+
+## Code
+
+```typescript
+// src/tools/get-weather.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_weather',
+  description: 'Get current weather for a city',
+  inputSchema: {
+    city: z.string().min(1).describe('City name'),
+    units: z.enum(['celsius', 'fahrenheit']).default('celsius').describe('Temperature units'),
+  },
+  outputSchema: {
+    temperature: z.number(),
+    condition: z.string(),
+    humidity: z.number(),
+    city: z.string(),
+  },
+})
+export class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string; units: 'celsius' | 'fahrenheit' }) {
+    const url = `https://api.weather.example.com/v1/current?city=${encodeURIComponent(input.city)}&units=${input.units}`;
+
+    // Use this.fetch() for HTTP calls — the framework handles errors in the tool execution flow.
+    const response = await this.fetch(url);
+
+    if (!response.ok) {
+      // Use this.fail() for business-logic errors
+      this.fail(new Error(`Weather API error: ${response.status} ${response.statusText}`));
+    }
+
+    const data = await response.json();
+
+    return {
+      temperature: data.temp,
+      condition: data.condition,
+      humidity: data.humidity,
+      city: input.city,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Defining Zod `inputSchema` with validation (`.min(1)`, `.enum()`, `.default()`)
+- Defining `outputSchema` to prevent data leaks and ensure type safety
+- Using `this.fetch()` for HTTP calls within tools
+- Using `this.fail()` for business-logic error handling
+- Using `.describe()` on schema fields for LLM-friendly tool descriptions
+
+## Related
+
+- See `example-weather-api` for the full end-to-end weather API example with tests

package/catalog/frontmcp-guides/references/example-knowledge-base.md

@@ -639,3 +639,13 @@ describe('AuditLogPlugin', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                            | Level        | Description                                                                                                                                   |
+| -------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`agent-and-plugin`](../examples/example-knowledge-base/agent-and-plugin.md)                       | Advanced     | Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.    |
+| [`multi-app-composition`](../examples/example-knowledge-base/multi-app-composition.md)             | Basic        | Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration. |
+| [`vector-search-and-resources`](../examples/example-knowledge-base/vector-search-and-resources.md) | Intermediate | Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.           |
+
+> See all examples in [`examples/example-knowledge-base/`](../examples/example-knowledge-base/)

package/catalog/frontmcp-guides/references/example-task-manager.md

@@ -509,3 +509,13 @@ describe('Task Manager E2E', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                  | Level        | Description                                                                                                                                    |
+| ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`auth-and-crud-tools`](../examples/example-task-manager/auth-and-crud-tools.md)         | Basic        | Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection. |
+| [`authenticated-e2e-tests`](../examples/example-task-manager/authenticated-e2e-tests.md) | Advanced     | Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.              |
+| [`redis-provider-with-di`](../examples/example-task-manager/redis-provider-with-di.md)   | Intermediate | Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.                  |
+
+> See all examples in [`examples/example-task-manager/`](../examples/example-task-manager/)

package/catalog/frontmcp-guides/references/example-weather-api.md

@@ -292,3 +292,13 @@ describe('Weather Server E2E', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                     | Level        | Description                                                                                                                            |
+| ------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [`server-and-app-setup`](../examples/example-weather-api/server-and-app-setup.md)           | Basic        | Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.                        |
+| [`unit-and-e2e-tests`](../examples/example-weather-api/unit-and-e2e-tests.md)               | Intermediate | Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.              |
+| [`weather-tool-with-schemas`](../examples/example-weather-api/weather-tool-with-schemas.md) | Basic        | Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`. |
+
+> See all examples in [`examples/example-weather-api/`](../examples/example-weather-api/)

package/catalog/frontmcp-production-readiness/SKILL.md

@@ -9,7 +9,7 @@ priority: 10
 visibility: both
 license: Apache-2.0
 metadata:
-  docs: https://docs.agentfront.dev/frontmcp/production/overview
+  docs: https://docs.agentfront.dev/frontmcp/deployment/production-build
 ---
 
 # FrontMCP Production Readiness Audit
@@ -94,5 +94,5 @@ After completing both common and target-specific checklists:
 
 ## Reference
 
-- [FrontMCP Production Guide](https://docs.agentfront.dev/frontmcp/production)
+- [Production Build](https://docs.agentfront.dev/frontmcp/deployment/production-build)
 - Related skills: `frontmcp-config`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-setup`

package/catalog/frontmcp-production-readiness/examples/common-checklist/caching-and-performance.md

@@ -0,0 +1,102 @@
+---
+name: caching-and-performance
+reference: common-checklist
+level: advanced
+description: 'Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.'
+tags: [production, redis, cache, session, performance, checklist]
+features:
+  - 'Configuring per-tool cache TTL instead of a single global value'
+  - 'Using Redis-backed cache for multi-instance consistency'
+  - 'Setting session TTL to prevent unbounded storage growth'
+  - 'Implementing `onDestroy()` in providers for proper connection cleanup'
+  - 'Using connection pool limits and timeouts to prevent resource exhaustion'
+---
+
+# Caching and Performance Configuration
+
+Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { CachePlugin } from '@frontmcp/plugins';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'perf-server', version: '1.0.0' },
+  apps: [MyApp],
+  plugins: [
+    new CachePlugin({
+      // Per-tool TTL tuning (not one-size-fits-all)
+      ttl: {
+        get_weather: 300_000, // 5 minutes — data changes slowly
+        list_tasks: 10_000, // 10 seconds — data changes frequently
+      },
+      defaultTtl: 60_000, // 1 minute default
+    }),
+  ],
+
+  // Redis for multi-instance cache consistency
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: 6379,
+  },
+
+  // Session TTL to prevent unbounded growth
+  session: {
+    ttl: 3600_000, // 1 hour
+  },
+})
+export default class PerfServer {}
+```
+
+```typescript
+// src/providers/db-connection.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const DB_POOL = Symbol('DbPool');
+
+@Provider({ token: DB_POOL, scope: ProviderScope.GLOBAL })
+export class DbConnectionProvider {
+  private pool!: { query: Function; end: Function };
+
+  async onInit(): Promise<void> {
+    // Connection pool with limits — prevents resource exhaustion
+    this.pool = await this.createPool({
+      host: process.env.DB_HOST,
+      max: 20, // Maximum connections
+      idleTimeoutMs: 30_000, // Close idle connections after 30s
+      connectionTimeoutMs: 5_000, // Don't hang on connection attempts
+    });
+  }
+
+  async query(sql: string, params: unknown[]): Promise<unknown> {
+    return this.pool.query(sql, params); // Parameterized — no SQL injection
+  }
+
+  async onDestroy(): Promise<void> {
+    // Clean up on shutdown — prevents connection leaks
+    await this.pool.end();
+  }
+
+  private async createPool(config: Record<string, unknown>): Promise<{ query: Function; end: Function }> {
+    // Replace with your database driver (e.g., pg, mysql2)
+    throw new Error('Implement with your database driver');
+  }
+}
+```
+
+## What This Demonstrates
+
+- Configuring per-tool cache TTL instead of a single global value
+- Using Redis-backed cache for multi-instance consistency
+- Setting session TTL to prevent unbounded storage growth
+- Implementing `onDestroy()` in providers for proper connection cleanup
+- Using connection pool limits and timeouts to prevent resource exhaustion
+
+## Related
+
+- See `common-checklist` for the full performance and memory management checklist

package/catalog/frontmcp-production-readiness/examples/common-checklist/observability-setup.md

@@ -0,0 +1,104 @@
+---
+name: observability-setup
+reference: common-checklist
+level: intermediate
+description: 'Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production.'
+tags: [production, observability, checklist, setup]
+features:
+  - 'Using `this.mark()` to annotate execution phases for tracing'
+  - 'Using `this.fail()` for business-logic errors without exposing internals'
+  - 'Setting timeouts on all external calls via `AbortSignal.timeout()`'
+  - 'Implementing health check providers that verify downstream dependencies'
+---
+
+# Observability and Error Handling Setup
+
+Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production.
+
+## Code
+
+```typescript
+// src/tools/monitored-tool.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'monitored_operation',
+  description: 'A tool with proper error handling and observability markers',
+  inputSchema: {
+    operationId: z.string().min(1).describe('Operation identifier'),
+  },
+  outputSchema: {
+    status: z.string(),
+    operationId: z.string(),
+  },
+})
+export class MonitoredOperationTool extends ToolContext {
+  async execute(input: { operationId: string }) {
+    // Mark execution phases for tracing and duration metrics
+    this.mark('validation');
+    // ... validate business rules ...
+
+    this.mark('processing');
+    const result = await this.processOperation(input.operationId);
+
+    if (!result) {
+      // Use this.fail() with specific errors — never expose stack traces
+      this.fail(new Error(`Operation not found: ${input.operationId}`));
+    }
+
+    // Report progress for long-running operations
+    await this.respondProgress(1, 1);
+
+    return { status: 'completed', operationId: input.operationId };
+  }
+
+  private async processOperation(id: string): Promise<boolean> {
+    // External call with timeout — always set timeouts for external services
+    const response = await this.fetch(`https://api.example.com/operations/${id}`, {
+      signal: AbortSignal.timeout(5000), // 5 second timeout
+    });
+    return response.ok;
+  }
+}
+```
+
+```typescript
+// src/providers/health-check.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const HEALTH_CHECK = Symbol('HealthCheck');
+
+@Provider({ token: HEALTH_CHECK, scope: ProviderScope.GLOBAL })
+export class HealthCheckProvider {
+  async checkRedis(): Promise<boolean> {
+    // Verify downstream dependency is reachable
+    try {
+      // ... ping Redis ...
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async checkDatabase(): Promise<boolean> {
+    try {
+      // ... run a lightweight query ...
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `this.mark()` to annotate execution phases for tracing
+- Using `this.fail()` for business-logic errors without exposing internals
+- Setting timeouts on all external calls via `AbortSignal.timeout()`
+- Implementing health check providers that verify downstream dependencies
+
+## Related
+
+- See `common-checklist` for the full observability and monitoring checklist

package/catalog/frontmcp-production-readiness/examples/common-checklist/security-hardening.md

@@ -0,0 +1,95 @@
+---
+name: security-hardening
+reference: common-checklist
+level: basic
+description: 'Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.'
+tags: [production, redis, session, security, throttle, checklist]
+features:
+  - "Restricting CORS origins to known domains instead of using `'*'`"
+  - 'Configuring rate limiting via the `throttle` option'
+  - 'Using Redis for session storage in multi-instance deployments'
+  - 'Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks'
+---
+
+# Security Hardening Configuration
+
+Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'secure-server', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Authentication: use remote OAuth provider
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env.AUTH_CLIENT_ID!,
+  },
+
+  // CORS: restrict to known origins (never use '*' in production)
+  cors: {
+    origin: ['https://app.example.com', 'https://admin.example.com'],
+    credentials: true,
+    maxAge: 86400, // Cache preflight for 24 hours
+  },
+
+  // Rate limiting: prevent abuse
+  throttle: {
+    windowMs: 60_000, // 1 minute window
+    max: 100, // 100 requests per window per client
+  },
+
+  // Session storage: use Redis (not in-memory) for multi-instance
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: 6379,
+  },
+})
+export default class SecureServer {}
+```
+
+```typescript
+// src/tools/safe-query.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'safe_query',
+  description: 'Query data with validated and sanitized input',
+  inputSchema: {
+    query: z.string().min(1).max(500).describe('Search query'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results'),
+  },
+  outputSchema: {
+    results: z.array(z.object({ id: z.string(), title: z.string() })),
+    total: z.number(),
+  },
+})
+export class SafeQueryTool extends ToolContext {
+  async execute(input: { query: string; limit: number }) {
+    // Zod already validated input — safe to use
+    // outputSchema prevents accidental data leaks
+    return { results: [], total: 0 };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Restricting CORS origins to known domains instead of using `'*'`
+- Configuring rate limiting via the `throttle` option
+- Using Redis for session storage in multi-instance deployments
+- Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks
+
+## Related
+
+- See `common-checklist` for the full security, performance, and reliability checklist

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