mcp-ts-template 1.6.3 → 1.7.1

package/README.md

@@ -1,16 +1,16 @@
 # 🚀 MCP TypeScript Template: Agent, Server & Client
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
-[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
-[![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--03--26-lightgrey.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/changelog.mdx)
-[![Version](https://img.shields.io/badge/Version-1.6.2-blue.svg)](./CHANGELOG.md)
+[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.15.1-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
+[![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--06--18-lightgrey.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx)
+[![Version](https://img.shields.io/badge/Version-1.7.0-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/mcp-ts-template/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/mcp-ts-template?style=social)](https://github.com/cyanheads/mcp-ts-template)
 
 **Jumpstart your [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) development with this comprehensive TypeScript Template for building autonomous agents, servers, and clients.**
 
-This template provides a solid, beginner-friendly foundation for building all components of the MCP ecosystem, adhering to the **MCP 2025-03-26 specification**. It includes a powerful agent framework, a fully-featured server, a robust client, production-ready utilities, and clear documentation to get you up and running quickly.
+This template provides a solid, beginner-friendly foundation for building all components of the MCP ecosystem, adhering to the **MCP 2025-06-18 specification**. It includes a powerful agent framework, a fully-featured server, a robust client, production-ready utilities, and clear documentation to get you up and running quickly.
 
 ## 🏛️ Three-Part Architecture
 

package/dist/mcp-server/resources/echoResource/registration.js

@@ -60,13 +60,12 @@ export const registerEchoResource = async (server) => {
                 };
             }
             catch (error) {
-                const handledError = ErrorHandler.handleError(error, {
+                // Re-throw to be caught by the SDK's top-level error handler
+                throw ErrorHandler.handleError(error, {
                     operation: "echoResourceReadHandler",
                     context: handlerContext,
                     input: { uri: uri.href, params },
                 });
-                // Re-throw to be caught by the SDK's top-level error handler
-                throw handledError;
             }
         });
         logger.info(`Resource '${resourceName}' registered successfully.`, registrationContext);

package/dist/mcp-server/tools/catFactFetcher/logic.d.ts

@@ -20,14 +20,28 @@ export declare const CatFactFetcherInputSchema: z.ZodObject<{
  */
 export type CatFactFetcherInput = z.infer<typeof CatFactFetcherInputSchema>;
 /**
- * Defines the structure of the JSON payload returned by the `get_random_cat_fact` tool handler.
+ * Zod schema for the successful response of the `get_random_cat_fact` tool.
  */
-export interface CatFactFetcherResponse {
+export declare const CatFactFetcherResponseSchema: z.ZodObject<{
+    fact: z.ZodString;
+    length: z.ZodNumber;
+    requestedMaxLength: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    length: number;
+    timestamp: string;
     fact: string;
+    requestedMaxLength?: number | undefined;
+}, {
     length: number;
-    requestedMaxLength?: number;
     timestamp: string;
-}
+    fact: string;
+    requestedMaxLength?: number | undefined;
+}>;
+/**
+ * Defines the structure of the JSON payload returned by the `get_random_cat_fact` tool handler.
+ */
+export type CatFactFetcherResponse = z.infer<typeof CatFactFetcherResponseSchema>;
 /**
  * Processes the core logic for the `get_random_cat_fact` tool.
  * It calls the Cat Fact Ninja API and returns the fetched fact.

package/dist/mcp-server/tools/catFactFetcher/logic.js

@@ -19,6 +19,22 @@ export const CatFactFetcherInputSchema = z
         .describe("Optional: The maximum character length of the cat fact to retrieve."),
 })
     .describe("Input schema for the get_random_cat_fact tool. Allows specifying a maximum length for the fact.");
+/**
+ * Zod schema for the successful response of the `get_random_cat_fact` tool.
+ */
+export const CatFactFetcherResponseSchema = z.object({
+    fact: z.string().describe("The retrieved cat fact."),
+    length: z.number().int().describe("The character length of the cat fact."),
+    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."),
+});
 /**
  * Processes the core logic for the `get_random_cat_fact` tool.
  * It calls the Cat Fact Ninja API and returns the fetched fact.

package/dist/mcp-server/tools/catFactFetcher/registration.js

@@ -4,9 +4,9 @@
  * Cat Fact Ninja API.
  * @module src/mcp-server/tools/catFactFetcher/registration
  */
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { BaseErrorCode } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
-import { CatFactFetcherInputSchema, catFactFetcherLogic, } from "./logic.js";
+import { CatFactFetcherInputSchema, catFactFetcherLogic, CatFactFetcherResponseSchema, } from "./logic.js";
 /**
  * Registers the 'get_random_cat_fact' tool and its handler with the MCP server.
  *
@@ -22,46 +22,47 @@ export const registerCatFactFetcherTool = async (server) => {
     });
     logger.info(`Registering tool: '${toolName}'`, registrationContext);
     await ErrorHandler.tryCatch(async () => {
-        server.tool(toolName, toolDescription, CatFactFetcherInputSchema.shape, async (params, mcpContext) => {
+        server.registerTool(toolName, {
+            title: "Get Random Cat Fact",
+            description: toolDescription,
+            inputSchema: CatFactFetcherInputSchema.shape,
+            outputSchema: CatFactFetcherResponseSchema.shape,
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: true,
+            },
+        }, async (params) => {
             const handlerContext = requestContextService.createRequestContext({
                 parentRequestId: registrationContext.requestId,
                 operation: "HandleToolRequest",
                 toolName: toolName,
-                mcpToolContext: mcpContext,
                 input: params,
             });
             try {
                 const result = await catFactFetcherLogic(params, handlerContext);
+                // Return both structuredContent for modern clients and
+                // stringified content for backward compatibility.
                 return {
+                    structuredContent: result,
                     content: [
                         { type: "text", text: JSON.stringify(result, null, 2) },
                     ],
-                    isError: false,
                 };
             }
             catch (error) {
-                const handledError = ErrorHandler.handleError(error, {
+                const mcpError = ErrorHandler.handleError(error, {
                     operation: "catFactFetcherToolHandler",
                     context: handlerContext,
                     input: params,
                 });
-                const mcpError = handledError instanceof McpError
-                    ? handledError
-                    : new McpError(BaseErrorCode.INTERNAL_ERROR, "An unexpected error occurred while fetching a cat fact.", { originalErrorName: handledError.name });
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: {
-                                    code: mcpError.code,
-                                    message: mcpError.message,
-                                    details: mcpError.details,
-                                },
-                            }),
-                        },
-                    ],
                     isError: true,
+                    content: [{ type: "text", text: `Error: ${mcpError.message}` }],
+                    structuredContent: {
+                        code: mcpError.code,
+                        message: mcpError.message,
+                        details: mcpError.details,
+                    },
                 };
             }
         });

package/dist/mcp-server/tools/echoTool/logic.d.ts

@@ -36,22 +36,34 @@ export declare const EchoToolInputSchema: z.ZodObject<{
  */
 export type EchoToolInput = z.infer<typeof EchoToolInputSchema>;
 /**
- * Defines the structure of the JSON payload returned by the `echo_message` tool.
+ * Zod schema for the successful response of the `echo_message` tool.
  */
-export interface EchoToolResponse {
-    /** The original message provided in the input. */
+export declare const EchoToolResponseSchema: z.ZodObject<{
+    originalMessage: z.ZodString;
+    formattedMessage: z.ZodString;
+    repeatedMessage: z.ZodString;
+    mode: z.ZodEnum<["standard", "uppercase", "lowercase"]>;
+    repeatCount: z.ZodNumber;
+    timestamp: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
     originalMessage: string;
-    /** The message after applying the specified formatting mode. */
+    mode: "standard" | "uppercase" | "lowercase";
     formattedMessage: string;
-    /** The formatted message repeated the specified number of times, joined by spaces. */
     repeatedMessage: string;
-    /** The formatting mode that was applied. */
-    mode: (typeof ECHO_MODES)[number];
-    /** The number of times the message was repeated. */
     repeatCount: number;
-    /** Optional ISO 8601 timestamp of when the response was generated. */
-    timestamp?: string;
-}
+    timestamp?: string | undefined;
+}, {
+    originalMessage: string;
+    mode: "standard" | "uppercase" | "lowercase";
+    formattedMessage: string;
+    repeatedMessage: string;
+    repeatCount: number;
+    timestamp?: string | undefined;
+}>;
+/**
+ * Defines the structure of the JSON payload returned by the `echo_message` tool.
+ */
+export type EchoToolResponse = z.infer<typeof EchoToolResponseSchema>;
 /**
  * Processes the core logic for the `echo_message` tool.
  * It takes validated input parameters, formats the message according to the specified mode,

package/dist/mcp-server/tools/echoTool/logic.js

@@ -6,6 +6,7 @@
  */
 import { z } from "zod";
 import { logger } from "../../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 /**
  * Defines the valid formatting modes for the echo tool operation.
  */
@@ -39,8 +40,32 @@ export const EchoToolInputSchema = z
         .optional()
         .default(true)
         .describe("Whether to include an ISO 8601 timestamp in the response. Defaults to true."),
-})
-    .describe("Zod schema for validating the input arguments for the echo_message tool.");
+});
+/**
+ * Zod schema for the successful response of the `echo_message` tool.
+ */
+export const EchoToolResponseSchema = z.object({
+    originalMessage: z
+        .string()
+        .describe("The original message provided in the input."),
+    formattedMessage: z
+        .string()
+        .describe("The message after applying the specified formatting mode."),
+    repeatedMessage: z
+        .string()
+        .describe("The formatted message repeated the specified number of times, joined by spaces."),
+    mode: z.enum(ECHO_MODES).describe("The formatting mode that was applied."),
+    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."),
+});
 /**
  * Processes the core logic for the `echo_message` tool.
  * It takes validated input parameters, formats the message according to the specified mode,
@@ -55,6 +80,9 @@ export async function echoToolLogic(params, context) {
         ...context,
         toolInput: params,
     });
+    if (params.message === "fail") {
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, "The message was 'fail'.");
+    }
     let formattedMessage = params.message;
     switch (params.mode) {
         case "uppercase":

package/dist/mcp-server/tools/echoTool/registration.js

@@ -4,9 +4,9 @@
  * and the asynchronous handler function that processes tool invocation requests.
  * @module src/mcp-server/tools/echoTool/registration
  */
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { BaseErrorCode } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
-import { EchoToolInputSchema, echoToolLogic } from "./logic.js";
+import { EchoToolInputSchema, echoToolLogic, EchoToolResponseSchema, } from "./logic.js";
 /**
  * Registers the 'echo_message' tool and its handler with the provided MCP server instance.
  *
@@ -22,46 +22,47 @@ export const registerEchoTool = async (server) => {
     });
     logger.info(`Registering tool: '${toolName}'`, registrationContext);
     await ErrorHandler.tryCatch(async () => {
-        server.tool(toolName, toolDescription, EchoToolInputSchema.shape, async (params, mcpContext) => {
+        server.registerTool(toolName, {
+            title: "Echo Message",
+            description: toolDescription,
+            inputSchema: EchoToolInputSchema.shape,
+            outputSchema: EchoToolResponseSchema.shape,
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: false,
+            },
+        }, async (params) => {
             const handlerContext = requestContextService.createRequestContext({
                 parentRequestId: registrationContext.requestId,
                 operation: "HandleToolRequest",
                 toolName: toolName,
-                mcpToolContext: mcpContext,
                 input: params,
             });
             try {
                 const result = await echoToolLogic(params, handlerContext);
+                // Return both structuredContent for modern clients and
+                // stringified content for backward compatibility.
                 return {
+                    structuredContent: result,
                     content: [
                         { type: "text", text: JSON.stringify(result, null, 2) },
                     ],
-                    isError: false,
                 };
             }
             catch (error) {
-                const handledError = ErrorHandler.handleError(error, {
+                const mcpError = ErrorHandler.handleError(error, {
                     operation: "echoToolHandler",
                     context: handlerContext,
                     input: params,
                 });
-                const mcpError = handledError instanceof McpError
-                    ? handledError
-                    : new McpError(BaseErrorCode.INTERNAL_ERROR, "An unexpected error occurred in the echo tool.", { originalErrorName: handledError.name });
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: {
-                                    code: mcpError.code,
-                                    message: mcpError.message,
-                                    details: mcpError.details,
-                                },
-                            }),
-                        },
-                    ],
                     isError: true,
+                    content: [{ type: "text", text: `Error: ${mcpError.message}` }],
+                    structuredContent: {
+                        code: mcpError.code,
+                        message: mcpError.message,
+                        details: mcpError.details,
+                    },
                 };
             }
         });

package/dist/mcp-server/tools/imageTest/logic.d.ts

@@ -12,8 +12,15 @@ export declare const FetchImageTestInputSchema: z.ZodObject<{
     trigger?: boolean | undefined;
 }>;
 export type FetchImageTestInput = z.infer<typeof FetchImageTestInputSchema>;
-export interface FetchImageTestResponse {
+export declare const FetchImageTestResponseSchema: z.ZodObject<{
+    data: z.ZodString;
+    mimeType: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    mimeType: string;
     data: string;
+}, {
     mimeType: string;
-}
+    data: string;
+}>;
+export type FetchImageTestResponse = z.infer<typeof FetchImageTestResponseSchema>;
 export declare function fetchImageTestLogic(input: FetchImageTestInput, parentRequestContext: RequestContext): Promise<FetchImageTestResponse>;

package/dist/mcp-server/tools/imageTest/logic.js

@@ -12,6 +12,10 @@ export const FetchImageTestInputSchema = z.object({
         .default(true)
         .describe("A trigger to invoke the tool and fetch a new cat image."),
 });
+export const FetchImageTestResponseSchema = z.object({
+    data: z.string().describe("Base64 encoded image data."),
+    mimeType: z.string().describe("The MIME type of the image (e.g., 'image/jpeg')."),
+});
 const CAT_API_URL = "https://cataas.com/cat";
 export async function fetchImageTestLogic(input, parentRequestContext) {
     const operationContext = requestContextService.createRequestContext({

package/dist/mcp-server/tools/imageTest/registration.js

@@ -2,9 +2,9 @@
  * @fileoverview Registration for the fetch_image_test MCP tool.
  * @module src/mcp-server/tools/imageTest/registration
  */
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { BaseErrorCode } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
-import { FetchImageTestInputSchema, fetchImageTestLogic, } from "./logic.js";
+import { FetchImageTestInputSchema, fetchImageTestLogic, FetchImageTestResponseSchema, } from "./logic.js";
 /**
  * Registers the fetch_image_test tool with the MCP server.
  * @param server - The McpServer instance.
@@ -17,14 +17,18 @@ export function registerFetchImageTestTool(server) {
         operation,
     });
     ErrorHandler.tryCatch(async () => {
-        server.tool(toolName, toolDescription, FetchImageTestInputSchema.shape, async (input, mcpProvidedContext) => {
-            const parentRequestId = mcpProvidedContext &&
-                typeof mcpProvidedContext === "object" &&
-                "requestId" in mcpProvidedContext
-                ? mcpProvidedContext.requestId
-                : registrationContext.requestId;
+        server.registerTool(toolName, {
+            title: "Fetch Cat Image",
+            description: toolDescription,
+            inputSchema: FetchImageTestInputSchema.shape,
+            outputSchema: FetchImageTestResponseSchema.shape,
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: true,
+            },
+        }, async (input) => {
             const handlerContext = requestContextService.createRequestContext({
-                parentRequestId,
+                parentRequestId: registrationContext.requestId,
                 operation: "fetchImageTestToolHandler",
                 toolName: toolName,
                 input,
@@ -32,6 +36,7 @@ export function registerFetchImageTestTool(server) {
             try {
                 const result = await fetchImageTestLogic(input, handlerContext);
                 return {
+                    structuredContent: result,
                     content: [
                         {
                             type: "image",
@@ -39,32 +44,22 @@ export function registerFetchImageTestTool(server) {
                             mimeType: result.mimeType,
                         },
                     ],
-                    isError: false,
                 };
             }
             catch (error) {
-                const handledError = ErrorHandler.handleError(error, {
+                const mcpError = ErrorHandler.handleError(error, {
                     operation: "fetchImageTestToolHandler",
                     context: handlerContext,
                     input,
                 });
-                const mcpError = handledError instanceof McpError
-                    ? handledError
-                    : new McpError(BaseErrorCode.INTERNAL_ERROR, "An unexpected error occurred while fetching the image.", { originalErrorName: handledError.name });
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: {
-                                    code: mcpError.code,
-                                    message: mcpError.message,
-                                    details: mcpError.details,
-                                },
-                            }),
-                        },
-                    ],
                     isError: true,
+                    content: [{ type: "text", text: `Error: ${mcpError.message}` }],
+                    structuredContent: {
+                        code: mcpError.code,
+                        message: mcpError.message,
+                        details: mcpError.details,
+                    },
                 };
             }
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ts-template",
-  "version": "1.6.3",
+  "version": "1.7.1",
   "description": "Jumpstart Model Context Protocol (MCP) development with this production-ready TypeScript template. Build robust MCP servers and clients with built-in utilities, authentication, and service integrations. Agent framework utilizing MCP Client included.",
   "main": "dist/index.js",
   "files": [
@@ -35,35 +35,37 @@
     "fetch-spec": "ts-node --esm scripts/fetch-openapi-spec.ts",
     "format": "prettier --write \"**/*.{ts,js,json,md,html,css}\"",
     "inspector": "npx mcp-inspector --config mcp.json --server mcp-ts-template",
-    "db:duckdb-example": "MCP_LOG_LEVEL=debug tsc && node dist/storage/duckdbExample.js"
+    "db:duckdb-example": "MCP_LOG_LEVEL=debug tsc && node dist/storage/duckdbExample.js",
+    "test:perf": "ts-node scripts/performance-tester.ts",
+    "test:perf:batch": "ts-node scripts/performance-tester.ts --tool=echo_message --requests=100 --concurrency=10 --batchSize=10"
   },
   "dependencies": {
-    "@duckdb/node-api": "^1.3.1-alpha.23",
-    "@hono/node-server": "^1.15.0",
-    "@modelcontextprotocol/sdk": "^1.15.0",
-    "@supabase/supabase-js": "^2.50.3",
-    "@types/node": "^24.0.10",
+    "@duckdb/node-api": "^1.3.2-alpha.24",
+    "@hono/node-server": "^1.16.0",
+    "@modelcontextprotocol/sdk": "^1.16.0",
+    "@supabase/supabase-js": "^2.52.0",
+    "@types/node": "^24.0.14",
     "@types/sanitize-html": "^2.16.0",
     "@types/validator": "13.15.2",
     "chrono-node": "^2.8.0",
     "dotenv": "^16.6.1",
-    "eslint": "^9.30.1",
-    "hono": "^4.8.4",
+    "eslint": "^9.31.0",
+    "hono": "^4.8.5",
     "ignore": "^7.0.5",
-    "jose": "^6.0.11",
+    "jose": "^6.0.12",
     "js-yaml": "^4.1.0",
-    "node-cron": "^4.2.0",
-    "openai": "^5.8.2",
+    "node-cron": "^4.2.1",
+    "openai": "^5.10.1",
     "partial-json": "^0.1.7",
     "sanitize-html": "^2.17.0",
     "tiktoken": "^1.0.21",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.35.1",
+    "typescript-eslint": "^8.37.0",
     "validator": "13.15.15",
     "winston": "^3.17.0",
     "winston-transport": "^4.9.0",
-    "zod": "^3.25.74"
+    "zod": "^3.25.76"
   },
   "keywords": [
     "typescript",
@@ -105,7 +107,7 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.30.1",
+    "@eslint/js": "^9.31.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node-cron": "^3.0.11",
     "axios": "^1.10.0",