feat: add structured logging with Pino and environment configuration

- Introduced `src/logger.ts` for structured logging using Pino, with support for OpenTelemetry trace correlation.
- Updated `src/index.ts` to utilize the new logger for handling MCP requests and server operations.
- Added environment configuration in `src/config.ts` with validation using Zod.
- Enhanced error handling and logging throughout the application.
- Updated documentation in `.cursorrules` and `CLAUDE.md` to reflect new features and usage instructions.
- Added support for environment variables including `PORT`, `NODE_ENV`, `SERVER_NAME`, `SERVER_VERSION`, and `LOG_LEVEL`.

Author: nickytonline

.cursorrules

@@ -36,6 +36,9 @@ This is a TypeScript template for building Model Context Protocol (MCP) servers.
   - Defines all available MCP tools with their JSON schemas
   - Routes tool calls to registered tool handlers
   - Handles error responses in MCP format
+- **`src/config.ts`** - Environment configuration with validation using Zod
+- **`src/logger.ts`** - Structured logging with Pino (OpenTelemetry compatible)
+- **`src/lib/utils.ts`** - Utility functions for MCP response formatting
 
 ### Template MCP Tools Available
 
@@ -73,16 +76,30 @@ The template includes one example tool to demonstrate MCP tool implementation:
 - Uses Express for reliable HTTP handling with excellent TypeScript support
 - Session management handles MCP initialization and transport lifecycle
 - Error handling returns MCP-formatted error messages rather than throwing
+- **Structured Logging**: Uses Pino for production-ready logging with OpenTelemetry trace correlation
+- **Configuration Management**: Environment variables validated with Zod schemas
+- **Graceful Shutdown**: Proper SIGTERM/SIGINT handling for container environments
 
 ## Template Usage
 
 This is a template project for creating new MCP servers. To customize:
 
 1. Update `package.json` with your project name and description
-2. Replace the echo tool in `src/index.ts` with your custom tools
-3. Add additional TypeScript files for business logic as needed
-4. Update README.md to document your specific MCP server functionality
-5. Modify this .cursorrules file to reflect your project's architecture
+2. Update environment variables in `src/config.ts` (SERVER_NAME, SERVER_VERSION, etc.)
+3. Replace the echo tool in `src/index.ts` with your custom tools
+4. Add additional TypeScript files for business logic as needed
+5. Update README.md to document your specific MCP server functionality
+6. Modify this .cursorrules file to reflect your project's architecture
+
+## Environment Variables
+
+The following environment variables are supported (see `src/config.ts`):
+
+- `PORT` - Server port (default: 3000)
+- `NODE_ENV` - Environment (development/production/test)
+- `SERVER_NAME` - MCP server name (default: mcp-typescript-template)
+- `SERVER_VERSION` - Server version (default: 1.0.0)
+- `LOG_LEVEL` - Logging level (error/warn/info/debug, default: info)
 
 ## Coding Guidelines
 
@@ -91,4 +108,15 @@ This is a template project for creating new MCP servers. To customize:
 - Prefer functional programming patterns where appropriate
 - Keep methods focused and single-responsibility
 - Use meaningful variable and function names
-- Add JSDoc comments for public APIs
+- Add JSDoc comments for public APIs
+- **Use structured logging**: Always use the `logger` from `src/logger.ts` instead of `console.log`
+- **Environment variables**: Add new config to `src/config.ts` with Zod validation
+- **Error handling**: Use try-catch blocks and log errors with context using structured logging
+
+## Logging Best Practices
+
+- Use appropriate log levels: `error`, `warn`, `info`, `debug`
+- Include relevant context in log messages (user IDs, session IDs, etc.)
+- Log structured data as the second parameter: `logger.info("message", { key: value })`
+- Error logs should include error details: `logger.error("Error message", { error: error.message })`
+- The logger automatically includes trace correlation when OpenTelemetry is configured

CLAUDE.md

@@ -32,6 +32,9 @@ This is a TypeScript template for building Model Context Protocol (MCP) servers.
   - Defines all available MCP tools with their JSON schemas
   - Routes tool calls to registered tool handlers
   - Handles error responses in MCP format
+- **`src/config.ts`** - Environment configuration with validation using Zod
+- **`src/logger.ts`** - Structured logging with Pino (OpenTelemetry compatible)
+- **`src/lib/utils.ts`** - Utility functions for MCP response formatting
 
 ### Template MCP Tools Available
 
@@ -61,16 +64,39 @@ The template includes one example tool to demonstrate MCP tool implementation:
 - Uses Express for reliable HTTP handling with excellent TypeScript support
 - Session management handles MCP initialization and transport lifecycle
 - Error handling returns MCP-formatted error messages rather than throwing
+- **Structured Logging**: Uses Pino for production-ready logging with OpenTelemetry trace correlation
+- **Configuration Management**: Environment variables validated with Zod schemas
+- **Graceful Shutdown**: Proper SIGTERM/SIGINT handling for container environments
 
 ## Template Usage
 
 This is a template project for creating new MCP servers. To customize:
 
 1. Update `package.json` with your project name and description
-2. Replace the echo tool in `src/index.ts` with your custom tools
-3. Add additional TypeScript files for business logic as needed
-4. Update README.md to document your specific MCP server functionality
-5. Modify this CLAUDE.md file to reflect your project's architecture
+2. Update environment variables in `src/config.ts` (SERVER_NAME, SERVER_VERSION, etc.)
+3. Replace the echo tool in `src/index.ts` with your custom tools
+4. Add additional TypeScript files for business logic as needed
+5. Update README.md to document your specific MCP server functionality
+6. Modify this CLAUDE.md file to reflect your project's architecture
+
+## Environment Variables
+
+The following environment variables are supported (see `src/config.ts`):
+
+- `PORT` - Server port (default: 3000)
+- `NODE_ENV` - Environment (development/production/test)
+- `SERVER_NAME` - MCP server name (default: mcp-typescript-template)
+- `SERVER_VERSION` - Server version (default: 1.0.0)
+- `LOG_LEVEL` - Logging level (error/warn/info/debug, default: info)
+
+## Logging Best Practices
+
+- Use appropriate log levels: `error`, `warn`, `info`, `debug`
+- Include relevant context in log messages (user IDs, session IDs, etc.)
+- Log structured data as the second parameter: `logger.info("message", { key: value })`
+- Error logs should include error details: `logger.error("Error message", { error: error.message })`
+- The logger automatically includes trace correlation when OpenTelemetry is configured
+- Use the `logger` from `src/logger.ts` instead of `console.log`
 
 ## Adding New Tools
 
@@ -80,4 +106,6 @@ When adding new tools to the MCP server:
 2. Provide a clear title and description
 3. Define input schema using Zod for validation
 4. Return responses in MCP content format with JSON stringified data
-5. Handle errors gracefully and return appropriate error messages
+5. Handle errors gracefully and return appropriate error messages
+6. Use structured logging to track tool usage: `logger.info("Tool executed", { toolName, args })`
+7. Log errors with context: `logger.error("Tool execution failed", { toolName, error: error.message })`