@frontmcp/skills 1.1.2-beta.1 → 1.2.0

package/catalog/frontmcp-production-readiness/examples/production-cloudflare/wrangler-config.md

@@ -2,88 +2,67 @@
 name: wrangler-config
 reference: production-cloudflare
 level: basic
-description: 'Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.'
-tags: [production, cloudflare, cache, session, wrangler, config]
+description: 'Checklist for verifying the `wrangler.toml` produced by `frontmcp build --target cloudflare` is production-ready. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-cloudflare.md`; this file is checklist-only.'
+tags:
+  - production
+  - cloudflare
+  - cache
+  - session
+  - wrangler
+  - checklist
 features:
-  - 'Complete `wrangler.toml` with KV bindings for sessions and cache'
-  - 'Separate staging/production environment configs'
-  - 'Cloudflare Worker entry point via `createCloudflareHandler`'
-  - 'Secrets managed via `wrangler secret put` (not in config files)'
+  - Verify `main = "dist/cloudflare/index.js"` (the build adapter writes this — never override)
+  - Verify KV bindings for sessions and cache exist
+  - Verify staging / production environment configs are separated
+  - Verify secrets are NOT in `wrangler.toml` — use `wrangler secret put`
 ---
 
-# Wrangler Configuration with KV Bindings
-
-Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.
-
-## Code
-
-```toml
-# wrangler.toml
-name = "my-mcp-worker"
-main = "dist/worker.js"
-compatibility_date = "2024-01-01"
-
-# Custom domain routing
-routes = [
-  { pattern = "mcp.example.com/*", zone_name = "example.com" }
-]
-
-# KV namespace for session storage
-[[kv_namespaces]]
-binding = "MCP_SESSIONS"
-id = "abc123def456"
-
-# KV namespace for cache
-[[kv_namespaces]]
-binding = "MCP_CACHE"
-id = "def456ghi789"
-
-# Environment-specific config
-[env.staging]
-name = "my-mcp-worker-staging"
-routes = [
-  { pattern = "mcp-staging.example.com/*", zone_name = "example.com" }
-]
-
-[env.production]
-name = "my-mcp-worker-production"
-routes = [
-  { pattern = "mcp.example.com/*", zone_name = "example.com" }
-]
-```
-
-```typescript
-// src/main.ts
-import { FrontMcp } from '@frontmcp/sdk';
-import { MyApp } from './my.app';
-
-@FrontMcp({
-  info: { name: 'cf-mcp', version: '1.0.0' },
-  apps: [MyApp],
-
-  // CORS: use the workers.dev or custom domain
-  cors: {
-    origin: ['https://app.example.com'],
-  },
-})
-export default class CloudflareMcpServer {}
-```
-
-```typescript
-// src/worker.ts — Cloudflare Worker entry point
-import { createCloudflareHandler } from '@frontmcp/adapters/cloudflare';
-import Server from './main';
-
-export default createCloudflareHandler(Server);
-```
+# Wrangler Configuration: Production-Readiness Checklist
+
+Checklist for verifying the `wrangler.toml` produced by `frontmcp build --target cloudflare` is production-ready. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-cloudflare.md`; this file is checklist-only.
+
+## Build artifact checks
+
+- [ ] `frontmcp build --target cloudflare` runs cleanly with no warnings
+- [ ] The build adapter wrote `main = "dist/cloudflare/index.js"` to `wrangler.toml` — **do not hand-edit this line**; the adapter overwrites it on every build (PR #374 — overriding silently breaks `wrangler deploy`)
+- [ ] `dist/cloudflare/index.js` exists after build and is what `wrangler deploy` uploads
+- [ ] No hand-written `src/worker.ts` with a fictional `createCloudflareHandler(...)` — the build emits the entry; your code stays the decorated `@FrontMcp` class
+- [ ] Bundle size is < 10 MB compressed (Workers limit)
+
+## Routes & domains
+
+- [ ] `routes = [{ pattern = "<host>/*", zone_name = "<zone>" }]` set for the right hostnames
+- [ ] Custom domain or `*.workers.dev` subdomain matches what `cors.origin` accepts in your `@FrontMcp` config
+- [ ] Separate `[env.staging]` and `[env.production]` blocks with distinct names + routes
+
+## KV / Durable Objects / R2
+
+- [ ] At least one `[[kv_namespaces]]` block bound for sessions if HA / multi-region (e.g. `binding = "MCP_SESSIONS"`)
+- [ ] Cache binding (KV or Cache API) exists if `CachePlugin` is configured
+- [ ] Durable Objects only used when stateful coordination is required (rate limiting, locks)
+- [ ] R2 binding exists if the server reads/writes blobs (no filesystem in Workers)
+
+## Secrets & environment
+
+- [ ] No secrets in `wrangler.toml` — all set via `wrangler secret put <NAME>`
+- [ ] `[vars]` block contains only non-sensitive config (region names, feature flags)
+- [ ] `compatibility_date` set to a recent date and locked
+
+## Deploy & observability
+
+- [ ] Deploy with `wrangler deploy --env production` (not the unscoped form)
+- [ ] `wrangler tail` works against the production worker for live debugging
+- [ ] Dashboard shows recent successful deploys
 
 ## What This Demonstrates
 
-- Complete `wrangler.toml` with KV bindings for sessions and cache
-- Separate staging/production environment configs
-- Cloudflare Worker entry point via `createCloudflareHandler`
-- Secrets managed via `wrangler secret put` (not in config files)
+- Verify `main = "dist/cloudflare/index.js"` (the build adapter writes this — never override)
+- Verify KV bindings for sessions and cache exist
+- Verify staging / production environment configs are separated
+- Verify secrets are NOT in `wrangler.toml` — use `wrangler secret put`
 
 ## Related
 
-- See `production-cloudflare` for the full Cloudflare Workers checklist
+- Configuration source of truth: `frontmcp-deployment/references/deploy-to-cloudflare.md`
+- Build adapter source: `libs/cli/src/commands/build/adapters/cloudflare.ts`
+- See `production-cloudflare` for the Cloudflare runtime / scaling checklist

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

@@ -2,18 +2,26 @@
 name: cold-start-connection-reuse
 reference: production-lambda
 level: intermediate
-description: 'Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.'
-tags: [production, lambda, performance, cold, start, connection]
+description: Shows how to minimize Lambda cold starts with lazy initialization on first call and the module-scope connection-reuse pattern for external services.
+tags:
+  - production
+  - lambda
+  - performance
+  - cold
+  - start
+  - connection
 features:
-  - 'Connection reuse pattern: caching connections in module scope across warm invocations'
-  - 'Lazy-loading heavy dependencies (`pg`) via dynamic `import()` to reduce cold start'
-  - 'Not closing connections in `onDestroy()` for Lambda (they survive freeze/thaw)'
-  - 'Keeping module scope lightweight with no heavy initialization'
+  - 'Connection reuse pattern: caching the connection promise in module scope so it survives Lambda freeze/thaw'
+  - Lazy-loading heavy dependencies (`pg`) via dynamic `import()` on first use, not at module load
+  - Not closing connections on shutdown for Lambda (they survive freeze/thaw — and providers have no `onDestroy` hook anyway)
+  - Keeping module scope lightweight with no heavy initialization
 ---
 
 # Cold Start Optimization and Connection Reuse
 
-Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.
+Shows how to minimize Lambda cold starts with lazy initialization on first call and the module-scope connection-reuse pattern for external services.
+
+> `@Provider`-decorated classes do NOT have `onInit` / `onDestroy` lifecycle hooks. Initialize lazily on first method call. For Lambda specifically, do **not** wire any shutdown hook for DB connections — Lambda freezes the execution context between invocations and your connection survives, so explicit close is wrong.
 
 ## Code
 
@@ -23,38 +31,34 @@ import { Provider, ProviderScope } from '@frontmcp/sdk';
 
 export const DB_CLIENT = Symbol('DbClient');
 
-// Connection reuse pattern: connections survive between warm invocations
-// but must handle cold starts and reconnection gracefully
-let cachedConnection: unknown | undefined;
+// Module-scope cache — survives freeze/thaw between Lambda invocations.
+let cachedConnectionPromise: Promise<unknown> | undefined;
 
 @Provider({ token: DB_CLIENT, scope: ProviderScope.GLOBAL })
 export class DbConnectionProvider {
-  private connection: unknown;
-
-  async onInit(): Promise<void> {
-    // Reuse connection across warm invocations
-    if (cachedConnection) {
-      this.connection = cachedConnection;
-      return;
+  // Lazy on first getConnection() — heavy SDK import does not run at module load.
+  async getConnection(): Promise<unknown> {
+    if (!cachedConnectionPromise) {
+      const promise = (async () => {
+        const { Client } = await import('pg');
+        const client = new Client({
+          host: process.env.DB_HOST,
+          connectionTimeoutMillis: 5000, // Don't hang on connection attempts
+        });
+        await client.connect();
+        return client;
+      })();
+      // Reset on failure so the next warm invocation can retry instead of
+      // permanently caching a rejected promise.
+      promise.catch(() => {
+        if (cachedConnectionPromise === promise) cachedConnectionPromise = undefined;
+      });
+      cachedConnectionPromise = promise;
     }
-
-    // Lazy-load the database driver — reduces cold start time
-    const { Client } = await import('pg');
-    this.connection = new Client({
-      host: process.env.DB_HOST,
-      connectionTimeoutMillis: 5000, // Don't hang on connection attempts
-    });
-    await (this.connection as { connect: () => Promise<void> }).connect();
-
-    // Cache for warm invocations
-    cachedConnection = this.connection;
-  }
-
-  getConnection() {
-    return this.connection;
+    return cachedConnectionPromise;
   }
 
-  // Note: Don't close in onDestroy for Lambda — connection survives freeze/thaw
+  // Note: Do NOT close in any shutdown hook for Lambda — connection survives freeze/thaw.
 }
 ```
 
@@ -77,12 +81,11 @@ import { DB_CLIENT } from '../providers/db-connection.provider';
 })
 export class OptimizedQueryTool extends ToolContext {
   async execute(input: { id: string }) {
-    const db = this.get(DB_CLIENT);
+    const db = this.get(DB_CLIENT) as { getConnection: () => Promise<{ query: Function }> };
 
     // Parameterized query — prevents SQL injection
-    const result = await (db as { getConnection: () => { query: Function } })
-      .getConnection()
-      .query('SELECT * FROM records WHERE id = $1', [input.id]);
+    const conn = await db.getConnection();
+    const result = await conn.query('SELECT * FROM records WHERE id = $1', [input.id]);
 
     if (!result.rows[0]) {
       this.fail(new Error(`Record not found: ${input.id}`));
@@ -113,9 +116,9 @@ export default class FastLambdaServer {}
 
 ## What This Demonstrates
 
-- Connection reuse pattern: caching connections in module scope across warm invocations
-- Lazy-loading heavy dependencies (`pg`) via dynamic `import()` to reduce cold start
-- Not closing connections in `onDestroy()` for Lambda (they survive freeze/thaw)
+- Connection reuse pattern: caching the connection promise in module scope so it survives Lambda freeze/thaw
+- Lazy-loading heavy dependencies (`pg`) via dynamic `import()` on first use, not at module load
+- Not closing connections on shutdown for Lambda (they survive freeze/thaw — and providers have no `onDestroy` hook anyway)
 - Keeping module scope lightweight with no heavy initialization
 
 ## Related

package/catalog/frontmcp-production-readiness/examples/production-lambda/sam-template.md

@@ -2,106 +2,75 @@
 name: sam-template
 reference: production-lambda
 level: basic
-description: 'Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration.'
-tags: [production, lambda, session, sam, template]
+description: 'Checklist for verifying the SAM template pairs correctly with the bundle produced by `frontmcp build --target lambda`. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-lambda.md`; this file is checklist-only.'
+tags:
+  - production
+  - lambda
+  - session
+  - sam
+  - checklist
 features:
-  - 'Complete SAM template with API Gateway, Lambda function, and DynamoDB table'
-  - 'DynamoDB for session storage with TTL-based automatic cleanup'
-  - 'Lambda handler entry point via `createLambdaHandler`'
-  - 'Pay-per-request billing for cost-effective scaling'
-  - 'IAM policies scoped to the specific DynamoDB table'
+  - 'Verify `Handler: handler.handler` with `CodeUri: dist/lambda/` (the build emits `dist/lambda/handler.cjs`)'
+  - No hand-written `src/lambda.ts` with a fictional `createLambdaHandler` import
+  - DynamoDB session table has TTL enabled for automatic cleanup
+  - IAM policies are scoped (no `*` resources / actions)
+  - API Gateway proxy route forwards to the function
 ---
 
-# SAM Template with API Gateway and DynamoDB
-
-Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration.
-
-## Code
-
-```yaml
-# ci/template.yaml
-AWSTemplateFormatVersion: '2010-09-09'
-Transform: AWS::Serverless-2016-10-31
-Description: FrontMCP Lambda deployment
-
-Globals:
-  Function:
-    Runtime: nodejs20.x
-    Timeout: 30
-    MemorySize: 256
-    Environment:
-      Variables:
-        NODE_ENV: production
-        SESSION_TABLE: !Ref SessionTable
-
-Resources:
-  McpFunction:
-    Type: AWS::Serverless::Function
-    Properties:
-      Handler: dist/lambda.handler
-      CodeUri: .
-      Events:
-        McpApi:
-          Type: Api
-          Properties:
-            Path: /mcp/{proxy+}
-            Method: ANY
-      Policies:
-        - DynamoDBCrudPolicy:
-            TableName: !Ref SessionTable
-
-  SessionTable:
-    Type: AWS::DynamoDB::Table
-    Properties:
-      TableName: mcp-sessions
-      BillingMode: PAY_PER_REQUEST
-      AttributeDefinitions:
-        - AttributeName: sessionId
-          AttributeType: S
-      KeySchema:
-        - AttributeName: sessionId
-          KeyType: HASH
-      TimeToLiveSpecification:
-        AttributeName: ttl
-        Enabled: true
-
-Outputs:
-  ApiEndpoint:
-    Description: API Gateway endpoint URL
-    Value: !Sub 'https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/mcp/'
-```
-
-```typescript
-// src/lambda.ts — Lambda handler entry point
-import { createLambdaHandler } from '@frontmcp/adapters/lambda';
-import Server from './main';
-
-export const handler = createLambdaHandler(Server);
-```
-
-```typescript
-// src/main.ts
-import { FrontMcp } from '@frontmcp/sdk';
-import { MyApp } from './my.app';
-
-@FrontMcp({
-  info: { name: 'lambda-mcp', version: '1.0.0' },
-  apps: [MyApp],
-  cors: {
-    origin: ['https://app.example.com'],
-  },
-})
-export default class LambdaMcpServer {}
-```
+# SAM Template: Production-Readiness Checklist
+
+Checklist for verifying the SAM template pairs correctly with the bundle produced by `frontmcp build --target lambda`. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-lambda.md`; this file is checklist-only.
+
+## Build artifact checks
+
+- [ ] `frontmcp build --target lambda` succeeded with no warnings
+- [ ] `dist/lambda/handler.cjs` exists — this is the bundled handler the build adapter writes
+- [ ] No hand-written `src/lambda.ts` importing a fictional `createLambdaHandler` from `@frontmcp/adapters/lambda` — the build adapter generates the entry; your code stays the decorated `@FrontMcp` class
+- [ ] `Handler: handler.handler` with `CodeUri: dist/lambda/` in `template.yaml` (filename `handler.cjs` → handler symbol `handler`). NOT `dist/lambda.handler` or `index.handler`
+- [ ] `CodeUri: .` (or pointed at the project root containing `dist/`) so SAM packages the bundled handler
+
+## Function configuration
+
+- [ ] `Runtime: nodejs20.x` (or current LTS)
+- [ ] `MemorySize` and `Timeout` sized to your workload (defaults: 256 MB / 30 s)
+- [ ] `Environment.Variables` includes `NODE_ENV: production` and any required app env
+- [ ] Reserved or provisioned concurrency set for latency-sensitive endpoints
+
+## Session / state
+
+- [ ] DynamoDB session table has `BillingMode: PAY_PER_REQUEST` (or capacity sized correctly)
+- [ ] `TimeToLiveSpecification.AttributeName: ttl` and `Enabled: true` for automatic session cleanup
+- [ ] In `@FrontMcp`, sessions point at DynamoDB / ElastiCache — never in-memory in Lambda
+- [ ] No filesystem writes outside `/tmp` (default 512 MB; configurable up to 10 GB via SAM `EphemeralStorage` if needed)
+
+## API Gateway / routing
+
+- [ ] Path is `/mcp/{proxy+}` with `Method: ANY` so MCP transport reaches the handler
+- [ ] CORS configured at API Gateway OR via `@FrontMcp` `cors`, not both
+- [ ] Stage names (`Prod` / `Staging`) match deploy pipeline
+
+## IAM hardening
+
+- [ ] No `Action: '*'` or `Resource: '*'` in the function's policies
+- [ ] DynamoDB access scoped to `!Ref SessionTable` only
+- [ ] Secrets read via SSM / Secrets Manager scoped to `/<app>/<env>/*`
+
+## Observability
+
+- [ ] CloudWatch alarm on `Errors` metric
+- [ ] CloudWatch alarm on `Throttles` metric
+- [ ] Dead Letter Queue (SQS) configured for failed async invocations
 
 ## What This Demonstrates
 
-- Complete SAM template with API Gateway, Lambda function, and DynamoDB table
-- DynamoDB for session storage with TTL-based automatic cleanup
-- Lambda handler entry point via `createLambdaHandler`
-- Pay-per-request billing for cost-effective scaling
-- IAM policies scoped to the specific DynamoDB table
+- Verify `Handler: handler.handler` with `CodeUri: dist/lambda/` (the build emits `dist/lambda/handler.cjs`)
+- No hand-written `src/lambda.ts` with a fictional `createLambdaHandler` import
+- DynamoDB session table has TTL enabled for automatic cleanup
+- IAM policies are scoped (no `*` resources / actions)
+- API Gateway proxy route forwards to the function
 
 ## Related
 
-- See `production-lambda` for the full SAM/CloudFormation and Lambda runtime checklist
+- Configuration source of truth: `frontmcp-deployment/references/deploy-to-lambda.md`
+- Build adapter source: `libs/cli/src/commands/build/adapters/lambda.ts`
+- See `production-lambda` for the runtime / scaling checklist

package/catalog/frontmcp-production-readiness/examples/production-lambda/scaling-and-monitoring.md

@@ -27,7 +27,7 @@ Resources:
   McpFunction:
     Type: AWS::Serverless::Function
     Properties:
-      Handler: dist/lambda.handler
+      Handler: dist/handler.handler # Build adapter emits dist/handler.cjs → handler symbol
       CodeUri: .
       Runtime: nodejs20.x
       Timeout: 30
@@ -92,32 +92,42 @@ import { Provider, ProviderScope } from '@frontmcp/sdk';
 
 export const SECRETS = Symbol('Secrets');
 
+// Providers do NOT have onInit/onDestroy — load lazily on first read.
 @Provider({ token: SECRETS, scope: ProviderScope.GLOBAL })
 export class SecretsProvider {
-  private cache = new Map<string, string>();
+  private cache: Map<string, string> | undefined;
 
-  async onInit(): Promise<void> {
-    // Load secrets from AWS SSM Parameter Store (not env vars for sensitive data)
+  private async ensureLoaded(): Promise<Map<string, string>> {
+    if (this.cache) return this.cache;
+    const cache = new Map<string, string>();
     const { SSMClient, GetParametersByPathCommand } = await import('@aws-sdk/client-ssm');
     const ssm = new SSMClient({});
     const path = process.env.SECRETS_PATH ?? '/mcp/production/';
 
-    const result = await ssm.send(
-      new GetParametersByPathCommand({
-        Path: path,
-        WithDecryption: true,
-      }),
-    );
-
-    for (const param of result.Parameters ?? []) {
-      const key = param.Name?.replace(path, '') ?? '';
-      this.cache.set(key, param.Value ?? '');
-    }
+    // Walk every page — GetParametersByPath caps results and returns NextToken
+    // when more parameters exist. Without this loop, large /<env>/ namespaces
+    // silently lose secrets after the first page.
+    let nextToken: string | undefined;
+    do {
+      const result = await ssm.send(
+        new GetParametersByPathCommand({ Path: path, WithDecryption: true, NextToken: nextToken }),
+      );
+      for (const param of result.Parameters ?? []) {
+        const key = param.Name?.replace(path, '') ?? '';
+        cache.set(key, param.Value ?? '');
+      }
+      nextToken = result.NextToken;
+    } while (nextToken);
+    this.cache = cache;
+    return cache;
   }
 
-  get(key: string): string {
-    const value = this.cache.get(key);
-    if (!value) {
+  async get(key: string): Promise<string> {
+    const cache = await this.ensureLoaded();
+    const value = cache.get(key);
+    // `cache.has` / `value === undefined` so empty-string secrets are still
+    // returned (a falsy `!value` check would treat `""` as missing).
+    if (value === undefined) {
       throw new Error(`Secret not found: ${key}`);
     }
     return value;

package/catalog/frontmcp-production-readiness/examples/production-node-sdk/multi-instance-cleanup.md

@@ -2,18 +2,24 @@
 name: multi-instance-cleanup
 reference: production-node-sdk
 level: advanced
-description: 'Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources.'
-tags: [production, sdk, node, multi, instance, cleanup]
+description: 'Shows how multiple SDK instances can coexist without conflicts, and how to clean up timers and listeners — given that `@Provider` classes have **no** `onInit` / `onDestroy` lifecycle hooks. The pattern is: initialize in the constructor, expose an explicit `stop()` method, and have the host app call it before `server.dispose()`.'
+tags:
+  - production
+  - sdk
+  - node
+  - multi
+  - instance
+  - cleanup
 features:
-  - 'Implementing `onDestroy()` in providers to clean up timers and listeners'
-  - 'Ensuring multiple instances coexist without sharing global state'
-  - 'Testing that dispose removes all event listeners (no leaks)'
-  - 'Verifying one instance still works after another is disposed'
+  - Explicit `stop()` method on providers (since `@Provider` classes have no `onDestroy` lifecycle hook)
+  - Ensuring multiple instances coexist without sharing global state
+  - Testing that dispose removes all event listeners (no leaks)
+  - Verifying one instance still works after another is disposed
 ---
 
 # Multi-Instance Coexistence and Cleanup
 
-Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources.
+Shows how multiple SDK instances can coexist without conflicts, and how to clean up timers and listeners — given that `@Provider` classes have **no** `onInit` / `onDestroy` lifecycle hooks. The pattern is: initialize in the constructor, expose an explicit `stop()` method, and have the host app call it before `server.dispose()`.
 
 ## Code
 
@@ -28,24 +34,28 @@ export class PollingProvider {
   private intervalId: ReturnType<typeof setInterval> | undefined;
   private listeners: Array<() => void> = [];
 
-  async onInit(): Promise<void> {
-    // Start a polling interval
+  constructor() {
+    // Init at construction time — there is no async onInit hook on providers.
     this.intervalId = setInterval(() => {
       this.listeners.forEach((fn) => fn());
     }, 10_000);
+    // Don't keep the event loop alive on its own.
+    this.intervalId.unref?.();
   }
 
   addListener(fn: () => void): void {
     this.listeners.push(fn);
   }
 
-  async onDestroy(): Promise<void> {
-    // Clean up timer — prevents dangling intervals after dispose
+  /**
+   * Explicit cleanup. Host app calls this before `server.dispose()`.
+   * (Providers have no onDestroy hook, so this is the explicit pattern.)
+   */
+  stop(): void {
     if (this.intervalId) {
       clearInterval(this.intervalId);
       this.intervalId = undefined;
     }
-    // Remove all listener references — prevents memory leaks
     this.listeners.length = 0;
   }
 }
@@ -71,7 +81,11 @@ describe('Multi-instance coexistence', () => {
     expect(tools1.tools.length).toBeGreaterThan(0);
     expect(tools2.tools.length).toBeGreaterThan(0);
 
-    // Clean up both — no shared global state
+    // Clean up instance 1: stop providers (cancels timers / clears listeners),
+    // then dispose the server. The framework does NOT call provider.stop() for
+    // you — it's the host app's responsibility, which is why the provider
+    // exposes the explicit method.
+    server1.scope.providers.get(BackgroundJobProvider).stop();
     await client1.close();
     await server1.dispose();
 
@@ -79,6 +93,7 @@ describe('Multi-instance coexistence', () => {
     const result = await client2.callTool('my_tool', { input: 'still-alive' });
     expect(result).toBeDefined();
 
+    server2.scope.providers.get(BackgroundJobProvider).stop();
     await client2.close();
     await server2.dispose();
   });
@@ -100,7 +115,7 @@ describe('Multi-instance coexistence', () => {
 
 ## What This Demonstrates
 
-- Implementing `onDestroy()` in providers to clean up timers and listeners
+- Explicit `stop()` method on providers (since `@Provider` classes have no `onDestroy` lifecycle hook)
 - Ensuring multiple instances coexist without sharing global state
 - Testing that dispose removes all event listeners (no leaks)
 - Verifying one instance still works after another is disposed