这次我们来看一个非常实用的技术教程如何从零开始搭建一个 MCP Server。这个教程来自 Matt Pocock一位知名的 TypeScript 专家内容聚焦于使用 Prompt 工程和 Cursor AI 来快速构建一个功能性的 MCP 服务器。对于想要将 AI 能力集成到工作流、或者希望为 Claude、Cursor 等 AI 工具创建自定义工具的开发者来说这是一个极佳的入门点。教程的核心价值在于“实战”。它不空谈概念而是通过 5 条精心设计的 Prompt引导你一步步完成一个 MCP Server 的搭建。这意味着你不需要预先掌握复杂的 MCP 协议细节而是通过“与 AI 对话”的方式让 AI 帮你生成大部分代码。这大大降低了开发门槛尤其适合前端和 Node.js 开发者。本文将带你完整复现这个流程。我们会拆解这 5 条核心 Prompt 的作用手把手完成环境准备、项目初始化、代码生成、功能测试以及最终的集成验证。无论你是想学习 MCP 开发还是想提升使用 Cursor 这类 AI 编程工具的效能这篇文章都能提供直接的、可操作的路径。1. 核心能力速览在深入细节之前我们先快速了解通过本教程你将获得什么以及需要准备什么。能力项说明项目类型MCP (Model Context Protocol) Server 开发教程技术栈TypeScript, Node.js, MCP SDK核心方法使用 5 条结构化 Prompt 驱动 Cursor AI 生成代码开发环境Cursor IDE (或任何支持 Claude 的编辑器) Node.js 环境硬件门槛无特殊要求普通开发机即可主要依赖云 AI 模型能力启动方式通过npm run dev启动开发服务器可通过 stdio 或 HTTP 与 AI 应用通信主要功能构建一个具备自定义 Tools工具和 Resources资源的 MCP Server接口能力遵循 MCP 标准协议可被 Claude Desktop、Cursor 等兼容 MCP 的客户端调用适合场景为 AI 助手扩展自定义能力如查询内部 API、操作数据库、执行特定脚本简单来说你将学会如何用最少的代码和 AI 的辅助创建一个能让 Claude 等 AI 使用的“外挂”工具服务器。2. 适用场景与使用边界这个教程适合谁前端/Node.js 开发者希望为团队或自己创建高效的 AI 增强工具。AI 应用爱好者对将大模型接入实际工作流程感兴趣想了解 MCP 这一新兴标准。Cursor IDE 用户希望深度定制 Cursor 中 AI 助手的能力让其能访问特定知识或执行特定操作。Prompt 工程师想学习如何通过结构化 Prompt 引导 AI 完成复杂开发任务。能解决什么问题能力扩展让 Claude 这类通用 AI 模型能够调用你编写的特定函数比如查询公司内部数据、发送格式化通知、操作本地文件系统在安全范围内等。流程自动化将重复性的、需要特定知识的任务封装成 MCP Tool通过自然语言指令触发。降低开发成本利用 AI 生成 MCP Server 的样板代码开发者只需关注核心业务逻辑。不适合什么场景超高性能要求MCP 通信有一定开销不适合对延迟要求极高的实时系统。完全离线环境本教程依赖 Cursor 的 AI 功能或类似云端大模型来生成代码。替代传统 APIMCP 主要设计用于 AI 与工具的交互并非直接面向普通用户或移动端。安全与合规边界权限控制MCP Server 执行的工具可能具有潜在风险如文件删除、命令执行。务必在 Prompt 和代码中明确限制工具的操作范围切勿生成具有破坏性或高权限的工具。信息暴露通过 MCP 暴露的 Resources资源可能包含敏感信息。确保在生成代码时不对敏感数据进行硬编码并考虑访问控制。依赖安全AI 生成的代码可能引入有安全风险的依赖包务必进行审查。3. 环境准备与前置条件开始之前请确保你的开发环境满足以下要求。这是后续所有步骤的基础。Node.js 环境你需要安装 Node.js建议 LTS 版本如 18.x 或 20.x。这是运行 TypeScript 和 MCP Server 的基石。检查方式打开终端运行node --version和npm --version确认能正确输出版本号。代码编辑器 / IDE强烈推荐使用 Cursor IDE。它是本教程的核心工具其深度集成的 AI 功能基于 Claude 3 系列模型能完美执行 Matt Pocock 的 Prompt 策略。如果你使用其他编辑器如 VS Code则需要确保能方便地调用 Claude API 或具备类似能力的插件。Cursor 获取从 Cursor 官网下载并安装。包管理工具使用npm或yarn。本教程以npm为例。基本的 TypeScript 知识虽然 AI 会生成大部分代码但理解基本的类型、接口和模块概念有助于你调试和定制生成的代码。网络环境使用 Cursor AI 功能需要稳定的网络连接以便与云端模型通信。4. 安装部署与启动方式我们的目标不是手动编写一个 MCP Server而是通过 Prompt 引导 AI 来创建。因此“安装部署”在这里指的是创建项目并让 AI 填充内容的过程。4.1 创建项目目录与初始化首先创建一个干净的项目目录并初始化。# 1. 创建项目文件夹并进入 mkdir my-mcp-server cd my-mcp-server # 2. 初始化 npm 项目生成 package.json npm init -y # 3. 初始化 TypeScript 配置 npx tsc --init执行后你会得到基础的package.json和tsconfig.json文件。4.2 安装核心依赖接下来安装 MCP 开发所需的 SDK 和类型定义。在终端中执行npm install modelcontextprotocol/sdk npm install --save-dev typescript types/nodemodelcontextprotocol/sdk是官方提供的 SDK包含了构建 Server 和 Client 所需的所有工具。4.3 配置 TypeScript打开tsconfig.json确保包含以下关键配置以适配 Node.js 和模块化开发{ compilerOptions: { target: ES2022, module: NodeNext, moduleResolution: NodeNext, outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src/**/*], exclude: [node_modules] }4.4 创建源代码结构创建src目录并在其中创建入口文件。mkdir src touch src/index.ts至此一个最基础的 TypeScript 项目骨架就搭建完成了。接下来就是使用 Matt Pocock 的 5 条 Prompt 魔法时刻。5. 功能测试与效果验证5条Prompt实战拆解这是教程的核心。我们将逐条分析这 5 条 Prompt并在 Cursor 中实践观察 AI 如何生成代码。核心思路我们不是在终端输入命令而是在 Cursor 的 Chat 界面中将每一条 Prompt 发送给 AI并引导它将生成的代码写入到我们创建的项目文件中。5.1 Prompt 1项目初始化与框架搭建目标让 AI 理解我们要构建一个 MCP Server并生成基础的服务器框架代码。Prompt 示例“我正在构建一个 Model Context Protocol (MCP) Server。我已经创建了一个空的 TypeScript 项目安装了modelcontextprotocol/sdk。请为我在src/index.ts中创建一个最基本的 MCP Server 骨架。它应该能够启动一个服务器并通过 stdio 进行通信。请包含必要的导入、Server 初始化、工具和资源的空列表以及启动逻辑。”操作与预期结果在 Cursor 中打开my-mcp-server项目。在 Chat 面板中输入上述 Prompt。AI通常是 Claude 3.5 Sonnet会理解请求并生成一段 TypeScript 代码。要求 AI 将代码写入src/index.ts文件。你可以使用 Cursor 的功能引用文件或者直接告诉 AI “请将这段代码写入 src/index.ts”。预期生成代码关键点从 SDK 导入Server类。创建server实例。定义空的tools和resources。调用server.connect()并通过stdio传输层启动。包含基本的错误处理。验证检查src/index.ts文件应该看到一个可以运行的 MCP Server 主干代码。5.2 Prompt 2添加第一个 Tool工具目标让 AI 为我们的 Server 添加一个具体的、可被 AI 调用的功能。Prompt 示例“现在请为这个 MCP Server 添加一个 Tool。这个 Tool 叫做get_weather它应该接收一个参数location字符串类型并返回一个模拟的天气信息字符串例如The weather in {location} is sunny and 22°C.。请更新src/index.ts将这个 Tool 注册到 server 的 tools 列表中。确保遵循 MCP SDK 中 Tool 的定义格式包括 name, description, 和 inputSchema。”操作与预期结果继续在 Cursor Chat 中发送此 Prompt。AI 会生成get_weather工具的定义包括其输入 JSON Schema。它应该会修改之前的代码将新的 tool 对象添加到server.setRequestHandler中的tools数组里。预期生成代码关键点一个符合Tool接口的对象包含name,description。一个inputSchema定义type: “object”和properties: { location: { type: “string” } }。在server.setRequestHandler的tools部分包含这个新工具。一个处理函数当该工具被调用时返回模拟的天气数据。验证检查代码现在tools数组不应为空应包含get_weather的定义。你可以尝试运行服务器但此时还无法直观测试工具。5.3 Prompt 3添加一个 Resource资源目标让 AI 添加一种“资源”这类似于为 AI 提供可读取的上下文信息或文档。Prompt 示例“接下来请添加一个 Resource。这个 Resource 的 URI 是‘note://today’mimeType 是‘text/plain’内容是一段简单的文本‘This is a note for today: Remember to review the MCP project.’。请更新src/index.ts将这个 Resource 注册到 server 的 resources 列表中。同样请遵循 MCP SDK 中 Resource 的定义格式。”操作与预期结果发送此 Prompt 给 AI。AI 会生成Resource对象的定义并将其添加到resources列表中。预期生成代码关键点一个Resource对象包含uri,mimeType,name可选description可选。在server.setRequestHandler的resources部分包含这个新资源。可能还会包含一个readResource的处理器用于当客户端请求该 URI 时返回定义好的文本内容。验证检查代码resources数组现在应包含note://today这个资源项。5.4 Prompt 4完善启动脚本与测试准备目标让 AI 帮助完善package.json中的脚本方便我们启动和测试服务器。Prompt 示例“为了便于开发和测试请帮我更新package.json文件。添加一个‘dev’脚本用于以监视模式运行 TypeScript 编译并启动服务器。脚本可以类似‘tsc --watch node dist/index.js’但请考虑跨平台兼容性例如使用concurrently或npm-run-all。同时请确保tsconfig.json的配置正确能将编译输出到dist目录。”操作与预期结果发送此 Prompt。AI 可能会建议安装额外的开发依赖如concurrently或tsx。根据 AI 的建议在终端执行安装命令例如npm install --save-dev concurrently。AI 会生成更新后的package.json的scripts部分。预期结果package.json中新增“dev”: “concurrently \“tsc --watch\” \“node dist/index.js\””或类似的脚本。tsconfig.json中的outDir已正确设置为“./dist”。验证查看package.json现在你应该可以通过npm run dev命令来启动开发服务器了。5.5 Prompt 5集成测试与客户端连接目标指导我们如何测试这个 MCP Server 是否真正工作。由于直接测试需要 MCP 客户端AI 可能会提供多种方案。Prompt 示例“我的 MCP Server 已经初步完成。我想测试它是否能被一个 MCP 客户端例如 Claude Desktop正确连接和调用。请为我提供下一步的测试步骤。另外能否也创建一个简单的、用于本地测试的 MCP Client 脚本放在src/test-client.ts中这个脚本可以连接到我们的 stdio 服务器并列出可用的 tools 和 resources。”操作与预期结果发送此 Prompt。这是对 AI 综合能力的考验。AI 可能会提供两种路径路径 A推荐指导你配置 Claude Desktop。它会告诉你如何编辑 Claude Desktop 的配置文件例如~/Library/Application Support/Claude/claude_desktop_config.json在 Mac 上添加你的 MCP Server 配置。路径 B备用生成一个测试客户端脚本。预期生成代码/指导如果生成测试客户端代码会导入Client和StdioServerTransport来自 MCP SDK。脚本会启动一个子进程运行你的 server然后通过 transport 连接并发送tools/list和resources/list请求。会给出清晰的 Claude Desktop 配置示例。// Claude Desktop 配置示例AI可能提供 { “mcpServers”: { “my-weather-server”: { “command”: “node”, “args”: [“/absolute/path/to/your/project/dist/index.js”] } } }验证这是功能验证的关键一步。成功意味着你的 MCP Server 活了。6. 接口 API 与批量任务MCP Server 本身不是一个传统的 HTTP API 服务器它通过 stdio、HTTP 或 SSE 等传输层与客户端通信。其“接口”就是 MCP 协议定义的一系列 JSON-RPC 请求和响应。6.1 协议接口理解对于你创建的 Server客户端如 Claude可以调用以下核心接口tools/list获取服务器注册的所有工具列表。这就是你通过get_weather定义暴露的东西。tools/call调用一个具体的工具。客户端会发送工具名和参数你的服务器处理并返回结果。resources/list获取服务器提供的资源列表。resources/read读取一个特定资源的内容。你的src/index.ts中的server.setRequestHandler就是在处理这些请求。6.2 “批量任务”在 MCP 中的体现MCP 本身不直接管理“批量任务”但你可以通过设计 Tool 来实现类似效果。单个 Tool 处理批量逻辑你可以创建一个 Tool例如process_files它的输入参数是一个文件路径数组。在该 Tool 的处理函数中你使用循环或Promise.all来处理所有文件。客户端发起批量调用AI 客户端如 Claude可以理解用户“处理所有这些文件”的指令然后自动、连续地多次调用tools/call接口针对每个文件这由客户端逻辑控制。示例一个简单的批量处理 Tool 思路// 在 Tool 定义中 { name: “process_multiple_items”, description: “Process a list of items.”, inputSchema: { type: “object”, properties: { items: { type: “array”, items: { type: “string” }, description: “List of items to process” } }, required: [“items”] } } // 在处理函数中 async (params: any) { const { items } params; const results []; for (const item of items) { // 处理每个 item results.push(Processed: ${item}); } return { content: [{ type: “text”, text: results.join(‘\n’) }], }; }7. 资源占用与性能观察由于这是一个运行在 Node.js 上的轻量级服务其资源占用主要取决于你的工具函数的复杂度如果工具函数执行 CPU 密集型计算如图像处理或大量 I/O 操作会占用更多资源。并发请求量MCP Server 需要处理来自 AI 客户端的多个并发请求。如何观察资源占用进程管理使用系统自带工具如htop(Linux/macOS) 或任务管理器 (Windows)查看node进程的 CPU 和内存使用情况。Node.js 内置可以在代码中使用process.memoryUsage()来记录内存使用。启动监控在开发时最简单的观察方式就是运行npm run dev后看终端是否有异常错误以及进程是否稳定运行。性能优化建议异步操作确保所有 Tool 的处理函数都是async的对于数据库查询、网络请求等 I/O 操作使用异步避免阻塞。错误处理在每个 Tool 的处理函数中使用try…catch防止单个工具崩溃导致整个 Server 挂掉。避免全局状态尽量不要在 Server 中维护复杂的全局可变状态以减少竞态条件和内存泄漏风险。8. 常见问题与排查方法在按照 Prompt 构建和运行 MCP Server 的过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案运行npm run dev时报 TypeScript 编译错误1.tsconfig.json配置不正确。2. 代码语法错误或类型不匹配。3. 依赖未安装。1. 检查终端错误信息定位到具体文件和行号。2. 运行npx tsc --noEmit只检查类型错误。1. 根据错误信息修正tsconfig.json或代码。2. 确保已运行npm install安装了所有依赖。Server 启动后立即退出或无响应1. 传输层配置错误如 stdio 未正确连接。2. 入口文件index.ts逻辑有误进程提前结束。1. 检查server.connect()的参数和调用方式。2. 在代码开始处添加console.log(‘Server starting…’)调试。1. 确保server.connect()使用的是new StdioServerTransport()且await其完成。2. 参考 MCP SDK 官方示例核对启动逻辑。Claude Desktop 无法连接 Server1. Claude Desktop 配置文件路径或格式错误。2. Server 命令路径不是绝对路径。3. Server 本身未成功启动。1. 检查 Claude Desktop 的日志通常可在其设置中找到。2. 手动在终端运行 Server 命令看是否能独立启动。1. 确保配置文件 JSON 格式正确路径无误。2. 使用pwd命令获取项目绝对路径并完整填入args。3. 先确保npm run dev能独立运行 Server。AI 客户端看不到自定义的 Tool1. Tool 未正确注册到server.setRequestHandler。2. Tool 的定义格式不符合 SDK 要求。3. 客户端缓存了旧的 Server 信息。1. 检查tools数组是否包含你的 Tool 对象。2. 使用测试客户端脚本调用tools/list进行验证。1. 对照 SDK 文档检查 Tool 对象的字段name,description,inputSchema。2. 重启 AI 客户端如 Claude Desktop。调用 Tool 时返回错误1. Tool 处理函数抛出异常。2. 客户端发送的参数格式与inputSchema不匹配。1. 查看 Server 运行终端的错误输出。2. 在 Tool 处理函数内添加详细的console.log打印参数。1. 在处理函数内部添加try-catch返回友好的错误信息。2. 确保inputSchema正确定义并与客户端调用匹配。npm run dev脚本执行混乱concurrently命令配置问题或tsc --watch未编译完成就启动了node。观察终端输出看是编译失败还是 node 启动失败。可以分步执行先开一个终端运行npm run build:watch如果配置了再开另一个终端运行npm start。9. 最佳实践与使用建议基于 Matt Pocock 的 Prompt 驱动开发模式结合 MCP 开发经验总结以下最佳实践Prompt 需具体、清晰AI 生成代码的质量极大依赖于 Prompt。像 Matt 一样明确指定文件路径src/index.ts、依赖项已安装 SDK、预期功能返回天气字符串和格式要求遵循 MCP SDK 格式。迭代式开发不要试图用一条巨型 Prompt 生成所有功能。遵循教程的步骤1) 骨架 - 2) 单个工具 - 3) 单个资源 - 4) 配置优化 - 5) 测试。这更符合 AI 的上下文处理能力也便于你逐步理解代码。代码审查与理解AI 生成的代码需要你进行审查。确保你理解每一行代码的作用特别是涉及安全如文件操作、命令执行的部分。这是你的项目AI 只是助手。利用 TypeScript 类型安全MCP SDK 提供了良好的类型定义。在 Cursor 中充分利用 TypeScript 的智能提示和类型检查可以减少运行时错误。为 Tool 编写清晰的描述和 Schemadescription和inputSchema不仅是给 SDK 用的更是给 AI 客户端如 Claude看的。清晰、准确的描述能帮助 AI 更好地理解何时以及如何使用你的工具。分离配置与逻辑当工具变多时考虑将 Tool 和 Resource 的定义移到单独的文件如src/tools/weather.ts中然后在主文件中导入和注册。这能让index.ts更清晰。日志记录在 Server 启动和 Tool 被调用时添加console.log这对于调试和监控 Server 状态至关重要。安全性第一永远不要生成或接受 AI 建议的、具有破坏性或不加限制的工具如delete_all_files、execute_arbitrary_command。始终假设工具会被调用并施加必要的参数验证和权限检查。10. 总结与下一步通过 Matt Pocock 这 5 条 Prompt 的引导我们完成了一个 MCP Server 从零到一的搭建。这个过程清晰地展示了如何将自然语言指令Prompt转化为可工作的代码极大地提升了开发效率。最值得尝试的点低门槛入门 MCP你无需事先精通 MCP 协议细节通过“提问-生成”的方式就能上手。掌握 AI 辅助开发模式学会了如何用结构化的 Prompt 指挥 AI 完成特定、复杂的编码任务这是一种可迁移的高效技能。获得一个可扩展的底座生成的index.ts是一个功能完备的 MCP Server 模板你可以在此基础上继续添加更多工具和资源。最先应该验证的功能 成功启动 Server 并通过 Claude Desktop 或测试客户端看到你定义的get_weather工具和note://today资源是第一个里程碑。这证明整个通信链路是通的。最容易踩的坑路径问题Claude Desktop 配置中args的绝对路径错误。依赖问题忘记安装modelcontextprotocol/sdk或 TypeScript。协议版本确保使用的 SDK 版本与客户端兼容目前通常问题不大。后续扩展方向连接真实数据源将get_weather工具改为调用真实的天气 API。添加数据库工具创建连接本地 SQLite 或 PostgreSQL 的工具让 AI 可以查询数据。集成内部系统封装公司内部的 API 或脚本作为 MCP Tool。探索更多传输层尝试 HTTP 或 SSE 传输让 Server 能被更多客户端访问。打包与分发将你的 Server 打包成 Docker 镜像或 NPM 包方便团队共享。这个项目就像一个乐高底座5 条 Prompt 给了你最初的几块积木和拼装说明书。接下来发挥你的想象力用同样的 Prompt 工程方法去构建真正能提升你工作效率的 AI 工具链吧。建议收藏本文在实践每个步骤时回头查阅。
