AI导哈

MCP服务器模板

一个基于TypeScript和FastMCP的最小化MCP服务器启动模板，提供基础项目结构、天气服务示例和CI/CD工作流。

  • by MarvelNwachukwu
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 MarvelNwachukwu/my-mcp-server

使用说明


MCP服务器启动模板

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

MCP • 快速MCP（FastMCP）• TypeScript

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

特点/特性

  • 基本项目结构，包含 src/lib， src/services， src/tools。
  • TypeScript 配置（编译为 dist/）。
  • fastmcp 用于MCP服务器的实现。
  • 一个天气服务示例，展示：
    • 适当的文件夹结构（库、服务、工具）
    • API集成与错误处理
    • 使用Zod进行参数验证
    • 关注点分离
  • GitHub Actions 工作流用于持续集成（CI）和发布（默认手动触发）。

入门指南

使用此模板创建新的MCP服务器项目最简单的方法是通过ADK CLI：

npm install -g @iqai/adk-cli # if you haven't already
adk new --template mcp-starter my-mcp-server
cd my-mcp-server
pnpm install

你也可以通过复制文件直接使用这个模板，但为了获得最佳效果，建议使用命令行界面（CLI）。

运行服务器

默认（生产/开发）路由

要在生产环境或进行标准开发时运行您的MCP服务器，请使用：

pnpm dev

快速迭代与代理设置（ADK CLI）

对于快速原型制作、交互式测试或初始代理设置，请使用ADK CLI：

adk run   # Interactive CLI chat with your agents
adk web   # Web interface for easy testing and demonstration

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

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

    从获取API密钥 OpenWeather（开放天气）。

  2. 初始提交： 在这个阶段进行初始提交是个好主意。

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

  3. 开发您的服务器：

    • 在（此处）添加您的自定义工具 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/weather-service.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" }

发布管理（更改集）

这个模板已准备好用于发布管理 更改集（或更改批次）。

  1. 如果尚未在开发依赖项中，请安装 Changesets CLI： 模板 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

    按照提示操作。这将在（指定位置）创建一个Markdown文件 .changeset 描述变更的目录。 将此更改集文件与您的代码更改一起提交。

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

    • 确保所有带有其更改集文件的功能拉取请求（PRs）都被合并到 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. 合并“版本包”拉取请求。
      3. 合并后，工作流将在（某处/系统上）再次运行 main这次，它将运行 pnpm run publish-packages （其中应包括 changeset publish) 以发布到 npm 并创建 GitHub 发行版/标签。
    • 要启用自动发布流程： 改变 on: workflow_dispatch 在里面 release.yml to on: push: branches: [main] （或者您的发布分支）。

可用脚本

  • pnpm run build将 TypeScript 编译为 JavaScript dist/ 并使输出结果可执行。
  • pnpm run dev以开发模式运行服务器，使用 tsx （TypeScript 的热重载）。
  • pnpm run start运行已构建的服务器（来自 dist/) 使用 Node。

快速开发环境搭建

为了在开发过程中实现快速迭代，请使用 dev 支持热重载的脚本：

pnpm run dev

这运行着 tsx watch src/index.ts 当你对TypeScript文件进行更改时，它会自动重启服务器。

开发环境下的MCP客户端配置

光标（.cursor/mcp.json):

{
  "mcpServers": {
    "weather-dev": {
      "command": "/Users/marvelsmbp/Documents/OSS/my-mcp-server/node_modules/.bin/tsx",
      "args": ["watch", "/Users/marvelsmbp/Documents/OSS/my-mcp-server/src/index.ts"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop（桌面版）： 添加一个开发服务器条目，使用：

  • 命令： /Users/marvelsmbp/Documents/OSS/my-mcp-server/node_modules/.bin/tsx
  • 参数： ["watch", "/Users/marvelsmbp/Documents/OSS/my-mcp-server/src/index.ts"]
  • Env:（此处“Env”可能是一个缩写或特定上下文中的术语，但直接翻译无具体含义，若作为“Environment”的缩写，则可译为“环境”） OPENWEATHER_API_KEY=your_api_key_here

开发工作流程

  1. 启动开发服务器： pnpm run dev
  2. 配置MCP客户端 使用 tsx watch 命令（参见上面的配置）
  3. 编辑TypeScript文件 在 src/ - 更改后自动重启服务器
  4. 在Cursor/Claude中进行测试 - 工具立即反映更改
  5. 用于生产： 将客户端切换回 node dist/index.js 并且运行 pnpm run build

测试您的MCP服务器

选项1：直接使用MCP服务器 直接使用MCP客户端连接服务器，或将服务器集成到其他应用程序中。

选项2：使用ADK CLI（用于客户端测试） 这个模板创建了一个MCP（多上下文处理/多条件概率等，具体含义根据上下文确定） 服务器你可以创建一个简单的客户端来测试它：

  1. 全局安装ADK CLI：

    npm install -g @iqai/adk-cli

  2. 创建一个简单的代理，使用您的MCP服务器（在单独的测试目录中）：

    # In a test directory, create an agents/agent.ts file that connects to your MCP server
adk run  # Test the integration
adk web  # Web interface for testing

这种方法对于测试您的MCP服务器工具在ADK生态系统中的运行情况非常有用。

使用服务器

在构建（pnpm run build), 你可以运行服务器：

  • 如果直接链接或全局安装： mcp-hello-server （或您自定义的文件夹名称）。
  • 通过节点： node dist/index.js
  • Via pnpm dlx （一旦发布）： pnpm dlx your-published-package-name

相关 MCP