MCP极简入门:node+idea运行简单的MCP服务和MCP客户端

本文将指导你使用 Node.js 和 IntelliJ IDEA 创建并运行一个简单的 MCP(Model Context Protocol)服务端和客户端。示例使用 TypeScript 和 @modelcontextprotocol/sdk,通过 Stdio 协议实现通信。服务端提供一个加法工具,客户端列出工具并调用它。适合初学者快速入门 MCP 开发。

前提条件

  • Node.js:建议 v16 或以上,安装后运行 node --version 确认。

  • IntelliJ IDEA:配置好 Node.js 和 TypeScript 支持,推荐IntelliJ IDEA 2024.3.5 (Ultimate Edition),太老了无法直接执行tsx。

  • 依赖

    • @modelcontextprotocol/sdk:MCP SDK。
    • zod:用于输入验证。
    • tsx:运行 TypeScript 文件。
  • 基础的 TypeScript 知识。

项目设置

  1. 创建项目

    • 打开 IntelliJ IDEA,选择 File > New > Project,选择 Node.js 项目模板。
    • 项目命名为 mcp-quickstart,选择 Node.js 版本,点击 Create。
  2. 安装依赖

    • 打开终端(IDEA 底部 Terminal),运行:

      kotlin 复制代码
       npm init -y
       npm install @modelcontextprotocol/sdk zod tsx --save-dev
  3. 配置 TypeScript

    • 在项目根目录创建 tsconfig.json:

      json 复制代码
       {
         "compilerOptions": {
           "target": "ESNext",
           "module": "CommonJS",
           "strict": true,
           "esModuleInterop": true,
           "skipLibCheck": true,
           "forceConsistentCasingInFileNames": true,
           "outDir": "./dist"
         },
         "include": ["*.ts"]
       }

创建 MCP 服务端

创建一个简单的 MCP 服务端,提供一个加法工具。

  1. 新建文件 McpServer.ts:

    • 在项目根目录创建 McpServer.ts,添加以下代码:

      javascript 复制代码
       import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
       import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
       import { z } from 'zod'
       ​
       // Create an MCP server
       const server = new McpServer({
         name: 'demo-server',
         version: '1.0.0'
       })
       ​
       // Add an addition tool
       server.registerTool(
         'add',
         {
           title: 'Addition Tool',
           description: 'Add two numbers',
           inputSchema: { a: z.number(), b: z.number() }
         },
         async ({ a, b }) => ({
           content: [{ type: 'text', text: String(a + b) }]
         })
       )
       ​
       // Add a dynamic greeting resource
       server.registerResource(
         'greeting',
         new ResourceTemplate('greeting://{name}', { list: undefined }),
         {
           title: 'Greeting Resource', // Display name for UI
           description: 'Dynamic greeting generator'
         },
         async (uri, { name }) => ({
           contents: [
             {
               uri: uri.href,
               text: `Hello, ${name}!`
             }
           ]
         })
       )
       ​
       // 启动服务器
       async function startServer() {
         try {
           const transport = new StdioServerTransport()
           await server.connect(transport)
           console.error('MCP 服务器在 Stdio 上运行...')
         } catch (error) {
           console.error('服务器错误:', error)
           process.exit(1)
         }
       }
       ​
       startServer().catch((error) => {
         console.error('主程序错误:', error)
         process.exit(1)
       })
       ​
  2. 代码说明

    • 创建一个名为demo-server 的 MCP 服务器。
    • 注册一个 add 工具,接受两个数字(a 和 b),返回它们的和。
    • 使用 StdioServerTransport 通过标准输入/输出通信。

创建 MCP 客户端

创建一个客户端,连接服务端,列出工具并调用加法工具。

  1. 新建文件 McpClient.ts:

    • 在项目根目录创建 McpClient.ts,添加以下代码:

      javascript 复制代码
       #!/usr/bin/env node
       import { Client } from '@modelcontextprotocol/sdk/client/index.js'
       import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
       ​
       // 客户端设置
       const client = new Client({
         name: 'example-client',
         version: '1.0.0'
       })
       ​
       // 客户端逻辑:连接服务器并与之交互
       async function startClient() {
         try {
           // 使用命令和参数方式初始化传输层
           const transport = new StdioClientTransport({
             command: 'npx.cmd',
             args: ['tsx', 'McpServer.ts']
           })
       ​
           await client.connect(transport)
           console.log('已连接到 MCP 服务器:', client.serverInfo?.name || '未知')
       ​
           // 列出可用工具
           const toolsList = await client.listTools()
           console.log(
             '可用工具:',
             toolsList.tools.map((t) => t.name)
           )
       ​
           // 调用加法工具
           if (toolsList.tools.some((t) => t.name === 'add')) {
             const result = await client.callTool({
               name: 'add',
               arguments: { a: 5, b: 3 }
             })
             console.log('加法结果:', result.content[0].text)
           }
       ​
           // 断开客户端连接
           await client.close()
           console.log('客户端已断开连接。')
         } catch (error) {
           console.error('客户端错误:', error)
           process.exit(1)
         }
       }
       ​
       startClient().catch((error) => {
         console.error('主程序错误:', error)
         process.exit(1)
       })
       ​
  2. 代码说明

    • 创建一个名为 example-client 的 MCP 客户端。
    • 使用 spawn 启动服务器进程(McpServer.ts),通过 tsx 运行。
    • 通过 StdioClientTransport 连接服务器,列出工具并调用 add 工具(输入 a=5, b=3)。
    • 包含错误处理和进程清理。

在 IntelliJ IDEA 中运行

  1. 右键文件运行
  1. 创建运行配置

    • 点击 Run > Edit Configurations。

    • 点击 + 添加新配置,选择 Node.js。

    • 设置以下字段:

      • Name:MCP Client
      • Node interpreter:选择你的 Node.js 路径(运行 which node 确认)。
      • TypeScript Loader: 选择Boudled(tsx),只有选择这个才能直接运行。
      • Node parameters:留空。
      • File:选择 node_modules/tsx/dist/cli.js(tsx 的入口)。
    • 保存配置。

  1. 运行客户端

    • 点击 IDEA 顶部绿色三角形(Run),选择 MCP Client。

    • 或者在终端运行:

      复制代码
       npx tsx McpClient.ts

预期输出

less 复制代码
 MCP 服务器在 Stdio 上运行...
 已连接到 MCP 服务器: 未知
 可用工具: [ 'add' ]
 加法结果: 8
 客户端已断开连接。

调试常见问题

  1. 错误: The "path" argument must be of type string:

    • 确认 mcp-client.ts 中使用 spawn("npx.cmd", ["tsx", "mcp-server.ts"], { shell: true })(Windows 环境)。

    • 确保 tsx 已安装:

      css 复制代码
       npm install --save-dev tsx
  2. 错误: McpError: Cannot read properties of null (reading '_def'):

    • 确保 @modelcontextprotocol/sdk 和 zod 版本最新:

      java 复制代码
       npm install @modelcontextprotocol/sdk@latest zod@latest
    • 检查 mcp-server.ts 中的 addToolSchema 是否正确定义。

  3. 服务器名称显示"未知"

    • 确认 mcp-server.ts 中 McpServer 的 name 字段设置为 "example-server"。

    • 在客户端添加调试日志:

      arduino 复制代码
       console.log("服务器信息:", client.serverInfo);

总结

通过以上步骤,你在 IntelliJ IDEA 中成功搭建并运行了一个简单的 MCP 服务端和客户端。服务端提供了一个加法工具,客户端通过 Stdio 协议调用它。这个示例展示了 MCP 的核心功能,适合快速入门。你可以进一步扩展工具功能或尝试其他协议(如 WebSocket)。

相关推荐
浪裡遊1 小时前
React Hooks全面解析:从基础到高级的实用指南
开发语言·前端·javascript·react.js·node.js·ecmascript·php
whale fall2 小时前
npm install安装的node_modules是什么
前端·npm·node.js
会飞的鱼先生2 小时前
Node.js-http模块
网络协议·http·node.js
每天开心7 小时前
一文教你掌握事件机制
前端·javascript·ai编程
每天开心8 小时前
深入理解 CSS 选择器:从基础到高级
css·html·ai编程
俞乾9 小时前
Context Engineering(上下文工程)是 AI Agent 成功的关键吗?
openai·ai编程
kingchen10 小时前
稳定的Claude Code渠道,白嫖100刀
ai编程
量子位10 小时前
“英伟达显卡就是一坨 ”!博主 6000 字檄文怒批:烧接口、缺单元、驱动变砖还威胁媒体
ai编程
运器12310 小时前
【一起来学AI大模型】算法核心:数组/哈希表/树/排序/动态规划(LeetCode精练)
开发语言·人工智能·python·算法·ai·散列表·ai编程