@frontmcp/skills 1.0.3 → 1.1.0-beta.1

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({

package/catalog/frontmcp-setup/examples/setup-project/vercel-serverless-server.md

@@ -19,8 +19,7 @@ Configure a FrontMCP server for Vercel deployment with Vercel KV storage and mod
 
 ```typescript
 // src/tools/lookup-user.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'lookup_user',
@@ -37,6 +36,7 @@ export default class LookupUserTool extends ToolContext {
 ```typescript
 // src/apps/users.app.ts
 import { App } from '@frontmcp/sdk';
+
 import LookupUserTool from '../tools/lookup-user.tool';
 
 @App({
@@ -49,7 +49,9 @@ export class UsersApp {}
 ```typescript
 // src/main.ts
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { UsersApp } from './apps/users.app';
 
 @FrontMcp({

package/catalog/frontmcp-setup/examples/setup-redis/hybrid-vercel-kv-with-pubsub.md

@@ -2,18 +2,20 @@
 name: hybrid-vercel-kv-with-pubsub
 reference: setup-redis
 level: advanced
-description: 'Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions.'
+description: 'Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions in distributed multi-instance deployments.'
 tags: [setup, vercel-kv, redis, vercel, session, hybrid]
 features:
   - 'Vercel KV handles sessions (`redis` config) while a real Redis handles pub/sub (`pubsub` config)'
-  - 'Vercel KV does not support pub/sub operations, so a separate Redis instance is required'
-  - 'Resources with `subscribe: true` rely on the `pubsub` config for real-time notifications'
+  - 'Vercel KV does not support pub/sub operations, so a separate Redis instance is required for distributed setups'
+  - 'Resource subscriptions across multiple server instances rely on the `pubsub` config for cross-instance notifications (single-instance servers use in-memory subscriptions automatically)'
   - "The `pubsub` field accepts `provider: 'redis'` only (no Vercel KV support)"
 ---
 
 # Hybrid Vercel KV with Redis Pub/Sub
 
-Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions.
+Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions in distributed multi-instance deployments.
+
+> **Note:** Single-server deployments (stdio, binary, or single-instance HTTP) do not need pub/sub — resource subscriptions work in-memory out of the box.
 
 ## Code
 
@@ -50,7 +52,6 @@ import { Resource, ResourceContext } from '@frontmcp/sdk';
   uri: 'metrics://live',
   name: 'Live Metrics',
   mimeType: 'application/json',
-  subscribe: true,
 })
 export default class LiveMetricsResource extends ResourceContext {
   async read() {
@@ -69,8 +70,8 @@ REDIS_PUBSUB_PASSWORD=secret
 ## What This Demonstrates
 
 - Vercel KV handles sessions (`redis` config) while a real Redis handles pub/sub (`pubsub` config)
-- Vercel KV does not support pub/sub operations, so a separate Redis instance is required
-- Resources with `subscribe: true` rely on the `pubsub` config for real-time notifications
+- Vercel KV does not support pub/sub operations, so a separate Redis instance is required for distributed setups
+- Resource subscriptions across multiple server instances rely on the `pubsub` config for cross-instance notifications (single-instance servers use in-memory subscriptions automatically)
 - The `pubsub` field accepts `provider: 'redis'` only (no Vercel KV support)
 
 ## Related

package/catalog/frontmcp-setup/references/setup-project.md

@@ -141,6 +141,7 @@ The `@FrontMcp` decorator accepts a `FrontMcpMetadata` object with these fields:
 
 ```typescript
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
 
 @FrontMcp({
@@ -180,6 +181,7 @@ export default class Server {}
 
 ```typescript
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
 
 @FrontMcp({
@@ -225,8 +227,7 @@ export default class Server {}
 Create `src/tools/add.tool.ts`:
 
 ```typescript
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'add',
@@ -249,6 +250,7 @@ Create `src/apps/calc.app.ts`:
 
 ```typescript
 import { App } from '@frontmcp/sdk';
+
 import AddTool from '../tools/add.tool';
 
 @App({
@@ -276,7 +278,9 @@ Update `src/main.ts`:
 
 ```typescript
 import 'reflect-metadata';
+
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { CalcApp } from './apps/calc.app';
 
 @FrontMcp({
@@ -292,24 +296,21 @@ Resources, Prompts, and Skills follow the same decorator pattern:
 
 ```typescript
 // Resource - returns MCP ReadResourceResult
-import { Resource, ResourceContext } from '@frontmcp/sdk';
+// Prompt - returns MCP GetPromptResult
+
+// Skill - compound capability with tools + instructions
+import { Prompt, PromptContext, Resource, ResourceContext, Skill, SkillContext } from '@frontmcp/sdk';
 
 @Resource({ uri: 'config://app', name: 'App Config', mimeType: 'application/json' })
 export default class AppConfigResource extends ResourceContext {
   /* ... */
 }
 
-// Prompt - returns MCP GetPromptResult
-import { Prompt, PromptContext } from '@frontmcp/sdk';
-
 @Prompt({ name: 'summarize', description: 'Summarize a document' })
 export default class SummarizePrompt extends PromptContext {
   /* ... */
 }
 
-// Skill - compound capability with tools + instructions
-import { Skill, SkillContext } from '@frontmcp/sdk';
-
 @Skill({ name: 'data-analysis', description: 'Analyze datasets' })
 export default class DataAnalysisSkill extends SkillContext {
   /* ... */

package/catalog/frontmcp-setup/references/setup-redis.md

@@ -15,15 +15,16 @@ description: Provision and configure Redis or Vercel KV for session storage and
 
 ### Recommended
 
-- Resource subscriptions with `subscribe: true` are enabled and need pub/sub
+- Resource subscriptions with `subscribe: true` across **multiple server instances** (distributed pub/sub)
 - Auth sessions or elicitation state must persist across server restarts
 - Distributed rate limiting is configured in the throttle guard
 
 ### Skip When
 
-- Running a single-instance stdio-only server for local development -- use `setup-sqlite` or in-memory stores
+- Running a single-instance stdio-only server for local development -- use `setup-sqlite` or in-memory stores (resource subscriptions work in-memory without Redis)
 - Only need to configure session TTL and key prefix on an already-provisioned Redis -- use `configure-session`
 - Deploying a read-only MCP server with no sessions, subscriptions, or stateful tools
+- Using resource subscriptions on a single server instance -- subscriptions work in-memory out of the box
 
 > **Decision:** Use this skill to provision and connect Redis (Docker, existing instance, or Vercel KV); use `configure-session` to tune session-specific options after Redis is available.
 
@@ -217,9 +218,11 @@ const sessionStore = createSessionStoreSync({
 });
 ```
 
-## Step 4 -- Pub/Sub for Resource Subscriptions
+## Step 4 -- Pub/Sub for Resource Subscriptions (Multi-Instance Only)
 
-If your server exposes resources with `subscribe: true`, you need pub/sub. Pub/sub requires a real Redis instance -- Vercel KV does not support pub/sub operations.
+> **Single-server note:** If you run a single server instance (stdio, binary, or single-instance HTTP), resource subscriptions work in-memory without any Redis or pub/sub configuration. Skip this step for local development and single-server deployments.
+
+For **distributed multi-instance** deployments where subscription state must be shared across server instances, you need pub/sub. Pub/sub requires a real Redis instance -- Vercel KV does not support pub/sub operations.
 
 For a hybrid setup (Vercel KV for sessions, Redis for pub/sub):
 
@@ -318,13 +321,13 @@ You should see session keys like `mcp:session:<session-id>`.
 
 ## Common Patterns
 
-| Pattern                | Correct                                                                                    | Incorrect                                               | Why                                                                                                                                         |
-| ---------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Redis provider field   | `redis: { provider: 'redis', host: '...', port: 6379 }`                                    | `redis: { host: '...', port: 6379 }` without `provider` | Both forms are type-safe (the SDK's `RedisOptions` union accepts both shapes), but explicit `provider: 'redis'` improves clarity and intent |
-| Environment variables  | `host: process.env['REDIS_HOST'] ?? 'localhost'`                                           | Hardcoding `host: 'redis.internal'` in source           | Hardcoded values break across environments (dev, staging, prod); always read from env with a sensible fallback                              |
-| Vercel KV credentials  | Let Vercel auto-inject `KV_REST_API_URL` and `KV_REST_API_TOKEN`                           | Manually setting KV tokens in the `redis` config object | Auto-injection is safer and ensures tokens rotate correctly; manual values risk stale or committed secrets                                  |
-| Docker persistence     | `command: redis-server --appendonly yes` in docker-compose                                 | Running Redis without `--appendonly` in development     | Without AOF persistence, data is lost on container restart; `--appendonly yes` preserves data across restarts                               |
-| Pub/sub with Vercel KV | Separate `pubsub: { provider: 'redis', ... }` alongside `redis: { provider: 'vercel-kv' }` | Expecting Vercel KV to handle pub/sub                   | Vercel KV does not support pub/sub; a real Redis instance is required for resource subscriptions                                            |
+| Pattern                | Correct                                                                                    | Incorrect                                               | Why                                                                                                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Redis provider field   | `redis: { provider: 'redis', host: '...', port: 6379 }`                                    | `redis: { host: '...', port: 6379 }` without `provider` | Both forms are type-safe (the SDK's `RedisOptions` union accepts both shapes), but explicit `provider: 'redis'` improves clarity and intent                                                |
+| Environment variables  | `host: process.env['REDIS_HOST'] ?? 'localhost'`                                           | Hardcoding `host: 'redis.internal'` in source           | Hardcoded values break across environments (dev, staging, prod); always read from env with a sensible fallback                                                                             |
+| Vercel KV credentials  | Let Vercel auto-inject `KV_REST_API_URL` and `KV_REST_API_TOKEN`                           | Manually setting KV tokens in the `redis` config object | Auto-injection is safer and ensures tokens rotate correctly; manual values risk stale or committed secrets                                                                                 |
+| Docker persistence     | `command: redis-server --appendonly yes` in docker-compose                                 | Running Redis without `--appendonly` in development     | Without AOF persistence, data is lost on container restart; `--appendonly yes` preserves data across restarts                                                                              |
+| Pub/sub with Vercel KV | Separate `pubsub: { provider: 'redis', ... }` alongside `redis: { provider: 'vercel-kv' }` | Expecting Vercel KV to handle pub/sub                   | Vercel KV does not support pub/sub; a real Redis instance is required for distributed resource subscriptions (single-instance servers use in-memory subscriptions and do not need pub/sub) |
 
 ## Verification Checklist
 
@@ -359,11 +362,11 @@ You should see session keys like `mcp:session:<session-id>`.
 
 ## Examples
 
-| Example                                                                                   | Level        | Description                                                                                         |
-| ----------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------- |
-| [`docker-redis-local-dev`](../examples/setup-redis/docker-redis-local-dev.md)             | Basic        | Provision Redis with Docker Compose and connect a FrontMCP server for local session storage.        |
-| [`hybrid-vercel-kv-with-pubsub`](../examples/setup-redis/hybrid-vercel-kv-with-pubsub.md) | Advanced     | Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions. |
-| [`vercel-kv-serverless`](../examples/setup-redis/vercel-kv-serverless.md)                 | Intermediate | Configure a FrontMCP server with Vercel KV as the session store for serverless deployment.          |
+| Example                                                                                   | Level        | Description                                                                                                                                   |
+| ----------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`docker-redis-local-dev`](../examples/setup-redis/docker-redis-local-dev.md)             | Basic        | Provision Redis with Docker Compose and connect a FrontMCP server for local session storage.                                                  |
+| [`hybrid-vercel-kv-with-pubsub`](../examples/setup-redis/hybrid-vercel-kv-with-pubsub.md) | Advanced     | Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions in distributed multi-instance deployments. |
+| [`vercel-kv-serverless`](../examples/setup-redis/vercel-kv-serverless.md)                 | Intermediate | Configure a FrontMCP server with Vercel KV as the session store for serverless deployment.                                                    |
 
 > See all examples in [`examples/setup-redis/`](../examples/setup-redis/)
 

package/catalog/frontmcp-testing/examples/test-direct-client/basic-create-test.md

@@ -19,9 +19,7 @@ Test tools in-memory without any HTTP overhead using the `create()` function fro
 
 ```typescript
 // src/__tests__/direct-client.spec.ts
-import { create } from '@frontmcp/sdk';
-import { tool } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { create, tool, z } from '@frontmcp/sdk';
 
 const AddTool = tool({
   name: 'add',

package/catalog/frontmcp-testing/examples/test-direct-client/openai-claude-format-test.md

@@ -19,9 +19,7 @@ Verify that tools are returned in the correct format for OpenAI and Claude clien
 
 ```typescript
 // src/__tests__/client-formats.spec.ts
-import { connectOpenAI } from '@frontmcp/sdk';
-import { tool } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { connectOpenAI, tool, z } from '@frontmcp/sdk';
 
 const AddTool = tool({
   name: 'add',

package/catalog/frontmcp-testing/examples/test-tool-unit/schema-validation-test.md

@@ -19,8 +19,8 @@ Validate that a tool's Zod input schema rejects invalid data before `execute()`
 
 ```typescript
 // src/tools/__tests__/add.tool.schema.spec.ts
-import { z } from 'zod';
-import { ToolContext } from '@frontmcp/sdk';
+import { ToolContext, z } from '@frontmcp/sdk';
+
 import { AddTool } from '../add.tool';
 
 describe('AddTool schema validation', () => {

package/catalog/frontmcp-testing/references/test-direct-client.md

@@ -8,9 +8,7 @@ description: In-memory testing with create() and connectOpenAI/connectClaude wit
 Uses `connect()` or `create()` for in-memory testing without HTTP overhead.
 
 ```typescript
-import { create, connectOpenAI } from '@frontmcp/sdk';
-import { tool } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { connectOpenAI, create, tool, z } from '@frontmcp/sdk';
 
 const AddTool = tool({
   name: 'add',

package/catalog/frontmcp-testing/references/test-tool-unit.md

@@ -6,8 +6,8 @@ description: Unit test a ToolContext execute method with mock context, inputs, a
 # Unit Testing a Tool
 
 ```typescript
-import { z } from 'zod';
-import { ToolContext } from '@frontmcp/sdk';
+import { ToolContext, z } from '@frontmcp/sdk';
+
 import { AddTool } from '../tools/add.tool';
 
 describe('AddTool', () => {