基于MCP模板快速构建AI Agent工具服务器：从原理到实践

1. 项目概述MCP模板的定位与价值最近在折腾AI Agent的开发特别是想让它能调用我自己的工具和API绕不开的一个概念就是MCPModel Context Protocol。这玩意儿说白了就是给大模型和外部工具之间搭的一座标准化的桥。你肯定也遇到过想让ChatGPT或者Claude去操作你的数据库、调用你的内部API或者读取某个特定格式的文件直接搞很麻烦要么得写一堆复杂的提示词要么就得自己封装一层又一层。MCP就是为了解决这个“连接”问题而生的协议。那么adamwulf/mcp-template这个项目就是一座帮你快速搭建这座桥的“脚手架”。它不是MCP协议本身而是一个开箱即用的模板项目。想象一下你要开发一个能让AI使用的工具服务器MCP Server从零开始你得配置环境、理解协议规范、处理通信、管理依赖……一堆琐事。这个模板把这些基础工作都做好了你只需要关注最核心的部分你的工具逻辑是什么。对于任何想快速入门MCP服务端开发或者希望将自己的能力比如一个内部查询系统、一个文件处理器、一个专有API快速暴露给AI模型的开发者来说这个模板的价值不言而喻。它大幅降低了MCP生态的准入门槛让你能跳过前期繁琐的搭建直接进入业务逻辑的创作。2. 核心架构与设计思路拆解2.1 MCP协议的核心思想工具即资源在深入模板之前有必要先理解MCP协议的设计哲学。它把AI模型客户端需要使用的“能力”抽象为两种核心概念资源Resources和工具Tools。资源Resources可以理解为“数据”或“信息源”。比如一个数据库连接、一个特定的JSON文件、一个网页的实时内容。客户端AI可以“读取”这些资源的内容将其作为上下文信息。在协议中这通过resources/list和resources/read等方法实现。工具Tools可以理解为“动作”或“函数”。比如“执行一次数据库查询”、“发送一封邮件”、“调用某个计算API”。客户端可以“调用”这些工具并获取执行结果。这通过tools/list和tools/call等方法实现。MCP Server的核心工作就是向客户端宣告“我这里有这些资源它们的URI和描述和这些工具它们的输入参数和描述”并且在客户端请求时提供资源内容或执行工具调用。adamwulf/mcp-template的设计正是围绕这一思想展开的。它提供了一个清晰的代码结构让你分别定义资源和工具并处理了底层的协议通信通常基于JSON-RPC over stdio 或 SSE让你只需填充“宣告列表”和“处理函数”这两个核心部分。2.2 模板项目的结构解析一个典型的基于此模板的项目结构会非常清晰这也是其作为“模板”的价值所在。虽然具体文件可能因版本略有差异但核心模块通常包括mcp-my-server/ ├── src/ │ ├── server.ts (或 index.ts) # 服务器主入口初始化并启动MCP Server │ ├── resources/ # 资源定义模块 │ │ └── my-resource.ts # 定义具体的资源如“系统状态文档” │ ├── tools/ # 工具定义模块 │ │ └── my-tool.ts # 定义具体的工具如“查询用户信息” │ └── types.ts # 共享的类型定义TypeScript项目 ├── package.json # 项目依赖和脚本定义 ├── tsconfig.json # TypeScript配置如使用TS └── README.md # 项目说明和快速启动指南设计思路的核心在于“分离关注点”协议层封装模板已经用某个MCP SDK比如modelcontextprotocol/sdk处理了与客户端的握手、心跳、请求路由和响应格式化。你不需要关心JSON-RPC的消息格式该怎么拼。业务逻辑隔离你将不同的能力资源、工具分门别类地放在不同的文件中保持代码的整洁和可维护性。新增一个工具只需在tools/目录下新建一个文件并导出。标准化入口主入口文件server.ts的职责非常单一导入你定义的所有资源和工具将它们注册到MCP Server实例然后启动服务。这个模式几乎是固定的大大减少了心智负担。注意使用模板时务必仔细阅读其README.md。不同的模板版本可能基于不同的语言Node.js, Python等或不同的底层SDK启动方式和配置项会有差异。盲目复制代码可能无法运行。3. 从零开始使用模板构建你的第一个MCP Server理论说得再多不如动手做一遍。下面我们以创建一个“简易系统信息查询”MCP Server为例演示如何使用模板。3.1 环境准备与项目初始化假设模板是基于 Node.js/TypeScript 的。首先确保你的环境就绪# 1. 确保已安装 Node.js (版本建议16) 和 npm/yarn/pnpm node --version # 2. 克隆模板仓库这里以adamwulf的模板为例实际请以项目最新README为准 git clone https://github.com/adamwulf/mcp-template.git my-system-info-server cd my-system-info-server # 3. 安装依赖 npm install # 或 yarn install 或 pnpm install安装完成后花几分钟浏览一下package.json和src/目录下的文件了解现有的结构和示例代码。通常模板会自带一两个示例比如一个“echo”工具你可以先运行起来试试确保基础环境没问题。# 尝试运行示例服务器具体命令看package.json中的scripts npm run dev如果控制台没有报错显示服务器已启动可能在监听某个stdio说明模板基础环境运行正常。3.2 定义你的第一个资源系统状态报告资源的作用是提供静态或动态的内容供AI读取。我们来创建一个资源它提供一个包含当前时间、系统平台和Node.js版本的文本报告。在src/resources/目录下创建新文件system-status.ts// src/resources/system-status.ts import { ResourceTemplate } from “modelcontextprotocol/sdk/server”; // 导入类型具体导入路径根据模板使用的SDK调整 // 1. 定义资源模板 export const systemStatusResource: ResourceTemplate { // 资源的唯一标识URI客户端通过这个URI来请求读取 uri: “resource://my-server/system-status”, // 资源的友好名称和描述帮助AI理解这是什么 name: “System Status Report”, description: “A report containing current system time, platform, and Node.js version.”, // 当客户端请求读取此资源时执行的函数 async handler() { const now new Date().toISOString(); const platform process.platform; const nodeVersion process.version; // 返回资源的内容通常是文本或JSON return { contents: [{ // MCP协议中内容可以是text, image, blob等类型 type: “text” as const, // 实际返回的文本内容 text: System Status Report\n Generated at: ${now}\n Platform: ${platform}\n Node.js Version: ${nodeVersion}\n ---\n All systems operational. }] }; } };关键点解析uri这是资源的地址遵循URI格式。你可以自定义命名空间如resource://my-server/确保其唯一性即可。handler这是一个异步函数在这里执行生成资源内容的逻辑。你可以在这里连接数据库、读取文件、调用API最后返回结构化的内容。contents返回的是一个数组允许包含多个内容块。这里我们只返回一个text类型的块。3.3 定义你的第一个工具计算阶乘工具允许AI执行一个动作。我们创建一个计算阶乘的简单工具。在src/tools/目录下创建新文件calculate-factorial.ts// src/tools/calculate-factorial.ts import { Tool } from “modelcontextprotocol/sdk/server”; // 导入类型 // 定义工具的参数模式使用JSON Schema const factorialArgsSchema { type: “object”, properties: { number: { type: “number”, description: “The non-negative integer to calculate the factorial for.”, minimum: 0, maximum: 100 // 防止数字过大导致计算时间过长或溢出 } }, required: [“number”], additionalProperties: false } as const; // 2. 定义工具 export const calculateFactorialTool: Tool { // 工具的唯一名称用于在工具列表中标识 name: “calculate_factorial”, // 工具的描述AI根据这个决定是否以及如何调用它 description: “Calculate the factorial (n!) of a given non-negative integer.”, // 工具的输入参数模式 inputSchema: factorialArgsSchema, // 当客户端调用此工具时执行的函数 async handler(args: { number: number }) { const n args.number; // 输入验证虽然JSON Schema已有基础验证这里可以加业务逻辑验证 if (!Number.isInteger(n) || n 0) { throw new Error(Input must be a non-negative integer. Received: ${n}); } // 计算阶乘 let result 1n; // 使用BigInt处理大数 for (let i 2n; i BigInt(n); i) { result * i; } // 返回工具执行结果 return { content: [{ type: “text” as const, text: The factorial of ${n} is: ${result.toString()} }] }; } };关键点解析inputSchema这是重中之重。它使用JSON Schema精确描述了AI调用此工具时需要提供的参数。清晰的Schema能极大提升AI调用的准确率。务必详细定义type,description,required等字段。handler接收args参数其结构由inputSchema定义。在这里执行核心业务逻辑。返回格式与资源类似返回包含content数组的对象。注意工具调用可以返回文本、图像甚至触发副作用如发送邮件。3.4 集成与启动服务器现在我们需要把新定义的资源和工具“注册”到主服务器中。打开src/server.ts或主入口文件通常你会看到类似以下的模式// src/server.ts (示例根据你的模板调整) import { Server } from “modelcontextprotocol/sdk/server”; // 导入SDK Server类 import { StdioServerTransport } from “modelcontextprotocol/sdk/server/stdio”; // 导入stdio传输方式 // 导入我们刚刚创建的资源 import { systemStatusResource } from “./resources/system-status”; // 导入我们刚刚创建的工具 import { calculateFactorialTool } from “./tools/calculate-factorial”; // 1. 创建MCP Server实例 const server new Server( { name: “my-system-info-server”, // 你的服务器名称 version: “0.1.0”, }, { // 服务器能力声明 capabilities: { resources: {}, // 启用资源功能 tools: {}, // 启用工具功能 }, } ); // 2. 注册资源 // 注意模板可能提供了更优雅的批量注册方式这里展示基础方法 server.setRequestHandler(“resources/list”, async () { return { resources: [{ uri: systemStatusResource.uri, name: systemStatusResource.name, description: systemStatusResource.description, // 可能还有 mimeType 等其他属性 }] }; }); server.setRequestHandler(resources/read, async (request) { if (request.params.uri systemStatusResource.uri) { return await systemStatusResource.handler(); } throw new Error(Resource not found: ${request.params.uri}); }); // 3. 注册工具 server.setRequestHandler(“tools/list”, async () { return { tools: [{ name: calculateFactorialTool.name, description: calculateFactorialTool.description, inputSchema: calculateFactorialTool.inputSchema, }] }; }); server.setRequestHandler(“tools/call”, async (request) { if (request.params.name calculateFactorialTool.name) { return await calculateFactorialTool.handler(request.params.arguments as any); } throw new Error(Tool not found: ${request.params.name}); }); // 4. 启动服务器使用stdio传输这是与AI客户端集成的常见方式 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(“MCP Server running on stdio”); // 使用stderr输出日志避免污染stdout协议流 } main().catch((error) { console.error(“Server error:”, error); process.exit(1); });实操心得在实际模板中注册过程可能被封装成更简洁的辅助函数比如server.registerResource(systemStatusResource)和server.registerTool(calculateFactorialTool)。请务必以你克隆的模板代码为准。核心思想是在对应的请求处理器resources/list,tools/list中返回你定义的资源/工具列表在read和call处理器中根据URI或名称路由到具体的处理函数。4. 测试与调试让你的MCP Server真正跑起来开发完成后不能只等AI来调用我们需要先进行本地测试。4.1 使用MCP Inspector进行手动测试最官方的测试工具是MCP Inspector。它是一个命令行工具可以连接并交互式地测试你的MCP Server。# 全局安装MCP Inspector npm install -g modelcontextprotocol/inspector # 在你的项目目录下启动Inspector并连接你的服务器 # 假设你的服务器启动命令是 npm start它会通过stdio通信 npx modelcontextprotocol/inspector npm startInspector会启动一个本地Web界面通常在http://localhost:5173。打开浏览器你将能看到一个界面里面列出了你的服务器宣告的所有资源和工具。你可以点击资源查看其返回的内容。点击工具输入参数并执行查看返回结果。 这是验证你的服务器行为是否符合预期的最直接方法。4.2 集成到AI客户端以Claude Desktop为例真正的考验是与AI客户端集成。以Claude Desktop为例找到配置文件Claude Desktop的MCP配置通常位于macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件在mcpServers对象中添加你的服务器配置。{ “mcpServers”: { “my-system-info-server”: { “command”: “node”, “args”: [ “/ABSOLUTE/PATH/TO/YOUR/PROJECT/dist/server.js” // 指向你编译后的JS入口文件 ], “env”: { “NODE_ENV”: “production” } } } }关键点args必须使用绝对路径。对于TypeScript项目你需要先运行npm run build编译成JS。重启Claude Desktop保存配置文件并完全重启Claude Desktop应用。测试对话新建一个对话你可以尝试输入“请读取一下系统状态报告” 或 “帮我计算一下15的阶乘”。Claude应该能识别并调用你服务器提供的资源和工具。4.3 常见问题与排查技巧实录即使按照步骤操作也难免会遇到问题。下面是一些我踩过的坑和解决方案问题现象可能原因排查步骤与解决方案Inspector连接失败或提示协议错误1. 服务器未正确启动。2. 服务器输出的首条消息不是有效的MCP初始化消息。3. 传输方式不匹配。1. 单独运行服务器命令npm start看是否有立即报错。2. 检查服务器入口文件确保第一时间调用server.connect(transport)且没有提前console.log污染stdio流。3. 确认Inspector和服务器使用相同的传输方式都是stdio。Claude Desktop无法识别工具/资源1. 配置文件路径错误。2. 服务器启动失败或崩溃。3.tools/list或resources/list返回格式错误。1. 检查配置文件JSON格式特别是路径中的斜杠和绝对路径。2. 查看Claude Desktop的日志文件位置因系统而异通常会有MCP服务器加载失败的详细错误。3. 使用Inspector测试确保/tools/list和/resources/list端点返回正确的数据结构。AI调用了工具但参数总是传错inputSchema定义不够清晰或完整。1. 在inputSchema中为每个参数提供详细的description。2. 使用enum限定可选值使用minimum/maximum限定数字范围。3. 在工具的description字段中用自然语言再次说明工具的用途和参数要求。服务器运行一段时间后崩溃未处理异步操作中的异常。在所有的async handler函数内部使用try...catch包裹核心逻辑并返回格式化的错误信息而不是让异常直接抛出导致进程崩溃。工具执行速度慢影响AI响应工具执行了耗时操作如网络请求、复杂计算。1. 对于耗时操作考虑在工具描述中注明。2. 如果可能实现异步非阻塞操作或提供进度反馈如果协议支持。3. 在资源中预处理一些信息避免工具调用时重复计算。一个重要的调试技巧在开发初期可以在服务器代码中添加详细的日志输出到console.error然后在通过Inspector或Claude调用时观察这些日志输出。这能帮你精准定位问题发生在哪个环节。5. 进阶实践构建更实用的MCP Server掌握了基础之后我们可以利用这个模板构建更贴近真实场景的工具。5.1 连接外部API天气查询工具假设我们想提供一个查询城市天气的工具。我们需要调用一个公开的天气API如OpenWeatherMap。安装HTTP客户端npm install axios定义工具(src/tools/weather.ts)import { Tool } from “modelcontextprotocol/sdk/server”; import axios from “axios”; const argsSchema { type: “object”, properties: { city: { type: “string”, description: “The name of the city to get weather for, e.g., ‘London’ or ‘New York’.” }, countryCode: { type: “string”, description: “Optional two-letter country code (ISO 3166-1 alpha-2) to disambiguate cities, e.g., ‘US’ for New York, US.” } }, required: [“city”], additionalProperties: false } as const; export const weatherTool: Tool { name: “get_weather”, description: “Get the current weather conditions for a specified city.”, inputSchema: argsSchema, async handler(args: { city: string; countryCode?: string }) { // 从环境变量获取API密钥避免硬编码 const apiKey process.env.OPENWEATHER_API_KEY; if (!apiKey) { throw new Error(“OpenWeatherMap API key is not configured.”); } let query args.city; if (args.countryCode) { query ,${args.countryCode}; } try { const response await axios.get( https://api.openweathermap.org/data/2.5/weather, { params: { q: query, appid: apiKey, units: “metric”, // 使用摄氏度 lang: “zh_cn” // 返回中文描述 }, timeout: 5000 // 设置超时 } ); const data response.data; const weather data.weather[0]; const main data.main; return { content: [{ type: “text”, text: 城市${data.name}\n 天气${weather.description}\n 温度${main.temp}°C (体感 ${main.feels_like}°C)\n 湿度${main.humidity}%\n 气压${main.pressure} hPa\n 风速${data.wind.speed} m/s }] }; } catch (error: any) { // 处理API错误给出友好提示 if (error.response) { throw new Error(天气API请求失败: ${error.response.data.message || error.response.status}); } else if (error.request) { throw new Error(“无法连接到天气服务请检查网络。”); } else { throw new Error(查询配置错误: ${error.message}); } } } };配置环境变量在项目根目录创建.env文件添加OPENWEATHER_API_KEYyour_api_key_here。并在代码中通过dotenv包加载需安装npm install dotenv并在入口文件顶部import ‘dotenv/config’。注册工具将weatherTool导入并注册到主服务器。这个例子展示了如何安全地集成外部API使用环境变量管理密钥、处理网络请求和错误以及格式化返回给AI的信息。5.2 实现有状态资源实时日志尾随资源不一定是静态的。我们可以创建一个“实时日志”资源每次读取都返回文件最新的若干行。// src/resources/tail-log.ts import fs from ‘fs/promises’; import path from ‘path’; import { ResourceTemplate } from “modelcontextprotocol/sdk/server”; const LOG_FILE_PATH path.resolve(process.cwd(), ‘app.log’); export const tailLogResource: ResourceTemplate { uri: “resource://my-server/tail-app-log”, name: “Application Log Tail”, description: “The last 50 lines of the application log file.”, async handler() { try { const content await fs.readFile(LOG_FILE_PATH, ‘utf-8’); const lines content.split(‘\n’); const lastLines lines.slice(-50).join(‘\n’); // 获取最后50行 return { contents: [{ type: “text”, text: Tail of ${LOG_FILE_PATH} \n${lastLines} }] }; } catch (error: any) { if (error.code ‘ENOENT’) { return { contents: [{ type: “text”, text: Log file not found at: ${LOG_FILE_PATH} }] }; } throw error; // 重新抛出其他错误 } } };这个资源每次被读取时都会去读一次文件实现了“准实时”的查看效果。你可以扩展它比如增加一个lines查询参数让AI可以指定要查看的行数。6. 性能优化与安全考量当你的MCP Server开始提供更多功能时就需要考虑一些工程化问题。6.1 性能优化要点连接池与缓存如果工具需要频繁访问数据库或外部API考虑在服务器生命周期内创建连接池或缓存层避免每次调用都建立新连接。异步与非阻塞确保所有handler函数都是异步的并且内部执行的是非阻塞I/O操作。避免在handler中进行CPU密集型计算如果不可避免考虑使用工作线程或任务队列。资源列表的静态化如果资源列表是固定的不要在每次resources/list请求时都动态生成。可以在服务器启动时计算好并缓存。精简响应内容AI上下文有限返回给资源read和工具call的结果应尽可能简洁、信息密集。避免返回冗长的JSON或无关细节。6.2 安全最佳实践输入验证再次强调永远不要信任来自客户端的输入。即使在inputSchema中定义了类型在handler内部也要进行业务逻辑层面的验证如权限检查、范围校验。环境变量管理所有密钥、令牌、数据库连接字符串等敏感信息必须通过环境变量传入绝不可硬编码在源码中。错误处理工具或资源处理函数抛出的错误会被传递回AI。确保错误信息对AI有用例如“城市未找到”但不要泄露内部堆栈信息或敏感系统详情。权限最小化MCP Server进程应该以最低必要的系统权限运行。特别是当工具能执行文件操作或系统命令时。速率限制考虑对工具的调用频率做限制防止被滥用。可以在工具handler中实现简单的计数器或者使用更专业的中间件。使用adamwulf/mcp-template这类模板就像获得了一辆组装好的赛车底盘发动机、变速箱、悬挂这些基础且复杂的部分已经就位。你的工作就是专注于设计和制造那个最能体现你创意的车身和动力调校——也就是你的业务逻辑。它通过规范化的结构、处理底层通信的复杂性让你能快速将想法转化为AI可用的实际能力。无论是用于个人效率提升还是构建团队内部的AI助手基础设施掌握MCP服务端开发都是一个越来越有价值的技能。从这个模板开始无疑是上手最快的方式。