快速启动mcp服务器模板

Name: 快速启动mcp服务器模板
Author: jarodtaylor

作者：jarodtaylor5 星标更新：2025-05-28

安装使用来源：spider==github.com

项目介绍

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`	健康检查端点路径

文档

入门指南 - 常见用例的逐步示例
扩展服务器 - 添加自定义工具和资源
工具配置 - TypeScript和Biome配置
生产部署 - 完整部署指南

故障排除

端口已被占用

# 查找使用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许可证 - 欢迎使用此样板进行您的项目！

愉快地构建！ 🎉

如果您发现此样板有用，请给仓库加⭐星！