mcp-ts-template 2.1.8 → 2.2.0

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-2.1.8-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--06--18-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.18.2-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/mcp-ts-template/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.2.22-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Code Coverage](https://img.shields.io/badge/Coverage-77.29%25-brightgreen.svg?style=flat-square)](./coverage/lcov-report/)
+[![Version](https://img.shields.io/badge/Version-2.2.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--06--18-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.18.2-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/mcp-ts-template/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.2.22-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Code Coverage](https://img.shields.io/badge/Coverage-83.55%25-brightgreen.svg?style=flat-square)](./coverage/lcov-report/)
 
 </div>
 
@@ -14,6 +14,7 @@
 ## ✨ Features
 
 - **Declarative Tools & Resources**: Define capabilities in single, self-contained files. The framework handles registration and execution.
+- **Elicitation Support**: Tools can interactively prompt the user for missing parameters during execution, streamlining user workflows.
 - **Robust Error Handling**: A unified `McpError` system ensures consistent, structured error responses across the server.
 - **Pluggable Authentication**: Secure your server with zero-fuss support for `none`, `jwt`, or `oauth` modes.
 - **Abstracted Storage**: Swap storage backends (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2`) without changing business logic.
@@ -29,22 +30,25 @@
 
 ### Installation
 
-1.  **Clone the repository:**
-    ```sh
-    git clone https://github.com/cyanheads/mcp-ts-template.git
-    ```
-2.  **Navigate into the directory:**
-    ```sh
-    cd mcp-ts-template
-    ```
-3.  **Install dependencies:**
-    ```sh
-    bun install
-    ```
+1.
+**Clone the repository:**
+```sh
+git clone https://github.com/cyanheads/mcp-ts-template.git
+```
+2.
+**Navigate into the directory:**
+```sh
+cd mcp-ts-template
+```
+3.
+**Install dependencies:**
+```sh
+bun install
+```
 
 ## 🛠️ Understanding the Template: Tools & Resources
 
-This template includes working examples of a tool (`template_echo_message`) and a resource (`echo-resource`). Here’s how they are structured.
+This template includes working examples of tools and resources.
 
 ### 1. Example Tool: `template_echo_message`
 
@@ -56,7 +60,7 @@ This tool echoes back a message with optional formatting. You can find the full
 ```ts
 // Located at: src/mcp-server/tools/definitions/template-echo-message.tool.ts
 import { z } from 'zod';
-import type { ToolDefinition } from '@/mcp-server/tools/utils/toolDefinition.js';
+import type { SdkContext, ToolDefinition } from '@/mcp-server/tools/utils/toolDefinition.js';
 import { withToolAuth } from '@/mcp-server/transports/auth/lib/withAuth.js';
 import { type RequestContext, logger } from '@/utils/index.js';
 
@@ -86,7 +90,8 @@ const OutputSchema = z.object({
 // 2. Implement the pure business logic for the tool.
 async function echoToolLogic(
   input: z.infer<typeof InputSchema>,
-  context: RequestContext,
+  appContext: RequestContext,
+  sdkContext: SdkContext,
 ): Promise<z.infer<typeof OutputSchema>> {
   // ... logic to format and repeat the message
   const formattedMessage = input.message.toUpperCase(); // simplified for example
@@ -98,7 +103,7 @@ async function echoToolLogic(
 export const echoTool: ToolDefinition<typeof InputSchema, typeof OutputSchema> =
   {
     name: 'template_echo_message', // The official tool name
-    title: 'Echo Message',
+    title: 'Template Echo Message',
     description:
       'Echoes a message back with optional formatting and repetition.',
     inputSchema: InputSchema,
@@ -107,7 +112,7 @@ export const echoTool: ToolDefinition<typeof InputSchema, typeof OutputSchema> =
   };
 ```
 
-The `echoTool` is registered in `src/mcp-server/tools/definitions/index.ts`, making it available to the server on startup.
+The `echoTool` is registered in `src/mcp-server/tools/definitions/index.ts`, making it available to the server on startup. For an example of how to use the new elicitation feature, see `template_madlibs_elicitation.tool.ts`.
 
 </details>
 
@@ -175,14 +180,14 @@ Like the tool, `echoResourceDefinition` is registered in `src/mcp-server/resourc
 
 All configuration is centralized and validated at startup in `src/config/index.ts`. Key environment variables in your `.env` file include:
 
-| Variable                | Description                                                                    | Default     |
-| :---------------------- | :----------------------------------------------------------------------------- | :---------- |
-| `MCP_TRANSPORT_TYPE`    | The transport to use: `stdio` or `http`.                                       | `http`      |
-| `MCP_HTTP_PORT`         | The port for the HTTP server.                                                  | `3010`      |
-| `MCP_AUTH_MODE`         | Authentication mode: `none`, `jwt`, or `oauth`.                                | `none`      |
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `MCP_TRANSPORT_TYPE` | The transport to use: `stdio` or `http`. | `http` |
+| `MCP_HTTP_PORT` | The port for the HTTP server. | `3010` |
+| `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |
 | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv`, `r2`. | `in-memory` |
-| `OTEL_ENABLED`          | Set to `true` to enable OpenTelemetry.                                         | `false`     |
-| `LOG_LEVEL`             | The minimum level for logging.                                                 | `info`      |
+| `OTEL_ENABLED` | Set to `true` to enable OpenTelemetry. | `false` |
+| `LOG_LEVEL` | The minimum level for logging. | `info` |
 
 ### Authentication & Authorization
 
@@ -219,43 +224,48 @@ All configuration is centralized and validated at startup in `src/config/index.t
 - **Run checks and tests**:
   ```sh
   bun devcheck # Lints, formats, type-checks, and more
-  bun test         # Runs the test suite
+  bun test # Runs the test suite
   ```
 
 ### Cloudflare Workers
 
-1.  **Build the Worker bundle**:
-    ```sh
-    bun build:worker
-    ```
-2.  **Run locally with Wrangler**:
-    ```sh
-    bun deploy:dev
-    ```
-3.  **Deploy to Cloudflare**:
-    `sh
+1.
+**Build the Worker bundle**:
+```sh
+bun build:worker
+```
+2.
+**Run locally with Wrangler**:
+```sh
+bun deploy:dev
+```
+3.
+**Deploy to Cloudflare**:
+`sh
 bun deploy:prod
-` > **Note**: The `wrangler.toml` file is pre-configured to enable `nodejs_compat` for best results.
+`
+> **Note**: The `wrangler.toml` file is pre-configured to enable `nodejs_compat` for best results.
 
 ## 📂 Project Structure
 
-| Directory                              | Purpose & Contents                                                                   |
-| :------------------------------------- | :----------------------------------------------------------------------------------- |
-| `src/mcp-server/tools/definitions`     | Your tool definitions (`*.tool.ts`). This is where you add new capabilities.         |
+| Directory | Purpose & Contents |
+| :--- | :--- |
+| `src/mcp-server/tools/definitions` | Your tool definitions (`*.tool.ts`). This is where you add new capabilities. |
 | `src/mcp-server/resources/definitions` | Your resource definitions (`*.resource.ts`). This is where you add new data sources. |
-| `src/mcp-server/transports`            | Implementations for HTTP and STDIO transports, including auth middleware.            |
-| `src/storage`                          | The `StorageService` abstraction and all storage provider implementations.           |
-| `src/services`                         | Integrations with external services (e.g., the default OpenRouter LLM provider).     |
-| `src/container`                        | Dependency injection container registrations and tokens.                             |
-| `src/utils`                            | Core utilities for logging, error handling, performance, security, and telemetry.    |
-| `src/config`                           | Environment variable parsing and validation with Zod.                                |
-| `tests/`                               | Unit and integration tests, mirroring the `src/` directory structure.                |
+| `src/mcp-server/transports` | Implementations for HTTP and STDIO transports, including auth middleware. |
+| `src/storage` | The `StorageService` abstraction and all storage provider implementations. |
+| `src/services` | Integrations with external services (e.g., the default OpenRouter LLM provider). |
+| `src/container` | Dependency injection container registrations and tokens. |
+| `src/utils` | Core utilities for logging, error handling, performance, security, and telemetry. |
+| `src/config` | Environment variable parsing and validation with Zod. |
+| `tests/` | Unit and integration tests, mirroring the `src/` directory structure. |
 
 ## 🧑‍💻 Agent Development Guide
 
 For a strict set of rules when using this template with an AI agent, please refer to **`AGENTS.md`**. Key principles include:
 
 - **Logic Throws, Handlers Catch**: Never use `try/catch` in your tool/resource `logic`. Throw an `McpError` instead.
+- **Use Elicitation for Missing Input**: If a tool requires user input that wasn't provided, use the `elicitInput` function from the `SdkContext` to ask the user for it.
 - **Pass the Context**: Always pass the `RequestContext` object through your call stack.
 - **Use the Barrel Exports**: Register new tools and resources only in the `index.ts` barrel files.
 

package/dist/index.js

@@ -117229,7 +117229,7 @@ var z = /* @__PURE__ */ Object.freeze({
 // package.json
 var package_default = {
   name: "mcp-ts-template",
-  version: "2.1.7",
+  version: "2.1.8",
   mcpName: "io.github.cyanheads/mcp-ts-template",
   description: "The definitive, production-grade template for building powerful and scalable Model Context Protocol (MCP) servers with TypeScript, featuring built-in observability (OpenTelemetry), declarative tooling, robust error handling, and a modular, DI-driven architecture.",
   main: "dist/index.js",
@@ -117284,8 +117284,8 @@ var package_default = {
     prepare: "[ -d .husky ] && husky || true",
     inspector: "bunx mcp-inspector --config mcp.json --server mcp-ts-template",
     "db:duckdb-example": "MCP_LOG_LEVEL=debug tsc && node dist/storage/duckdbExample.js",
-    test: "bun test",
-    "test:coverage": "bun test --coverage",
+    test: "bun test --config vitest.config.ts",
+    "test:coverage": "bun test --coverage --config vitest.config.ts",
     audit: "bun audit",
     "audit:fix": "bun audit --fix",
     "publish-mcp": "bun scripts/validate-mcp-publish-schema.ts"
@@ -117750,6 +117750,7 @@ var JsonRpcErrorCode;
   JsonRpcErrorCode2[JsonRpcErrorCode2["ConfigurationError"] = -32008] = "ConfigurationError";
   JsonRpcErrorCode2[JsonRpcErrorCode2["InitializationFailed"] = -32009] = "InitializationFailed";
   JsonRpcErrorCode2[JsonRpcErrorCode2["DatabaseError"] = -32010] = "DatabaseError";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["SerializationError"] = -32070] = "SerializationError";
   JsonRpcErrorCode2[JsonRpcErrorCode2["UnknownError"] = -32099] = "UnknownError";
 })(JsonRpcErrorCode ||= {});
 
@@ -124913,6 +124914,8 @@ var import_tsyringe5 = __toESM(require_cjs3(), 1);
 import { existsSync, mkdirSync } from "fs";
 import { readFile, readdir, rm, writeFile } from "fs/promises";
 import path2 from "path";
+var FILE_ENVELOPE_VERSION = 1;
+
 class FileSystemProvider {
   storagePath;
   constructor(storagePath) {
@@ -124949,12 +124952,38 @@ class FileSystemProvider {
     }
     return filePath;
   }
+  buildEnvelope(value, options) {
+    const expiresAt = options?.ttl ? Date.now() + options.ttl * 1000 : undefined;
+    return {
+      __mcp: { v: FILE_ENVELOPE_VERSION, ...expiresAt ? { expiresAt } : {} },
+      value
+    };
+  }
+  async parseAndValidate(raw, tenantId, key, filePath, context) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && "__mcp" in parsed) {
+        const env2 = parsed;
+        const expiresAt = env2.__mcp?.expiresAt;
+        if (expiresAt && Date.now() > expiresAt) {
+          try {
+            await rm(filePath);
+          } catch {}
+          return null;
+        }
+        return env2.value;
+      }
+      return parsed;
+    } catch (error2) {
+      throw new McpError(-32070 /* SerializationError */, `Failed to parse stored JSON for key "${key}" (tenant "${tenantId}").`, { ...context, error: error2 });
+    }
+  }
   async get(tenantId, key, context) {
     const filePath = this.getFilePath(tenantId, key);
     return ErrorHandler.tryCatch(async () => {
       try {
         const data = await readFile(filePath, "utf-8");
-        return JSON.parse(data);
+        return this.parseAndValidate(data, tenantId, key, filePath, context);
       } catch (error2) {
         if (error2 instanceof Error && "code" in error2 && error2.code === "ENOENT") {
           return null;
@@ -124967,10 +124996,11 @@ class FileSystemProvider {
       input: { tenantId, key }
     });
   }
-  async set(tenantId, key, value, context) {
+  async set(tenantId, key, value, context, options) {
     const filePath = this.getFilePath(tenantId, key);
     return ErrorHandler.tryCatch(async () => {
-      const content = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+      const envelope = this.buildEnvelope(value, options);
+      const content = JSON.stringify(envelope, null, 2);
       mkdirSync(path2.dirname(filePath), { recursive: true });
       await writeFile(filePath, content, "utf-8");
     }, {
@@ -124997,11 +125027,39 @@ class FileSystemProvider {
       input: { tenantId, key }
     });
   }
+  async listFilesRecursively(dir, baseDir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+      const fullPath = path2.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...await this.listFilesRecursively(fullPath, baseDir));
+      } else if (entry.isFile()) {
+        const rel = path2.relative(baseDir, fullPath);
+        results.push(rel.split(path2.sep).join("/"));
+      }
+    }
+    return results;
+  }
   async list(tenantId, prefix, context) {
     return ErrorHandler.tryCatch(async () => {
       const tenantPath = this.getTenantPath(tenantId);
-      const files = await readdir(tenantPath);
-      return files.filter((file) => file.startsWith(prefix));
+      const allKeys = await this.listFilesRecursively(tenantPath, tenantPath);
+      const candidateKeys = allKeys.filter((k) => k.startsWith(prefix));
+      const validKeys = [];
+      for (const k of candidateKeys) {
+        const filePath = this.getFilePath(tenantId, k);
+        try {
+          const raw = await readFile(filePath, "utf-8");
+          const value = await this.parseAndValidate(raw, tenantId, k, filePath, context);
+          if (value !== null) {
+            validKeys.push(k);
+          }
+        } catch (_e) {
+          continue;
+        }
+      }
+      return validKeys;
     }, {
       operation: "FileSystemProvider.list",
       context,
@@ -125154,6 +125212,8 @@ SupabaseProvider = __legacyDecorateClassTS([
 ], SupabaseProvider);
 
 // src/storage/providers/cloudflare/r2Provider.ts
+var R2_ENVELOPE_VERSION = 1;
+
 class R2Provider {
   bucket;
   constructor(bucket) {
@@ -125162,58 +125222,99 @@ class R2Provider {
   getR2Key(tenantId, key) {
     return `${tenantId}:${key}`;
   }
-  async get(tenantId, key, context) {
-    const r2Key = this.getR2Key(tenantId, key);
-    logger.debug(`[R2Provider] Getting key: ${r2Key}`, context);
-    const object = await this.bucket.get(r2Key);
-    if (object === null) {
-      logger.debug(`[R2Provider] Key not found: ${r2Key}`, context);
-      return null;
-    }
+  buildEnvelope(value, options) {
+    const expiresAt = options?.ttl ? Date.now() + options.ttl * 1000 : undefined;
+    return {
+      __mcp: { v: R2_ENVELOPE_VERSION, ...expiresAt ? { expiresAt } : {} },
+      value
+    };
+  }
+  parseAndValidate(raw, tenantId, key, context) {
     try {
-      return await object.json();
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && "__mcp" in parsed) {
+        const env2 = parsed;
+        const expiresAt = env2.__mcp?.expiresAt;
+        if (expiresAt && Date.now() > expiresAt) {
+          return null;
+        }
+        return env2.value;
+      }
+      return parsed;
     } catch (error2) {
-      logger.error(`[R2Provider] Failed to parse JSON for key: ${r2Key}`, {
-        ...context,
-        error: error2
-      });
-      return null;
+      throw new McpError(-32070 /* SerializationError */, `[R2Provider] Failed to parse JSON for key: ${this.getR2Key(tenantId, key)}`, { ...context, error: error2 });
     }
   }
+  async get(tenantId, key, context) {
+    const r2Key = this.getR2Key(tenantId, key);
+    return ErrorHandler.tryCatch(async () => {
+      logger.debug(`[R2Provider] Getting key: ${r2Key}`, context);
+      const object = await this.bucket.get(r2Key);
+      if (object === null) {
+        return null;
+      }
+      const text = await object.text();
+      const value = this.parseAndValidate(text, tenantId, key, context);
+      if (value === null) {
+        await this.bucket.delete(r2Key).catch(() => {});
+        logger.debug(`[R2Provider] Key expired and removed: ${r2Key}`, context);
+      }
+      return value;
+    }, {
+      operation: "R2Provider.get",
+      context,
+      input: { tenantId, key }
+    });
+  }
   async set(tenantId, key, value, context, options) {
     const r2Key = this.getR2Key(tenantId, key);
-    logger.debug(`[R2Provider] Setting key: ${r2Key}`, { ...context, options });
-    const valueToStore = JSON.stringify(value);
-    const putOptions = {};
-    if (options?.ttl) {
-      logger.warning(`[R2Provider] TTL is not natively supported by R2. The 'ttl' option for key '${r2Key}' will be ignored.`, context);
-    }
-    await this.bucket.put(r2Key, valueToStore, putOptions);
-    logger.debug(`[R2Provider] Successfully set key: ${r2Key}`, context);
+    return ErrorHandler.tryCatch(async () => {
+      logger.debug(`[R2Provider] Setting key: ${r2Key}`, {
+        ...context,
+        options
+      });
+      const envelope = this.buildEnvelope(value, options);
+      const body = JSON.stringify(envelope);
+      await this.bucket.put(r2Key, body);
+      logger.debug(`[R2Provider] Successfully set key: ${r2Key}`, context);
+    }, {
+      operation: "R2Provider.set",
+      context,
+      input: { tenantId, key }
+    });
   }
   async delete(tenantId, key, context) {
     const r2Key = this.getR2Key(tenantId, key);
-    logger.debug(`[R2Provider] Deleting key: ${r2Key}`, context);
-    const head = await this.bucket.head(r2Key);
-    if (head === null) {
-      logger.debug(`[R2Provider] Key to delete not found: ${r2Key}`, context);
-      return false;
-    }
-    await this.bucket.delete(r2Key);
-    logger.debug(`[R2Provider] Successfully deleted key: ${r2Key}`, context);
-    return true;
+    return ErrorHandler.tryCatch(async () => {
+      logger.debug(`[R2Provider] Deleting key: ${r2Key}`, context);
+      const head = await this.bucket.head(r2Key);
+      if (head === null) {
+        logger.debug(`[R2Provider] Key to delete not found: ${r2Key}`, context);
+        return false;
+      }
+      await this.bucket.delete(r2Key);
+      logger.debug(`[R2Provider] Successfully deleted key: ${r2Key}`, context);
+      return true;
+    }, {
+      operation: "R2Provider.delete",
+      context,
+      input: { tenantId, key }
+    });
   }
   async list(tenantId, prefix, context) {
     const r2Prefix = this.getR2Key(tenantId, prefix);
-    logger.debug(`[R2Provider] Listing keys with prefix: ${r2Prefix}`, context);
-    const listOptions = {
-      prefix: r2Prefix
-    };
-    const listed = await this.bucket.list(listOptions);
-    const tenantPrefix = `${tenantId}:`;
-    const keys = listed.objects.map((obj) => obj.key.startsWith(tenantPrefix) ? obj.key.substring(tenantPrefix.length) : obj.key);
-    logger.debug(`[R2Provider] Found ${keys.length} keys with prefix: ${r2Prefix}`, context);
-    return keys;
+    return ErrorHandler.tryCatch(async () => {
+      logger.debug(`[R2Provider] Listing keys with prefix: ${r2Prefix}`, context);
+      const listed = await this.bucket.list({ prefix: r2Prefix });
+      const tenantPrefix = `${tenantId}:`;
+      const keys = listed.objects.map((obj) => obj.key.startsWith(tenantPrefix) ? obj.key.substring(tenantPrefix.length) : obj.key);
+      logger.debug(`[R2Provider] Found ${keys.length} keys with prefix: ${r2Prefix}`, context);
+      return keys;
+    }, {
+      operation: "R2Provider.list",
+      context,
+      input: { tenantId, prefix }
+    });
   }
 }
 
@@ -125228,59 +125329,78 @@ class KvProvider {
   }
   async get(tenantId, key, context) {
     const kvKey = this.getKvKey(tenantId, key);
-    logger.debug(`[KvProvider] Getting key: ${kvKey}`, context);
-    try {
-      const result = await this.kv.get(kvKey, "json");
-      if (result === null) {
-        logger.debug(`[KvProvider] Key not found: ${kvKey}`, context);
-        return null;
+    return ErrorHandler.tryCatch(async () => {
+      logger.debug(`[KvProvider] Getting key: ${kvKey}`, context);
+      try {
+        const result = await this.kv.get(kvKey, "json");
+        return result;
+      } catch (error2) {
+        throw new McpError(-32070 /* SerializationError */, `[KvProvider] Failed to parse JSON for key: ${kvKey}`, { ...context, error: error2 });
       }
-      return result;
-    } catch (error2) {
-      logger.error(`[KvProvider] Failed to get or parse key: ${kvKey}`, {
-        ...context,
-        error: error2
-      });
-      return null;
-    }
+    }, {
+      operation: "KvProvider.get",
+      context,
+      input: { tenantId, key }
+    });
   }
   async set(tenantId, key, value, context, options) {
     const kvKey = this.getKvKey(tenantId, key);
-    logger.debug(`[KvProvider] Setting key: ${kvKey}`, { ...context, options });
-    const valueToStore = JSON.stringify(value);
-    const putOptions = {};
-    if (options?.ttl) {
-      putOptions.expirationTtl = options.ttl;
-    }
-    await this.kv.put(kvKey, valueToStore, putOptions);
-    logger.debug(`[KvProvider] Successfully set key: ${kvKey}`, context);
+    return ErrorHandler.tryCatch(async () => {
+      logger.debug(`[KvProvider] Setting key: ${kvKey}`, {
+        ...context,
+        options
+      });
+      const valueToStore = JSON.stringify(value);
+      const putOptions = {};
+      if (options?.ttl) {
+        putOptions.expirationTtl = options.ttl;
+      }
+      await this.kv.put(kvKey, valueToStore, putOptions);
+      logger.debug(`[KvProvider] Successfully set key: ${kvKey}`, context);
+    }, {
+      operation: "KvProvider.set",
+      context,
+      input: { tenantId, key }
+    });
   }
   async delete(tenantId, key, context) {
     const kvKey = this.getKvKey(tenantId, key);
-    logger.debug(`[KvProvider] Deleting key: ${kvKey}`, context);
-    const value = await this.kv.get(kvKey);
-    if (value === null) {
-      logger.debug(`[KvProvider] Key to delete not found: ${kvKey}`, context);
-      return false;
-    }
-    await this.kv.delete(kvKey);
-    logger.debug(`[KvProvider] Successfully deleted key: ${kvKey}`, context);
-    return true;
+    return ErrorHandler.tryCatch(async () => {
+      logger.debug(`[KvProvider] Deleting key: ${kvKey}`, context);
+      const value = await this.kv.get(kvKey);
+      if (value === null) {
+        logger.debug(`[KvProvider] Key to delete not found: ${kvKey}`, context);
+        return false;
+      }
+      await this.kv.delete(kvKey);
+      logger.debug(`[KvProvider] Successfully deleted key: ${kvKey}`, context);
+      return true;
+    }, {
+      operation: "KvProvider.delete",
+      context,
+      input: { tenantId, key }
+    });
   }
   async list(tenantId, prefix, context) {
     const kvPrefix = this.getKvKey(tenantId, prefix);
-    logger.debug(`[KvProvider] Listing keys with prefix: ${kvPrefix}`, context);
-    const listed = await this.kv.list({ prefix: kvPrefix });
-    const tenantPrefix = `${tenantId}:`;
-    const keys = listed.keys.map((keyInfo) => keyInfo.name.startsWith(tenantPrefix) ? keyInfo.name.substring(tenantPrefix.length) : keyInfo.name);
-    logger.debug(`[KvProvider] Found ${keys.length} keys with prefix: ${kvPrefix}`, context);
-    return keys;
+    return ErrorHandler.tryCatch(async () => {
+      logger.debug(`[KvProvider] Listing keys with prefix: ${kvPrefix}`, context);
+      const listed = await this.kv.list({ prefix: kvPrefix });
+      const tenantPrefix = `${tenantId}:`;
+      const keys = listed.keys.map((keyInfo) => keyInfo.name.startsWith(tenantPrefix) ? keyInfo.name.substring(tenantPrefix.length) : keyInfo.name);
+      logger.debug(`[KvProvider] Found ${keys.length} keys with prefix: ${kvPrefix}`, context);
+      return keys;
+    }, {
+      operation: "KvProvider.list",
+      context,
+      input: { tenantId, prefix }
+    });
   }
 }
 
 // src/storage/core/storageFactory.ts
 var isServerless3 = typeof process === "undefined" || process.env.IS_SERVERLESS === "true";
-function createStorageProvider(config2) {
+function createStorageProvider(config2, deps = {}) {
   const context = requestContextService.createRequestContext({
     operation: "createStorageProvider"
   });
@@ -125302,16 +125422,19 @@ function createStorageProvider(config2) {
       if (!config2.supabase?.url || !config2.supabase?.serviceRoleKey) {
         throw new McpError(-32008 /* ConfigurationError */, "SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY must be set for the supabase storage provider.", context);
       }
+      if (deps.supabaseClient) {
+        return new SupabaseProvider(deps.supabaseClient);
+      }
       return import_tsyringe5.container.resolve(SupabaseProvider);
     case "cloudflare-r2":
       if (isServerless3) {
-        const bucket = globalThis.R2_BUCKET;
+        const bucket = deps.r2Bucket ?? globalThis.R2_BUCKET;
         return new R2Provider(bucket);
       }
       throw new McpError(-32008 /* ConfigurationError */, "Cloudflare R2 storage is only available in a Cloudflare Worker environment.", context);
     case "cloudflare-kv":
       if (isServerless3) {
-        const kv = globalThis.KV_NAMESPACE;
+        const kv = deps.kvNamespace ?? globalThis.KV_NAMESPACE;
         return new KvProvider(kv);
       }
       throw new McpError(-32008 /* ConfigurationError */, "Cloudflare KV storage is only available in a Cloudflare Worker environment.", context);
@@ -125387,9 +125510,9 @@ function withRequiredScopes(requiredScopes) {
 
 // src/mcp-server/transports/auth/lib/withAuth.ts
 function withToolAuth(requiredScopes, logicFn) {
-  return async (input, context) => {
+  return async (input, context, sdkContext) => {
     withRequiredScopes(requiredScopes);
-    return Promise.resolve(logicFn(input, context));
+    return Promise.resolve(logicFn(input, context, sdkContext));
   };
 }
 function withResourceAuth(requiredScopes, logicFn) {
@@ -128768,7 +128891,7 @@ var import_tsyringe8 = __toESM(require_cjs3(), 1);
 
 // src/mcp-server/tools/definitions/template-cat-fact.tool.ts
 var TOOL_NAME = "template_cat_fact";
-var TOOL_TITLE = "template_cat_fact";
+var TOOL_TITLE = "Template Cat Fact";
 var TOOL_DESCRIPTION = "Fetches a random cat fact from a public API with an optional maximum length.";
 var TOOL_ANNOTATIONS = {
   readOnlyHint: true,
@@ -128790,20 +128913,20 @@ var OutputSchema2 = z.object({
   requestedMaxLength: z.number().int().optional().describe("The maximum length that was requested for the fact."),
   timestamp: z.string().datetime().describe("ISO 8601 timestamp of when the response was generated.")
 }).describe("Cat fact tool response payload.");
-async function catFactToolLogic(input, context) {
+async function catFactToolLogic(input, appContext, _sdkContext) {
   logger.debug("Processing template_cat_fact logic.", {
-    ...context,
+    ...appContext,
     toolInput: input
   });
   const url = input.maxLength !== undefined ? `${CAT_FACT_API_URL}?max_length=${input.maxLength}` : CAT_FACT_API_URL;
-  logger.info(`Fetching random cat fact from: ${url}`, context);
-  const response = await fetchWithTimeout(url, CAT_FACT_API_TIMEOUT_MS, context);
+  logger.info(`Fetching random cat fact from: ${url}`, appContext);
+  const response = await fetchWithTimeout(url, CAT_FACT_API_TIMEOUT_MS, appContext);
   if (!response.ok) {
     const errorText = await response.text().catch(() => {
       return;
     });
     throw new McpError(-32000 /* ServiceUnavailable */, `Cat Fact API request failed: ${response.status} ${response.statusText}`, {
-      requestId: context.requestId,
+      requestId: appContext.requestId,
       httpStatusCode: response.status,
       responseBody: errorText
     });
@@ -128812,12 +128935,12 @@ async function catFactToolLogic(input, context) {
   const parsed = CatFactApiSchema.safeParse(rawData);
   if (!parsed.success) {
     logger.error("Cat Fact API response validation failed", {
-      ...context,
+      ...appContext,
       receivedData: rawData,
       issues: parsed.error.issues
     });
     throw new McpError(-32000 /* ServiceUnavailable */, "Cat Fact API returned unexpected data format.", {
-      requestId: context.requestId,
+      requestId: appContext.requestId,
       issues: parsed.error.issues
     });
   }
@@ -128829,7 +128952,7 @@ async function catFactToolLogic(input, context) {
     timestamp: new Date().toISOString()
   };
   logger.notice("Random cat fact fetched and processed successfully.", {
-    ...context,
+    ...appContext,
     factLength: toolResponse.length
   });
   return toolResponse;
@@ -128855,7 +128978,7 @@ var catFactTool = {
 
 // src/mcp-server/tools/definitions/template-echo-message.tool.ts
 var TOOL_NAME2 = "template_echo_message";
-var TOOL_TITLE2 = "Echo Message";
+var TOOL_TITLE2 = "Template Echo Message";
 var TOOL_DESCRIPTION2 = "Echoes a message back with optional formatting and repetition.";
 var TOOL_ANNOTATIONS2 = {
   readOnlyHint: true,
@@ -128881,17 +129004,17 @@ var OutputSchema3 = z.object({
   repeatCount: z.number().int().min(1).describe("The number of times the message was repeated."),
   timestamp: z.string().datetime().optional().describe("Optional ISO 8601 timestamp of when the response was generated.")
 }).describe("Echo tool response payload.");
-async function echoToolLogic(input, context) {
+async function echoToolLogic(input, appContext, _sdkContext) {
   logger.debug("Processing echo message logic.", {
-    ...context,
+    ...appContext,
     toolInput: input
   });
   if (input.message === TEST_ERROR_TRIGGER_MESSAGE) {
     const errorData = {
-      requestId: context.requestId
+      requestId: appContext.requestId
     };
-    if (typeof context.traceId === "string") {
-      errorData.traceId = context.traceId;
+    if (typeof appContext.traceId === "string") {
+      errorData.traceId = appContext.traceId;
     }
     throw new McpError(-32007 /* ValidationError */, "Deliberate failure triggered.", errorData);
   }
@@ -128950,7 +129073,7 @@ function arrayBufferToBase64(buffer) {
 
 // src/mcp-server/tools/definitions/template-image-test.tool.ts
 var TOOL_NAME3 = "template_image_test";
-var TOOL_TITLE3 = "Fetch Image Test";
+var TOOL_TITLE3 = "Template Image Test";
 var TOOL_DESCRIPTION3 = "Fetches a random cat image and returns it base64-encoded with the MIME type. Useful for testing image handling.";
 var TOOL_ANNOTATIONS3 = {
   readOnlyHint: true,
@@ -128965,25 +129088,25 @@ var OutputSchema4 = z.object({
   data: z.string().describe("Base64 encoded image data."),
   mimeType: z.string().describe("The MIME type of the image (e.g., 'image/jpeg').")
 }).describe("Image tool response payload.");
-async function imageTestToolLogic(input, context) {
+async function imageTestToolLogic(input, appContext, _sdkContext) {
   logger.debug("Processing template_image_test logic.", {
-    ...context,
+    ...appContext,
     toolInput: input
   });
-  const response = await fetchWithTimeout(CAT_API_URL, API_TIMEOUT_MS, context);
+  const response = await fetchWithTimeout(CAT_API_URL, API_TIMEOUT_MS, appContext);
   if (!response.ok) {
     const errorText = await response.text().catch(() => {
       return;
     });
     throw new McpError(-32000 /* ServiceUnavailable */, `Image API request failed: ${response.status} ${response.statusText}`, {
-      requestId: context.requestId,
+      requestId: appContext.requestId,
       httpStatusCode: response.status,
       responseBody: errorText
     });
   }
   const arrayBuf = await response.arrayBuffer();
   if (arrayBuf.byteLength === 0) {
-    throw new McpError(-32000 /* ServiceUnavailable */, "Image API returned an empty payload.", { requestId: context.requestId });
+    throw new McpError(-32000 /* ServiceUnavailable */, "Image API returned an empty payload.", { requestId: appContext.requestId });
   }
   const mimeType = response.headers.get("content-type") || "image/jpeg";
   const result = {
@@ -128991,7 +129114,7 @@ async function imageTestToolLogic(input, context) {
     mimeType
   };
   logger.notice("Image fetched and encoded successfully.", {
-    ...context,
+    ...appContext,
     mimeType,
     byteLength: arrayBuf.byteLength
   });
@@ -129017,8 +129140,91 @@ var imageTestTool = {
   responseFormatter: responseFormatter3
 };
 
+// src/mcp-server/tools/definitions/template_madlibs_elicitation.tool.ts
+var TOOL_NAME4 = "template_madlibs_elicitation";
+var TOOL_TITLE4 = "Mad Libs Elicitation Game";
+var TOOL_DESCRIPTION4 = "Plays a game of Mad Libs. If any parts of speech (noun, verb, adjective) are missing, it will use elicitation to ask the user for them.";
+var TOOL_ANNOTATIONS4 = {
+  readOnlyHint: true,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var InputSchema4 = z.object({
+  noun: z.string().optional().describe("A noun for the story."),
+  verb: z.string().optional().describe("A verb (past tense) for the story."),
+  adjective: z.string().optional().describe("An adjective for the story.")
+}).describe("Inputs for the Mad Libs game. Any missing fields will be elicited.");
+var OutputSchema5 = z.object({
+  story: z.string().describe("The final, generated Mad Libs story."),
+  noun: z.string().describe("The noun used in the story."),
+  verb: z.string().describe("The verb used in the story."),
+  adjective: z.string().describe("The adjective used in the story.")
+}).describe("The completed Mad Libs story and the words used.");
+function hasElicitInput(ctx) {
+  return typeof ctx?.elicitInput === "function";
+}
+async function elicitAndValidate(partOfSpeech, sdkContext) {
+  if (!hasElicitInput(sdkContext)) {
+    throw new McpError(-32600 /* InvalidRequest */, "Elicitation is not available in the current context.", { requestId: sdkContext.requestId, operation: "madlibs.elicit" });
+  }
+  const elicitedUnknown = await sdkContext.elicitInput({
+    message: `I need a ${partOfSpeech}.`,
+    schema: { type: "string" }
+  });
+  const validation = z.string().min(1).safeParse(elicitedUnknown);
+  if (!validation.success) {
+    throw new McpError(-32602 /* InvalidParams */, `Invalid ${partOfSpeech} received from user.`, { provided: elicitedUnknown });
+  }
+  return validation.data;
+}
+async function madlibsToolLogic(input, appContext, sdkContext) {
+  logger.debug("Processing Mad Libs logic.", { ...appContext, toolInput: input });
+  const noun = input.noun ?? await elicitAndValidate("noun", sdkContext);
+  const verb = input.verb ?? await elicitAndValidate("verb", sdkContext);
+  const adjective = input.adjective ?? await elicitAndValidate("adjective", sdkContext);
+  const story = `The ${adjective} ${noun} ${verb} over the lazy dog.`;
+  const response = {
+    story,
+    noun,
+    verb,
+    adjective
+  };
+  return Promise.resolve(response);
+}
+function responseFormatter4(result) {
+  return [
+    {
+      type: "text",
+      text: result.story
+    },
+    {
+      type: "text",
+      text: JSON.stringify({
+        noun: result.noun,
+        verb: result.verb,
+        adjective: result.adjective
+      }, null, 2)
+    }
+  ];
+}
+var madlibsElicitationTool = {
+  name: TOOL_NAME4,
+  title: TOOL_TITLE4,
+  description: TOOL_DESCRIPTION4,
+  inputSchema: InputSchema4,
+  outputSchema: OutputSchema5,
+  annotations: TOOL_ANNOTATIONS4,
+  logic: withToolAuth(["tool:madlibs:play"], madlibsToolLogic),
+  responseFormatter: responseFormatter4
+};
+
 // src/mcp-server/tools/definitions/index.ts
-var allToolDefinitions = [catFactTool, echoTool, imageTestTool];
+var allToolDefinitions = [
+  catFactTool,
+  echoTool,
+  imageTestTool,
+  madlibsElicitationTool
+];
 
 // src/mcp-server/tools/utils/toolHandlerFactory.ts
 var defaultResponseFormatter2 = (result) => [
@@ -129027,25 +129233,29 @@ var defaultResponseFormatter2 = (result) => [
 function createMcpToolHandler({
   toolName,
   logic,
-  responseFormatter: responseFormatter4 = defaultResponseFormatter2
+  responseFormatter: responseFormatter5 = defaultResponseFormatter2
 }) {
   return async (input, callContext) => {
-    const sessionId = typeof callContext?.sessionId === "string" ? callContext.sessionId : undefined;
-    const handlerContext = requestContextService.createRequestContext({
-      parentContext: callContext,
+    const sdkContext = callContext;
+    const sessionId = typeof sdkContext?.sessionId === "string" ? sdkContext.sessionId : undefined;
+    const appContext = requestContextService.createRequestContext({
+      parentContext: sdkContext,
       operation: "HandleToolRequest",
       additionalContext: { toolName, sessionId, input }
     });
+    if ("elicitInput" in sdkContext && typeof sdkContext.elicitInput === "function") {
+      appContext.elicitInput = sdkContext.elicitInput;
+    }
     try {
-      const result = await measureToolExecution(() => logic(input, handlerContext), { ...handlerContext, toolName }, input);
+      const result = await measureToolExecution(() => logic(input, appContext, sdkContext), { ...appContext, toolName }, input);
       return {
         structuredContent: result,
-        content: responseFormatter4(result)
+        content: responseFormatter5(result)
       };
     } catch (error2) {
       const mcpError = ErrorHandler.handleError(error2, {
         operation: `tool:${toolName}`,
-        context: handlerContext,
+        context: appContext,
         input
       });
       return {
@@ -133920,7 +134130,8 @@ async function createMcpServerInstance() {
     capabilities: {
       logging: {},
       resources: { listChanged: true },
-      tools: { listChanged: true }
+      tools: { listChanged: true },
+      elicitation: {}
     }
   });
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ts-template",
-  "version": "2.1.8",
+  "version": "2.2.0",
   "mcpName": "io.github.cyanheads/mcp-ts-template",
   "description": "The definitive, production-grade template for building powerful and scalable Model Context Protocol (MCP) servers with TypeScript, featuring built-in observability (OpenTelemetry), declarative tooling, robust error handling, and a modular, DI-driven architecture.",
   "main": "dist/index.js",
@@ -55,8 +55,8 @@
     "prepare": "[ -d .husky ] && husky || true",
     "inspector": "bunx mcp-inspector --config mcp.json --server mcp-ts-template",
     "db:duckdb-example": "MCP_LOG_LEVEL=debug tsc && node dist/storage/duckdbExample.js",
-    "test": "bun test",
-    "test:coverage": "bun test --coverage",
+    "test": "bun test --config vitest.config.ts",
+    "test:coverage": "bun test --coverage --config vitest.config.ts",
     "audit": "bun audit",
     "audit:fix": "bun audit --fix",
     "publish-mcp": "bun scripts/validate-mcp-publish-schema.ts"
@@ -154,6 +154,7 @@
     "mcp",
     "model-context-protocol",
     "mcp-server",
+    "elicitation",
     "observability",
     "opentelemetry",
     "otel",