企业官网建设流程全解析

1. 项目概述：一个为AI应用构建MCP服务器的现代模板

如果你正在为大型语言模型（LLM）应用，比如基于Claude、GPTs或Cursor等工具，开发一个自定义的“工具箱”，那么你很可能已经接触过模型上下文协议（Model Context Protocol， MCP）。简单来说，MCP就像一套标准化的“插件接口”，它允许你的AI助手安全、可控地访问外部工具、数据源和API，比如查询数据库、读取文件、调用天气服务等。而phughesmcr/deno-mcp-template这个项目，就是一个专门为使用Deno运行时来快速构建这类MCP服务器而设计的现代化脚手架。

我最初接触MCP时，是从零开始搭建环境、配置协议、处理类型定义，过程相当繁琐。直到发现了这个模板，它把构建MCP服务器的核心流程标准化、模块化了，让你能跳过大量重复的基建工作，直接聚焦在实现你的业务逻辑上。它基于Deno，这是一个由Node.js原班人马打造的、更安全、更现代的JavaScript/TypeScript运行时，天生支持TypeScript和ES模块，无需复杂的构建配置，特别适合快速开发和部署轻量级服务。

这个模板的核心价值在于，它为你预设了一个结构清晰、类型安全、开箱即用的MCP服务器项目骨架。你只需要关心两件事：定义你的工具（Tools）和配置你的资源（Resources），剩下的协议通信、错误处理、生命周期管理，模板都帮你搞定了。无论是想为团队内部构建一个连接私有数据库的AI助手，还是开发一个面向公众的、能操作特定SaaS平台的AI插件，这个模板都能让你在几分钟内就搭起一个可运行的原型。

2. 核心架构与设计思路拆解

2.1 为什么选择Deno作为MCP服务器的运行时？

在决定使用这个模板之前，理解其技术选型背后的逻辑至关重要。MCP服务器本质上是一个提供标准化JSON-RPC接口的HTTP或stdio服务。为什么模板作者phughesmcr选择了Deno，而不是更常见的Node.js或Python？

首先，安全性是首要考量。Deno默认是安全的，脚本无法访问文件系统、网络或环境变量，除非显式通过命令行标志（如--allow-read，--allow-net）授权。这对于MCP服务器来说是天作之合。MCP的核心原则之一就是“最小权限访问”，服务器只能访问用户明确授权的资源。Deno的权限模型与这一理念完美契合，你可以在启动命令中精确控制服务器能做什么，从根源上减少了安全风险。

其次，开发体验的极致简化。Deno内置了TypeScript编译器、测试运行器、代码格式化工具（deno fmt）和代码检查工具（deno lint）。这意味着你不需要分别配置tsc、jest、prettier和eslint。对于MCP开发这种强类型交互的场景，TypeScript的支持是刚需，而Deno让其变得无比自然。此外，Deno使用URL导入模块，直接引用远程ES模块，告别了package.json和node_modules，依赖管理清晰无比。

最后，性能与现代化标准。Deno构建在V8引擎和Rust之上，性能优异。它原生支持顶层的await、Web标准API（如fetch），并且其标准库（std）非常实用。对于MCP服务器这种通常I/O密集（网络请求、文件读写）而非CPU密集的应用，Deno的异步处理和网络库表现非常出色。

注意：如果你和你的团队已经深度绑定Node.js生态，切换至Deno可能需要一个学习适应期。但就MCP服务器这种相对独立、边界清晰的项目而言，Deno带来的安全性和开发效率提升是非常值得的。

2.2 MCP模板的核心目录结构解析

克隆phughesmcr/deno-mcp-template项目后，你会看到一个非常清晰且克制的目录结构。这不仅仅是文件摆放，更体现了作者对MCP服务器职责的深刻理解。

deno-mcp-template/ ├── src/ │ ├── main.ts # 服务器入口，MCP服务器实例的创建与配置中心 │ ├── tools/ # 工具（Tools）实现目录 │ │ └── example.ts # 示例工具，演示如何定义一个工具 │ ├── resources/ # 资源（Resources）实现目录（可选） │ │ └── example.ts # 示例资源，演示如何定义一个资源 │ └── types.ts # 项目用到的共享TypeScript类型定义 ├── deno.json # Deno项目配置文件，替代package.json ├── deno.lock # 依赖锁文件，确保环境一致性 ├── .gitignore └── README.md

• src/main.ts：这是整个服务器的心脏。在这里，你创建Server实例，并通过use()方法将你在tools/和resources/目录下定义的功能“挂载”到服务器上。它还负责处理服务器的启动逻辑（监听stdio或HTTP）。
• src/tools/：这是你大展拳脚的地方。MCP中的“工具”指的是AI可以调用的函数，例如“获取天气”、“创建待办事项”、“查询用户信息”。每个工具都是一个独立的模块，需要明确其输入参数（inputSchema）和具体的执行函数（execute）。模板中的example.ts提供了一个完整的范本。
• src/resources/：资源代表了AI可以读取的“数据源”，比如一个文本文件、一个网页的URL、或者数据库中的一张表。资源通过URI标识，服务器可以声明它提供了哪些资源，并在AI请求时返回其内容。如果你的MCP服务器不需要提供只读数据源，这个目录可以忽略。
• deno.json：这是Deno项目的神经中枢。它定义了脚本入口、导入映射、任务（tasks）、编译选项和依赖。模板中预配置了dev和start等命令，让你通过deno task dev就能启动开发服务器。

这种结构强制实现了关注点分离：工具逻辑、资源逻辑、服务器配置各司其职，使得代码易于维护、测试和扩展。当你需要新增一个功能时，只需在tools/下新建一个*.ts文件，然后在main.ts中引入并注册即可。

2.3 模板的“开箱即用”特性与预设配置

这个模板不仅仅是空目录，它包含了让一个基础MCP服务器立刻跑起来的所有必要代码和配置。

首先看deno.json，它预置了几个关键配置：

{ "tasks": { "dev": "deno run --watch --allow-read --allow-env src/main.ts", "start": "deno run --allow-read --allow-env src/main.ts" }, "imports": { "@modelcontextprotocol/sdk": "jsr:@modelcontextprotocol/sdk@^0.6.0" } }

dev任务在开发时使用，--watch标志支持文件热重载，修改代码后服务器会自动重启，极大提升开发效率。start用于生产环境运行。权限方面，默认只开启了--allow-read（用于可能读取本地文件资源）和--allow-env（用于读取环境变量，如API密钥），这体现了最小权限原则。

其次，src/main.ts中已经搭建好了服务器骨架：

import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; // 导入工具 import { fetchWeatherTool } from "./tools/example.js"; const server = new Server( { name: "my-mcp-server", version: "0.1.0" }, { capabilities: { tools: {}, resources: {} } } ); // 注册工具 server.setRequestHandler(工具列表请求， () => [fetchWeatherTool]); server.setRequestHandler(工具调用请求， async (request) => { if (request.params.name === fetchWeatherTool.name) { // 调用工具执行函数 return await fetchWeatherTool.execute(request.params.arguments); } throw new Error(`未知工具: ${request.params.name}`); }); // 启动服务器（stdio模式，这是与AI桌面客户端通信的典型方式） const transport = new StdioServerTransport(); await server.connect(transport);

这段代码创建了服务器，声明了能力，注册了工具处理器，并建立了stdio传输层。你几乎不需要修改这部分，只需专注于导入和注册更多工具。

最后，src/tools/example.ts提供了一个详尽的工具定义示例，包括如何使用zod库定义严格的输入参数模式（schema），如何在execute函数中实现业务逻辑，以及如何返回结构化的结果。这为你编写自己的工具提供了完美的参考。

3. 从零开始：使用模板构建你的第一个MCP工具

3.1 环境准备与项目初始化

假设你已经安装了Deno（可以通过官方脚本curl -fsSL https://deno.land/install.sh | sh一键安装），现在开始创建你的第一个MCP服务器。

第一步，从GitHub克隆模板仓库：

deno run -A jsr:@gb/gh@latest clone phughesmcr/deno-mcp-template my-weather-assistant cd my-weather-assistant

这里使用了Deno的gh工具来克隆仓库。-A标志授予了所有权限，因为克隆操作需要网络和文件系统权限。当然，你也可以直接使用git clone命令。

第二步，进入项目目录，立即尝试运行示例服务器，验证一切正常：

deno task dev

如果看到类似“Server running on stdio”或没有报错静静等待连接的状态，说明模板服务器已经成功启动。此时，你可以用任何实现了MCP客户端协议的AI应用（如Claude Desktop， 并正确配置了MCP服务器设置）来连接它，理论上就能调用示例中的“获取天气”工具了。

实操心得：在开发初期，我建议使用一个简单的测试脚本来验证你的MCP服务器，而不是每次都启动完整的AI客户端。你可以编写一个模拟客户端，通过stdio或HTTP向你的服务器发送标准的JSON-RPC请求，并打印响应。这能极大提升调试效率。模板的README里有时会提供这样的测试脚本，如果没有，可以基于MCP SDK的Client类自己写一个。

3.2 剖析与改造一个示例工具

让我们深入看看src/tools/example.ts，理解一个MCP工具是如何构成的。

import { z } from "https://deno.land/x/zod@v3.22.4/mod.ts"; import { Tool } from "@modelcontextprotocol/sdk/server/index.js"; // 1. 定义输入参数的模式（Schema） const WeatherArgsSchema = z.object({ location: z.string().describe("城市名称，例如：Beijing, London"), unit: z.enum(["celsius", "fahrenheit"]).default("celsius").describe("温度单位"), }); // 2. 定义工具本身 export const fetchWeatherTool: Tool = { name: "fetch_weather", description: "获取指定城市的当前天气情况", inputSchema: { type: "object", properties: WeatherArgsSchema.shape, }, // 3. 实现执行函数 async execute(args: z.infer<typeof WeatherArgsSchema>) { const { location, unit } = args; // 模拟API调用 await new Promise(resolve => setTimeout(resolve, 100)); // 模拟网络延迟 const temp = unit === "celsius" ? 22 : 72; return { content: [ { type: "text", text: `当前${location}的天气晴朗，气温${temp}度（${unit}）。`, }, ], }; }, };

这个示例工具清晰地展示了三个部分：

1. 参数验证（使用Zod）：WeatherArgsSchema使用Zod库定义了工具需要的参数location（字符串）和unit（枚举，默认摄氏）。Zod不仅能做运行时验证，其.describe()方法生成的描述还会被AI客户端用来理解参数含义，这对生成正确的调用参数至关重要。
2. 工具元数据：name是工具的全局唯一标识符；description告诉AI这个工具是做什么的，AI会据此决定何时调用它；inputSchema将Zod模式转换为JSON Schema，这是MCP协议要求的格式。
3. 业务逻辑（execute）：这是工具的核心。它接收验证后的参数，执行实际操作（这里模拟了网络请求），并返回一个固定格式的结果。结果中的content数组可以包含文本、图像等多种类型。

现在，我们来将其改造成一个真实的工具，比如调用一个免费的天气API（例如Open-Meteo）。

首先，我们需要更新deno.json，添加我们需要的依赖（比如用于HTTP请求的std/http，但Deno内置的fetch通常就够了）和可能的环境变量。

{ "tasks": { "dev": "deno run --watch --allow-read --allow-env --allow-net src/main.ts", "start": "deno run --allow-read --allow-env --allow-net src/main.ts" }, "imports": { "@modelcontextprotocol/sdk": "jsr:@modelcontextprotocol/sdk@^0.6.0", "zod": "https://deno.land/x/zod@v3.22.4/mod.ts" } }

注意，我们在dev和start任务中增加了--allow-net权限，因为我们的工具需要访问外部天气API。

接着，修改src/tools/example.ts（或新建一个src/tools/weather.ts）：

import { z } from "zod"; import { Tool } from "@modelcontextprotocol/sdk/server/index.js"; const WeatherArgsSchema = z.object({ location: z.string().describe("城市名称，例如：Beijing, London"), }); export const fetchRealWeatherTool: Tool = { name: "fetch_real_weather", description: "获取指定城市的实时天气和未来两日预报", inputSchema: { type: "object", properties: WeatherArgsSchema.shape, }, async execute(args: z.infer<typeof WeatherArgsSchema>) { const { location } = args; // 在实际项目中，这里应该有一个从城市名到经纬度的地理编码服务。 // 为了简化，我们使用一个固定的坐标（例如伦敦）或一个简单的映射。 // 这里假设location是“London”。 const latitude = 51.5074; const longitude = -0.1278; try { const response = await fetch( `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current_weather=true&hourly=temperature_2m&timezone=auto` ); if (!response.ok) { throw new Error(`天气API请求失败: ${response.status}`); } const data = await response.json(); const currentTemp = data.current_weather.temperature; const weatherCode = data.current_weather.weathercode; // 可以根据weatherCode映射为中文描述，这里简化处理 const weatherDesc = getWeatherDescription(weatherCode); return { content: [ { type: "text", text: `当前${location}的天气情况：${weatherDesc}，气温${currentTemp}°C。`, }, { type: "text", text: `未来几小时温度趋势：${data.hourly.temperature_2m.slice(0, 6).join(‘， ‘)}°C`, }, ], }; } catch (error) { // 良好的错误处理对于AI理解至关重要 return { content: [ { type: "text", text: `获取${location}天气信息时出错：${error.message}。请检查城市名称或稍后重试。`, }, ], isError: true, // MCP协议中表示这是一个错误结果 }; } }, }; // 简单的天气代码映射函数 function getWeatherDescription(code: number): string { const map: Record<number, string> = { 0: “晴朗”， 1: “大部晴朗”， 2: “局部多云”， 3: “多云”， 45: “雾”， 48: “冻雾”， 51: “小雨”， 61: “雨”， 80: “阵雨”， }; return map[code] || `天气代码${code}`; }

最后，别忘了在src/main.ts中导入并注册这个新工具：

// ... 其他导入 import { fetchRealWeatherTool } from “./tools/weather.js”; // 假设文件名为weather.ts // ... 在server.setRequestHandler中注册 server.setRequestHandler(工具列表请求， () => [fetchRealWeatherTool /*, 其他工具... */]); server.setRequestHandler(工具调用请求， async (request) => { if (request.params.name === fetchRealWeatherTool.name) { return await fetchRealWeatherTool.execute(request.params.arguments); } // ... 其他工具判断 });

3.3 定义与提供资源（Resources）

除了工具，MCP服务器还可以提供“资源”。资源是只读的、可通过URI寻址的数据片段。例如，你的服务器可以声明它提供了file:///etc/hosts这个资源，当AI需要读取该文件内容时，就会向你的服务器发起请求。

在模板的src/resources/example.ts中，有一个简单的示例：

import { Resource } from “@modelcontextprotocol/sdk/server/index.js”; export const exampleResource: Resource = { uri: “example://greeting”, name: “示例问候资源”， description: “一个简单的静态文本资源”， mimeType: “text/plain”， // 当AI请求该资源时，调用此函数获取内容 async getContent() { return { contents: [ { uri: “example://greeting”， mimeType: “text/plain”， text: “你好，世界！这是一个来自MCP服务器的资源。”， }, ], }; }, };

在main.ts中，你需要通过server.setRequestHandler为resources/list和resources/read请求注册处理器，将你的资源列表和读取逻辑关联上去。

资源的典型应用场景包括：

• 提供静态文档：如项目README、API文档。
• 聚合动态数据：如从内部仪表盘拉取数据，生成一个汇总报告资源。
• 文件系统代理：在用户授权下，将本地特定目录的文件以资源形式暴露给AI（需谨慎处理权限！）。

注意事项：资源URI的设计应有清晰的命名空间，避免冲突。例如，使用your-server://作为前缀。同时，getContent函数应做好错误处理，对于不存在的资源或访问错误，返回合适的错误信息。

4. 开发、调试与部署全流程指南

4.1 高效的本地开发与调试技巧

使用deno task dev启动开发服务器后，它会在stdio上等待连接。但如何调试呢？这里有几个实用技巧：

1. 使用MCP Inspector进行可视化调试：Anthropic官方提供了一个强大的调试工具叫MCP Inspector。你可以通过npm全局安装：npm install -g @modelcontextprotocol/inspector。然后，在一个终端运行你的MCP服务器（deno task start），在另一个终端运行：mcp-inspector —-transport stdio “deno task start”。Inspector会启动一个本地Web界面，你可以在这里手动发送tools/list，tools/call等请求，并直观地查看请求和响应，这对于调试工具逻辑和协议交互无比方便。

2. 集成到Claude Desktop进行端到端测试：这是最终的测试环境。编辑Claude Desktop的配置文件（通常在~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS），添加你的服务器配置：

{ “mcpServers”: { “my-weather-server”: { “command”: “deno”， “args”: [ “run”， “--allow-read”， “--allow-env”， “--allow-net”， “/ABSOLUTE/PATH/TO/YOUR/PROJECT/src/main.ts” ], “env”: { “OPEN_METEO_API_KEY”: “your_key_here” // 如果需要 } } } }

重启Claude Desktop后，你就可以在对话中直接使用你的工具了。这是验证工具描述是否清晰、AI调用是否准确的最佳方式。

3. 编写单元测试：Deno内置了测试框架。为你的工具execute函数编写单元测试可以确保核心逻辑的稳定性。例如，为fetchRealWeatherTool编写一个测试，模拟fetch请求返回固定数据，验证函数是否能正确解析并返回预期格式的内容。使用Deno.test和assert或expect风格的断言库即可。

4.2 生产环境部署与配置管理

开发完成后，你需要将MCP服务器部署到一个稳定运行的环境中。部署方式取决于你的使用场景：

场景一：个人或小团队使用，与Claude Desktop集成这是最简单的情况。你只需要将最终代码打包（其实Deno项目本身就是“打包”好的），确保目标机器安装了相同版本的Deno。然后，像上面调试那样，在每个人的Claude Desktop配置中指向部署好的脚本路径（可以是网络路径或本地路径）。你可以将项目编译成一个可执行的单文件（使用deno compile）来简化分发。

场景二：作为公共服务，供多个AI客户端通过HTTP连接MCP也支持HTTP/SSE传输。你需要修改src/main.ts中的启动部分，使用new HTTPServerTransport创建一个HTTP服务器。然后，将服务部署到任何云平台（如Deno Deploy， Fly.io， Railway）或你自己的服务器上。客户端配置中，command字段将变为一个URL。

关键的生产环境考量：

1. 权限最小化：在deno task start命令中，只开启必要的权限。例如，如果工具只需要网络访问，就不要开--allow-read。
2. 环境变量管理：API密钥、数据库连接字符串等敏感信息必须通过环境变量传入。在deno.json的start任务中，它们已经通过--allow-env允许读取。在生产环境，使用平台提供的Secret管理工具或.env文件（配合dotenv库）来管理。
3. 日志与监控：在服务器代码中添加日志记录，记录工具调用、错误等信息。Deno标准库提供了log模块。对于更复杂的监控，可以考虑集成像Opentelemetry这样的遥测库。
4. 错误处理与用户体验：确保所有可能的错误（网络超时、API限流、无效输入）都在工具execute函数中被捕获，并返回对AI友好的错误信息。避免将内部堆栈跟踪泄露给客户端。
5. 版本管理：当你的工具更新时，考虑在服务器信息中更新版本号。这有助于客户端进行兼容性管理。

4.3 性能优化与安全加固建议

随着工具数量的增加，一些优化和安全措施变得必要。

性能优化：

• 连接池与缓存：如果你的工具需要频繁访问数据库或外部API，考虑在服务器生命周期内创建连接池，而不是每次调用都新建连接。对于不经常变化的数据，可以实现一个简单的内存缓存（注意缓存失效策略）。
• 异步初始化：如果某些工具需要加载大型模型或配置文件，可以在服务器启动时进行异步初始化，并将初始化结果保存在闭包中供execute函数使用，避免每次调用都重复加载。
• 精简依赖：定期检查deno.json中的imports，移除未使用的依赖。Deno的依赖是远程URL，清晰的依赖树有助于快速启动。

安全加固：

• 输入验证（再次强调）：Zod是你的第一道防线。严格定义输入模式，拒绝任何不符合预期的参数。对于字符串参数，注意防范注入攻击（如SQL注入、命令注入），即使AI生成的内容通常可信，也要做无害化处理。
• 权限细分：如果可能，不要使用-A（所有权限）。仔细评估每个工具需要的权限，并为不同的工具集配置不同的Deno运行权限（这可能需要更复杂的架构，如将高权限工具分离到独立进程中）。
• 速率限制：如果你的服务器公开暴露，应考虑对客户端IP或会话实施速率限制，防止滥用。可以使用中间件或装饰器模式在调用工具前进行限流检查。
• 审计日志：记录所有工具的调用记录，包括调用者（如果协议支持）、工具名、参数（注意脱敏敏感参数）和时间戳。这对于故障排查和安全审计至关重要。

5. 进阶应用与生态集成

5.1 构建复杂工具链与工具组合

一个强大的MCP服务器往往不止提供一个工具，而是提供一组相互关联的工具，形成一个“工具链”。例如，一个“客户支持助手”MCP服务器可能包含以下工具：

• search_knowledge_base: 根据用户问题搜索内部知识库。
• create_support_ticket: 在工单系统中创建新的支持工单。
• get_customer_info: 根据客户ID查询客户基本信息。
• escalate_to_engineer: 将复杂问题升级分配给工程师。

这些工具可以组合使用。AI可能会先调用search_knowledge_base，如果没找到答案，再调用get_customer_info确认客户详情，最后调用create_support_ticket。你的MCP服务器内部，这些工具可以共享一些状态或客户端（比如同一个数据库连接池、同一个认证后的API客户端实例）。你可以在src/main.ts中初始化这些共享资源，然后通过闭包或依赖注入的方式传递给各个工具的execute函数。

5.2 与现有后端服务及数据库集成

大多数有意义的MCP工具都需要与现有系统交互。模板项目可以轻松集成各种后端服务。

集成数据库：假设使用PostgreSQL，你可以使用Deno的PostgreSQL客户端，如postgres。首先在deno.json中导入它，然后在main.ts中初始化连接池：

import postgres from “jsr:@db/postgres”; const pool = new postgres.Pool({ connectionString: Deno.env.get(“DATABASE_URL”), }, 10); // 连接池大小

然后，在工具的execute函数中，从连接池获取客户端并执行查询。务必做好SQL参数化查询，防止注入。

调用内部REST API：使用Deno内置的fetch即可。建议将API基础URL和认证头（如API Key）配置在环境变量中。可以为所有需要调用该API的工具创建一个共享的、配置好的fetch函数封装，处理通用的错误重试和认证逻辑。

使用第三方SDK：许多SaaS服务提供了TypeScript/JavaScript SDK。你可以通过JSR或直接URL将它们导入到你的项目中。例如，集成GitHub API可以使用octokit，集成Slack可以使用@slack/web-api。确保遵循这些SDK的认证和初始化要求。

5.3 扩展模板：添加中间件与自定义传输层

模板提供了基础框架，但你完全可以扩展它以满足更复杂的需求。

添加中间件（Middleware）：MCP SDK的Server类本身可能不直接支持中间件模式，但你可以通过高阶函数或包装execute函数来实现类似功能。例如，创建一个“日志中间件”：

function withLogging(tool: Tool): Tool { return { …tool, async execute(args: any) { console.log(`[${new Date().toISOString()}] 调用工具: ${tool.name}， 参数:`, args); const start = Date.now(); try { const result = await tool.execute(args); console.log(`[${new Date().toISOString()}] 工具 ${tool.name} 调用成功，耗时: ${Date.now() - start}ms`); return result; } catch (error) { console.error(`[${new Date().toISOString()}] 工具 ${tool.name} 调用失败:`, error); throw error; } }, }; } // 使用时 const loggedTool = withLogging(fetchRealWeatherTool);

你可以类似地创建认证中间件、参数转换中间件等。

自定义传输层：模板默认使用StdioServerTransport，这是与桌面客户端通信的标准方式。如果你需要支持WebSocket、自定义TCP协议或其他通信方式，你可以实现MCP SDK中定义的Transport接口。这通常用于将MCP服务器嵌入到其他应用程序中，或者实现更复杂的通信场景。

6. 常见问题排查与实战心得

6.1 开发与运行中的典型错误及解决

在开发和运行基于此模板的MCP服务器时，你可能会遇到一些典型问题。下面是一个快速排查指南：

6.2 从项目实践中萃取的独家心得

经过多个项目的打磨，我总结出一些在官方文档和模板中不会明确提及，但却能极大提升开发体验和项目质量的技巧。

心得一：工具命名与描述的“艺术”工具name和description是AI理解和使用它的唯一依据。命名要清晰、具体、动词开头，最好能反映其核心操作和领域，例如用create_jira_issue而非jira。描述要详尽，不仅说明功能，最好能举例说明典型使用场景和输入输出。例如：“在Jira项目中创建一个新的问题（Issue）。需要提供项目键、问题类型、摘要和描述。可选参数包括优先级、经办人等。成功时返回新创建问题的键（如PROJ-123）和链接。” 这样的描述能极大提高AI调用的准确性。

心得二：利用Zod的.describe()和.default()Zod不仅用于验证，更是与AI沟通的桥梁。为每个参数使用.describe()提供人类可读的描述，AI会利用这些信息来生成调用参数。合理使用.default()设置智能默认值，可以简化AI需要提供的参数数量，提升交互流畅度。例如，一个send_email工具，可以将cc参数默认设置为空数组[]。

心得三：设计“原子化”与“复合型”工具工具设计应遵循单一职责原则。一个工具只做一件事，并把它做好（原子化）。例如，get_user_by_id和update_user_profile应该是两个独立的工具。然而，有时AI需要执行一个多步骤流程。虽然AI可以顺序调用多个原子工具，但你也可以提供一个更高效的“复合型”工具。例如，一个onboard_new_user工具，内部封装了创建账户、发送欢迎邮件、分配初始权限等一系列操作。这需要在原子性和效率之间取得平衡。

心得四：为工具添加“模拟模式”或“空跑模式”在开发初期，或者当外部API不稳定、有调用限制时，为工具的execute函数添加一个“模拟模式”非常有用。可以通过环境变量MOCK_MODE=true来触发。在模拟模式下，工具返回预设的模拟数据，而不是真正调用外部服务。这让你和AI可以完整地测试工具调用流程和结果处理逻辑，而无需依赖外部依赖。这在演示或编写自动化测试时也特别方便。

心得五：版本化你的MCP服务器当你的工具集更新，特别是进行不兼容的变更（如删除参数、改变返回值结构）时，考虑对服务器进行版本化管理。可以在Server初始化时提供版本号，并在客户端配置中指定兼容的版本范围。对于重大变更，甚至可以并行运行不同版本的服务端，让客户端逐步迁移。这在小团队内部可能不是问题，但在开发供多人使用的公共服务时至关重要。