MCP Server Boilerplate 39k

🚀 MCP 服务器骨架代码

本项目提供了模型上下文协议（MCP）服务器的简单实现，可作为构建自定义工具的基础模板，帮助开发者快速搭建自己的 MCP 服务器并扩展功能。

🚀 快速开始

按照以下步骤，您可以快速搭建并启动 MCP 服务器：

1. 克隆代码仓库到本地。
2. 安装所需的依赖包。
3. 根据需求修改 .env 文件中的配置。
4. 启动服务器并测试功能。

✨ 主要特性

工具管理

通过 src/index.ts 文件能够定义和注册自定义工具。默认实现包含以下工具：

• echo：简单回显工具。
• random-string：生成随机字符串。
• math-calculate：执行数学计算。

环境配置

项目支持通过环境变量进行配置，主要涉及以下方面：

• 端口配置：修改 .env 文件中的 PORT 变量，可调整服务器监听的端口。
• 日志级别：通过设置 .env 中的 NODE_ENV 和 LOG_LEVEL，能控制日志输出的详细程度。

📦 安装指南

步骤 1: 克隆代码仓库

在终端中运行以下命令以克隆此项目：

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

步骤 2: 安装依赖项

使用 npm 或 yarn 安装所需的包：

• npm：

npm install

• yarn：

yarn install

步骤 3: 启动服务器

安装完成后，启动服务器：

npm run dev

或

yarn dev

💻 使用示例

基础用法

在 src/index.ts 文件中，按照以下模式添加新的工具：

/**
 * 定义工具的模式
 * name 和 description 决定了工具的选择方式
 * handler 返回 CallToolResult（异步情况下返回 Promise）
 */
server.tool(
  "新工具名称",
  "新工具的功能描述",
  {参数名: z.类型().describe("参数说明")},
  ({参数名}) => ({内容: [{type: "text", text: 结果}]}),
);

📚 详细文档

项目结构

mcp-server/
├── .env                # 环境变量配置文件
├── .gitignore          # Git 仓库忽略规则
├── package.json        # 包依赖和脚本配置
├── tsconfig.json       # TypeScript 编译器配置
├── src/
│   ├── index.ts       # 应用入口点
│   └── types/         # 类型定义文件夹（持续更新中）
└── README.md           # 项目说明文档

目录结构说明

• src/：项目的核心源码目录。
  • index.ts：应用启动入口文件。
  • types/：类型定义文件夹，用于统一管理接口和数据结构。
• .env：环境变量配置文件，包含运行时所需的各种参数。
• package.json：项目依赖管理和脚本执行的配置文件。

主要依赖包

• @modelcontextprotocol/sdk: ^1.9.0 - MCP 服务器实现所需的 SDK
• zod: ^3.24.2 - 用于类型验证和模式定义的库

开发工具配置

使用 Biome 进行代码质量管理

Biome 是一个高效的 JavaScript 和 TypeScript 语言服务器，支持代码检查、格式化等功能。项目中通过 biome.json 文件进行了定制化的配置。

可用命令

# 检查代码质量
npm run lint

# 自动修复代码问题
npm run lint:fix

# 格式化代码
npm run format

# 自动调整格式
npm run format:fix

参考文章

简易的自定义MCP服务器的搭建方法 - Zenn 中的文章提供了详细的指导，本文档是对该文章内容的补充说明。

前提条件

• Node.js：需要安装版本16.0或更高。
• npm 或 yarn ：用于包管理。
• Git （可选）：如果使用 Git 进行代码仓库管理。

🔧 技术细节

环境变量配置

项目支持通过环境变量进行配置，主要涉及端口配置和日志级别控制。修改 .env 文件中的 PORT 变量可调整服务器监听的端口；通过设置 .env 中的 NODE_ENV 和 LOG_LEVEL 能控制日志输出的详细程度。

工具定义与注册

通过 src/index.ts 文件可以定义和注册自定义工具。在该文件中，使用 server.tool 方法来定义工具，其中 name 和 description 决定了工具的选择方式，handler 返回 CallToolResult（异步情况下返回 Promise）。