@frontmcp/skills 1.0.3 → 1.1.0-beta.1

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

@@ -16,10 +16,11 @@ A multi-app knowledge base MCP server with three composed apps: document ingesti
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { IngestionApp } from './ingestion/ingestion.app';
-import { SearchApp } from './search/search.app';
-import { ResearchApp } from './research/research.app';
 import { AuditLogPlugin } from './plugins/audit-log.plugin';
+import { ResearchApp } from './research/research.app';
+import { SearchApp } from './search/search.app';
 
 @FrontMcp({
   info: { name: 'knowledge-base', version: '1.0.0' },
@@ -40,6 +41,7 @@ export default class KnowledgeBaseServer {}
 ```typescript
 // src/ingestion/ingestion.app.ts
 import { App } from '@frontmcp/sdk';
+
 import { VectorStoreProvider } from './providers/vector-store.provider';
 import { IngestDocumentTool } from './tools/ingest-document.tool';
 
@@ -56,8 +58,8 @@ export class IngestionApp {}
 
 ```typescript
 // src/ingestion/providers/vector-store.provider.ts
-import { Provider } from '@frontmcp/sdk';
 import type { Token } from '@frontmcp/di';
+import { Provider } from '@frontmcp/sdk';
 
 export interface DocumentChunk {
   id: string;
@@ -142,10 +144,9 @@ export class VectorStoreProvider implements VectorStore {
 
 ```typescript
 // src/ingestion/tools/ingest-document.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
-import { VECTOR_STORE } from '../providers/vector-store.provider';
-import type { DocumentChunk } from '../providers/vector-store.provider';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+import { VECTOR_STORE, type DocumentChunk } from '../providers/vector-store.provider';
 
 @Tool({
   name: 'ingest_document',
@@ -238,9 +239,10 @@ export class IngestDocumentTool extends ToolContext {
 ```typescript
 // src/search/search.app.ts
 import { App } from '@frontmcp/sdk';
+
 import { VectorStoreProvider } from '../ingestion/providers/vector-store.provider';
-import { SearchDocsTool } from './tools/search-docs.tool';
 import { DocResource } from './resources/doc.resource';
+import { SearchDocsTool } from './tools/search-docs.tool';
 
 @App({
   name: 'Search',
@@ -256,8 +258,8 @@ export class SearchApp {}
 
 ```typescript
 // src/search/tools/search-docs.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
 import { VECTOR_STORE } from '../../ingestion/providers/vector-store.provider';
 
 @Tool({
@@ -318,8 +320,9 @@ export class SearchDocsTool extends ToolContext {
 
 ```typescript
 // src/search/resources/doc.resource.ts
-import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
 import type { ReadResourceResult } from '@frontmcp/protocol';
+import { ResourceContext, ResourceTemplate } from '@frontmcp/sdk';
+
 import { VECTOR_STORE } from '../../ingestion/providers/vector-store.provider';
 
 @ResourceTemplate({
@@ -368,6 +371,7 @@ export class DocResource extends ResourceContext<{ documentId: string }> {
 ```typescript
 // src/research/research.app.ts
 import { App } from '@frontmcp/sdk';
+
 import { ResearcherAgent } from './agents/researcher.agent';
 
 @App({
@@ -382,10 +386,10 @@ export class ResearchApp {}
 
 ```typescript
 // src/research/agents/researcher.agent.ts
-import { Agent, AgentContext } from '@frontmcp/sdk';
-import { z } from 'zod';
-import { SearchDocsTool } from '../../search/tools/search-docs.tool';
+import { Agent, AgentContext, z } from '@frontmcp/sdk';
+
 import { IngestDocumentTool } from '../../ingestion/tools/ingest-document.tool';
+import { SearchDocsTool } from '../../search/tools/search-docs.tool';
 
 @Agent({
   name: 'research_topic',
@@ -442,8 +446,7 @@ export class ResearcherAgent extends AgentContext {
 
 ```typescript
 // src/plugins/audit-log.plugin.ts
-import { Plugin } from '@frontmcp/sdk';
-import type { PluginHookContext } from '@frontmcp/sdk';
+import { Plugin, type PluginHookContext } from '@frontmcp/sdk';
 
 @Plugin({
   name: 'AuditLog',
@@ -515,6 +518,7 @@ export class AuditLogPlugin {
 ```typescript
 // test/researcher.agent.spec.ts
 import { AgentContext } from '@frontmcp/sdk';
+
 import { ResearcherAgent } from '../src/research/agents/researcher.agent';
 
 describe('ResearcherAgent', () => {
@@ -590,9 +594,10 @@ describe('ResearcherAgent', () => {
 
 ```typescript
 // test/audit-log.plugin.spec.ts
-import { AuditLogPlugin } from '../src/plugins/audit-log.plugin';
 import type { PluginHookContext } from '@frontmcp/sdk';
 
+import { AuditLogPlugin } from '../src/plugins/audit-log.plugin';
+
 describe('AuditLogPlugin', () => {
   let plugin: AuditLogPlugin;
 

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

@@ -45,6 +45,7 @@ An authenticated task management MCP server with CRUD tools, a Redis-backed prov
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { TasksApp } from './tasks.app';
 
 @FrontMcp({
@@ -63,11 +64,12 @@ export default class TaskManagerServer {}
 ```typescript
 // src/tasks.app.ts
 import { App } from '@frontmcp/sdk';
+
 import { RedisTaskStoreProvider } from './providers/task-store.provider';
 import { CreateTaskTool } from './tools/create-task.tool';
+import { DeleteTaskTool } from './tools/delete-task.tool';
 import { ListTasksTool } from './tools/list-tasks.tool';
 import { UpdateTaskTool } from './tools/update-task.tool';
-import { DeleteTaskTool } from './tools/delete-task.tool';
 
 @App({
   name: 'Tasks',
@@ -100,8 +102,9 @@ export interface Task {
 
 ```typescript
 // src/providers/task-store.provider.ts
-import { Provider } from '@frontmcp/sdk';
 import type { Token } from '@frontmcp/di';
+import { Provider } from '@frontmcp/sdk';
+
 import type { Task } from '../types/task';
 
 export interface TaskStore {
@@ -167,8 +170,8 @@ export class RedisTaskStoreProvider implements TaskStore {
 
 ```typescript
 // src/tools/create-task.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
 import { TASK_STORE } from '../providers/task-store.provider';
 
 @Tool({
@@ -219,8 +222,8 @@ export class CreateTaskTool extends ToolContext {
 
 ```typescript
 // src/tools/list-tasks.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
 import { TASK_STORE } from '../providers/task-store.provider';
 
 @Tool({
@@ -277,8 +280,8 @@ export class ListTasksTool extends ToolContext {
 
 ```typescript
 // src/tools/update-task.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
 import { TASK_STORE } from '../providers/task-store.provider';
 
 @Tool({
@@ -331,8 +334,8 @@ export class UpdateTaskTool extends ToolContext {
 
 ```typescript
 // src/tools/delete-task.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
 import { TASK_STORE } from '../providers/task-store.provider';
 
 @Tool({
@@ -385,8 +388,9 @@ export class DeleteTaskTool extends ToolContext {
 ```typescript
 // test/create-task.tool.spec.ts
 import { ToolContext } from '@frontmcp/sdk';
-import { CreateTaskTool } from '../src/tools/create-task.tool';
+
 import { TASK_STORE, type TaskStore } from '../src/providers/task-store.provider';
+import { CreateTaskTool } from '../src/tools/create-task.tool';
 import type { Task } from '../src/types/task';
 
 describe('CreateTaskTool', () => {
@@ -465,6 +469,7 @@ describe('CreateTaskTool', () => {
 ```typescript
 // test/tasks.e2e.spec.ts
 import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
+
 import Server from '../src/main';
 
 describe('Task Manager E2E', () => {

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

@@ -44,6 +44,7 @@ A complete beginner MCP server that exposes a weather lookup tool and a static r
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { WeatherApp } from './weather.app';
 
 @FrontMcp({
@@ -60,8 +61,9 @@ export default class WeatherServer {}
 ```typescript
 // src/weather.app.ts
 import { App } from '@frontmcp/sdk';
-import { GetWeatherTool } from './tools/get-weather.tool';
+
 import { CitiesResource } from './resources/cities.resource';
+import { GetWeatherTool } from './tools/get-weather.tool';
 
 @App({
   name: 'Weather',
@@ -78,8 +80,7 @@ export class WeatherApp {}
 
 ```typescript
 // src/tools/get-weather.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'get_weather',
@@ -149,6 +150,7 @@ export class CitiesResource extends ResourceContext {
 ```typescript
 // test/get-weather.tool.spec.ts
 import { ToolContext } from '@frontmcp/sdk';
+
 import { GetWeatherTool } from '../src/tools/get-weather.tool';
 
 describe('GetWeatherTool', () => {
@@ -239,6 +241,7 @@ describe('GetWeatherTool', () => {
 ```typescript
 // test/weather.e2e.spec.ts
 import { McpTestClient, TestServer } from '@frontmcp/testing';
+
 import Server from '../src/main';
 
 describe('Weather Server E2E', () => {

package/catalog/frontmcp-observability/examples/telemetry-api/tool-custom-spans.md

@@ -19,15 +19,14 @@ Create child spans, events, and attributes inside a tool's execute method using
 
 ```typescript
 // src/apps/my-app/tools/weather.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'get_weather',
   description: 'Get weather for a city',
   inputSchema: { city: z.string() },
 })
-export class GetWeatherTool extends ToolContext<typeof GetWeatherTool> {
+export class GetWeatherTool extends ToolContext {
   async execute({ city }: { city: string }) {
     // Event on the "tool get_weather" span
     this.telemetry.addEvent('request-received', { city });

package/catalog/frontmcp-observability/examples/tracing-setup/basic-tracing.md

@@ -27,7 +27,9 @@ setupOTel({ serviceName: 'my-server', exporter: 'console' });
 ```typescript
 // src/server.ts
 import './setup-otel'; // Must be first import
+
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { MyApp } from './apps/my-app';
 
 @FrontMcp({
@@ -40,15 +42,14 @@ export default class Server {}
 
 ```typescript
 // src/apps/my-app/tools/hello.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'hello',
   description: 'Say hello',
   inputSchema: { name: z.string() },
 })
-export class HelloTool extends ToolContext<typeof HelloTool> {
+export class HelloTool extends ToolContext {
   async execute({ name }: { name: string }) {
     return { greeting: `Hello, ${name}!` };
   }

package/catalog/frontmcp-observability/references/telemetry-api.md

@@ -22,15 +22,14 @@ Every execution context (tools, resources, prompts, agents) gets a `this.telemet
 ## Usage in Tools
 
 ```typescript
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'analyze_data',
   description: 'Analyze dataset with custom telemetry',
   inputSchema: { datasetId: z.string() },
 })
-class AnalyzeDataTool extends ToolContext<typeof AnalyzeDataTool> {
+class AnalyzeDataTool extends ToolContext {
   async execute({ datasetId }: { datasetId: string }) {
     // Events go on the "tool analyze_data" span
     this.telemetry.addEvent('analysis-started', { datasetId });

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

@@ -19,8 +19,7 @@ Shows how to configure structured logging, error handling with MCP error codes,
 
 ```typescript
 // src/tools/monitored-tool.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'monitored_operation',

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

@@ -19,8 +19,8 @@ Shows how to configure authentication, CORS, input validation, and rate limiting
 
 ```typescript
 // src/main.ts
-import { FrontMcp } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { FrontMcp, z } from '@frontmcp/sdk';
+
 import { MyApp } from './my.app';
 
 @FrontMcp({
@@ -59,8 +59,7 @@ export default class SecureServer {}
 
 ```typescript
 // src/tools/safe-query.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'safe_query',

package/catalog/frontmcp-production-readiness/examples/distributed-ha/ha-kubernetes-3-replicas.md

@@ -0,0 +1,229 @@
+---
+name: ha-kubernetes-3-replicas
+reference: distributed-ha
+level: intermediate
+description: Deploy FrontMCP with 3 replicas, Redis, and automatic session failover on Kubernetes
+tags: [ha, kubernetes, redis, distributed, session-takeover, heartbeat]
+features:
+  - Configuring @FrontMcp with Redis for distributed deployment
+  - Kubernetes Deployment YAML with 3 replicas and readiness probes
+  - Verifying heartbeat keys and session takeover via redis-cli
+  - NGINX sticky sessions for session affinity
+---
+
+# HA Kubernetes Deployment with 3 Replicas
+
+Deploy FrontMCP with 3 replicas, Redis, and automatic session failover on Kubernetes
+
+## Code
+
+### Server Configuration
+
+```typescript
+// src/main.ts
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'echo',
+  description: 'Echo a message',
+  inputSchema: { message: z.string() },
+})
+class EchoTool extends ToolContext {
+  async execute(input: { message: string }) {
+    return { echo: input.message };
+  }
+}
+
+@App({ name: 'main', tools: [EchoTool] })
+class MainApp {}
+
+@FrontMcp({
+  info: { name: 'ha-demo', version: '1.0.0' },
+  apps: [MainApp],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] || 'redis',
+    port: 6379,
+  },
+  transport: {
+    persistence: {
+      redis: {
+        provider: 'redis',
+        host: process.env['REDIS_HOST'] || 'redis',
+        port: 6379,
+      },
+    },
+  },
+})
+class Server {}
+```
+
+### Config File
+
+```typescript
+// frontmcp.config.ts
+import { defineConfig } from '@frontmcp/cli';
+
+export default defineConfig({
+  name: 'ha-demo',
+  version: '1.0.0',
+  deployments: [
+    {
+      target: 'distributed',
+      ha: {
+        heartbeatIntervalMs: 10000,
+        heartbeatTtlMs: 30000,
+      },
+      server: {
+        headers: {
+          hsts: 'max-age=31536000',
+          contentTypeOptions: 'nosniff',
+          frameOptions: 'DENY',
+        },
+      },
+    },
+  ],
+});
+```
+
+### Dockerfile
+
+```dockerfile
+FROM node:24-alpine AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN FRONTMCP_DEPLOYMENT_MODE=distributed npx frontmcp build --target distributed
+
+FROM node:24-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/dist/distributed ./dist
+COPY --from=builder /app/package.json ./
+RUN yarn install --frozen-lockfile --production && yarn cache clean
+EXPOSE 3000
+HEALTHCHECK --interval=15s --timeout=5s --retries=3 --start-period=10s \
+  CMD wget -qO- http://localhost:3000/healthz || exit 1
+CMD ["node", "dist/main.js"]
+```
+
+### Kubernetes Manifests
+
+```yaml
+# k8s/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mcp-server
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: mcp-server
+  template:
+    metadata:
+      labels:
+        app: mcp-server
+    spec:
+      containers:
+        - name: mcp-server
+          image: my-registry/ha-demo:latest
+          env:
+            - name: FRONTMCP_DEPLOYMENT_MODE
+              value: distributed
+            - name: REDIS_HOST
+              value: redis
+          ports:
+            - containerPort: 3000
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: 3000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: 3000
+            initialDelaySeconds: 10
+            periodSeconds: 15
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: mcp-server
+spec:
+  selector:
+    app: mcp-server
+  ports:
+    - port: 3000
+      targetPort: 3000
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: redis
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: redis
+  template:
+    metadata:
+      labels:
+        app: redis
+    spec:
+      containers:
+        - name: redis
+          image: redis:7-alpine
+          ports:
+            - containerPort: 6379
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: redis
+spec:
+  selector:
+    app: redis
+  ports:
+    - port: 6379
+```
+
+### Verification
+
+```bash
+# Deploy
+kubectl apply -f k8s/
+
+# Check pods
+kubectl get pods -l app=mcp-server
+# NAME                          READY   STATUS    RESTARTS
+# mcp-server-7b8f9-abc12        1/1     Running   0
+# mcp-server-7b8f9-def34        1/1     Running   0
+# mcp-server-7b8f9-ghi56        1/1     Running   0
+
+# Check heartbeat keys in Redis
+kubectl exec -it deploy/redis -- redis-cli KEYS "mcp:ha:heartbeat:*"
+# 1) "mcp:ha:heartbeat:mcp-server-7b8f9-abc12"
+# 2) "mcp:ha:heartbeat:mcp-server-7b8f9-def34"
+# 3) "mcp:ha:heartbeat:mcp-server-7b8f9-ghi56"
+
+# Kill a pod and watch takeover
+kubectl delete pod mcp-server-7b8f9-abc12
+# After ~30s, its heartbeat expires and sessions are claimed by surviving pods
+```
+
+## What This Demonstrates
+
+- Configuring @FrontMcp with Redis for distributed deployment
+- Kubernetes Deployment YAML with 3 replicas and readiness probes
+- Verifying heartbeat keys and session takeover via redis-cli
+- NGINX sticky sessions for session affinity
+
+## Related
+
+- See `distributed-ha` for the full HA architecture reference
+- See `deploy-to-node` for single-pod Docker deployment
+- See `frontmcp-config` for configuration file options

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

@@ -20,10 +20,9 @@ Shows how to use `@frontmcp/utils` for cross-platform crypto operations that wor
 
 ```typescript
 // src/tools/browser-safe-hash.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 // @frontmcp/utils wraps Web Crypto API — works in browsers
-import { sha256Hex, sha256Base64url, randomUUID } from '@frontmcp/utils';
+import { randomUUID, sha256Base64url, sha256Hex } from '@frontmcp/utils';
 
 @Tool({
   name: 'hash_data',

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

@@ -81,8 +81,7 @@ main();
 
 ```typescript
 // src/tools/safe-tool.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'process_file',

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

@@ -46,8 +46,7 @@ new_classes = ["RateLimiterDO"]
 
 ```typescript
 // src/tools/rate-limited-action.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'rate_limited_action',
@@ -85,8 +84,7 @@ export class RateLimitedActionTool extends ToolContext {
 
 ```typescript
 // src/tools/file-upload.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'upload_file',

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

@@ -20,10 +20,9 @@ Shows how to write tools that are compatible with the Cloudflare Workers runtime
 
 ```typescript
 // src/tools/worker-safe.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 // Use @frontmcp/utils — wraps Web Crypto API, works in Workers
-import { sha256Hex, randomUUID, base64urlEncode } from '@frontmcp/utils';
+import { base64urlEncode, randomUUID, sha256Hex } from '@frontmcp/utils';
 
 @Tool({
   name: 'transform_data',

package/catalog/frontmcp-production-readiness/examples/production-lambda/cold-start-connection-reuse.md

@@ -60,8 +60,8 @@ export class DbConnectionProvider {
 
 ```typescript
 // src/tools/optimized-query.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
 import { DB_CLIENT } from '../providers/db-connection.provider';
 
 @Tool({
@@ -96,6 +96,7 @@ export class OptimizedQueryTool extends ToolContext {
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 // Only import lightweight modules at the top level
 // Heavy imports happen lazily in providers
 import { MyApp } from './my.app';