A comprehensive starter template for building Model Context Protocol (MCP) servers with TypeScript. This template provides a solid foundation for developers of all skill levels to quickly bootstrap production-ready MCP projects.

• TypeScript First: Complete type safety with comprehensive type definitions
• Production Ready: Robust error handling, logging, and validation
• Modular Architecture: Clean separation of concerns following SOLID principles
• Comprehensive Testing: Unit tests with Jest and high coverage standards
• Docker Support: Containerization for easy deployment
• CI/CD Ready: GitHub Actions workflows included
• Developer Friendly: Extensive documentation and debugging tools
• Security Focused: Input validation and secure file operations
• Health Monitoring: Built-in health checks and metrics

• Node.js 18.0.0 or higher
• npm 8.0.0 or higher (or yarn/pnpm equivalent)

Choose your preferred package manager:

Using npm:

git clone https://github.com/onamfc/mcp-starter-template-ts.git cd mcp-starter-template-ts npm install npm run build npm start

Using yarn:

git clone https://github.com/onamfc/mcp-starter-template-ts.git cd mcp-starter-template-ts yarn install yarn build yarn start

Using pnpm:

git clone https://github.com/onamfc/mcp-starter-template-ts.git cd mcp-starter-template-ts pnpm install pnpm build pnpm start

For development with hot reloading:

npm run dev

This will start the server with automatic restarts when you modify source files.

src/ ├── server.ts # Main MCP server implementation ├── types/ # TypeScript type definitions │ └── index.ts ├── tools/ # MCP tools implementation │ ├── setup.ts # Tool registration and management │ ├── calculator.ts # Mathematical calculations │ ├── filesystem.ts # File system operations │ ├── text-processing.ts # Text manipulation and analysis │ └── weather.ts # Weather information (mock) ├── resources/ # MCP resources implementation │ ├── setup.ts # Resource registration and management │ ├── config.ts # Configuration access │ ├── docs.ts # Documentation resource │ └── logs.ts # Logs access ├── utils/ # Utility functions │ ├── config.ts # Configuration management │ ├── logger.ts # Structured logging │ ├── validation.ts # Input validation │ ├── errors.ts # Error handling │ └── health.ts # Health check utilities └── __tests__/ # Test files ├── server.test.ts ├── tools/ └── utils/ 

The server can be configured through environment variables. Create a .env file in the project root:

# Server Configuration PORT=3000 HOST=localhost LOG_LEVEL=info NODE_ENV=development # Feature Flags ENABLE_HEALTH_CHECK=true # Security MAX_REQUEST_SIZE=10mb CORS_ORIGINS=* # External Services (if needed) # WEATHER_API_KEY=your_api_key_here # DATABASE_URL=your_database_url_here

Perform mathematical calculations with support for basic arithmetic operations.

Parameters:

• expression (string, required): Mathematical expression to evaluate
• precision (number, optional): Number of decimal places (default: 2)

Example:

{ "name": "calculate", "arguments": { "expression": "2 + 3 * 4", "precision": 2 } }

Read and write files within the project directory with security restrictions.

Parameters:

• operation (string, required): Operation type (read, write, list, exists)
• path (string, required): File or directory path (relative to project root)
• content (string, optional): Content to write (required for write operation)
• encoding (string, optional): File encoding (utf8, base64, default: utf8)

Example:

{ "name": "filesystem", "arguments": { "operation": "read", "path": "package.json" } }

Process and analyze text with various operations.

Parameters:

• operation (string, required): Operation type (count, uppercase, lowercase, reverse, wordcount, sentiment)
• text (string, required): Text content to process
• options (object, optional): Additional options for the operation

Example:

{ "name": "text-processing", "arguments": { "operation": "sentiment", "text": "I love this amazing weather today!" } }

Get current weather information and forecasts (mock implementation).

Parameters:

• location (string, required): Location name or coordinates
• units (string, optional): Temperature units (metric, imperial, kelvin, default: metric)
• forecast (boolean, optional): Include 5-day forecast (default: false)

Example:

{ "name": "weather", "arguments": { "location": "New York, NY", "units": "metric", "forecast": true } }

Access current application configuration and settings.

Complete API documentation and usage examples.

Recent application logs and events.

• npm run dev - Start development server with hot reloading
• npm run build - Build the project for production
• npm start - Start the production server
• npm test - Run test suite
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage report
• npm run lint - Run ESLint
• npm run lint:fix - Run ESLint with auto-fix
• npm run format - Format code with Prettier
• npm run format:check - Check code formatting
• npm run type-check - Run TypeScript type checking
• npm run clean - Clean build artifacts
• npm run health - Check server health
• npm run validate-config - Validate configuration

1. Create a new file in src/tools/your-tool.ts
2. Implement the ToolDefinition interface
3. Add comprehensive error handling and logging
4. Register the tool in src/tools/setup.ts
5. Add tests in src/__tests__/tools/your-tool.test.ts

Example tool structure:

export const yourTool: ToolDefinition = { name: 'your-tool', description: 'Description of what your tool does', inputSchema: { type: 'object', properties: { // Define your parameters here }, required: ['requiredParam'], }, handler: async (args, context) => { // Implement your tool logic here // Always include proper error handling and logging }, };

1. Create a new file in src/resources/your-resource.ts
2. Implement the ResourceDefinition interface
3. Add the resource to src/resources/setup.ts
4. Add tests for the resource

Run the complete test suite:

npm test

Run tests in watch mode during development:

npm run test:watch

Generate coverage report:

npm run test:coverage

This project includes comprehensive code quality tools:

• ESLint: Linting with TypeScript support
• Prettier: Code formatting
• TypeScript: Type checking
• Jest: Testing framework

Run all quality checks:

npm run lint && npm run format:check && npm run type-check

docker build -t mcp-server .

docker run -p 3000:3000 mcp-server

For development with additional services:

docker-compose up --build

npm run build

1. Set NODE_ENV=production
2. Configure appropriate log levels
3. Set up proper CORS origins
4. Configure external service credentials
5. Set up monitoring and alerting

The server includes built-in health check endpoints:

• Health status: GET http://localhost:3001/health
• Metrics: GET http://localhost:3001/metrics

• All file operations are restricted to the project directory
• Input validation is performed on all tool parameters
• Expressions in calculator tool are sanitized to prevent code injection
• Request logging includes tracking for security auditing
• Error messages do not expose sensitive system information

Server won't start:

• Check that the port is not already in use
• Verify Node.js version (must be 18.0.0 or higher)
• Run npm run validate-config to check configuration

Tools not working:

• Check the logs for detailed error messages
• Verify input parameters match the tool schema
• Ensure file paths are relative and within project directory

Build failures:

• Run npm run clean to remove old build artifacts
• Check for TypeScript errors with npm run type-check
• Verify all dependencies are installed

Test failures:

• Make sure you're in the project root directory
• Check that all environment variables are set correctly
• Run tests individually to isolate issues: npm test -- --testNamePattern="specific test"

Enable debug logging:

LOG_LEVEL=debug npm run dev

1. Check the troubleshooting section above
2. Review the API documentation at resource://docs/api
3. Check recent logs at resource://logs/recent
4. Open an issue on the project repository

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes with tests
4. Run the full test suite: npm test
5. Run quality checks: npm run lint && npm run format:check && npm run type-check
6. Commit your changes with a descriptive message
7. Push to your fork and submit a pull request

• Follow the existing code style and patterns
• Add comprehensive tests for new features
• Include JSDoc comments for all public functions
• Update documentation for any API changes
• Ensure all tests pass and coverage remains high

Use conventional commit format:

• feat: add new weather tool
• fix: resolve validation error in calculator
• docs: update installation instructions
• test: add tests for file system tool
• chore: update dependencies

MIT License - see LICENSE file for details.

See CHANGELOG.md for version history and updates.

• Documentation: Check the /docs directory for detailed guides
• Issues: Report bugs or request features via GitHub issues
• Discussions: Join community discussions for questions and ideas

• Add more built-in tools (HTTP client, database operations)
• Implement plugin system for external tools
• Add WebSocket transport support
• Create web-based admin interface
• Add metrics and monitoring dashboard
• Implement rate limiting and request quotas
• Add authentication and authorization
• Create tool marketplace integration