AI导哈

MCP服务器模板

一个通用的、最小化的Model Context Protocol (MCP)服务器启动模板，提供创建新MCP服务器的干净起点，包含简单示例工具和最佳实践。

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

使用说明

节点MCP服务器引导程序

一个通用且最小化的模型上下文协议（MCP）服务器启动模板。它为使用TypeScript创建新的MCP服务器提供了一个干净的起点，包含了一个简单的示例工具和最佳实践。

特点/特性

  • 🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或直接保留为“🚀”，用以表达快速、前进或科技感等含义。在没有具体上下文的情况下，可以简单地将其理解为“火箭”或直接用该符号表示。 最少设置仅包含必要的依赖项（MCP SDK + Zod）
  • 🛠️（扳手或工具的象征，常用于表示进行维修、修理或使用工具的动作） 简单示例单身 ping 展示该模式的工具
  • ✅ 表示正确或确认。 测试已包含在内单元测试、集成测试和MCP Inspector测试
  • 🔍（放大镜图标，通常表示搜索或查看细节） 检查员整合自动化bash测试及用于调试的交互式用户界面
  • 📦 箱子/包裹 TypeScript使用严格模式进行完全类型化
  • 🔨 这个符号可以翻译为“锤子”或“打”（在某些语境下，如表示打人或打东西的动作）。不过，单独的符号翻译时通常保留其图形形式，但在中文中，我们常用“锤子”或根据上下文用“打”来表达这个符号的含义。所以，这个符号在中文中可以理解为“锤子”或“打”。 构建工具Vite，用于快速打包
  • 🎯（瞄准靶心） 清洁架构工具注册模式，便于扩展
  • 📝 文档齐全全面的行内文档

项目结构

node-mcp-server/
├── src/
│   ├── server.ts              # Main MCP server
│   ├── tools/
│   │   ├── index.ts           # Tool registry
│   │   ├── types.ts           # Shared types
│   │   └── ping/              # Example ping tool
│   │       ├── schema.ts      # Zod schema
│   │       ├── definition.ts  # Tool metadata
│   │       ├── handler.ts     # Tool implementation
│   │       └── index.ts       # Exports
│   └── utils/
│       └── logger/            # Structured logger
├── tests/                     # Tests mirror src/ structure
│   ├── tools/
│   │   └── ping/
│   │       ├── handler.test.ts      # Unit tests for handler
│   │       ├── schema.test.ts       # Unit tests for schema
│   │       └── definition.test.ts   # Unit tests for definition
│   ├── utils/
│   │   └── logger/
│   │       └── logger.test.ts       # Unit tests for logger
│   ├── scripts/
│   │   └── bootstrap.test.ts        # Bootstrap script tests
│   ├── server.test.ts               # Server tests
│   └── integration/
│       ├── ping-inspector.test.ts   # MCP protocol integration tests
│       └── bootstrap.test.ts        # Bootstrap E2E tests
├── scripts/
│   ├── bootstrap.js           # Interactive project setup
│   └── test-inspector.sh      # Bash inspector tests
├── bin/
│   └── cli.js                 # CLI wrapper (Yarn PnP support)
├── inspector-config.json      # MCP Inspector configuration
└── dist/                      # Compiled output

快速入门

为你的项目搭建基础（或：为你的项目进行初始化配置）

开始的最简单方法是使用交互式引导脚本：

# Run the bootstrap script to customize the template
yarn bootstrap

这将提示您输入：

  • 项目名称
  • 作者姓名
  • 版本（默认：1.0.0）
  • 描述
  • Node 版本（默认：v20.19.0）

该脚本会自动更新所有文件并安装依赖项。

手动安装

如果您更倾向于手动设置：

# Install dependencies
yarn install

发展

# Run in development mode with hot reload
yarn dev

构建

# Build the project
yarn build

测试

# Run all tests
yarn test

# Run only unit tests
yarn test:unit

# Run integration tests
yarn test:integration

# Run bootstrap script tests (unit + E2E)
yarn test:bootstrap

# Run MCP Inspector tests (bash script)
yarn test:inspector

# Open interactive MCP Inspector UI
yarn test:inspector:ui

测试结构

组织测试以反映源文件夹结构，便于导航。每个源文件在相同相对位置都有一个对应的测试文件：

src/tools/ping/handler.ts    → tests/tools/ping/handler.test.ts
src/tools/ping/schema.ts     → tests/tools/ping/schema.test.ts
src/tools/ping/definition.ts → tests/tools/ping/definition.test.ts
src/utils/logger/logger.ts   → tests/utils/logger/logger.test.ts
src/server.ts                → tests/server.test.ts

测试类别：

  • 单元测试单独测试各个组件

    • 工具处理程序、模式和定义
    • 像日志记录器这样的实用函数
    • 引导脚本验证和更新功能

  • 集成测试 (tests/integration/): 完整测试工作流

    • ping-inspector.test.ts通过SDK客户端进行MCP协议通信
    • bootstrap.test.ts在隔离环境中实现端到端的自举工作流程

为新工具添加测试

在创建新工具时（例如。， my-tool)，创建相应的测试文件：

# Source files
src/tools/my-tool/
├── handler.ts
├── schema.ts
├── definition.ts
└── index.ts

# Test files (mirror structure)
tests/tools/my-tool/
├── handler.test.ts      # Test handler logic
├── schema.test.ts       # Test Zod schema validation
└── definition.test.ts   # Test tool metadata

它是如何工作的

Ping 工具

所包含的 ping 该工具展示了MCP工具实现的完整模式：

  1. 模式/架构 (schema.ts): 使用 Zod 验证定义输入/输出类型
  2. 定义 （definition.ts)：为MCP协议提供工具元数据
  3. 处理程序（或“处理器”） (handler.ts): 包含实际的工具逻辑
  4. 索引 (index.ts): 导出所有组件

当被调用时，ping 工具：

  • 使用结构化日志记录器记录“Hello from ping tool!”
  • 返回服务器健康状态和可选的自定义消息
  • 展示了MCP响应格式

服务器架构

服务器（src/server.ts) 遵循以下模式：

  1. 初始化创建具有特定功能的MCP服务器
  2. 注册处理程序:
    • ListTools返回可用工具
    • CallTool执行带有验证的工具处理器
  3. 连接附加到stdio传输以进行通信

添加新工具

添加一个新工具：

  1. 创建工具文件 在 src/tools/ （例如。， my-tool/)：

    • schema.ts - Zod 输入/输出验证模式
    • definition.ts - MCP工具元数据
    • handler.ts - 工具实现逻辑
    • index.ts - 重新出口所有组件

  2. 创建测试文件 在 tests/tools/my-tool/:

    • schema.test.ts - 测试 Zod 模式验证
    • definition.test.ts - 测试工具元数据
    • handler.test.ts - 测试处理程序逻辑

  3. 注册于 src/tools/index.ts：

// Add to imports
import { myToolDefinition, MyToolInputSchema, myToolHandler } from './my-tool/index.js';

// Add to toolDefinitions array
export const toolDefinitions: ToolDefinition[] = [
  pingToolDefinition,
  myToolDefinition, // Add here
];

// Add to createToolHandlers
export function createToolHandlers(serverInfo: ServerInfo) {
  return {
    ping: async (args: unknown) => {
      const validated = PingInputSchema.parse(args);
      return pingHandler(validated, serverInfo);
    },
    my_tool: async (args: unknown) => {
      const validated = MyToolInputSchema.parse(args);
      return myToolHandler(validated, serverInfo);
    },
  };
}
  1. 添加集成测试 in tests/integration/ 并更新 scripts/test-inspector.sh 使用新工具进行测试

依赖项

运行时

  • @modelcontextprotocol/sdkMCP协议实现
  • zod运行时模式验证

发展

  • typescript类型检查
  • vite构建工具
  • vitest测试框架
  • tsx开发 TypeScript 执行器
  • eslint代码 linting（代码检查/代码格式化）
  • prettier代码格式化

配置

TypeScript

该项目采用了严格的TypeScript配置，包括：

  • ES2022目标
  • Node16模块解析
  • 路径别名（@/* → ./src/*)
  • 已启用源映射

构建

Vite 已配置为：

  • 作为ES模块打包
  • 目标节点20+
  • 将所有依赖项外部化
  • 在输出中添加shebang横幅

记录日志

设置 LOG_LEVEL 环境变量用于控制日志记录：

  • debug所有日志
  • info信息、警告、错误（默认）
  • warn仅警告和错误
  • error仅错误

文件导入

所有进口都必须使用 .js 扩展（TypeScript 对 ESM 的约定）：

import { logger } from './utils/logger/index.js';  // Correct
import { logger } from './utils/logger/index';     // Wrong - will fail

这是必要的，因为TypeScript编译为ESM（ECMAScript模块）格式，而Node.js要求ES模块必须明确指定文件扩展名。

使用MCP Inspector进行测试

此模板包含使用MCP Inspector工具进行的全面测试，以验证您的服务器对MCP协议的实现。

检查器配置

该 inspector-config.json 文件配置MCP Inspector以连接到您的服务器：

{
  "mcpServers": {
    "node-mcp-server": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "env": {
        "LOG_LEVEL": "error"
      }
    }
  }
}

运行检查员测试

使用检查器测试您的MCP服务器有两种方法：

1. 自动化的Bash脚本测试

运行验证所有服务器功能的自动化测试套件：

yarn test:inspector

这运行着 scripts/test-inspector.sh，该测试：

  • 服务器连接和工具列表
  • Ping工具的基本功能
  • 响应结构验证
  • 自定义消息参数处理
  • 服务器元数据存在

该脚本提供带颜色编码的输出以及通过/失败测试的总结。

2. 集成测试（TypeScript）

使用Vitest和MCP SDK进行全面集成测试：

yarn test:integration

这些测试（tests/integration/ping-inspector.test.ts验证：

  • 通过MCP协议列出工具
  • 使用各种参数执行工具
  • 响应格式验证
  • 对无效输入的错误处理
  • 连续多次工具调用
  • 时间戳验证

3. 交互式检查器用户界面

启动交互式MCP Inspector网页界面：

yarn test:inspector:ui

这会打开一个基于浏览器的用户界面，在其中您可以：

  • 手动测试工具
  • 检查请求/响应的有效载荷
  • 实时调试服务器行为

为新工具添加检查器测试

当你添加新工具时，请同时更新两个测试文件：

Bash 脚本 (scripts/test-inspector.sh)：

run_test "Your new tool test" \
    "npx mcp-inspector --config $CONFIG_FILE --server $SERVER_NAME --cli --method tools/call --tool-name your_tool --arguments '{}'" \
    'expected_pattern_in_output'

集成测试 (tests/integration/ping-inspector.test.ts)：

it('should call your new tool', async () => {
  const response = await client.callTool({
    name: 'your_tool',
    arguments: {},
  });

  expect(response.content).toBeDefined();
  // Add your assertions
});

与Claude Desktop配合使用

要在Claude Desktop中使用此MCP服务器，请将其添加到您的Claude配置文件中。

配置文件位置

配置文件位于：

  • macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows： %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

配置

在你的配置文件中添加以下内容：

{
  "mcpServers": {
     "node-mcp-server": {
      "command": "npx",
      "args": ["-y", "/absolute/path/to/node-mcp-server"]
    }
  }
}

替换 /absolute/path/to/node-mcp-server 以及此项目目录的实际绝对路径。

注：该 npx 命令通过（某种方式）与包协同工作 bin/cli.js，它自动处理Yarn PnP（Plug and Play）和标准node_modules安装 -y 该标志确保 npx 运行时不会提示确认。

验证安装

更新配置后：

  1. 重启Claude桌面版
  2. MCP服务器应出现在MCP工具列表中
  3. 你可以通过让Claude使用它来测试一下 ping 工具

自定义此模板

这是一个通用模板，旨在根据您的特定使用场景进行定制：

  1. 更新服务器名称改变 SERVER_NAME 并且 SERVER_VERSION 在 src/server.ts
  2. 更新包信息修改 name， description，以及 version 在 package.json
  3. 自定义或移除Ping工具要么删除它，要么将其作为你自己的工具模板使用
  4. 添加您的工具按照既定模式创建新工具
  5. 更新README文件根据您的特定服务器定制此文档

许可证

麻省理工学院（MIT）- 详见LICENSE.txt文件

作者

“suhcodes”这个词汇本身并不是一个常见的英文单词或短语，它看起来像是一个特定上下文或领域内的术语，或者是某个特定名称、代码的拼写。由于没有具体的上下文，我无法给出一个准确的翻译。不过，如果“suhcodes”是某个特定系统、程序或领域的代码或术语，那么它的翻译可能需要根据该系统、程序或领域的具体含义来确定。在没有具体上下文的情况下，我们只能将其作为一个无法直接翻译的特定词汇来处理

下一步行动

  1. 自定义服务器名称和元数据
  2. 移除或修改示例ping工具
  3. 按照既定模式添加自己的工具
  4. 为你的工具编写测试
  5. 用你的项目详情更新这个README文件
  6. 构建并部署您的MCP服务器！

资源

相关 MCP