如果你最近关注 AI 编程助手尤其是 Cursor、Claude Desktop 这类工具可能会频繁听到一个词MCP Server。它听起来像某种高深的后端服务让很多开发者望而却步。但真相是它的核心价值恰恰在于降低复杂性——它让 AI 助手能安全、标准化地访问你本地的文件、数据库、API甚至执行特定命令而无需你把所有隐私数据都上传到云端。网上很多教程一上来就讲协议规范、TypeScript 类型定义让人看得云里雾里。但 Matt Pocock 的实战教程揭示了一个更本质的事实搭建一个可用的 MCP Server核心逻辑可能只需要几十行代码真正的门槛在于理解其设计哲学和与 AI 的交互模式。本文将带你拆解这个实战教程的精髓。我们不会止步于翻译和复述而是会深入剖析为什么这 5 条 Prompt 能奏效背后对应的代码是什么如何从零搭建、调试并集成到你的工作流中更重要的是我们会探讨在 CSDN 开发者最关心的场景下——比如连接内部数据库、调用公司内部 API、处理特定格式的日志文件——如何定制你自己的 MCP Server真正让 AI 成为你得力的“副驾驶”。读完本文你将能透彻理解 MCPModel Context Protocol的核心概念与解决的问题。跟随步骤从零搭建一个功能完整的 MCP Server。掌握利用 Prompt 驱动开发、并与 Cursor 等工具集成的完整流程。获得定制化开发自己 MCP Server 的思路与最佳实践。1. MCP Server 究竟是什么它解决了什么痛点在深入代码之前我们必须先厘清一个根本问题为什么需要 MCP Server没有它的时候我们是怎么和 AI 编程助手协作的想象一个典型场景你想让 Cursor 帮你分析一个本地的nginx.log日志文件找出错误率最高的接口。传统做法是手动把日志文件的一部分内容复制出来。粘贴到 Cursor 的聊天窗口。加上 Prompt“请分析这段日志找出错误码非 200 的请求并统计接口路径。”如果日志太大你可能需要分多次复制粘贴过程繁琐且容易遗漏。这个过程有几个明显痛点上下文限制大文件无法一次性提供。操作繁琐需要人工执行“打开文件-复制-粘贴”的机械操作。安全隐患你可能无意中将包含敏感信息IP、密钥、用户数据的日志片段暴露给了云端 AI。无法执行动作AI 只能“看”不能“做”。比如它无法帮你重启服务、查询数据库当前状态。MCP (Model Context Protocol) 就是为了解决这些问题而生的一个开放协议。你可以把它理解为 AI 世界里的“驱动程序”或“插件标准”。一个 MCP Server 就是一个遵循该协议的后台进程它负责资源Resources向 AI 模型安全地暴露本地的数据源如文件系统、数据库、API 端点。AI 可以通过协议“读取”这些资源但无需直接接触原始数据。工具Tools向 AI 模型提供可调用的函数工具。AI 可以“请求”Server 执行某个工具比如运行一个 Shell 命令、发送一个 HTTP 请求Server 执行后把结果返回给 AI。所以MCP Server 的核心价值是在 AI 模型和你本地的、私有的或受控的环境之间建立了一个安全、标准化、可编程的桥梁。AI 模型通过这个桥梁获取上下文Context和使用工具Tools从而能够完成更复杂、更贴近真实开发环境的任务。对于 CSDN 的开发者读者来说理解这一点至关重要学习 MCP 不是为了追逐新概念而是为了解锁 AI 助手更深层次的生产力让它从“一个能聊天的代码补全工具”升级为“一个能理解你整个项目上下文并执行安全操作的智能体”。2. 环境准备搭建你的第一个 MCP Server 需要什么Matt Pocock 的教程基于 Node.js 生态。为了完全复现并理解整个过程你需要准备以下环境。别担心即使你是前端新手跟着步骤走也能顺利完成。2.1 基础运行环境Node.js版本 18 或更高。这是运行 JavaScript/TypeScript MCP Server 的基础。前往 Node.js 官网 下载安装 LTS 版本。包管理工具推荐使用pnpm因为它更快且节省磁盘空间。这也是教程中使用的工具。如果你使用npm或yarn后续命令需要稍作调整。# 如果你没有安装 pnpm可以通过 npm 安装 npm install -g pnpm # 安装后验证 pnpm --version代码编辑器Visual Studio Code 或 Cursor 均可。本文演示将使用 VS Code但原理完全相通。2.2 初始化项目打开终端创建一个新的项目目录并初始化。# 创建一个项目文件夹 mkdir my-first-mcp-server cd my-first-mcp-server # 初始化 package.json 文件 pnpm init -y这会在当前目录生成一个package.json文件。2.3 安装核心依赖MCP 协议有官方的 TypeScript SDK (modelcontextprotocol/sdk)它提供了构建 Server 和 Client 所需的类型和工具。我们还需要zod库来进行参数验证。pnpm add modelcontextprotocol/sdk zod同时我们需要安装 TypeScript 及其相关的开发依赖以便编写和编译 TypeScript 代码。pnpm add -D typescript types/node tsxtypescriptTypeScript 编译器。types/nodeNode.js 的类型定义文件。tsx一个 TypeScript 执行器可以像运行.js文件一样直接运行.ts文件非常适合开发和调试。初始化 TypeScript 配置npx tsc --init这会生成一个tsconfig.json文件。你可以保持默认配置或根据需要进行调整。至此你的开发环境就准备好了。接下来我们将进入核心环节如何用 5 条关键的 Prompt 来驱动构建过程。3. 核心流程拆解5条Prompt如何驱动开发Matt Pocock 教程的精妙之处在于它展示了如何用 AI比如 Cursor来辅助构建一个与 AI 通信的 Server。这是一个“元”过程。我们将其拆解为五个关键阶段并解释每个阶段的目标、对应的 Prompt 思路以及最终产出的代码。3.1 Prompt 阶段一定义 Server 的“能力清单”目标明确你的 MCP Server 要提供哪些“资源”(Resources)和“工具”(Tools)。Prompt 思路不要直接问“怎么建 MCP Server”而是描述你想要的功能。例如“我想构建一个 MCP Server它需要提供两个核心功能1. 作为一个资源Resource能让我读取项目根目录下的README.md文件的内容。2. 作为一个工具Tool能让我执行一个简单的命令比如获取当前系统的时间。”AI 的辅助作用基于这个描述AI 可以帮你勾勒出 Server 的基本骨架包括需要实现的协议方法initialize,resources/list,tools/list等并提示你使用modelcontextprotocol/sdk中的Server类。此阶段产出一个初步的server.ts文件结构包含了 Server 实例创建和基本的协议处理逻辑。3.2 Prompt 阶段二实现“资源”Resources的提供目标让 Server 能够声明并处理对特定资源如文件的读取请求。Prompt 思路聚焦于具体实现。例如“在刚才的 MCP Server 代码里如何具体实现resources/list方法让它返回一个指向README.md文件的资源描述并且如何实现resources/read方法来读取这个文件的实际内容”关键概念解释资源 URI类似于file:///README.md的标识符用于唯一指代一个资源。资源列表在initialize握手阶段或通过resources/list方法Server 告诉 ClientAI“我这里有这些资源可用。”资源读取当 AI 需要某个资源的上下文时它会通过resources/read请求 URIServer 负责返回内容如文本、JSON 等。此阶段产出在server.ts中补充resources相关的方法实现包括列出资源和读取资源内容的具体逻辑。3.3 Prompt 阶段三实现“工具”Tools的调用目标让 Server 能够声明并执行具体的操作函数。Prompt 思路描述工具的定义和执行。例如“现在需要添加一个工具Tool。这个工具的名字叫get_current_time它不需要任何输入参数。当被调用时它返回一个包含当前日期时间的字符串。请帮我实现tools/list来声明这个工具并实现tools/call来处理对这个工具的调用。”关键概念解释工具定义需要描述工具的名称、描述、输入参数模式使用zodschema 定义。这相当于函数的“签名”。工具调用AI 会根据对话决定调用哪个工具并传入参数。Server 的tools/call方法收到请求后执行对应的函数并将结果返回。此阶段产出在server.ts中补充tools相关的方法实现包括工具列表的定义和工具调用的处理函数。3.4 Prompt 阶段四配置 Server 的启动与 Stdio 通信目标让 Server 能够作为一个独立的进程启动并通过标准输入输出stdio与 AI Client 进行通信。Prompt 思路解决运行问题。例如“我的 MCP Server 代码写好了。如何启动这个 Server让它通过 stdio 方式监听请求请给出启动脚本和必要的配置。”关键概念解释Stdio 传输这是 MCP Server 最常见的运行方式。Server 进程不绑定网络端口而是通过stdin接收请求通过stdout发送响应。AI Client如 Claude Desktop会启动这个 Server 进程并与之通信。Server 启动代码中需要创建StdioServerTransport实例并将其绑定到 Server 实例然后开始监听。此阶段产出完善server.ts的启动逻辑并可能生成一个package.json中的启动脚本例如“start”: “tsx server.ts”。3.5 Prompt 阶段五集成与测试连接 Cursor/Claude目标将构建好的 MCP Server 配置到 AI 客户端如 Cursor并进行功能测试。Prompt 思路询问客户端配置。例如“我已经有了一个可运行的 MCP Server。如何将它配置到 Cursor 编辑器中使用需要修改哪个配置文件”关键概念解释客户端配置AI 客户端需要知道如何启动你的 Server。这通常通过一个配置文件如claude_desktop_config.json或 Cursor 的 MCP 设置来完成其中指定 Server 的命令行启动路径和参数。测试验证配置成功后在 AI 客户端的聊天窗口中你可以通过自然语言询问来测试功能例如“读取一下项目的 README 文件”或“现在几点了”AI 会自动调用对应的 MCP Server 功能。此阶段产出客户端配置文件的路径和内容示例以及验证功能是否正常的测试对话。通过这五个阶段我们从一个模糊的想法逐步引导 AI 和我们一起构建出一个具备明确功能的 MCP Server。接下来让我们把这些阶段融合起来看看完整的代码实现。4. 完整示例一个具备文件读取和时间查询的 MCP Server现在我们将上述五个阶段的成果整合形成一个完整的、可运行的 MCP Server 示例。我们将构建一个FileAndTimeServer它提供两个能力资源读取项目根目录下的README.md文件。工具执行get_current_time命令返回当前时间。4.1 项目结构my-first-mcp-server/ ├── package.json ├── tsconfig.json ├── server.ts # MCP Server 主文件 └── README.md # 用于测试的资源文件4.2 核心代码实现 (server.ts)// server.ts import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from modelcontextprotocol/sdk/types.js; import { z } from zod; import { readFileSync } from fs; import { join } from path; // 1. 创建 Server 实例 const server new Server( { name: file-and-time-server, version: 0.1.0, }, { capabilities: { resources: {}, // 声明支持 resources 功能 tools: {}, // 声明支持 tools 功能 }, } ); // 2. 定义工具的参数 Schema使用 zod const getCurrentTimeArgsSchema z.object({}); // 虽然此工具无需参数但定义一个空 schema 是良好的实践。 // 3. 处理 resources/list 请求列出可用资源 server.setRequestHandler(ListResourcesRequestSchema, async () { return { resources: [ { uri: file:///README.md, // 资源的唯一标识符 mimeType: text/markdown, // 资源的媒体类型 name: Project README, // 资源的友好名称 description: The README file of the current project, // 资源描述 }, ], }; }); // 4. 处理 resources/read 请求读取特定资源内容 server.setRequestHandler(ReadResourceRequestSchema, async (request) { const { uri } request.params; // 检查请求的 URI 是否是我们声明的资源 if (uri file:///README.md) { try { // 读取本地的 README.md 文件 // 注意这里使用的是相对路径假设 server.ts 在项目根目录 const filePath join(process.cwd(), README.md); const content readFileSync(filePath, utf-8); return { contents: [ { uri: uri, mimeType: text/markdown, text: content, }, ], }; } catch (error) { // 文件读取失败返回错误 throw new Error(Failed to read resource ${uri}: ${error}); } } // 如果请求的 URI 未找到抛出错误根据协议规范 throw new Error(Resource not found: ${uri}); }); // 5. 处理 tools/list 请求列出可用工具 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ { name: get_current_time, description: Get the current system date and time, inputSchema: { type: object, properties: {}, // 无输入参数 }, }, ], }; }); // 6. 处理 tools/call 请求执行工具调用 server.setRequestHandler(CallToolRequestSchema, async (request) { const { name, arguments: args } request.params; if (name get_current_time) { // 验证参数虽然本例中无参数但展示了模式 getCurrentTimeArgsSchema.parse(args); // 执行工具逻辑获取当前时间 const now new Date(); const timeString now.toLocaleString(zh-CN, { timeZone: Asia/Shanghai, hour12: false, }); return { content: [ { type: text, text: 当前系统时间是${timeString}, }, ], }; } // 如果请求的工具名未找到抛出错误 throw new Error(Tool not found: ${name}); }); // 7. 启动 Server使用 stdio 传输方式 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Server (File Time) is running on stdio...); } main().catch((error) { console.error(Server fatal error:, error); process.exit(1); });4.3 代码关键点解析Server 初始化创建Server实例时需要声明name,version和capabilities。capabilities告诉客户端本 Server 支持哪些协议功能resources,tools。请求处理器使用server.setRequestHandler(schema, handler)来注册处理特定协议请求的函数。这是 Server 逻辑的核心。资源ResourcesListResourcesRequestSchema: 返回一个资源描述列表。uri是资源的唯一标识客户端通过它来请求读取。ReadResourceRequestSchema: 根据传入的uri返回实际的内容。内容格式由mimeType和text或blob字段定义。工具ToolsListToolsRequestSchema: 返回一个工具描述列表。每个工具需要定义name,description和inputSchema输入参数的模式。CallToolRequestSchema: 根据传入的name和arguments执行对应的工具函数并返回结果。结果需要包裹在content数组中。错误处理对于无法处理的请求如未知的 URI 或工具名应抛出Error。Server SDK 会将其转换为协议规定的错误响应。传输层StdioServerTransport创建了一个基于标准输入输出的传输通道。这是与 AI 客户端集成的最常见方式。4.4 准备测试文件 (README.md)在项目根目录创建一个简单的README.md文件用于测试。# My First MCP Server 这是一个用于测试 MCP Server 资源读取功能的 Markdown 文件。 - 项目名称File and Time Server - 功能提供文件读取和获取系统时间的能力。 - 状态运行中。5. 运行、测试与集成到 Cursor代码写好了如何让它真正跑起来并被 AI 助手使用呢5.1 运行与调试 Server首先确保package.json中有启动脚本。// package.json { name: my-first-mcp-server, version: 0.1.0, type: module, scripts: { start: tsx server.ts }, dependencies: { modelcontextprotocol/sdk: ^0.6.0, zod: ^3.22.4 }, devDependencies: { types/node: ^20.0.0, tsx: ^4.7.0, typescript: ^5.0.0 } }然后在终端运行 Serverpnpm start如果一切正常你会看到输出MCP Server (File Time) is running on stdio...并且进程不会退出而是在等待标准输入。这表明你的 Server 已经成功启动并处于待命状态。注意此时如果你直接按 CtrlC进程会终止。因为目前还没有客户端连接它。我们需要配置一个客户端来连接它。5.2 集成到 Cursor 编辑器Cursor 内置了对 MCP Server 的支持。配置方式如下找到 Cursor 的 MCP 配置文件。macOS/Linux:~/.cursor/mcp.jsonWindows:%USERPROFILE%\.cursor\mcp.json如果文件或目录不存在请手动创建。编辑mcp.json文件。{ mcpServers: { my-file-time-server: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/PROJECT/my-first-mcp-server/server.ts ], env: { NODE_ENV: development } } } }关键参数解释command: 启动 Server 的命令。因为我们使用tsx直接运行.ts文件所以这里写node可能不行。更推荐的方式是使用pnpm执行脚本。args: 传递给命令的参数。我们需要指向编译后的.js文件或者使用能直接运行.ts的工具。更可靠的配置方式 首先确保你的项目可以通过一个命令启动。我们在package.json中已经定义了“start”: “tsx server.ts”。但 Cursor 需要调用一个可执行文件。我们可以创建一个启动脚本。方案A推荐使用 npm/pnpm 脚本{ mcpServers: { my-file-time-server: { command: pnpm, args: [ --dir, /ABSOLUTE/PATH/TO/YOUR/PROJECT/my-first-mcp-server, start ] } } }--dir参数指定了项目目录然后执行该目录下的start脚本。方案B直接使用 tsx如果你全局安装了tsx(npm install -g tsx)可以这样配置{ mcpServers: { my-file-time-server: { command: tsx, args: [ /ABSOLUTE/PATH/TO/YOUR/PROJECT/my-first-mcp-server/server.ts ] } } }重启 Cursor。修改配置文件后需要完全关闭并重新打开 Cursor以使配置生效。5.3 在 Cursor 中测试功能重启 Cursor 后打开一个聊天窗口例如在项目文件中右键选择“Chat with Cursor”。测试资源读取 在聊天框中输入“请读取一下这个项目的 README 文件。”Cursor 背后的 AI 模型如 Claude会识别到已配置的 MCP Server并通过协议调用resources/list和resources/read。你应该能看到 AI 的回复中包含了README.md文件的内容。测试工具调用 在聊天框中输入“现在几点了” 或 “调用 get_current_time 工具。”AI 会调用tools/call方法执行 Server 中的get_current_time函数并将结果返回给你。如果测试成功恭喜你你已经完成了一个功能完整的 MCP Server 的搭建、配置和集成。6. 常见问题与排查思路在实际操作中你可能会遇到一些问题。以下是常见问题的排查指南。问题现象可能原因排查方式解决方案运行pnpm start后立即退出1. 代码存在语法错误。2.server.ts中未正确调用server.connect()或main()函数。3. 依赖未安装。1. 检查终端错误信息。2. 在main()函数最后添加console.log或使用process.stdin.resume()临时保持进程不推荐长期使用。3. 运行pnpm install确保依赖完整。1. 根据错误信息修正 TypeScript/JavaScript 语法。2. 确保main()函数被调用且await server.connect(transport)执行成功。3. 重新安装依赖。Cursor 中无反应AI 不调用 Server1. Cursor 配置文件mcp.json路径或格式错误。2. 配置中的命令路径不正确。3. Server 启动命令失败Cursor 静默处理了错误。4. 需要重启 Cursor。1. 确认mcp.json文件在正确路径且为合法 JSON。2. 在终端手动执行配置中的command和args看能否启动 Server。3. 查看 Cursor 的开发者控制台Help - Toggle Developer Tools是否有相关错误日志。4. 确认已重启 Cursor。1. 使用 JSON 验证工具检查mcp.json。2. 使用绝对路径并确保命令在系统 PATH 中或可执行。3. 简化配置先确保 Server 能通过命令行独立运行。4. 务必重启 Cursor。AI 回复“找不到工具/资源”1. Server 的capabilities未正确声明支持tools或resources。2.list请求处理器返回的列表为空或格式错误。3. AI 的 Prompt 未触发工具调用逻辑。1. 检查Server初始化时的capabilities对象。2. 在list请求处理器中添加console.log调试输出。3. 尝试更明确的指令如“请使用 get_current_time 工具”。1. 确保capabilities中包含tools: {}和/或resources: {}。2. 确保list处理器返回的数组结构符合协议规范。3. 检查 AI 模型是否支持 MCP 工具调用Claude 3.5 支持良好。工具调用时报参数验证错误1.CallToolRequestSchema处理器中对arguments的解析或验证失败。2. AI 传入的参数格式与inputSchema定义不匹配。1. 在工具调用处理器中打印request.params查看实际传入的参数。2. 对比inputSchema的定义和实际传入的数据结构。1. 在工具处理器中使用try-catch包裹参数解析逻辑。2. 确保inputSchema的定义准确或将其设置为更宽松的模式如{}。读取文件资源失败1. 文件路径错误。2. 文件权限不足。3.uri匹配逻辑有误。1. 在ReadResourceRequestSchema处理器中打印process.cwd()和拼接后的filePath。2. 检查文件是否存在且可读。1. 使用join(__dirname, ‘../README.md’)等更稳定的路径解析方式。2. 确保 Server 进程有权限读取目标文件。3. 检查uri字符串是否完全匹配。7. 进阶与最佳实践打造属于你的生产级 MCP Server上面的例子是一个简单的起点。要构建一个真正有用、健壮的 MCP Server你需要考虑更多。以下是一些进阶建议和最佳实践。7.1 设计清晰的能力边界一个 MCP Server 应该职责单一。不要试图构建一个“万能” Server。好的模式是文件系统 Server专注于文件读写、目录遍历。数据库 Server提供安全的数据库查询通过参数化查询防止注入。内部 API Server封装公司内部 REST 或 GraphQL API。系统信息 Server获取服务器状态、日志、进程信息。7.2 安全性是第一要务MCP Server 运行在你的本地环境拥有执行命令和访问文件的权限必须谨慎。最小权限原则Server 只应拥有完成其功能所需的最小权限。避免提供像execute_shell这样强大的通用工具。输入验证与消毒对所有来自 AI 的输入工具参数、资源 URI进行严格的验证和消毒。防止路径遍历攻击如../../../etc/passwd或命令注入。环境隔离考虑在 Docker 容器或沙箱中运行高风险的 MCP Server以限制其影响范围。认证与授权针对网络 Server如果你的 Server 需要通过网络访问必须实现严格的认证机制。7.3 错误处理与日志友好的错误信息在tools/call或resources/read中抛出错误时信息应足够清晰让 AI 能理解问题所在例如“文件未找到/path/to/file”优于“Error: ENOENT”。结构化日志使用console.error记录 Server 的运行日志、收到的请求和错误便于调试。生产环境可集成 Winston、Pino 等日志库。7.4 性能与资源管理异步操作所有请求处理器async函数都应避免阻塞主线程。对于耗时的 I/O 操作如大文件读取、网络请求确保使用异步 API。资源缓存对于不常变化的资源可以考虑在内存中缓存但要注意缓存失效策略。连接管理如果使用网络传输需要妥善管理客户端连接的生命周期。7.5 一个更实用的示例项目文件搜索 Server让我们构思一个更贴近开发者需求的 Server一个能根据自然语言描述在项目中搜索相关文件的 Server。核心功能设计工具search_files输入参数query(字符串搜索关键词)fileExtension(可选字符串文件扩展名过滤)。内部逻辑使用glob库匹配文件读取文件内容使用简单的字符串匹配或更高级的向量搜索返回匹配的文件列表和摘要。资源可以将匹配到的文件作为资源暴露允许 AI 进一步读取其内容。代码片段示意import { glob } from glob; import fs from fs/promises; // ... 其他导入 server.setRequestHandler(ListToolsRequestSchema, async () ({ tools: [{ name: search_files, description: Search for files in the project based on content or name., inputSchema: { type: object, properties: { query: { type: string, description: Search keyword }, fileExtension: { type: string, description: Filter by file extension, e.g., .ts, .md } }, required: [query] } }] })); server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name search_files) { const { query, fileExtension } request.params.arguments as { query: string; fileExtension?: string }; const pattern fileExtension ? **/*${fileExtension} : **/*; const files await glob(pattern, { ignore: node_modules/** }); // 简化的内容搜索读取文件并检查是否包含 query const results []; for (const file of files.slice(0, 10)) { // 限制数量 try { const content await fs.readFile(file, utf-8); if (content.includes(query)) { results.push({ file, snippet: content.substring(0, 200) }); } } catch (e) { /* 忽略无权限文件 */ } } return { content: [{ type: text, text: 找到 ${results.length} 个文件:\n results.map(r - ${r.file}: ${r.snippet}...).join(\n) }] }; } throw new Error(Tool not found: ${request.params.name}); });这个 Server 让 AI 能“感知”你的项目文件内容极大地扩展了其辅助编程的能力边界。通过 Matt Pocock 教程中强调的 Prompt 驱动开发方法结合本文提供的完整实现路径、问题排查指南和进阶实践你现在已经具备了从零开始构建和定制各类 MCP Server 的能力。关键在于理解协议的核心是“资源”与“工具”的抽象以及如何安全、有效地将本地能力暴露给 AI。接下来就动手为你最繁琐的开发任务打造一个专属的 AI 增强工具吧。