mcp-ts-template 1.4.2 → 1.4.3

package/README.md

@@ -3,12 +3,12 @@
 [![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.12.1-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.4.2-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.4.3-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) Client & Server](https://modelcontextprotocol.io/) development with this TypeScript Repo Template!**
+**Jumpstart your [Model Context Protocol (MCP) Client & Server](https://modelcontextprotocol.io/) development with this TypeScript MCP Repo Template!**
 
 This template provides a solid, beginner-friendly foundation for building robust MCP servers and clients, adhering to the **MCP 2025-03-26 specification**. It includes production-ready utilities, a well-structured codebase, working examples, and clear documentation to get you up and running quickly.
 
@@ -18,15 +18,14 @@ Whether you're creating a new MCP server to extend an AI's capabilities or integ
 
 - [✨ Key Features](#-key-features)
 - [🌟 Projects Using This Template](#-projects-using-this-template)
-- [🏁 Quick Start](#quick-start)
+- [🏁 Quick Start](#-quick-start)
 - [⚙️ Configuration](#️-configuration)
-- [🔩 Server Configuration (Environment Variables)](#server-configuration-environment-variables)
-- [🔌 Client Configuration (`src/mcp-client/client-config/mcp-config.json`)](#client-configuration-mcp-configjson)
+- [🔩 Server Configuration (Environment Variables)](#-server-configuration-environment-variables)
 - [🏗️ Project Structure](#️-project-structure)
-- [🧩 Adding Tools/Resources](#-adding-your-own-tools--resources)
+- [🧩 Extending the MCP Server](#-extending-the-mcp-server)
 - [🌍 More MCP Resources](#-explore-more-mcp-resources)
 - [📜 License](#-license)
-- [📊 Detailed Features Table](#detailed-features-table)
+- [📊 Detailed Features Table](#-detailed-features-table)
 
 ## ✨ Key Features
 
@@ -129,39 +128,9 @@ Configure the MCP server's behavior using these environment variables:
 
 **Security Note for HTTP Transport:** When using `MCP_TRANSPORT_TYPE=http`, authentication is **mandatory** as per the MCP specification. This template includes JWT-based authentication middleware (`src/mcp-server/transports/authentication/authMiddleware.ts`). You **MUST** set a strong, unique `MCP_AUTH_SECRET_KEY` in your production environment for this security mechanism to function correctly. Failure to do so will result in bypassed authentication checks in development and fatal errors in production.
 
-### 🔌 Client Configuration (`src/mcp-client/client-config/mcp-config.json`)
-
-Configure the connections for the built-in **MCP client** using `src/mcp-client/client-config/mcp-config.json`. If this file is missing, it falls back to `src/mcp-client/client-config/mcp-config.json.example`.
-
-This file defines external MCP servers the client can connect to. The client implementation adheres to the **MCP 2025-03-26 specification**.
-
-**Example `mcp-config.json` (see `src/mcp-client/client-config/mcp-config.json.example` for the full version):**
-
-```json
-{
-  "mcpServers": {
-    "my-stdio-server": {
-      "command": "node", // Command or executable
-      "args": ["/path/to/my-server/index.js"], // Arguments for stdio
-      "env": { "LOG_LEVEL": "debug" }, // Optional environment variables
-      "transportType": "stdio" // Explicitly stdio (or omit for default)
-    },
-    "my-http-server": {
-      "command": "http://localhost:8080", // Base URL for HTTP
-      "args": [], // Not used for HTTP
-      "env": {}, // Not used for HTTP
-      "transportType": "http" // Explicitly http
-    }
-  }
-}
-```
-
-- **`command`**: Executable path (`stdio`) or Base URL (`http`).
-- **`args`**: Array of arguments (required for `stdio`).
-- **`env`**: Optional environment variables to set for the server process (`stdio`).
-- **`transportType`**: `stdio` (default) or `http`.
+### 🔌 Client Configuration
 
-See `src/mcp-client/client-config/configLoader.ts` for the Zod validation schema and `src/mcp-client/client-config/mcp-config.json.example` for a complete example.
+For detailed information on configuring the built-in **MCP client**, including how to set up connections to external MCP servers using `mcp-config.json`, please see the [Client Configuration Guide](src/mcp-client/client-config/README.md).
 
 ## 🏗️ Project Structure
 
@@ -198,21 +167,9 @@ npm run tree
 
 (This uses `scripts/tree.ts` to generate a current file tree, respecting `.gitignore`.)
 
-## 🧩 Adding Your Own Tools & Resources
-
-This template is designed for extension! Follow the high-level SDK patterns:
-
-1.  **Create Directories**: Add new directories under `src/mcp-server/tools/yourToolName/` or `src/mcp-server/resources/yourResourceName/`.
-2.  **Implement Logic (`logic.ts`)**: Define Zod schemas for inputs/outputs and write your core processing function.
-3.  **Register (`registration.ts`)**:
-    - **Tools**: Use `server.tool(name, description, zodSchemaShape, handler)` (SDK v1.10.2+). This handles schema generation, validation, and routing. Remember to add relevant annotations (`readOnlyHint`, `destructiveHint`, etc.) as untrusted hints.
-    - **Resources**: Use `server.resource(regName, template, metadata, handler)`.
-    - Wrap logic in `ErrorHandler.tryCatch` for robust error handling.
-4.  **Export & Import**: Export the registration function from your new directory's `index.ts` and call it within `createMcpServerInstance` in `src/mcp-server/server.ts`.
-
-Refer to the included `EchoTool` and `EchoResource` examples and the [.clinerules](.clinerules) cheatsheet for detailed patterns.
+## 🧩 Extending the MCP Server
 
-For an example of a tool that performs asynchronous operations, such as making an external API call, see the `get_random_cat_fact` tool located in `src/mcp-server/tools/catFactFetcher/`. This tool demonstrates how to use `async/await` within your tool's logic and handler, manage Promises, and integrate external data sources.
+For detailed guidance on how to add your own custom Tools and Resources to this MCP server template, including workflow examples and best practices, please see the [Server Extension Guide](src/mcp-server/README.md).
 
 ## 🌍 Explore More MCP Resources
 

package/dist/mcp-server/server.js

@@ -17,8 +17,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { config, environment } from "../config/index.js";
 import { ErrorHandler, logger, requestContextService } from "../utils/index.js";
 import { registerEchoResource } from "./resources/echoResource/index.js";
-import { registerEchoTool } from "./tools/echoTool/index.js";
 import { registerCatFactFetcherTool } from "./tools/catFactFetcher/index.js";
+import { registerEchoTool } from "./tools/echoTool/index.js";
 import { startHttpTransport } from "./transports/httpTransport.js";
 import { connectStdioTransport } from "./transports/stdioTransport.js";
 /**

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

@@ -4,4 +4,4 @@
  * primarily exporting the `registerCatFactFetcherTool` function.
  * @module src/mcp-server/tools/catFactFetcher/index
  */
-export { registerCatFactFetcherTool } from "./catFactFetcherRegistration.js";
+export { registerCatFactFetcherTool } from "./registration.js";

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

@@ -4,4 +4,4 @@
  * primarily exporting the `registerCatFactFetcherTool` function.
  * @module src/mcp-server/tools/catFactFetcher/index
  */
-export { registerCatFactFetcherTool } from "./catFactFetcherRegistration.js";
+export { registerCatFactFetcherTool } from "./registration.js";

package/dist/mcp-server/tools/catFactFetcher/{catFactFetcherRegistration.js → registration.js}

@@ -6,7 +6,7 @@
  */
 import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
-import { CatFactFetcherInputSchema, processCatFactFetcher, } from "./catFactFetcherLogic.js";
+import { CatFactFetcherInputSchema, processCatFactFetcher } from "./logic.js";
 /**
  * Registers the 'get_random_cat_fact' tool and its handler with the MCP server.
  *

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

@@ -8,7 +8,7 @@
  */
 import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
-import { EchoToolInputSchema, processEchoMessage } from "./echoToolLogic.js";
+import { EchoToolInputSchema, processEchoMessage } from "./logic.js";
 /**
  * Registers the 'echo_message' tool and its handler with the provided MCP server instance.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ts-template",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "TypeScript template for building Model Context Protocol (MCP) Servers & Clients. Features extensive utilities (logger, requestContext, etc.), STDIO & Streamable HTTP (with authMiddleware), examples, and type safety. Ideal starting point for creating production-ready MCP Servers & Clients.",
   "main": "dist/index.js",
   "files": [