AI导哈

MCP服务器启动模板

一个用于使用TypeScript和FastMCP构建模型上下文协议（MCP）服务器的最小启动模板，包含项目结构、类型设置、linting和格式化工具以及示例天气服务。

  • by BrainDAO
  • TypeScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 IQAIcom/mcp-server-starter

使用说明

MCP服务器启动模板

使用TypeScript和FastMCP构建模型上下文协议（MCP）服务器的最小启动模板。

特性

  • 项目基本结构 src/lib, src/services, src/tools.
  • TypeScript设置（编译为 dist/).
  • 用于起毛和格式化的生物特征。
  • fastmcp 用于MCP服务器实现。
  • 天气服务示例演示：
    • 正确的文件夹结构（库、服务、工具）
    • API与错误处理的集成
    • 使用Zod进行参数验证
    • 关注点分离
  • CI和Release的GitHub操作工作流（默认情况下为手动触发）。

入门指南

  1. 使用此模板创建新存储库： 点击 这里 根据此模板生成新的存储库。

  2. 导航到新项目：

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

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

    git init
git branch -M main # Or your preferred default branch name

  4. 定制 package.json:

    • 更新 name, version, description, author, repository等等。
    • 更新 bin 如果更改命令名，请输入。

  5. 安装依赖项：

    pnpm install

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

    # Create a .env file (add to .gitignore)
echo "OPENWEATHER_API_KEY=your_api_key_here" > .env

    从获取API密钥 开放天气.

  7. 初始提交： 在设置Husky和Changesets之前，最好在这个阶段做出初步承诺。

    git add .
git commit -m "feat: initial project setup from template"

  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进行参数验证
    • 用户友好的输出格式
    • 错误处理和用户指导

要使用天气工具：

# Set your OpenWeather API key
export OPENWEATHER_API_KEY=your_api_key_here

# Run the server
pnpm run start

# Connect with an MCP client and use the GET_WEATHER tool
# with parameter: { "city": "London" }

提交前林庭（哈士奇和林庭上演）

此模板包括 husky 和 lint-staged 在其 devDependencies 用于在提交前对暂存文件运行Biome。要设置它，请执行以下操作：

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

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

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

    pnpm install
pnpm dlx husky init

    这创建了一个 .husky 目录，并进行必要的设置。

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

    # Create or edit the pre-commit file
echo '#!/usr/bin/env sh' > .husky/pre-commit
echo '. "$(dirname -- "$0")/_/husky.sh"

pnpm lint-staged' >> .husky/pre-commit

# Make it executable
chmod +x .husky/pre-commit

  4. 配置 lint-staged 在……里面 package.json:

    // In 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. 测试一下： 对a进行一些更改 .ts 文件并尝试提交。Biome应在暂存文件上运行。

发布管理（变更集）

此模板已准备好使用发布管理 变更集.

  1. 安装变更集CLI（如果尚未在devDependencies中）： 模板 package.json 应包括 @changesets/cli如果没有：

    pnpm add -D @changesets/cli

  2. 初始化变更集： 此命令将创建 .changeset 包含一些配置文件的目录。

    pnpm changeset init
# or npx changeset init

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

  3. 在开发过程中添加变更集： 当您进行的更改会导致版本冲突（修复、功能、破坏性更改）：

    pnpm changeset add
# or npx changeset add

    按照提示操作。这将在 .changeset 描述更改的目录。 将此变更集文件与代码更改一起提交。

  4. 发布发布： GitHub操作工作流 release.yml （in 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发布/标签。
    • 要启用自动释放流： 改变 on: workflow_dispatch 在……里面 release.yml 向 on: push: branches: [main] （或您的发布分支）。

可用脚本

  • pnpm run build：将TypeScript编译为JavaScript dist/ 并使输出可执行。
  • pnpm run dev：使用以下命令在开发模式下运行服务器 tsx （TypeScript的热重载）。
  • pnpm run start：运行构建的服务器（从 dist/)使用Node。
  • pnpm run lint：使用Biome抓取代码库。
  • pnpm run format：使用Biome格式化代码库。

使用服务器

建成后(pnpm run build)，您可以运行服务器：

  • 直接连接或全局安装： mcp-hello-server （或您自定义的垃圾箱名称）。
  • 通过节点： node dist/index.js
  • 经由 pnpm dlx （一经发布）： pnpm dlx your-published-package-name

相关 MCP