手把手教你用Node.js开发一个MCP Server（附完整调试流程）

从零构建MCP Server的Node.js实战指南1. MCP协议与开发环境准备Model Context ProtocolMCP正在成为AI工具集成领域的新兴标准。这个由Anthropic提出的开放协议本质上为AI模型与外部系统搭建了一座标准化桥梁。想象一下当Claude这样的AI需要访问数据库、调用API或操作系统文件时MCP就像USB接口一样提供即插即用的连接能力。开发环境要求Node.js 18 环境TypeScript 5.0代码编辑器VS Code推荐终端工具iTerm2或Windows Terminal# 验证Node.js环境 node -v npm -v # 初始化项目 mkdir mcp-time-server cd mcp-time-server npm init -y npm install typescript types/node --save-dev npx tsc --init提示Windows用户需确保PATH中包含Node.js路径Mac用户建议通过nvm管理多版本Node2. 核心架构设计2.1 MCP Server的工作机制典型的MCP交互包含三个关键角色MCP Client集成在AI工具中如Claude、CursorMCP Server开发者实现的业务逻辑载体协议适配层处理JSON-RPC 2.0格式的通信// 典型请求结构示例 { jsonrpc: 2.0, method: tools/call, params: { name: getCurrentTime, arguments: {timezone: Asia/Shanghai} }, id: 1 }2.2 通信模式选择模式适用场景性能特点典型配置示例STDIO本地调试、CLI工具低延迟、高吞吐command: node, args: [server.js]SSE远程服务、Web集成实时事件推送url: http://localhost:8000/sse3. 实现时间服务Server3.1 初始化MCP Server首先安装官方SDKnpm install modelcontextprotocol/sdk zod创建基础服务框架import { McpServer } from modelcontextprotocol/sdk/server/mcp; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio; import { z } from zod; const server new McpServer({ name: TimeService, version: 1.0.0, description: 提供全球时区时间查询服务 });3.2 实现时间查询工具server.tool( getCurrentTime, 获取指定时区的当前时间, { timezone: z .string() .optional() .describe(IANA时区标识如America/New_York) }, async ({ timezone }) { try { const options timezone ? { timeZone: timezone } : {}; return { timestamp: new Date().toISOString(), localTime: new Date().toLocaleString(zh-CN, options), timezone: timezone || Intl.DateTimeFormat().resolvedOptions().timeZone }; } catch (error) { throw new Error(时区参数错误: ${error.message}); } } );3.3 启动服务async function start() { const transport new StdioServerTransport(); await server.connect(transport); console.log(⌚ 时间服务已启动); } start().catch(console.error);4. 调试与测试方案4.1 使用MCP Inspector官方提供的调试工具可可视化测试npx modelcontextprotocol/inspector node dist/server.js调试界面主要功能工具列表查看参数构造器原始请求/响应监控历史记录回放4.2 手动测试脚本创建测试用例验证功能const { spawn } require(child_process); const serverProcess spawn(node, [dist/server.js]); serverProcess.stdout.on(data, (data) { console.log([SERVER] ${data}); }); // 构造测试请求 const testRequest JSON.stringify({ jsonrpc: 2.0, method: tools/call, params: { name: getCurrentTime, arguments: { timezone: Europe/Berlin } }, id: Date.now() }); serverProcess.stdin.write(testRequest \n);4.3 常见问题排查时区无效错误验证IANA时区标识检查Node.js版本需≥14更新ICU数据npm install full-icuSTDIO通信故障Windows需使用cmd包装{ command: cmd, args: [/c, node, server.js] }5. 生产环境进阶配置5.1 性能优化策略连接池配置const transport new StdioServerTransport({ maxConnections: 10, idleTimeout: 30000 });日志集成npm install winstonimport winston from winston; const logger winston.createLogger({ level: debug, format: winston.format.json(), transports: [new winston.transports.File({ filename: mcp-debug.log })] }); server.setLogger((level, message) { logger.log(level, message); });5.2 安全防护措施输入验证z.string().regex(/^[A-Za-z_\/]$/).max(64)速率限制npm install express-rate-limit敏感操作审计server.on(toolCalled, (toolName, params) { auditLog(toolName, params); });6. 扩展开发实践6.1 多工具集成示例实现复合型天气预报服务server.tool(getWeather, ...); server.resource(cityList, ...); server.prompt(weatherQueryTips, ...);6.2 混合通信模式同时支持STDIO和HTTPimport { HttpServerTransport } from modelcontextprotocol/sdk/server/http; // HTTP服务 const httpTransport new HttpServerTransport({ port: 8080 }); server.connect(httpTransport); // STDIO服务 const stdioTransport new StdioServerTransport(); server.connect(stdioTransport);6.3 CI/CD集成示例GitHub Actions配置name: MCP Server Deployment on: [push] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - run: npm ci - run: npm test - run: docker build -t mcp-time-server . - run: docker push your-registry/mcp-time-server在实现过程中发现时区处理是最容易出错的环节。特别是在Docker环境中需要确保容器时区与宿主机一致。一个实用的技巧是在Dockerfile中加入ENV TZAsia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime