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 小时前
将GLM 4.5接入Claude Code,打造最具性价比的AI工程师
人工智能·ai编程·claude
Keegan小钢2 小时前
链上ETF研发日志 #2:智能合约开发完毕,测试准备中
智能合约·ai编程·claude
oil欧哟3 小时前
🧐 我开发的 AI 文本纠错/润色工具 Text-Well 上线了~
前端·ai编程·next.js
星空下的曙光6 小时前
nodejs项目中常用的npm包及分类
node.js
墨菲安全6 小时前
NPM组件 @0xme5war/apicli 等窃取主机敏感信息
前端·npm·node.js·主机信息窃取·npm恶意包·npm投毒
chaofan98013 小时前
阿里云通义灵码深度解析:AI编程时代的技术革命与实践探索
ai编程
cooljser14 小时前
0门槛免费使用 qwen-coder 的最佳方式
ai编程
程序员清风18 小时前
想让AI更强大?MCP协议了解一下!
面试·openai·ai编程
Sammyyyyy19 小时前
Node.js 是怎么一步步撼动PHP地位的
开发语言·node.js·php
结城19 小时前
使用node-cron实现Node.js定时任务
node.js