MCP Server Boilerplate 39k

🚀 MCP Server Skeleton Code

A simple implementation of the Model Context Protocol (MCP) server, serving as a basic template for building custom tools.

🚀 Quick Start

This project offers a fundamental implementation of an MCP server. By leveraging this skeleton code, you can rapidly build your own MCP server and effortlessly expand its functionality.

The article Simple Guide to Setting Up a Custom MCP Server - Zenn provides detailed instructions, and this document serves as a supplementary explanation to the content of that article.

✨ Prerequisites

• Node.js: Version 16.0 or higher is required.
• npm or yarn: For package management.
• Git (optional): If you use Git for code repository management.

📦 Installation

Step 1: Clone the Repository

Run the following commands in the terminal to clone this project:

git clone git@github.com:yourusername/mcp-server.git
cd mcp-server

Step 2: Install Dependencies

Use npm or yarn to install the required packages:

• npm:

npm install

• yarn:

yarn install

Step 3: Start the Server

After installation, start the server:

npm run dev

or

yarn dev

✨ Features

Tool Management

You can define and register custom tools through the src/index.ts file. The default implementation includes the following tools:

• echo: A simple echo tool.
• random-string: Generates a random string.
• math-calculate: Performs mathematical calculations.

Environment Configuration

The project supports configuration via environment variables, mainly covering the following aspects:

Port Configuration

Modify the PORT variable in the .env file to adjust the port on which the server listens.

Log Level

Control the level of log output detail by setting NODE_ENV and LOG_LEVEL in the .env file.

🔧 Technical Details

Project Structure

mcp-server/
├── .env                # Environment variable configuration file
├── .gitignore          # Git repository ignore rules
├── package.json        # Package dependencies and script configuration
├── tsconfig.json       # TypeScript compiler configuration
├── src/
│   ├── index.ts       # Application entry point
│   └── types/         # Type definition folder (continuously updated)
└── README.md           # Project documentation

Developing Extended Tools

In the src/index.ts file, add new tools following this pattern:

/**
 * Define the pattern for tools.
 * The name and description determine how the tool is selected.
 * The handler returns CallToolResult (returns a Promise in asynchronous cases).
 */
server.tool(
  "New Tool Name",
  "Description of the new tool's functionality",
  {Parameter Name: z.Type().describe("Parameter description")},
  ({Parameter Name}) => ({Content: [{type: "text", text: Result}]}),
);

Key Dependencies

• @modelcontextprotocol/sdk: ^1.9.0 - The SDK required for implementing the MCP server.
• zod: ^3.24.2 - A library for type validation and schema definition.

Development Tool Configuration

Using Biome for Code Quality Management

Biome is an efficient JavaScript and TypeScript language server that supports code inspection, formatting, and other features. The project has customized configuration through the biome.json file.

Available Commands

# Check code quality
npm run lint

# Automatically fix code issues
npm run lint:fix

# Format code
npm run format

# Automatically adjust formatting
npm run format:fix

Directory Structure Explanation

• src/: The core source code directory of the project.
  • index.ts: The entry file for starting the application.
  • types/: The type definition folder, used for unified management of interfaces and data structures.
• .env: The environment variable configuration file, containing various parameters required at runtime.
• package.json: The configuration file for project dependency management and script execution.

Quick Start Guide

1. Clone the code repository to your local machine.
2. Install the required dependency packages.
3. Modify the configuration in the .env file according to your needs.
4. Start the server and test the functionality.

Through these steps, you can easily set up a basic MCP server and expand and customize it according to your actual needs.