gemyago/typescript-mcp-boilerplate

HelloWorld MCP Server

A simple HelloWorld MCP (Model Context Protocol) server experiment built with TypeScript.

Features

This MCP server provides two simple tools:

• hello: Say hello to someone (default: "World")
• add: Add two numbers together

Prerequisites

• Node.js 22+ (LTS)
• npm
• nvm (recommended for Node.js version management)
• direnv (for environment management)

Setup

1. Node.js Version Management

   # If you have nvm installed:
   nvm use
   
   # This will use Node.js version 22 as specified in .nvmrc
   

2. Environment Setup with direnv

   # Allow direnv for this directory
   direnv allow
   
   # This will automatically add node_modules/.bin to your PATH
   

3. Install Dependencies

   npm install
   

Development

Available Scripts

• npm run dev - Run the server in development mode using tsx
• npm run build - Compile TypeScript to JavaScript
• npm start - Run the compiled server
• npm run lint - Run ESLint on the source code
• npm run lint:fix - Run ESLint and automatically fix issues
• npm run clean - Remove the dist directory

Running the Server

For development:

npm run dev

For production:

npm run build
npm start

MCP Server Usage

This server communicates via stdio and implements the Model Context Protocol. It provides:

Tools

1. hello

   • Description: Say hello to someone
   • Parameters:
     • name (optional): The name of the person to greet (default: "World")
   • Example: {"name": "Alice"} → "Hello, Alice! 👋 Welcome to the HelloWorld MCP server!"

2. add

   • Description: Add two numbers together
   • Parameters:
     • a (required): First number
     • b (required): Second number
   • Example: {"a": 5, "b": 3} → "5 + 3 = 8"

Project Structure

├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (after build)
├── .nvmrc               # Node.js version specification
├── .envrc               # direnv configuration
├── eslint.config.js     # ESLint configuration
├── tsconfig.json        # TypeScript configuration
├── package.json         # Node.js project configuration
└── README.md           # This file

Code Quality

This project uses:

• TypeScript for type safety
• ESLint with TypeScript support for code quality
• Strict TypeScript configuration for better type checking

License

MIT