MCP Server Boilerplate

🟢 Node.js 中的 MCP 服务

只需 2 分钟，即可在 Node.js 中构建并运行自定义 MCP 服务 ⏱️

概览 · 功能 · 安装 · 使用 MCP Inspector 测试 · 为测试设置环境变量 · 与 Cursor AI 集成 · 在 Cursor 中使用 MCP 工具（Agent 模式） · 代码概览 · 参考资料与资源 · 许可证

概览

MCP（Model Context Protocol） 是一个框架，可让你将自定义工具集成到 Cursor AI 等 AI 辅助开发环境中。MCP 服务会公开各种功能（例如数据检索或代码分析），供基于大模型的 IDE 按需调用。要了解更多关于 MCP 的信息，请参阅Model Context Protocol 简介。

本项目演示了如何使用 Node.js 以 JavaScript 实现 MCP 服务。它定义了两个工具：add 接受两个数字输入并返回它们的和；getApiKey 从 API_KEY 环境变量中获取 API 密钥。项目还提供了一个预定义提示词 add_numbers，让 AI 模型能够推断加法工具的用法。

要求

• Node.js： 需要 20 或更高版本。

功能

• MCP 集成： 向基于大模型的 IDE 公开工具功能。
• 加法工具： 接受两个数字参数并返回它们的和。
• MCP 提示词： 提供预定义提示词（“add_numbers”），让 AI 模型能够推断工具用法。
• 环境变量获取： 演示如何从配置文件中加载示例环境变量。
• 输入验证： 使用 Zod 进行架构验证。
• 标准输入/输出传输： 通过 StdioServerTransport 连接，以便与开发环境集成。

安装

1. 克隆代码仓库

   git clone <repository_url>
   cd <repository_directory>
   

2. 安装依赖项

   你可以通过以下两种方式之一安装项目依赖项：

   选项 1：使用现有的 package.json 安装

   只需运行：

   npm install
   

   选项 2：手动安装依赖项

   如果你愿意，可以删除现有的 package.json，然后手动安装所需的软件包：

   npm install @modelcontextprotocol/sdk zod
   

   然后，更新新生成的 package.json 文件，添加以下几行，以启用 ES Modules 并添加 mcp inspector 命令：

   "type": "module",
   "scripts": {
    "inspector": "npx @modelcontextprotocol/inspector node ./mcp-server.js"
   }
   

使用 MCP Inspector 测试

MCP Inspector 是一款调试工具，可让你在与 IDE 集成之前交互式测试服务的工具。

选项 1：使用 npx 直接运行

npx @modelcontextprotocol/inspector node ./mcp-server.js

选项 2：使用 npm 脚本

npm run inspector

这将：

1. 启动 MCP inspector 服务
2. 在浏览器中打开 inspector 界面
3. 允许你测试工具、资源和提示词

在浏览器中打开 MCP Server Inspector： http://localhost:6274/

为测试设置环境变量

若要使用不同的 API 密钥测试 getApiKey 工具，可以在运行 inspector 之前设置环境变量：

Linux/macOS（Bash/Zsh）：

# Temporary (current session only)
export API_KEY="your-test-key"
npm run inspector

# Or set for single command
API_KEY="your-test-key" npm run inspector

Windows（命令提示符）：

# Set for current session
set API_KEY=your-test-key
npm run inspector

Windows（PowerShell）：

# Set for current session
$env:API_KEY="your-test-key"
npm run inspector

# Or set for single command
$env:API_KEY="your-test-key"; npm run inspector

与 Cursor AI 集成

要将此 MCP 服务集成到 Cursor IDE 中，需要通过 Cursor 的设置界面添加配置：

1. 打开 Cursor IDE
2. 前往 Settings → Tools & Integrations
3. 点击 Add Custom MCP Server
4. 添加以下配置

重要提示： 如果已配置其他 MCP 服务，请勿覆盖整个配置。应将 "MCP Server Boilerplate" 对象添加到现有的 "mcpServers" 对象中。

示例配置文件： 此项目在 ./cursor/mcp.json 中提供了一个示例配置文件，供你参考或复制。

配置结构

以下是需要添加的配置：

Linux/macOS 示例：

{
  "MCP Server Boilerplate": {
    "command": "node",
    "args": ["/home/john/mcp-server-node/mcp-server.js"],
    "env": {
      "API_KEY": "abc-1234567890"
    }
  }
}

Windows 示例：

{
  "MCP Server Boilerplate": {
    "command": "node",
    "args": ["C:\\Users\\john\\mcp-server-node\\mcp-server.js"],
    "env": {
      "API_KEY": "abc-1234567890"
    }
  }
}

如果已配置其他 MCP 服务，完整配置可能如下所示：

{
  "mcpServers": {
    "existing-server": {
      "command": "python",
      "args": ["/path/to/existing/server.py"]
    },
    "MCP Server Boilerplate": {
      "command": "node",
      "args": ["/home/john/mcp-server-node/mcp-server.js"],
      "env": {
        "API_KEY": "abc-1234567890"
      }
    }
  }
}

配置参数

• MCP Server Boilerplate：
  这是服务器配置的键。你可以按需命名。

• command：
  用于运行服务器的 Node.js 可执行文件。你可以使用以下任一方式：

  • "node"（如果 Node.js 位于 PATH 中）
  • Node.js 可执行文件的完整路径（如有需要）

  查找 Node.js 路径：

  Linux/macOS：

  which node
  # Example output: /home/john/.nvm/versions/node/v20.13.1/bin/node
  

  Windows（命令提示符）：

  where node
  # Example output: C:\Program Files\nodejs\node.exe
  

  Windows（PowerShell）：

  Get-Command node
  # Example output: C:\Program Files\nodejs\node.exe
  

• args：
  包含 MCP 服务文件绝对路径的数组。

  Linux/macOS 示例：

  ["/home/john/mcp-server-node/mcp-server.js"]
  

  Windows 示例：

  ["C:\\Users\\john\\mcp-server-node\\mcp-server.js"]
  

• env：（可选）
  为 MCP 服务进程定义环境变量。在此示例中，API_KEY 被设置为 "abc-1234567890"。请根据你的环境调整此值。

代码概览

该项目由以下关键部分组成：

• MCP 服务初始化：
  使用 MCP SDK 中的 McpServer 实例化 MCP 服务，并通过 StdioServerTransport 连接。

• 工具定义：

  • add：
    使用 Zod 架构定义，接受两个数字（a 和 b），并以文本形式返回它们的和。
  • getApiKey：
    从环境变量 API_KEY 中获取 API 密钥，并以文本形式返回。

• 提示词定义：

  • add_numbers：
    一个预定义提示词，可让 AI 模型推断加法工具的用法。

重要说明：工具不一定要定义提示词。此示例仅展示提示词的一种功能：让 AI 模型根据你的输入推断要使用哪个工具。AI 也可以在判断任务需要时直接使用工具。

在 Cursor 中使用 MCP 工具（Agent 模式）

将 MCP 服务集成到 Cursor IDE 并启用 Agent 模式后，你可以通过多种方式使用这些工具：

使用加法工具

方法 1：自然语言提示词 只需使用如下自然语言提示词：

add 3 and 5

或

what is 7 plus 12?

方法 2：基于提示词调用工具 在聊天中输入以下提示词：

/add_numbers

输入此提示词后按 Enter，Cursor 将自动：

1. 识别出你想使用 Node Server 中的 add 工具
2. 显示 GUI 提示，要求输入两个数字参数
3. AI 模型将推断需要使用 add 工具来计算结果

加法工具的参数：

• 参数 a：要相加的第一个数字
• 参数 b：要相加的第二个数字
• 返回值：以文本形式返回两个数字的和

使用 API 密钥工具

对于 getApiKey 工具，你可以使用：

what is my API key?

或

get my API key

AI Agent 会根据你的请求自动推断应使用的工具。

参考与资源

• Model Context Protocol：typescript-sdk
• 5 分钟内在 Cursor 上使用自己的 MCP
• Model Context Protocol 简介

许可证

本项目采用 MIT License 许可。