MCP Server Boilerplate

这是一个 Model Context Protocol (MCP) 服务器的简单样板实现。

概要

本项目是 Model Context Protocol (MCP) 服务器的基本实现。通过使用此样板，您可以快速构建自己的 MCP 服务器并实现自定义工具。

基于 簡易な自作MCPサーバーをお試しで実装する方法 - Zenn 这篇文章，添加了实用的补充和辅助工具，更清晰地展示了 MCP 服务器的构建和扩展方法。

v1 分支

一个简单的将数值翻倍的工具。这是一个最小化的参考实现，展示了如何构建 MCP 服务器以及如何实现自定义工具。

v2 分支

在 v1 分支的基础上，添加了一个从虚拟服务器获取字符串数据的工具。

v3 分支

在 v2 分支的基础上，添加了获取并显示环境变量值的特性。需要在 MCP 配置文件中设置环境变量。

前提条件

• Node.js (v23.11.0 或更高版本)
• npm 或 yarn

支持的 MCP 客户端

• Claude Code
• VSCode
• Windsurf
• Cursor
• AWS Bedrock (未确认)

安装方法

# 克隆仓库
git clone [仓库URL]
cd mcp-server-boilerplate

# 安装依赖包
npm install

# 构建
npm run build

使用方法

请将以下配置添加到 MCP 客户端的 MCP 配置文件中。 请使用绝对路径指定。 (※ 无法在 Home 目录中使用 ~。)

{
  "mcpServers": {
    "mcp-server-boilerplate": {
      "command": "node",
      "args": [
          "/absolute/path/to/mcp-server-boilerplate/build/index.js"
      ],
      "env": {
        "FOO": "BAR"
      }
    }
  }
}

请使用以下命令启动虚拟服务器。虚拟服务器仅用于提供虚拟字符串数据。 (端口号可以任意指定，如果 3000 端口已被占用，请指定其他端口号。)

npx serve dummy-server

为了应用配置更改，请重启 MCP 客户端。 在代理模式下，执行各个工具的提示示例中的提示，以确认工具是否正常工作。（工具名称的指定不是必须的，但为了确保使用该工具而指定。）

提供的工具

double_number

将给定的数值翻倍。

参数

• num (number): 要翻倍的数值

返回值

• 输入数值的 2 倍值

提示示例

使用 double_number 将 3 翻倍的结果显示出来

get_test_text

从虚拟服务器获取字符串数据。 同时显示配置文件中环境变量 FOO 的值。

参数

• 无

返回值

• 获取的字符串数据

提示示例

获取测试用的字符串数据，并说明内容

開発方法

项目结构

mcp-server-boilerplate/
├── .vscode/                 # VSCode 配置
├── dummy-server/            # 虚拟服务器
├── build/                   # 构建输出目录
├── node_modules/            # 依赖包
├── src/                     # 源代码
│   ├── index.ts             # 入口点
│   └── {types}/             # 类型定义（计划添加）
├── {tests/}                 # 测试
├── .env                     # 环境变量
├── {.env.example}           # 环境变量示例
├── .gitignore               # Git 忽略配置
├── .windsurfrules           # Windsurf 配置
├── biome.json               # Biome 配置
├── package.json             # 依赖关系和配置
├── README.md                # README 文件
└── tsconfig.json            # TypeScript 配置

添加新工具的方法

编辑 src/index.ts 文件，并按照以下模式添加工具：

/**
 * 工具的定义
 * 根据 name 和 description 选择要执行的 tool
 * handler 返回 CallToolResult（异步情况下返回其 Promise）
 * @param name - 工具的名称
 * @param description - 工具的描述
 * @param args - 工具的参数定义
 * @param handler - 工具的实现
 */
server.tool(
  "工具的名称",
  "工具的描述",
  {参数名: z.型().describe("参数的描述")},
  ({参数名}) => ({content: [{type: "text", text: 结果}]}),
);

主要依赖包

• @modelcontextprotocol/sdk: ^1.9.0 - 实现 MCP 服务器所需的 SDK
• zod: ^3.24.2 - 用于类型验证和模式定义的库

开发工具

Biome

Biome 是一个用于 JavaScript 和 TypeScript 的快速 linter 和格式化工具。本项目使用它来保持代码的质量和一致性。 biome.json 文件中定义了项目特定的规则和配置。

以下 npm 脚本可用：

# 检查代码
npm run lint

# 检查代码并自动修复问题
npm run lint:fix

# 检查格式
npm run format

# 自动修复格式
npm run format:fix