快速启动mcp服务器模板
项目介绍
Fastify MCP 服务器样板
生产就绪的模型上下文协议（MCP）服务器样板：fastify-mcp + TypeScript + Biome + tsup (esbuild) + Docker
基于 fastify-mcp，用于处理强大的MCP协议。
您将获得什么
| 工具 | 目的 | 为什么不是其他替代方案？ |
|---|---|---|
| fastify-mcp | MCP协议集成 | 处理所有MCP服务器逻辑、会话管理和传输层。核心工具！ |
| Biome | 代码检查 + 格式化 | 替代ESLint + Prettier + 导入排序。速度快10-100倍，零配置 |
| tsup | 打包 | 使用esbuild。比webpack/rollup快10倍，完美支持ESM |
| Fastify | HTTP服务器 | 比Express快3倍，内置TypeScript支持，插件生态系统 |
| pino | 日志记录 | 最快的JSON日志记录器，漂亮的开发模式，生产就绪的结构化日志 |
| Docker | 部署 | 多阶段构建，安全加固，优化生产环境 |
特性
现代技术栈
- tsup (esbuild) - 比webpack/rollup快10倍的构建速度（约40毫秒）
- Biome - 全能工具链（替代ESLint + Prettier + 导入排序）
- TypeScript 5.7 带严格模式和完美的ESM支持
- Fastify 5.x - 高性能HTTP服务器（比Express快3倍）
- Pino日志记录 - 结构化的JSON日志，带有漂亮的开发模式
- 无需
.js扩展名 - 打包器处理所有模块解析
零配置开发体验
- 热重载 在监视模式下小于50毫秒
- 无工具冲突 - Biome + TypeScript完美协作
- 一键设置 -
npm install && npm run dev - 预配置VSCode - 包含扩展和设置
- 全面脚本 - 开发、构建、检查、格式化、验证、部署
部署就绪
- 多阶段Docker构建 以生成最优生产镜像
- Docker Compose 配置用于开发和生产
- 健康检查 带有详细的系统指标
- 基于环境的配置 （开发/生产）
- 非root容器用户 提高安全性
可观测性
- 请求跟踪 带有唯一的请求ID
- 健康端点 带有内存使用和运行时间指标
- 结构化日志 为日志聚合（如ELK）准备
- 错误处理 使用正确的HTTP状态码
快速开始
1. 克隆并设置
# 克隆此样板（替换为您的仓库名称）
git clone <https://github.com/your-username/fastify-m-服务器样板.git> my-mcp-server
cd my-mcp-server
# 安装依赖
npm install
# 复制环境文件
cp env.example .env
2. 启动开发
# 启动具有热重载的开发服务器
npm run dev
# 您的服务器现在正在 <http://localhost:8080> 运行
# 健康检查: <http://localhost:8080/health>
# MCP端点: <http://localhost:8080/mcp>
3. 使用MCP客户端测试
使用Cursor IDE:
- 打开Cursor IDE设置
- 添加MCP服务器配置：
- 传输方式: HTTP (可流式传输)
- URL:
http://localhost:8080/mcp
使用Claude Desktop:
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/path/to/your/mcp-server",
"env": {
"NODE_ENV": "production"
}
}
}
}
自定义
添加您的第一个工具
编辑 src/mcp-server.ts 并添加您的工具：
// 在工具数组中
{
name: "my_awesome_tool",
description: "做一些很棒的事情",
inputSchema: {
type: "object",
properties: {
input: {
type: "string",
description: "您的输入参数"
}
},
required: ["input"]
}
}
// 在工具处理器的switch语句中
case "my_awesome_tool": {
const input = args?.input as string;
// 您的工具逻辑在这里
const result = processInput(input);
return {
content: [{
type: "text",
text: `处理结果: ${result}`
}]
};
}
添加资源
// 在资源数组中
{
uri: "my-app://data",
name: "我的数据",
description: "应用程序数据资源",
mimeType: "application/json"
}
// 在资源处理器的switch语句中
case "my-app://data": {
const data = await fetchMyData();
return {
contents: [{
uri,
mimeType: "application/json",
text: JSON.stringify(data, null, 2)
}]
};
}
环境配置
在 src/config.ts 中添加您的环境变量：
export interface Config {
// ... 已存在的配置
myApiKey: string;
databaseUrl: string;
}
export function createConfig(): Config {
return {
// ... 已存在的配置
myApiKey: getEnvVar("MY_API_KEY"),
databaseUrl: getEnvVar("DATABASE_URL"),
};
}
可用脚本
开发
npm run dev # 启动带热重载
npm run dev:debug # 启动带Node.js调试器
npm run type-check # 仅进行TypeScript类型检查
构建
npm run build # 为开发构建
npm run build:prod # 为生产构建（已最小化）
npm run clean # 清除构建目录
代码质量
npm run lint # 检查代码规范规则
npm run lint:fix # 修复自动修复的代码规范问题
npm run format # 检查代码格式
npm run format:fix # 修复代码格式
npm run check # 运行代码规范和格式检查
npm run check:fix # 修复所有自动修复的问题
生产
npm run start # 启动已构建的应用程序
npm run validate # 运行类型检查+代码规范
npm run ci # 完整验证+生产构建
Docker部署
使用Docker开发
# 启动开发环境
docker-compose --profile dev up
# 生产部署
docker-compose up -d
手动Docker构建
# 构建生产镜像
docker build -t my-mcp-server .
# 运行容器
docker run -d \\
--name my-mcp-server \\
-p 8080:8080 \\
-e NODE_ENV=production \\
my-mcp-server
项目结构
fastify-mcp-server-boilerplate/
├── src/
│ ├── index.ts # 主服务器入口点
│ ├── mcp-server.ts # MCP服务器实现
│ └── config.ts # 环境配置
├── docs/ # 文档
│ ├── extending.md # 如何添加工具/资源
│ ├── tooling.md # TypeScript + Biome配置
│ └── production.md # 生产部署指南
├── dist/ # 编译后的JavaScript（生成）
├── .vscode/ # VSCode配置
├── Dockerfile # 多阶段生产构建
├── docker-compose.yml # 容器编排
├── tsup.config.ts # 构建配置
├── tsconfig.json # TypeScript配置
├── biome.json # 代码检查和格式化
└── package.json # 依赖项和脚本
健康监控
样板包括一个全面的健康端点：
curl <http://localhost:8080/health>
响应:
{
"status": "ok",
"timestamp": "2024-01-01T00:00:00.000Z",
"version": "1.0.0",
"name": "fastify-mcp-server-boilerplate",
"uptime": "123s",
"memory": {
"rss": "45MB",
"heapUsed": "12MB",
"heapTotal": "18MB"
},
"environment": "development"
}
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
PORT | 8080 | 服务器端口 |
HOST | localhost | 服务器主机 |
NODE_ENV | development | 环境: development/production/test |
LOG_LEVEL | debug (开发) / info (生产) | 日志级别 |
MCP_ENDPOINT | /mcp | MCP服务器端点路径 |
HEALTH_ENDPOINT | /health | 健康检查端点路径 |
文档
故障排除
端口已被占用
# 查找使用8080端口的进程
lsof -i :8080
# 杀死进程
kill -9 <PID>
# 或使用不同的端口
PORT=3000 npm run dev
构建问题
# 清除并重新构建
npm run clean
npm install
npm run build
Docker问题
# 查看容器日志
docker logs mcp-server
# 重建镜像
docker build --no-cache -t my-mcp-server .
贡献
- 分叉此仓库
- 创建一个特性分支:
git checkout -b feature/amazing-feature - 进行更改
- 运行验证:
npm run ci - 提交:
git commit -m '添加精彩特性' - 推送:
git push origin feature/amazing-feature - 打开一个拉取请求
许可证
MIT许可证 - 欢迎使用此样板进行您的项目！
为什么选择这个样板？
构建生产就绪的MCP服务器需要设置构建工具、代码检查、容器化、日志记录、错误处理等。此样板为您提供了一切，因此您可以专注于构建您的MCP工具和资源，而不是配置基础设施。
适用于：
- 构建AI驱动的开发者工具
- 为Cursor IDE、Claude Desktop创建集成
- MCP服务器的快速原型设计
- 使用最佳实践学习MCP开发
- 生产MCP服务器部署
致谢
此样板建立在优秀的开源工作之上：
- fastify-mcp 由@haroldadmin - 核心MCP集成，使这一切成为可能。处理协议实现、会话管理和传输层。
- Fastify - 高性能Web框架
- Biome - 现代工具链用于代码检查和格式化
- tsup - 由esbuild驱动的快速打包器
许可证
MIT许可证 - 欢迎使用此样板进行您的项目！
愉快地构建！ 🎉
如果您发现此样板有用，请给仓库加⭐星！