MCP Server Starter Template

使用TypeScript和FastMCP构建Model Context Protocol（MCP）服务器的最小启动模板。

特性

• 基本项目结构，包括src/lib、src/services、src/tools。
• TypeScript配置（编译到dist/）。
• 使用Biome进行代码检查和格式化。
• 使用fastmcp实现MCP服务器。
• 天气服务示例演示：
  • 正确的文件夹结构（lib、services、tools）
  • API集成及错误处理
  • 使用Zod进行参数验证
  • 关注点分离
• GitHub Actions工作流用于持续集成和发布（默认手动触发）。

快速开始

1. 从这个模板创建一个新的仓库： 点击这里生成一个新仓库。

2. 导航到你的新项目：

   cd /path/to/your-new-mcp-server
   

3. 初始化Git仓库（如果尚未初始化）：

   git init
   git branch -M main # 或者你首选的默认分支名称
   

4. 自定义package.json：

   • 更新name、version、description、author、repository等。
   • 如果更改命令名称，请更新bin条目。

5. 安装依赖项：

   pnpm install
   

6. 配置环境变量： 对于天气服务示例，你需要一个OpenWeather API密钥：

   # 创建一个.env文件（添加到.gitignore中）
   echo "OPENWEATHER_API_KEY=your_api_key_here" > .env
   

   从OpenWeather获取API密钥。

7. 初始提交： 在设置Husky和Changesets之前，这是一个很好的初始提交阶段。

   git add .
   git commit -m "feat: 从模板初始化项目"
   

8. 开发你的服务器：

   • 在src/tools/目录下添加自定义工具。
   • 在src/lib/和src/services/中实现逻辑。
   • 在src/index.ts中注册工具。

示例天气工具

此模板包含一个天气服务示例，展示了以下内容：

1. HTTP实用程序（src/lib/http.ts）：

   • 使用Zod验证的类型安全HTTP请求
   • 错误处理

2. 配置（src/lib/config.ts）：

   • 环境变量管理
   • 服务配置

3. 天气服务（src/services/weatherService.ts）：

   • API集成
   • 数据转换
   • 合适的错误传播

4. 天气工具（src/tools/weather.ts）：

   • 使用Zod进行参数验证
   • 用户友好的输出格式化
   • 错误处理和用户指导

要使用天气工具：

# 设置你的OpenWeather API密钥
export OPENWEATHER_API_KEY=your_api_key_here

# 运行服务器
pnpm run start

# 使用MCP客户端连接并使用GET_WEATHER工具
# 参数：{ "city": "London" }

提交前代码检查（Husky & lint-staged）

此模板在devDependencies中包含了husky和lint-staged，以便在提交前对暂存文件运行Biome。设置方法如下：

1. 确保你的package.json中有husky的准备脚本：

   {
     "scripts": {
       "prepare": "husky"
     }
   }
   

2. 安装依赖项并初始化husky：

   pnpm install
   pnpm dlx husky init
   

   这会创建一个包含必要设置的.husky目录。

3. 为lint-staged创建预提交钩子：

   # 创建或编辑pre-commit文件
   echo '#!/usr/bin/env sh' > .husky/pre-commit
   echo '. "$(dirname -- "$0")/_/husky.sh"
   
   pnpm lint-staged' >> .husky/pre-commit
   
   # 使其可执行
   chmod +x .husky/pre-commit
   

4. 在package.json中配置lint-staged：

   // 在package.json中
   "lint-staged": {
     "*.{js,ts,cjs,mjs,jsx,tsx,json,jsonc}": [
       "biome check --write --organize-imports-enabled=false --no-errors-on-unmatched"
     ]
   }
   

   根据需要调整Biome命令。上面的是一个常见示例。

5. 测试它： 暂存一些.ts文件的变化并尝试提交。Biome应该会在暂存文件上运行。

发布管理（Changesets）

此模板已准备好使用Changesets进行发布管理。

1. 安装Changesets CLI（如果尚未在devDependencies中）： 模板package.json应包含@changesets/cli。如果没有：

   pnpm add -D @changesets/cli
   

2. 初始化Changesets： 该命令将在.changeset目录中创建一些配置文件。

   pnpm changeset init
   # 或 npx changeset init
   

   提交生成的.changeset目录及其内容。

3. 开发过程中添加Changesets： 当你做出一个应该导致版本提升的更改（修复、功能、重大变更）时：

   pnpm changeset add
   # 或 npx changeset add
   

   跟随提示。这将在.changeset目录中创建一个描述更改的markdown文件。 将此更改集文件与你的代码更改一起提交。

4. 发布一个版本： GitHub Actions工作流release.yml（在mcp-server-starter/.github/workflows/中）已为此设置好。当你准备发布时：

   • 确保所有特性PR及其更改集文件都合并到了main。
   • 重要： 在发布前，请确保你的package.json是完整的。添加或更新字段如keywords、author、repository（例如，"repository": {"type": "git", "url": "https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git"}）、bugs（例如，"bugs": {"url": "https://github.com/YOUR_USERNAME/YOUR_REPO_NAME/issues"}）和homepage（例如，"homepage": "https://github.com/YOUR_USERNAME/YOUR_REPO_NAME#readme"），以提高npm上的可发现性和信息量。
   • release.yml工作流（默认手动触发）将：
     1. 运行changeset version以消耗更改集文件，更新package.json版本，并更新CHANGELOG.md。它将这些推送到changeset-release/main分支并打开一个“版本包”PR。
     2. 合并“版本包”PR。
     3. 合并后，工作流将在main上再次运行。这次，它将运行pnpm run publish-packages（应包括changeset publish）以发布到npm并创建GitHub Releases/标签。
   • 启用自动发布流程： 将release.yml中的on: workflow_dispatch更改为on: push: branches: [main]（或你的发布分支）。

可用脚本

• pnpm run build: 编译TypeScript到JavaScript并在dist/中生成可执行输出。
• pnpm run dev: 使用tsx运行服务器（TypeScript热重载）。
• pnpm run start: 使用Node运行构建的服务器（来自dist/）。
• pnpm run lint: 使用Biome检查代码库。
• pnpm run format: 使用Biome格式化代码库。

使用服务器

构建后（pnpm run build），你可以运行服务器：

• 直接链接或全局安装：mcp-hello-server（或你自定义的bin名称）。
• 通过node：node dist/index.js
• 通过pnpm dlx（一旦发布）：pnpm dlx your-published-package-name