@frontmcp/skills 1.0.4 → 1.1.0-beta.1

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';

package/catalog/frontmcp-production-readiness/examples/production-vercel/cold-start-optimization.md

@@ -45,8 +45,7 @@ export class LazyApiClientProvider {
 
 ```typescript
 // src/tools/cached-lookup.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 // Cache OpenAPI spec in module scope — survives warm invocations
 let cachedSpec: unknown | undefined;
@@ -78,6 +77,7 @@ export class CachedLookupTool extends ToolContext {
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 // Only import lightweight modules at the top level
 import { MyApp } from './my.app';
 

package/catalog/frontmcp-production-readiness/examples/production-vercel/stateless-serverless-design.md

@@ -19,10 +19,9 @@ Shows a fully stateless server design that works on Vercel edge runtime with no
 
 ```typescript
 // src/tools/edge-safe-tool.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 // Use @frontmcp/utils for cross-platform crypto — not node:crypto
-import { sha256Hex, randomUUID } from '@frontmcp/utils';
+import { randomUUID, sha256Hex } from '@frontmcp/utils';
 
 @Tool({
   name: 'process_request',
@@ -60,6 +59,7 @@ export class ProcessRequestTool extends ToolContext {
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { EdgeApp } from './edge.app';
 
 @FrontMcp({

package/catalog/frontmcp-production-readiness/references/distributed-ha.md

@@ -0,0 +1,194 @@
+---
+name: distributed-ha
+description: Deploy FrontMCP across multiple pods with heartbeat, session takeover, and notification relay for zero-downtime failover
+---
+
+# Distributed High Availability
+
+FrontMCP's HA module provides automatic session failover across multiple pods using Redis. Three components work together: HeartbeatService (liveness detection), session takeover (atomic CAS), and NotificationRelay (cross-pod MCP notifications).
+
+## When to Use This Skill
+
+### Must Use
+
+- Running 2+ FrontMCP pods behind a load balancer with Redis available
+- Production deployments where pod restarts must not drop active MCP sessions
+- Kubernetes deployments with rolling updates or horizontal pod autoscaling
+
+### Recommended
+
+- Any production deployment where zero-downtime upgrades are needed
+- Multi-region setups with Redis replication
+
+### Skip When
+
+- Single-pod deployments (use `deploy-to-node` instead)
+- Serverless platforms (Vercel, Lambda, Cloudflare) --- stateless by design
+- Development and testing --- use `direct-client` or standalone mode
+
+> **Decision:** Use this skill when you need session continuity across pod restarts. Skip for serverless or single-pod setups.
+
+## Prerequisites
+
+- Redis 6+ accessible from all pods
+- `@frontmcp/sdk` and `@frontmcp/cli` installed
+- `FRONTMCP_DEPLOYMENT_MODE=distributed` environment variable
+
+## Step 1: Configure @FrontMcp Decorator
+
+```typescript
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { provider: 'redis', host: 'redis', port: 6379 },
+  transport: {
+    persistence: {
+      redis: { provider: 'redis', host: 'redis', port: 6379 },
+    },
+  },
+})
+class Server {}
+```
+
+## Step 2: Create Configuration File
+
+```typescript
+// frontmcp.config.ts
+import { defineConfig } from '@frontmcp/cli';
+
+export default defineConfig({
+  name: 'my-server',
+  version: '1.0.0',
+  deployments: [
+    {
+      target: 'distributed',
+      ha: {
+        heartbeatIntervalMs: 10000,
+        heartbeatTtlMs: 30000,
+        takeoverGracePeriodMs: 5000,
+        redisKeyPrefix: 'mcp:ha:',
+      },
+    },
+  ],
+});
+```
+
+## Step 3: Build and Deploy
+
+```bash
+export FRONTMCP_DEPLOYMENT_MODE=distributed
+frontmcp build --target distributed
+```
+
+Deploy with Docker or Kubernetes (see example below).
+
+## Step 4: Verify Heartbeats
+
+```bash
+# Check heartbeat keys exist for each pod
+redis-cli --scan --pattern "mcp:ha:heartbeat:*"
+
+# Inspect a heartbeat value
+redis-cli GET "mcp:ha:heartbeat:mcp-server-7b8f9-abc12"
+# Returns: {"nodeId":"mcp-server-7b8f9-abc12","startedAt":1712620800000,"lastBeat":1712620810000,"sessionCount":5}
+```
+
+## Configuration
+
+| Field                   | Type   | Default   | Description                                      |
+| ----------------------- | ------ | --------- | ------------------------------------------------ |
+| `heartbeatIntervalMs`   | number | 10000     | How often each pod writes its heartbeat to Redis |
+| `heartbeatTtlMs`        | number | 30000     | TTL for heartbeat key (should be 2-3x interval)  |
+| `takeoverGracePeriodMs` | number | 5000      | Wait time before claiming orphaned sessions      |
+| `redisKeyPrefix`        | string | `mcp:ha:` | Redis key prefix for all HA keys                 |
+
+## Architecture
+
+### Heartbeat Service
+
+Each pod writes `mcp:ha:heartbeat:{nodeId}` to Redis every `heartbeatIntervalMs` with PX TTL of `heartbeatTtlMs`. The value contains `{ nodeId, startedAt, lastBeat, sessionCount }`. When a pod dies, the key expires.
+
+### Session Takeover
+
+When a request arrives for a session owned by a dead pod:
+
+1. The live pod checks if the owner's heartbeat key exists
+2. If missing, runs an atomic Lua CAS script: verifies `expectedOldNodeId`, updates `nodeId` + `reassignedAt`
+3. Returns `{ claimed: true }` on success, `{ claimed: false }` if another pod won the race
+
+### Notification Relay
+
+Each pod subscribes to `mcp:ha:notify:{nodeId}` via Redis Pub/Sub. Cross-pod MCP notifications (progress updates, resource changes) are published to the target pod's channel for local delivery.
+
+## Load Balancer Affinity
+
+FrontMCP sets:
+
+- **Cookie**: `__frontmcp_node` on Streamable HTTP initialize
+- **Header**: `X-FrontMCP-Machine-Id` on every distributed response
+
+NGINX sticky session example:
+
+```nginx
+upstream mcp_backend {
+    hash $cookie___frontmcp_node consistent;
+    server pod-1:3000;
+    server pod-2:3000;
+    server pod-3:3000;
+}
+```
+
+## Common Patterns
+
+| Pattern           | Correct                               | Incorrect                     | Why                                               |
+| ----------------- | ------------------------------------- | ----------------------------- | ------------------------------------------------- |
+| Heartbeat TTL     | `heartbeatTtlMs: 30000` (3x interval) | `heartbeatTtlMs: 10000` (1x)  | Too low causes false-positive pod death detection |
+| Redis connections | Dedicated pub/sub + data connections  | Shared single connection      | Pub/Sub blocks the connection                     |
+| Machine ID        | Let K8s set HOSTNAME                  | Override HOSTNAME in pod spec | Breaks session ownership mapping                  |
+
+## Errors
+
+| Error                       | When                                       | Solution                                                |
+| --------------------------- | ------------------------------------------ | ------------------------------------------------------- |
+| `SessionClaimConflictError` | Session claimed by another pod during race | Retry --- the load balancer will route to the new owner |
+| `HaConfigurationError`      | Redis not configured for distributed mode  | Add `redis` to `@FrontMcp()` config                     |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `FRONTMCP_DEPLOYMENT_MODE=distributed` set in deployment
+- [ ] Redis accessible from all pods
+- [ ] `heartbeatTtlMs` >= 2x `heartbeatIntervalMs`
+- [ ] Transport persistence configured with Redis
+
+### Runtime
+
+- [ ] `redis-cli --scan --pattern "mcp:ha:heartbeat:*"` shows entries for each pod
+- [ ] Killing a pod results in its heartbeat expiring within TTL
+- [ ] Surviving pods claim orphaned sessions after takeover grace period
+- [ ] `/healthz` and `/readyz` return healthy on all pods
+
+## Troubleshooting
+
+| Problem                                  | Cause                                  | Solution                                                                 |
+| ---------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
+| Sessions not transferred after pod death | `heartbeatTtlMs` too high              | Lower TTL while keeping >= 2x interval (e.g., 20-30s for a 10s interval) |
+| `HaConfigurationError` on startup        | Missing Redis config                   | Add `redis` to `@FrontMcp()` decorator                                   |
+| Duplicate notifications                  | Shared Redis subscriber connection     | Use dedicated connections per relay                                      |
+| Session takeover race failures           | High pod count + simultaneous restarts | Increase `takeoverGracePeriodMs`                                         |
+
+## Examples
+
+| Example                                                                              | Level        | Description                                                                          |
+| ------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
+| [`ha-kubernetes-3-replicas`](../examples/distributed-ha/ha-kubernetes-3-replicas.md) | Intermediate | Deploy FrontMCP with 3 replicas, Redis, and automatic session failover on Kubernetes |
+
+> See all examples in [`examples/distributed-ha/`](../examples/distributed-ha/)
+
+## Reference
+
+- [Documentation](https://docs.agentfront.dev/frontmcp/deployment/high-availability)
+- Related skills: `frontmcp-deployment`, `frontmcp-config`, `deploy-to-node`

package/catalog/frontmcp-setup/SKILL.md

@@ -52,17 +52,17 @@ Entry point for project setup and scaffolding. This skill helps you find the rig
 
 ## Scenario Routing Table
 
-| Scenario                                      | Reference                                    | Description                                                                                  |
-| --------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder (flags: `--target`, `--redis`, `--skills <bundle>`, `--cicd`, `--nx`, `--pm`) |
-| Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy                       |
-| Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules                                  |
-| Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for subscriptions                                           |
-| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                                      |
-| Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers                                |
-| Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands                             |
-| Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands, bundles, categories, search                                                    |
-| Generate or update project README.md          | `references/readme-guide.md`                 | Deployment-target-aware README for npm, CLI, Docker, serverless                              |
+| Scenario                                      | Reference                                    | Description                                                                                   |
+| --------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder (flags: `--target`, `--redis`, `--skills <bundle>`, `--cicd`, `--nx`, `--pm`)  |
+| Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy                        |
+| Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules                                   |
+| Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for distributed subscriptions (single-server uses in-memory) |
+| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                                       |
+| Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers                                 |
+| Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands                              |
+| Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands, bundles, categories, search                                                     |
+| Generate or update project README.md          | `references/readme-guide.md`                 | Deployment-target-aware README for npm, CLI, Docker, serverless                               |
 
 ## Recommended Reading Order
 

package/catalog/frontmcp-setup/examples/project-structure-standalone/feature-folder-organization.md

@@ -19,8 +19,7 @@ Organize a growing standalone project into domain-specific feature folders inste
 
 ```typescript
 // src/billing/create-invoice.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'create_invoice',
@@ -71,9 +70,10 @@ export class BillingProvider {
 ```typescript
 // src/my-app.app.ts
 import { App } from '@frontmcp/sdk';
+
+import { BillingProvider } from './billing/billing.provider';
 import CreateInvoiceTool from './billing/create-invoice.tool';
 import InvoiceResource from './billing/invoice.resource';
-import { BillingProvider } from './billing/billing.provider';
 
 @App({
   name: 'my-app',
@@ -87,7 +87,9 @@ export class MyApp {}
 ```typescript
 // src/main.ts
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { MyApp } from './my-app.app';
 
 @FrontMcp({

package/catalog/frontmcp-setup/examples/project-structure-standalone/minimal-standalone-layout.md

@@ -19,8 +19,7 @@ Set up the canonical file structure for a standalone FrontMCP project with one a
 
 ```typescript
 // src/tools/fetch-weather.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'fetch_weather',
@@ -37,6 +36,7 @@ export default class FetchWeatherTool extends ToolContext {
 ```typescript
 // src/my-app.app.ts
 import { App } from '@frontmcp/sdk';
+
 import FetchWeatherTool from './tools/fetch-weather.tool';
 
 @App({
@@ -49,7 +49,9 @@ export class MyApp {}
 ```typescript
 // src/main.ts
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { MyApp } from './my-app.app';
 
 @FrontMcp({

package/catalog/frontmcp-setup/examples/setup-project/basic-node-server.md

@@ -20,8 +20,7 @@ Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js
 
 ```typescript
 // src/tools/add.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'add',
@@ -41,6 +40,7 @@ export default class AddTool extends ToolContext {
 ```typescript
 // src/apps/calc.app.ts
 import { App } from '@frontmcp/sdk';
+
 import AddTool from '../tools/add.tool';
 
 @App({
@@ -53,7 +53,9 @@ export class CalcApp {}
 ```typescript
 // src/main.ts
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { CalcApp } from './apps/calc.app';
 
 @FrontMcp({