onamfc/mcp-starter-template-ts

MCP Starter Template

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.

Features

• 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

Quick Start

Prerequisites

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

Installation

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

Development Mode

For development with hot reloading:

npm run dev

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

Project Structure

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/

Configuration

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

Environment Variables

Available Tools

Calculator (calculate)

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
  }
}

File System (filesystem)

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"
  }
}

Text Processing (text-processing)

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!"
  }
}

Weather (weather)

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
  }
}

Available Resources

Configuration (resource://config/current)

Access current application configuration and settings.

Documentation (resource://docs/api)

Complete API documentation and usage examples.

Logs (resource://logs/recent)

Recent application logs and events.

Development

Available Scripts

• 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

Adding New Tools

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
  },
};

Adding New Resources

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

Testing

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

Code Quality

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 Support

Building the Docker Image

docker build -t mcp-server .

Running with Docker

docker run -p 3000:3000 mcp-server

Using Docker Compose

For development with additional services:

docker-compose up --build

Production Deployment

Build for Production

npm run build

Environment Setup

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

Health Monitoring

The server includes built-in health check endpoints:

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

Security Considerations

• 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

Troubleshooting

Common Issues

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"

Debug Mode

Enable debug logging:

LOG_LEVEL=debug npm run dev

Getting Help

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

Contributing

We welcome contributions! Please follow these guidelines:

Development Workflow

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

Code Standards

• 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

Commit Message Format

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

License

MIT License - see file for details.

Changelog

See for version history and updates.

Support

• 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

Roadmap

• 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