1. 项目概述与核心价值最近在折腾AI智能体开发特别是想让它们能更“自主”地处理一些任务比如查查数据、发个交易什么的。在这个过程中一个绕不开的坎就是“工具调用”。传统的做法要么是把一堆API接口硬编码进提示词要么是写死一堆函数调用逻辑不仅维护起来头疼智能体的能力边界也被框死了。直到我深度体验了由botwallet-co团队开源的mcp项目才算是找到了一个优雅的解法。这个项目全称是“Model Context Protocol”你可以把它理解为一套标准化的“插座”和“插头”规范。它定义了一套清晰的协议让大模型比如Claude、GPT能够动态地发现、理解并使用外部工具服务器而无需在模型层面进行任何预训练或硬编码。简单说它让AI智能体从“出厂时功能固定”变成了“可以随时插拔新技能”。botwallet-co/mcp这个仓库正是这个协议的一个官方参考实现同时也是一个功能强大的开发工具包。它的核心价值在于为开发者提供了一套开箱即用的SDK和工具让你能快速地将自己的数据源、API服务或者任何功能封装成符合MCP标准的“服务器”Server然后无缝地接入到支持MCP的“客户端”Client比如Claude Desktop、Cursor等。这意味着你写的工具可以被任何兼容MCP的AI应用使用极大地提升了工具的可复用性和智能体的灵活性。我花了几周时间用它把公司内部几个零散的查询接口和数据库连接器都标准化了现在团队里的AI助手都能安全、统一地调用这些能力开发效率提升非常明显。2. MCP协议核心原理与架构拆解要玩转botwallet-co/mcp首先得吃透MCP协议的基本思想。它采用了经典的客户端-服务器Client-Server架构但这里的交互语言是JSON-RPC over stdio标准输入输出或SSE服务器发送事件。这种设计非常巧妙因为它不依赖网络端口避免了复杂的网络配置和权限问题特别适合本地化、安全的工具集成。2.1 协议的核心交互流程整个协议的生命周期可以概括为几个关键阶段初始化握手客户端启动服务器进程服务器通过标准输出stdout发送一条initialize请求。客户端回应协商协议版本、能力等。这一步确立了通信基础。工具列表公布服务器紧接着或在后续通过tools/list通知向客户端宣告自己提供了哪些“工具”。每个工具都有唯一的名称、清晰的描述、以及严格的输入参数模式JSON Schema定义。这个描述至关重要它是大模型理解工具用途的“说明书”。工具调用与执行当用户向AI提出需求时AI模型运行在客户端会根据对话上下文和服务器公布的工具列表决定是否需要以及调用哪个工具。如果需要客户端会向服务器发送tools/call请求包含工具名和调用参数。服务器执行实际逻辑如查询数据库、调用API。结果返回服务器执行完毕后通过tools/call的响应将结果返回给客户端。结果可以是文本、结构化数据甚至是图片等多媒体内容通过特定的内容类型声明。客户端再将结果呈现给模型或用户。这个过程中服务器是完全被动的它只响应客户端的请求。而客户端尤其是集成了AI模型的则负责复杂的“意图理解”和“调度决策”。这种职责分离使得工具开发者可以专注于实现稳定的业务逻辑而无需关心AI是如何思考的。2.2botwallet-co/mcp项目的构成这个GitHub仓库不是一个单一工具而是一个生态工具箱主要包含以下几部分TypeScript/JavaScript SDK (modelcontextprotocol/sdk)这是核心。它提供了创建MCP服务器和客户端所需的所有类型定义、基础类和工具函数。用这个SDK你可以用几行代码就搭建起一个符合协议的服务器骨架。官方工具示例与服务器实现仓库里提供了多个高质量的示例比如sqlite服务器让AI能直接写SQL查数据库、filesystem服务器受限的文件读写、postgres服务器等。这些不仅是示例更是可以直接使用或参考的生产级代码。开发与调试工具例如modelcontextprotocol/sdk可能包含的测试工具以及如何配置主流AI客户端如Claude Desktop的详细指南。这对于开发和调试至关重要。注意MCP协议本身是语言无关的理论上可以用任何语言实现服务器。但botwallet-co/mcp提供的TS/JS SDK是目前最完善、最活跃的官方实现也是大多数开发者的首选。3. 从零开始构建你的第一个MCP服务器理论讲再多不如动手做一遍。我们来实现一个最简单的MCP服务器一个“时间查询服务器”。它提供一个工具当AI助手被问到“现在几点”或“今天星期几”时可以调用这个工具来获取准确的系统时间信息。3.1 环境准备与项目初始化首先确保你的环境有 Node.js (版本18或以上) 和 npm/yarn/pnpm。然后创建一个新目录并初始化项目。mkdir mcp-time-server cd mcp-time-server npm init -y接下来安装核心的MCP SDK。由于我们要创建服务器需要安装服务器包。npm install modelcontextprotocol/sdk同时我们也会用到zod库来方便地定义参数模式虽然SDK内部可能已经处理但显式安装有助于类型提示。npm install zod3.2 服务器代码实现创建一个名为server.js(或server.ts如果你用TypeScript) 的文件。我们将使用ES Module语法。// server.js import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; // 1. 创建Server实例声明名称和版本 const server new Server( { name: time-server, version: 1.0.0, }, { capabilities: { // 声明本服务器提供“工具”能力 tools: {}, }, } ); // 2. 定义“获取当前时间”工具 // 参数模式这里我们定义一个可选参数 format用于指定返回时间的格式 const getCurrentTimeSchema z.object({ format: z.enum([iso, human, timestamp]).optional().describe(时间输出格式iso标准格式human可读格式或时间戳), }); // 3. 实现工具的处理逻辑 server.setRequestHandler(tools/call, async (request) { // 检查调用的工具名是否匹配 if (request.params.name ! get_current_time) { throw new Error(Unknown tool: ${request.params.name}); } // 使用Zod安全地解析和验证传入的参数 const parsedArgs getCurrentTimeSchema.safeParse(request.params.arguments || {}); if (!parsedArgs.success) { throw new Error(Invalid arguments: ${parsedArgs.error.message}); } const { format human } parsedArgs.data; const now new Date(); let result; switch (format) { case iso: result now.toISOString(); // 例如 2023-10-27T08:30:00.000Z break; case timestamp: result Math.floor(now.getTime() / 1000).toString(); // 秒级时间戳 break; case human: default: // 一个更友好的格式 result now.toLocaleString(zh-CN, { timeZone: Asia/Shanghai, year: numeric, month: long, day: numeric, weekday: long, hour: 2-digit, minute: 2-digit, second: 2-digit, }); // 例如 “2023年10月27日星期五 16:30:00” break; } // 返回工具调用结果 return { content: [ { type: text, text: 当前时间是${result}, }, ], }; }); // 4. 在服务器初始化完成后公布工具列表 server.setRequestHandler(tools/list, async () { return { tools: [ { name: get_current_time, description: 获取当前的系统时间和日期。, inputSchema: { type: object, properties: { format: { type: string, enum: [iso, human, timestamp], description: 输出时间的格式。可选值iso标准ISO8601格式、human人类可读格式、timestampUnix秒级时间戳。默认为human。, }, }, }, }, ], }; }); // 5. 启动服务器使用标准输入输出作为传输层 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Time Server 已启动并等待连接...); } main().catch((error) { console.error(服务器启动失败:, error); process.exit(1); });3.3 配置AI客户端以使用你的服务器服务器写好了但孤零零的它无法工作。需要有一个MCP客户端来连接和调用它。最常用的客户端就是Anthropic Claude Desktop。下面是如何配置Claude Desktop来加载我们刚写的本地服务器。找到Claude Desktop的配置目录macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件如果文件不存在就创建它。我们需要在mcpServers部分添加我们的服务器配置。{ mcpServers: { time-server: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-time-server/server.js ], env: { NODE_ENV: development } } } }关键点time-server是给这个服务器配置起的任意名字方便管理。command必须是node因为我们的服务器是Node.js脚本。args里的路径必须是绝对路径。相对路径会导致Claude Desktop启动失败。配置完成后必须完全重启Claude Desktop应用不是关闭窗口而是从任务栏/程序坞退出再重新打开。验证与使用重启Claude后打开Claude你可以尝试问“现在几点了” Claude的回复中可能会显示一个get_current_time的工具调用按钮或者它直接调用工具并返回结果。你也可以指定格式“用ISO格式告诉我现在的时间。” 观察它是否会正确传递{“format”: “iso”}参数。实操心得在开发调试阶段强烈建议先不使用Claude Desktop而是用MCP SDK自带的测试客户端或者自己写一个简单的客户端脚本进行测试。因为Claude Desktop的配置缓存、重启要求比较繁琐不利于快速迭代。你可以写一个简单的test_client.js用ChildProcess启动你的服务器并模拟调用能更快地定位问题。4. 构建复杂生产级MCP服务器的关键要点简单的示例跑通后我们要考虑更实际的场景。比如连接公司内部的MySQL数据库让AI能安全地查询业务数据。这涉及到连接池管理、SQL安全、错误处理等复杂问题。4.1 连接池与资源管理在服务器中直接创建数据库连接是危险的因为MCP服务器进程是常驻的不当管理会导致连接泄漏。我们需要使用连接池。// 使用 mysql2 或 pg 库 import { createPool } from mysql2/promise; const pool createPool({ host: process.env.DB_HOST, user: process.env.DB_USER, password: process.env.DB_PASSWORD, database: process.env.DB_NAME, waitForConnections: true, connectionLimit: 5, // 根据负载调整 queueLimit: 0, }); // 在工具调用处理函数中获取连接 server.setRequestHandler(tools/call, async (request) { if (request.params.name query_database) { let connection; try { connection await pool.getConnection(); const [rows] await connection.execute(SELECT * FROM users WHERE status ?, [active]); // ... 处理并返回 rows } catch (error) { // 返回结构化的错误信息而非抛出避免服务器崩溃 return { content: [{ type: text, text: 查询失败: ${error.message} }], isError: true }; } finally { if (connection) connection.release(); // 关键一定要释放回连接池 } } });注意事项永远不要在工具描述或返回结果中泄露真实的数据库连接信息、表结构除非是设计好的、或具体的SQL错误详情。返回给AI和用户的信息应该是经过净化和概括的。4.2 动态工具列表与权限控制不是所有工具都应对所有用户或所有对话开放。MCP协议支持服务器在运行时动态返回工具列表。我们可以基于某些条件比如通过初始化参数传递的“用户角色”来过滤工具。// 假设客户端在初始化时传递了 clientInfo server.setRequestHandler(initialize, async (request) { const clientRole request.params.clientInfo?.metadata?.role || guest; // 将角色信息存储在server的上下文中 server.context.userRole clientRole; return { ... }; // 返回标准的initialize响应 }); server.setRequestHandler(tools/list, async (request) { const role server.context.userRole; const allTools [...]; // 所有预定义的工具配置 const allowedTools allTools.filter(tool { if (role admin) return true; if (role analyst tool.name.startsWith(query_)) return true; return false; // guest角色可能只有最基础的工具 }); return { tools: allowedTools }; });4.3 处理复杂参数与内容类型工具不仅可以返回文本还可以返回结构化数据JSON、图片base64、甚至文件。这对于数据可视化类工具非常有用。// 返回一个包含图表图片和摘要数据的复杂结果 server.setRequestHandler(tools/call, async (request) { if (request.params.name generate_sales_chart) { // 1. 生成图表获取Buffer const chartBuffer await generateChartFunction(); const base64Image chartBuffer.toString(base64); // 2. 准备结构化数据 const summaryData { totalSales: 100000, topProduct: Product A, growth: 15% }; return { content: [ { type: text, text: 这是本季度销售数据的图表和关键摘要, }, { type: image, data: base64Image, mimeType: image/png, // 必须指定MIME类型 }, { type: object, // 结构化数据 data: summaryData, } ], }; } });客户端如Claude在收到这样的响应后可能会以不同的方式渲染图片和对象极大地丰富了交互体验。5. 调试、测试与性能优化实战开发MCP服务器尤其是与AI客户端集成时调试是一大挑战。因为交互是异步的、基于进程间通信的。5.1 高效的调试策略独立测试脚本如前所述编写一个不依赖任何AI客户端的本地测试脚本是最高效的方式。这个脚本应该使用child_process.spawn启动你的服务器。模拟客户端向服务器的stdin写入JSON-RPC请求。监听服务器的stdout并解析JSON-RPC响应。这样你可以精确控制输入并立即看到输出快速验证逻辑。启用调试日志在你的服务器代码中有策略地添加日志输出到stderrconsole.error。因为MCP协议使用stdout进行通信所以调试信息必须输出到stderr以免干扰协议消息。Claude Desktop通常会捕获并显示stderr输出这在它的开发者控制台里非常有用。使用VS Code调试配置为你的服务器项目配置.vscode/launch.json让你可以直接在IDE中打断点调试。{ version: 0.2.0, configurations: [ { type: node, request: launch, name: Debug MCP Server, program: ${workspaceFolder}/server.js, stdio: [pipe, pipe, pipe] // 确保stdio被正确重定向 } ] }5.2 常见问题排查清单以下是我在开发过程中踩过的一些坑和解决方案问题现象可能原因排查步骤与解决方案Claude Desktop 提示 “无法连接MCP服务器” 或配置无效1. 配置文件路径错误。2.command或args中的路径不是绝对路径。3. Node.js 脚本存在语法错误导致进程立即退出。4. 配置文件格式错误JSON语法。1. 检查配置文件路径是否正确。2.确保使用绝对路径。可以用pwd(Unix) 或cd(Windows) 命令获取。3. 在终端手动运行node /path/to/server.js看是否有错误输出。4. 使用 JSON 验证工具检查claude_desktop_config.json。工具列表不显示或AI从不调用工具1. 服务器tools/list处理器未正确实现或返回格式错误。2. 工具描述 (description) 不够清晰AI无法理解其用途。3. 初始化握手失败。1. 用测试客户端调用tools/list检查返回的JSON结构是否符合协议。2.优化工具描述用自然语言清晰说明工具功能、适用场景、输入参数含义。这是AI决定是否调用的关键。3. 检查服务器启动日志看initialize请求是否被正确处理。工具调用后返回错误但服务器日志显示成功1. 服务器返回的响应格式不符合协议。2.content字段格式错误或type不被客户端支持。3. 返回了isError: true但客户端未友好处理。1. 严格遵循协议规范构建响应对象。使用SDK提供的类型可以避免此问题。2. 检查返回的content数组内每个对象的type和结构。对于text类型确保是{type: ‘text‘ text: ‘...‘}。3. 在错误处理中除了设置isError也应在content中提供友好的错误文本。服务器进程占用内存或CPU过高1. 存在内存泄漏如未释放数据库连接。2. 某个工具执行了非常耗时的同步操作阻塞了事件循环。3. 工具被AI频繁循环调用。1. 使用连接池并确保getConnection后必有release。2.将所有I/O操作文件、网络、数据库设计为异步。避免在工具处理器中执行CPU密集型同步计算。3. 可以考虑在工具层面添加简单的限流或状态检查防止AI陷入无效调用循环。5.3 性能与安全最佳实践超时控制为每个工具调用设置超时。如果某个数据库查询或API调用耗时过长应该主动中断并返回超时错误避免服务器线程被长时间占用。const { promisify } require(util); const timeout promisify(setTimeout); server.setRequestHandler(tools/call, async (request) { // 使用Promise.race实现超时 const toolPromise executeToolLogic(request); const timeoutPromise timeout(30000).then(() { throw new Error(工具调用超时30秒); }); try { const result await Promise.race([toolPromise, timeoutPromise]); return result; } catch (error) { // 处理超时或其他错误 } });输入验证与净化这是安全的重中之重。永远不要相信从AI客户端传来的参数。即使有JSON Schema定义也要在服务器端进行二次验证和净化特别是涉及SQL查询、文件路径、系统命令时。SQL: 使用参数化查询Prepared Statements绝对禁止字符串拼接。文件路径: 将操作限制在某个沙箱目录内并使用path.resolve和path.relative检查路径是否越界。命令执行: 尽量避免提供直接执行系统命令的工具。如果必须使用白名单机制严格限制可执行的命令和参数。环境变量与配置管理敏感信息如数据库密码、API密钥等必须通过环境变量或安全的配置管理系统传入绝不能硬编码在代码中。可以使用dotenv包在开发时加载.env文件。6. 进阶应用将现有服务快速MCP化你可能已经有很多现成的内部服务或脚本。将它们改造成MCP服务器可以立刻赋予AI调用能力。这里有一个快速改造的思路识别接口将你的服务功能抽象成一个个独立的“动作”或“查询”每个动作对应一个MCP工具。包装适配层创建一个新的Node.js项目使用MCP SDK。为每个“动作”编写一个包装函数这个函数内部去调用你原有的服务可能是HTTP API、GRPC、或直接调用函数库。定义工具描述为每个包装函数编写清晰、详细的工具描述和输入模式。这一步对AI的调用准确性影响巨大。处理差异原有服务的错误码、返回格式可能需要转换以符合MCP的响应格式和用户友好的要求。例如你有一个旧的用户查询REST APIGET /api/users?id123。你可以创建一个get_user_info工具它接收userId参数内部用axios调用老API然后将结果格式化成文本或对象返回。这种“适配器”模式让你无需重写核心业务逻辑就能快速融入AI生态。botwallet-co/mcp项目提供的SDK和模式正是为了降低这种集成成本。随着MCP被更多AI平台原生支持如Cursor、Windsurf等投资将现有能力进行MCP标准化会成为提升团队人效的一个高性价比选择。
基于MCP协议构建AI工具服务器：从原理到实战开发指南
发布时间：2026/7/8 8:21:44
1. 项目概述与核心价值最近在折腾AI智能体开发特别是想让它们能更“自主”地处理一些任务比如查查数据、发个交易什么的。在这个过程中一个绕不开的坎就是“工具调用”。传统的做法要么是把一堆API接口硬编码进提示词要么是写死一堆函数调用逻辑不仅维护起来头疼智能体的能力边界也被框死了。直到我深度体验了由botwallet-co团队开源的mcp项目才算是找到了一个优雅的解法。这个项目全称是“Model Context Protocol”你可以把它理解为一套标准化的“插座”和“插头”规范。它定义了一套清晰的协议让大模型比如Claude、GPT能够动态地发现、理解并使用外部工具服务器而无需在模型层面进行任何预训练或硬编码。简单说它让AI智能体从“出厂时功能固定”变成了“可以随时插拔新技能”。botwallet-co/mcp这个仓库正是这个协议的一个官方参考实现同时也是一个功能强大的开发工具包。它的核心价值在于为开发者提供了一套开箱即用的SDK和工具让你能快速地将自己的数据源、API服务或者任何功能封装成符合MCP标准的“服务器”Server然后无缝地接入到支持MCP的“客户端”Client比如Claude Desktop、Cursor等。这意味着你写的工具可以被任何兼容MCP的AI应用使用极大地提升了工具的可复用性和智能体的灵活性。我花了几周时间用它把公司内部几个零散的查询接口和数据库连接器都标准化了现在团队里的AI助手都能安全、统一地调用这些能力开发效率提升非常明显。2. MCP协议核心原理与架构拆解要玩转botwallet-co/mcp首先得吃透MCP协议的基本思想。它采用了经典的客户端-服务器Client-Server架构但这里的交互语言是JSON-RPC over stdio标准输入输出或SSE服务器发送事件。这种设计非常巧妙因为它不依赖网络端口避免了复杂的网络配置和权限问题特别适合本地化、安全的工具集成。2.1 协议的核心交互流程整个协议的生命周期可以概括为几个关键阶段初始化握手客户端启动服务器进程服务器通过标准输出stdout发送一条initialize请求。客户端回应协商协议版本、能力等。这一步确立了通信基础。工具列表公布服务器紧接着或在后续通过tools/list通知向客户端宣告自己提供了哪些“工具”。每个工具都有唯一的名称、清晰的描述、以及严格的输入参数模式JSON Schema定义。这个描述至关重要它是大模型理解工具用途的“说明书”。工具调用与执行当用户向AI提出需求时AI模型运行在客户端会根据对话上下文和服务器公布的工具列表决定是否需要以及调用哪个工具。如果需要客户端会向服务器发送tools/call请求包含工具名和调用参数。服务器执行实际逻辑如查询数据库、调用API。结果返回服务器执行完毕后通过tools/call的响应将结果返回给客户端。结果可以是文本、结构化数据甚至是图片等多媒体内容通过特定的内容类型声明。客户端再将结果呈现给模型或用户。这个过程中服务器是完全被动的它只响应客户端的请求。而客户端尤其是集成了AI模型的则负责复杂的“意图理解”和“调度决策”。这种职责分离使得工具开发者可以专注于实现稳定的业务逻辑而无需关心AI是如何思考的。2.2botwallet-co/mcp项目的构成这个GitHub仓库不是一个单一工具而是一个生态工具箱主要包含以下几部分TypeScript/JavaScript SDK (modelcontextprotocol/sdk)这是核心。它提供了创建MCP服务器和客户端所需的所有类型定义、基础类和工具函数。用这个SDK你可以用几行代码就搭建起一个符合协议的服务器骨架。官方工具示例与服务器实现仓库里提供了多个高质量的示例比如sqlite服务器让AI能直接写SQL查数据库、filesystem服务器受限的文件读写、postgres服务器等。这些不仅是示例更是可以直接使用或参考的生产级代码。开发与调试工具例如modelcontextprotocol/sdk可能包含的测试工具以及如何配置主流AI客户端如Claude Desktop的详细指南。这对于开发和调试至关重要。注意MCP协议本身是语言无关的理论上可以用任何语言实现服务器。但botwallet-co/mcp提供的TS/JS SDK是目前最完善、最活跃的官方实现也是大多数开发者的首选。3. 从零开始构建你的第一个MCP服务器理论讲再多不如动手做一遍。我们来实现一个最简单的MCP服务器一个“时间查询服务器”。它提供一个工具当AI助手被问到“现在几点”或“今天星期几”时可以调用这个工具来获取准确的系统时间信息。3.1 环境准备与项目初始化首先确保你的环境有 Node.js (版本18或以上) 和 npm/yarn/pnpm。然后创建一个新目录并初始化项目。mkdir mcp-time-server cd mcp-time-server npm init -y接下来安装核心的MCP SDK。由于我们要创建服务器需要安装服务器包。npm install modelcontextprotocol/sdk同时我们也会用到zod库来方便地定义参数模式虽然SDK内部可能已经处理但显式安装有助于类型提示。npm install zod3.2 服务器代码实现创建一个名为server.js(或server.ts如果你用TypeScript) 的文件。我们将使用ES Module语法。// server.js import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; // 1. 创建Server实例声明名称和版本 const server new Server( { name: time-server, version: 1.0.0, }, { capabilities: { // 声明本服务器提供“工具”能力 tools: {}, }, } ); // 2. 定义“获取当前时间”工具 // 参数模式这里我们定义一个可选参数 format用于指定返回时间的格式 const getCurrentTimeSchema z.object({ format: z.enum([iso, human, timestamp]).optional().describe(时间输出格式iso标准格式human可读格式或时间戳), }); // 3. 实现工具的处理逻辑 server.setRequestHandler(tools/call, async (request) { // 检查调用的工具名是否匹配 if (request.params.name ! get_current_time) { throw new Error(Unknown tool: ${request.params.name}); } // 使用Zod安全地解析和验证传入的参数 const parsedArgs getCurrentTimeSchema.safeParse(request.params.arguments || {}); if (!parsedArgs.success) { throw new Error(Invalid arguments: ${parsedArgs.error.message}); } const { format human } parsedArgs.data; const now new Date(); let result; switch (format) { case iso: result now.toISOString(); // 例如 2023-10-27T08:30:00.000Z break; case timestamp: result Math.floor(now.getTime() / 1000).toString(); // 秒级时间戳 break; case human: default: // 一个更友好的格式 result now.toLocaleString(zh-CN, { timeZone: Asia/Shanghai, year: numeric, month: long, day: numeric, weekday: long, hour: 2-digit, minute: 2-digit, second: 2-digit, }); // 例如 “2023年10月27日星期五 16:30:00” break; } // 返回工具调用结果 return { content: [ { type: text, text: 当前时间是${result}, }, ], }; }); // 4. 在服务器初始化完成后公布工具列表 server.setRequestHandler(tools/list, async () { return { tools: [ { name: get_current_time, description: 获取当前的系统时间和日期。, inputSchema: { type: object, properties: { format: { type: string, enum: [iso, human, timestamp], description: 输出时间的格式。可选值iso标准ISO8601格式、human人类可读格式、timestampUnix秒级时间戳。默认为human。, }, }, }, }, ], }; }); // 5. 启动服务器使用标准输入输出作为传输层 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Time Server 已启动并等待连接...); } main().catch((error) { console.error(服务器启动失败:, error); process.exit(1); });3.3 配置AI客户端以使用你的服务器服务器写好了但孤零零的它无法工作。需要有一个MCP客户端来连接和调用它。最常用的客户端就是Anthropic Claude Desktop。下面是如何配置Claude Desktop来加载我们刚写的本地服务器。找到Claude Desktop的配置目录macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件如果文件不存在就创建它。我们需要在mcpServers部分添加我们的服务器配置。{ mcpServers: { time-server: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-time-server/server.js ], env: { NODE_ENV: development } } } }关键点time-server是给这个服务器配置起的任意名字方便管理。command必须是node因为我们的服务器是Node.js脚本。args里的路径必须是绝对路径。相对路径会导致Claude Desktop启动失败。配置完成后必须完全重启Claude Desktop应用不是关闭窗口而是从任务栏/程序坞退出再重新打开。验证与使用重启Claude后打开Claude你可以尝试问“现在几点了” Claude的回复中可能会显示一个get_current_time的工具调用按钮或者它直接调用工具并返回结果。你也可以指定格式“用ISO格式告诉我现在的时间。” 观察它是否会正确传递{“format”: “iso”}参数。实操心得在开发调试阶段强烈建议先不使用Claude Desktop而是用MCP SDK自带的测试客户端或者自己写一个简单的客户端脚本进行测试。因为Claude Desktop的配置缓存、重启要求比较繁琐不利于快速迭代。你可以写一个简单的test_client.js用ChildProcess启动你的服务器并模拟调用能更快地定位问题。4. 构建复杂生产级MCP服务器的关键要点简单的示例跑通后我们要考虑更实际的场景。比如连接公司内部的MySQL数据库让AI能安全地查询业务数据。这涉及到连接池管理、SQL安全、错误处理等复杂问题。4.1 连接池与资源管理在服务器中直接创建数据库连接是危险的因为MCP服务器进程是常驻的不当管理会导致连接泄漏。我们需要使用连接池。// 使用 mysql2 或 pg 库 import { createPool } from mysql2/promise; const pool createPool({ host: process.env.DB_HOST, user: process.env.DB_USER, password: process.env.DB_PASSWORD, database: process.env.DB_NAME, waitForConnections: true, connectionLimit: 5, // 根据负载调整 queueLimit: 0, }); // 在工具调用处理函数中获取连接 server.setRequestHandler(tools/call, async (request) { if (request.params.name query_database) { let connection; try { connection await pool.getConnection(); const [rows] await connection.execute(SELECT * FROM users WHERE status ?, [active]); // ... 处理并返回 rows } catch (error) { // 返回结构化的错误信息而非抛出避免服务器崩溃 return { content: [{ type: text, text: 查询失败: ${error.message} }], isError: true }; } finally { if (connection) connection.release(); // 关键一定要释放回连接池 } } });注意事项永远不要在工具描述或返回结果中泄露真实的数据库连接信息、表结构除非是设计好的、或具体的SQL错误详情。返回给AI和用户的信息应该是经过净化和概括的。4.2 动态工具列表与权限控制不是所有工具都应对所有用户或所有对话开放。MCP协议支持服务器在运行时动态返回工具列表。我们可以基于某些条件比如通过初始化参数传递的“用户角色”来过滤工具。// 假设客户端在初始化时传递了 clientInfo server.setRequestHandler(initialize, async (request) { const clientRole request.params.clientInfo?.metadata?.role || guest; // 将角色信息存储在server的上下文中 server.context.userRole clientRole; return { ... }; // 返回标准的initialize响应 }); server.setRequestHandler(tools/list, async (request) { const role server.context.userRole; const allTools [...]; // 所有预定义的工具配置 const allowedTools allTools.filter(tool { if (role admin) return true; if (role analyst tool.name.startsWith(query_)) return true; return false; // guest角色可能只有最基础的工具 }); return { tools: allowedTools }; });4.3 处理复杂参数与内容类型工具不仅可以返回文本还可以返回结构化数据JSON、图片base64、甚至文件。这对于数据可视化类工具非常有用。// 返回一个包含图表图片和摘要数据的复杂结果 server.setRequestHandler(tools/call, async (request) { if (request.params.name generate_sales_chart) { // 1. 生成图表获取Buffer const chartBuffer await generateChartFunction(); const base64Image chartBuffer.toString(base64); // 2. 准备结构化数据 const summaryData { totalSales: 100000, topProduct: Product A, growth: 15% }; return { content: [ { type: text, text: 这是本季度销售数据的图表和关键摘要, }, { type: image, data: base64Image, mimeType: image/png, // 必须指定MIME类型 }, { type: object, // 结构化数据 data: summaryData, } ], }; } });客户端如Claude在收到这样的响应后可能会以不同的方式渲染图片和对象极大地丰富了交互体验。5. 调试、测试与性能优化实战开发MCP服务器尤其是与AI客户端集成时调试是一大挑战。因为交互是异步的、基于进程间通信的。5.1 高效的调试策略独立测试脚本如前所述编写一个不依赖任何AI客户端的本地测试脚本是最高效的方式。这个脚本应该使用child_process.spawn启动你的服务器。模拟客户端向服务器的stdin写入JSON-RPC请求。监听服务器的stdout并解析JSON-RPC响应。这样你可以精确控制输入并立即看到输出快速验证逻辑。启用调试日志在你的服务器代码中有策略地添加日志输出到stderrconsole.error。因为MCP协议使用stdout进行通信所以调试信息必须输出到stderr以免干扰协议消息。Claude Desktop通常会捕获并显示stderr输出这在它的开发者控制台里非常有用。使用VS Code调试配置为你的服务器项目配置.vscode/launch.json让你可以直接在IDE中打断点调试。{ version: 0.2.0, configurations: [ { type: node, request: launch, name: Debug MCP Server, program: ${workspaceFolder}/server.js, stdio: [pipe, pipe, pipe] // 确保stdio被正确重定向 } ] }5.2 常见问题排查清单以下是我在开发过程中踩过的一些坑和解决方案问题现象可能原因排查步骤与解决方案Claude Desktop 提示 “无法连接MCP服务器” 或配置无效1. 配置文件路径错误。2.command或args中的路径不是绝对路径。3. Node.js 脚本存在语法错误导致进程立即退出。4. 配置文件格式错误JSON语法。1. 检查配置文件路径是否正确。2.确保使用绝对路径。可以用pwd(Unix) 或cd(Windows) 命令获取。3. 在终端手动运行node /path/to/server.js看是否有错误输出。4. 使用 JSON 验证工具检查claude_desktop_config.json。工具列表不显示或AI从不调用工具1. 服务器tools/list处理器未正确实现或返回格式错误。2. 工具描述 (description) 不够清晰AI无法理解其用途。3. 初始化握手失败。1. 用测试客户端调用tools/list检查返回的JSON结构是否符合协议。2.优化工具描述用自然语言清晰说明工具功能、适用场景、输入参数含义。这是AI决定是否调用的关键。3. 检查服务器启动日志看initialize请求是否被正确处理。工具调用后返回错误但服务器日志显示成功1. 服务器返回的响应格式不符合协议。2.content字段格式错误或type不被客户端支持。3. 返回了isError: true但客户端未友好处理。1. 严格遵循协议规范构建响应对象。使用SDK提供的类型可以避免此问题。2. 检查返回的content数组内每个对象的type和结构。对于text类型确保是{type: ‘text‘ text: ‘...‘}。3. 在错误处理中除了设置isError也应在content中提供友好的错误文本。服务器进程占用内存或CPU过高1. 存在内存泄漏如未释放数据库连接。2. 某个工具执行了非常耗时的同步操作阻塞了事件循环。3. 工具被AI频繁循环调用。1. 使用连接池并确保getConnection后必有release。2.将所有I/O操作文件、网络、数据库设计为异步。避免在工具处理器中执行CPU密集型同步计算。3. 可以考虑在工具层面添加简单的限流或状态检查防止AI陷入无效调用循环。5.3 性能与安全最佳实践超时控制为每个工具调用设置超时。如果某个数据库查询或API调用耗时过长应该主动中断并返回超时错误避免服务器线程被长时间占用。const { promisify } require(util); const timeout promisify(setTimeout); server.setRequestHandler(tools/call, async (request) { // 使用Promise.race实现超时 const toolPromise executeToolLogic(request); const timeoutPromise timeout(30000).then(() { throw new Error(工具调用超时30秒); }); try { const result await Promise.race([toolPromise, timeoutPromise]); return result; } catch (error) { // 处理超时或其他错误 } });输入验证与净化这是安全的重中之重。永远不要相信从AI客户端传来的参数。即使有JSON Schema定义也要在服务器端进行二次验证和净化特别是涉及SQL查询、文件路径、系统命令时。SQL: 使用参数化查询Prepared Statements绝对禁止字符串拼接。文件路径: 将操作限制在某个沙箱目录内并使用path.resolve和path.relative检查路径是否越界。命令执行: 尽量避免提供直接执行系统命令的工具。如果必须使用白名单机制严格限制可执行的命令和参数。环境变量与配置管理敏感信息如数据库密码、API密钥等必须通过环境变量或安全的配置管理系统传入绝不能硬编码在代码中。可以使用dotenv包在开发时加载.env文件。6. 进阶应用将现有服务快速MCP化你可能已经有很多现成的内部服务或脚本。将它们改造成MCP服务器可以立刻赋予AI调用能力。这里有一个快速改造的思路识别接口将你的服务功能抽象成一个个独立的“动作”或“查询”每个动作对应一个MCP工具。包装适配层创建一个新的Node.js项目使用MCP SDK。为每个“动作”编写一个包装函数这个函数内部去调用你原有的服务可能是HTTP API、GRPC、或直接调用函数库。定义工具描述为每个包装函数编写清晰、详细的工具描述和输入模式。这一步对AI的调用准确性影响巨大。处理差异原有服务的错误码、返回格式可能需要转换以符合MCP的响应格式和用户友好的要求。例如你有一个旧的用户查询REST APIGET /api/users?id123。你可以创建一个get_user_info工具它接收userId参数内部用axios调用老API然后将结果格式化成文本或对象返回。这种“适配器”模式让你无需重写核心业务逻辑就能快速融入AI生态。botwallet-co/mcp项目提供的SDK和模式正是为了降低这种集成成本。随着MCP被更多AI平台原生支持如Cursor、Windsurf等投资将现有能力进行MCP标准化会成为提升团队人效的一个高性价比选择。
