这次我们来看一个关于 MCP Server 的实战教程。MCPModel Context Protocol是 Anthropic 提出的一种协议旨在让 AI 助手能够安全、结构化地访问外部工具和数据源。Matt Pocock 的这篇教程核心是教你如何从零开始用 5 条精心设计的 Prompt在 Cursor 这样的 AI 编程助手的帮助下快速搭建一个功能完整的 MCP Server。对于开发者而言这直接解决了“如何让 AI 助手如 Claude、Cursor安全可控地操作我的私有数据或内部工具”的痛点。整个过程不要求你精通 MCP 协议的所有细节而是通过 Prompt 工程引导 AI 帮你完成大部分编码工作显著降低了上手门槛。本文将带你走通这个流程重点关注环境准备、Prompt 设计、代码生成、调试部署以及最终的集成验证。1. 核心能力速览能力项说明项目类型基于 TypeScript 的 MCP Server 开发教程核心方法使用 5 条结构化 Prompt 引导 AI 编程助手Cursor生成代码技术栈TypeScript, Node.js, MCP SDK, Cursor IDE硬件门槛无特殊要求普通开发机即可主要依赖网络和 IDE启动方式通过npm run dev或npx tsx启动本地开发服务器接口能力提供符合 MCP 协议的 stdio 或 HTTP 服务供 AI 助手调用适合场景开发者希望为 AI 助手扩展自定义工具如查询数据库、调用内部 API、操作文件系统学习成本较低通过 Prompt 驱动无需从零阅读大量 MCP 文档2. 适用场景与使用边界这个教程非常适合以下几类开发者希望提升开发效率的工程师想为日常使用的 Cursor 或 Claude Desktop 添加专属工具比如一键查询项目状态、生成特定格式的代码片段、与内部系统交互。探索 AI 代理Agent能力的团队MCP 是构建企业级 AI 代理生态的基础设施。通过本教程可以快速理解如何将内部能力封装成 AI 可安全调用的工具。对 Prompt 工程和 AI 编程感兴趣的学习者教程本身就是 Prompt 工程的高级实践展示了如何通过清晰的指令让 AI 完成复杂项目搭建。使用边界与注意事项安全第一MCP Server 本质上是为 AI 开放了一个操作入口。在实现工具时必须严格进行权限控制和输入验证避免 AI 执行危险操作如删除关键文件、无限循环调用。数据合规如果 Server 涉及访问敏感数据需确保符合数据安全法规并在 Prompt 中明确告知 AI 数据的边界。依赖网络整个开发过程高度依赖 Cursor或类似工具的 AI 补全与问答能力需要稳定的网络环境。非可视化应用MCP Server 是后台服务不提供用户界面其功能通过 AI 助手的对话界面来触发和使用。3. 环境准备与前置条件在开始跟随 Prompt 构建之前你需要准备好基础开发环境。以下是必需的清单Node.js 环境建议安装最新的 LTS 版本如 v18.x 或 v20.x。这是运行 TypeScript 和 MCP Server 的基石。包管理工具npm或yarn或pnpm。本文示例将使用npm。代码编辑器/IDE强烈推荐 Cursor。它是本教程的核心工具深度集成了 AI 能力能完美响应后续的 Prompt。你也可以使用 VS Code 相关 AI 插件但体验可能不如 Cursor 流畅。TypeScript 基础虽然 Prompt 会引导生成代码但具备基本的 TypeScript 知识如类型、接口、模块将极大帮助你理解和调试生成的代码。MCP 基础概念了解 MCP 中的核心概念即可如Tool工具、Resource资源、Prompt提示模板。无需深入协议细节。环境检查命令打开终端运行以下命令确认环境就绪。# 检查 Node.js 和 npm 版本 node --version npm --version # 安装 TypeScript 编译器全局或局部均可 npm install -g typescript tsc --version4. 项目初始化与依赖安装我们从一个空目录开始让 AI 帮助我们一步步创建项目。创建项目目录并初始化在终端中创建一个新目录并进入然后初始化一个新的 npm 项目。mkdir my-mcp-server cd my-mcp-server npm init -y安装核心依赖根据 MCP 官方推荐我们需要安装modelcontextprotocol/sdk以及开发所需的 TypeScript 相关依赖。npm install modelcontextprotocol/sdk npm install -D typescript types/node tsxmodelcontextprotocol/sdk官方提供的 SDK包含了构建 Server 所需的所有类型和工具。typescriptTypeScript 编译器。types/nodeNode.js 的类型定义文件。tsx一个 TypeScript 执行器可以让我们直接运行.ts文件无需手动编译非常适合开发。初始化 TypeScript 配置生成一个基础的tsconfig.json文件。npx tsc --init --outDir dist --rootDir src --esModuleInterop --resolveJsonModule生成的tsconfig.json已经包含了常用配置。你可以稍后根据 AI 的建议进行调整。5. 五条核心 Prompt 实战解析这是教程最精华的部分。我们将逐条分析 Matt Pocock 设计的 Prompt并展示如何在 Cursor 中运用它们来生成代码。核心交互方式在 Cursor 中你可以通过Cmd/Ctrl K打开“Chat”面板或者直接在编辑器中使用“Composer”功能将以下 Prompt 粘贴进去并发送。AI 会根据你的项目上下文生成代码或给出指导。Prompt 1: 项目脚手架与基础结构目标让 AI 为我们创建 MCP Server 的基本骨架。Prompt 示例“我们正在创建一个 MCP Server。请基于modelcontextprotocol/sdk在src/index.ts中创建一个最基本的 MCP Server 骨架。它应该初始化一个 Server 实例并准备好启动。同时请更新package.json中的main字段和scripts字段添加dev脚本以便用tsx运行开发服务器。”AI 可能执行的操作创建src目录和src/index.ts文件。在index.ts中写入类似以下的代码import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new Server( { name: my-mcp-server, version: 0.1.0, }, { capabilities: { // 这里后续会定义工具Tools和资源Resources }, } ); async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Server running on stdio); } main().catch((error) { console.error(Server error:, error); process.exit(1); });修改package.json添加脚本{ main: dist/index.js, scripts: { dev: tsx watch src/index.ts, build: tsc } }Prompt 2: 定义第一个工具Tool目标让 AI 为我们的 Server 添加一个具体的、可被 AI 调用的工具。Prompt 示例“现在请为这个 Server 添加一个工具Tool。工具的名字叫get_weather它应该接收一个参数location字符串类型描述是‘获取指定城市的当前天气’。请实现这个工具的 handler 函数目前可以先返回一个模拟的天气数据例如‘{“temperature”: 22, “condition”: “Sunny”}’。请确保在 Server 的capabilities中正确注册这个工具。”AI 可能执行的操作在src/index.ts中导入Tool类型。定义get_weather工具及其 handler。更新 Server 的capabilities配置。代码结构会演变为import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; // 可能新增导入 import { CallToolResult } from modelcontextprotocol/sdk/types.js; const server new Server( { name: my-mcp-server, version: 0.1.0 }, { capabilities: { tools: { // 定义工具列表 get_weather: { name: get_weather, description: 获取指定城市的当前天气, inputSchema: { type: object, properties: { location: { type: string, description: 城市名称例如Beijing, Shanghai, }, }, required: [location], }, }, }, }, } ); // 注册工具的处理函数 server.setRequestHandler(tools/call, async (request) { if (request.params.name get_weather) { const location request.params.arguments?.location as string; // 模拟数据 const mockWeather { temperature: 22, condition: Sunny, location: location, }; return { content: [ { type: text, text: JSON.stringify(mockWeather, null, 2), }, ], } as CallToolResult; } throw new Error(Unknown tool: ${request.params.name}); }); // ... 剩余的 main 函数不变Prompt 3: 添加资源Resource支持目标让 Server 不仅能提供工具还能提供结构化的数据资源例如一个项目文件列表。Prompt 示例“接下来请为 Server 添加对资源Resources的支持。定义一个资源模板file:///project/{path}用于表示项目根目录下的文件。请实现resources/list和resources/read请求的 handler。list可以返回一个固定的文件列表例如[‘README.md’, ‘src/index.ts’]read可以根据uri读取对应文件的内容暂时可以返回模拟内容。同样记得更新capabilities。”AI 可能执行的操作在capabilities中添加resources字段。实现resources/list和resources/read的 handler。代码会继续扩展setRequestHandler部分可能会被重构以处理多种请求类型或者新增独立的 handler 设置。Prompt 4: 错误处理与输入验证目标增强 Server 的健壮性确保工具调用安全可靠。Prompt 示例“现在请改进get_weather工具。添加输入验证确保location参数不为空字符串。如果验证失败返回一个格式正确的错误。同时为整个 Server 添加一个顶层的错误处理中间件捕获未处理的异常并以 MCP 协议规定的错误格式返回避免 Server 崩溃。”AI 可能执行的操作在tools/call的 handler 中为get_weather添加if (!location || location.trim() ) { ... }的判断并返回{ error: ... }。可能会使用server.onerror或类似机制来设置全局错误监听。生成的代码会体现出更强的生产环境意识。Prompt 5: 配置与集成测试目标完成 Server 的最终配置并指导如何将其集成到 Claude Desktop 或 Cursor 中进行测试。Prompt 示例“最后请创建一个简单的配置文件claude_desktop_config.json展示如何将这个 MCP Server 配置到 Claude Desktop 中。同时在package.json中添加start脚本用于生产环境运行编译后的 JS 文件。另外请写一段简短的README.md说明项目的用途、如何安装、如何运行以及如何测试工具。”AI 可能执行的操作创建claude_desktop_config.json示例{ mcpServers: { my-mcp-server: { command: node, args: [/ABSOLUTE/PATH/TO/YOUR/PROJECT/dist/index.js], env: {} } } }更新package.json的scriptsstart: node dist/index.js。生成一个包含项目简介、安装步骤 (npm install)、开发运行 (npm run dev)、构建 (npm run build) 和测试说明的README.md草稿。6. 开发、运行与调试流程通过以上 5 条 PromptAI 已经帮你生成了项目的主要代码。现在你需要手动执行并测试。启动开发服务器在项目根目录下运行npm run dev如果一切正常终端会显示 “MCP Server running on stdio” 并挂起等待标准输入stdio的连接。这是 MCP Server 的标准运行模式。手动测试 Server可选为了验证 Server 是否能正常响应你可以创建一个简单的测试脚本test_client.mjs使用 ES 模块import { spawn } from child_process; import { Writable } from stream; const serverProcess spawn(node, [dist/index.js], { stdio: [pipe, pipe, inherit] // 继承 stderr 以便看错误 }); const writable new Writable({ write(chunk, encoding, callback) { console.log([Server Output]:, chunk.toString()); callback(); } }); serverProcess.stdout.pipe(writable); // 发送一个简单的 JSON-RPC 请求模拟工具调用 const request { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: get_weather, arguments: { location: Beijing } } }; serverProcess.stdin.write(JSON.stringify(request) \n); setTimeout(() { serverProcess.kill(); }, 2000); // 2秒后结束运行node test_client.mjs观察是否能收到模拟的天气数据。这能帮你确认 Server 的逻辑是否正确。在 Cursor 中实时调试这是最强大的部分。你不需要手动运行测试客户端。在 Cursor 中你可以在 Chat 里直接说“调用一下我的 MCP Server 里的get_weather工具location 设为 Shanghai。”Cursor 会识别到你项目中的 MCP Server如果已正确配置连接并发送请求。观察npm run dev的终端输出以及 Cursor 返回的结果。如果出错根据错误信息回到代码中用自然语言向 Cursor 描述问题例如“调用工具时出现了 JSON-RPC 解析错误请检查 handler 的返回值格式”让它帮你修复。7. 集成到 AI 助手环境让 MCP Server 真正发挥作用需要将其配置到 AI 助手客户端中。Claude Desktop 配置找到 Claude Desktop 的配置目录。macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json将之前生成的claude_desktop_config.json中的mcpServers部分合并到 Claude 的配置文件中。注意args中的路径必须替换为你项目dist/index.js的绝对路径。重启 Claude Desktop。在对话中你应该能发现 Claude 可以使用你自定义的get_weather工具了。在 Cursor 中配置如果支持一些深度集成 MCP 的 IDE如 Cursor 的新版本可能支持项目级别的 MCP Server 配置。通常是通过项目根目录下的.cursor/mcp.json或mcp.json文件进行配置。你可以询问 Cursor“如何为当前项目配置 MCP Server以便你能直接调用里面的工具” 它会给出最新的配置方法。8. 功能扩展与进阶实践基础 Server 运行起来后你可以通过更多 Prompt 引导 AI 进行功能扩展连接真实数据源“修改get_weather工具让它调用真实的天气 API比如 OpenWeatherMap。请添加一个配置项API_KEY的管理可以从环境变量中读取。”添加更多工具“请再添加一个工具search_files它接收一个query参数在项目目录内递归搜索包含该查询文本的文件并返回文件路径列表。”实现资源动态读取“修改resources/read的 handler让它根据uri中的file:///project/{path}真实地读取项目目录下的文件内容。”增加认证机制“为 Server 添加一个简单的 API 密钥认证。在启动时检查一个特定的请求头或参数密钥不匹配则拒绝请求。”打包与分发“请配置pkg或nexe将这个 MCP Server 打包成一个独立的可执行文件方便分发。”9. 常见问题与排查方法在开发过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案运行npm run dev后立即退出1. 代码存在语法错误。2. 依赖未正确安装。3.tsconfig.json配置有误。1. 查看终端报错信息。2. 运行npx tsc --noEmit检查 TypeScript 错误。3. 确认node_modules存在。1. 根据错误信息修复代码。2. 删除node_modules和package-lock.json重新npm install。3. 检查并修正tsconfig.json。Claude Desktop 无法识别 Server1. 配置文件路径错误。2. 配置文件格式错误JSON。3. Server 可执行文件路径错误或没有执行权限。1. 检查 Claude Desktop 配置文件的路径和内容。2. 使用JSONLint验证配置文件。3. 在终端中手动运行配置的命令看是否能启动 Server。1. 确保使用绝对路径。2. 修正 JSON 格式。3. 确保node命令在系统 PATH 中或使用which node获取全路径。调用工具时返回“未知工具”错误1. 工具名在capabilities中注册的名称与调用时不一致。2.setRequestHandler中没有处理对应的工具名。1. 检查capabilities.tools对象中的 key 是否与调用名完全一致。2. 在tools/callhandler 中添加console.log打印收到的请求名。1. 确保注册和调用的工具名大小写、拼写一致。2. 在 handler 中添加完备的条件判断。Server 运行但 AI 助手无反应1. AI 助手未正确加载 MCP 配置。2. Server 运行在 stdio 模式但 AI 助手未通过 stdio 连接。3. 协议版本不兼容。1. 重启 AI 助手客户端。2. 检查客户端日志如果有。3. 确认使用的modelcontextprotocol/sdk版本与客户端兼容。1. 确认配置后完全重启客户端。2. 查阅客户端官方文档对 MCP 的支持说明。3. 尝试更新 SDK 到最新版本。处理请求时 Server 崩溃1. Handler 中存在未捕获的异常。2. 异步操作未正确处理。1. 查看 Server 进程的 stderr 输出。2. 在 handler 中使用try...catch包裹核心逻辑。1. 如 Prompt 4 所建议添加全局和局部的错误处理。2. 确保所有异步操作都使用了await或妥善处理了 Promise。10. 最佳实践与使用建议遵循以下建议可以让你构建的 MCP Server 更健壮、更易用从模拟数据开始正如本教程所示先用硬编码数据实现工具逻辑确保整个 MCP 通信链路畅通再替换为真实的数据源或 API 调用。精心设计工具描述工具Tool的description和参数的description至关重要。AI 助手依靠这些描述来理解何时以及如何使用你的工具。描述应清晰、具体。严格的输入验证与错误处理永远不要信任来自 AI 助手的输入。在工具 handler 内部进行严格的类型检查和业务逻辑验证并返回友好的错误信息。环境变量管理配置API 密钥、服务地址等敏感或可配置信息务必通过环境变量如dotenv管理不要硬编码在代码中。利用 TypeScript 的类型优势MCP SDK 提供了完整的类型定义。充分利用它们来定义工具的参数和返回值类型可以减少运行时错误并让 AICursor在编程时提供更准确的补全。日志记录在 Server 中添加详细的日志记录例如使用winston或pino记录收到的请求、处理过程和错误这对于调试和监控至关重要。性能考虑如果工具操作比较耗时确保 handler 是异步的避免阻塞 Server 处理其他请求。对于可能长时间运行的操作可以考虑实现进度通知如果 MCP 协议版本支持。通过 Matt Pocock 的这 5 条 Prompt 教程我们看到了 Prompt 工程如何将复杂的协议学习和技术实现转化为一个可交互、可迭代的开发流程。你不需要成为 MCP 专家只需要清晰地描述目标AI 就能帮你填补大部分技术细节。这种开发模式尤其适合快速原型验证和为 AI 助手生态构建定制化工具。接下来你可以尝试将你日常工作中重复性的、需要查询内部文档或系统的操作封装成 MCP 工具让你的 AI 编程伙伴真正成为你的得力助手。