1. 项目概述为什么我们需要 MCP最近在折腾 AI 应用开发的朋友估计都绕不开一个词MCP也就是 Model Context Protocol。这玩意儿听起来挺唬人协议、标准啥的但说白了它就是一个让大模型比如 Claude、GPT能安全、方便地调用外部工具和数据的“接线员”和“翻译官”。想象一下你有一个能力超强的 AI 助手但它被困在一个封闭的房间里房间里只有几本固定的参考书。你想让它帮你查一下最新的股价、控制一下家里的智能灯或者分析一下你数据库里的销售数据它都无能为力。MCP 要做的就是给这个房间开一扇扇安全可控的“窗户”每扇窗户都连接着一个特定的外部能力——可能是搜索引擎、数据库、文件系统甚至是一个代码执行环境。AI 助手通过 MCP 这扇“窗户”就能看到外面的世界并动手操作。所以“从零搭建 MCP 服务”这个事核心价值就在于赋予 AI 真正的“动手能力”和“感知能力”。它不再是那个只会聊天的“鹦鹉”而变成了一个能帮你真正干活的“数字员工”。无论是通过 AI 一键分析本地文档、自动操作浏览器进行数据抓取还是连接公司内部的业务系统MCP 都是实现这些场景的关键桥梁。市面上像 Cursor、Claude Desktop、Windsurf 这些先进的 AI 编程或桌面助手其背后强大的插件生态很多都基于或兼容 MCP 协议。自己搭建 MCP 服务意味着你可以定制化地扩展 AI 的能力边界让它无缝融入你的个人工作流或企业技术栈而不再受限于官方或第三方提供的有限工具。2. MCP 核心原理与架构拆解要搭建先得弄明白它到底是怎么工作的。MCP 不是一个具体的软件而是一套通信协议和规范。它的架构非常清晰主要包含三个角色2.1 核心角色客户端、服务器与资源MCP 客户端 通常就是大模型应用本身。比如 Claude Desktop、Cursor IDE或者任何集成了 MCP 客户端库的应用。它的职责是发起请求比如“我想读一下/home/user/report.md这个文件”或者“请用搜索引擎查一下‘MCP 最新动态’”。MCP 服务器 这就是我们要搭建的核心。它是一个独立的进程封装了具体的功能逻辑。一个服务器可以提供一种或多种“工具”和“资源”。例如一个“文件系统服务器”提供了读写文件的工具一个“SQLite 服务器”提供了执行 SQL 查询的工具。服务器监听客户端的请求执行实际操作并返回结果。资源与工具 这是服务器暴露给客户端的能力实体。资源 通常指数据比如一个文件、一张数据库表、一个网页的 URL。资源有唯一的标识符URI和描述性的元数据MIME 类型、名称等。客户端可以“列出”和“读取”资源。工具 通常指可执行的操作比如“执行命令”、“运行搜索”、“发送 HTTP 请求”。工具需要输入参数执行后返回输出结果。2.2 通信流程基于 JSON-RPC 的会话MCP 客户端和服务器之间通过JSON-RPC 2.0协议进行通信这是一种轻量级的远程过程调用规范。通信通常建立在stdio标准输入/输出或SSE服务器发送事件之上这使得部署非常简单就像在命令行中调用一个脚本一样。一个典型的初始化会话流程如下客户端启动服务器进程或连接到服务器端点。双方交换initialize请求和响应协商协议版本、能力客户端声明它支持哪些特性服务器声明它提供了哪些资源和工具。服务器发送notifications告知客户端其初始的资源列表和工具列表。此后客户端就可以根据需要调用tools/call来执行工具或者发送resources/read请求来读取资源内容。2.3 设计精髓安全、标准化与可发现性MCP 协议的设计有几个关键优势这也是它迅速流行的原因安全性 工具的执行权限完全由服务器进程控制。AI 客户端只是发送请求它本身没有直接的系统权限。如果你搭建一个只读的文件服务器那么 AI 无论如何也无法通过它删除文件。这种沙箱化的设计至关重要。标准化 无论底层是操作文件、查询数据库还是调用天气 API对客户端AI而言交互方式都是统一的列出工具、调用工具。这极大地简化了 AI 应用集成外部能力的复杂度。可发现性 客户端可以在运行时动态发现服务器提供了哪些能力和资源无需预先硬编码。这使得插拔式扩展成为可能。注意 不要把 MCP 和 “Skill”、“Plugin” 等概念完全混淆。在某些平台如 Cursor的语境下“Skill” 可能特指其内部的一套功能模块系统而 MCP 是一种更底层、更通用的协议。一个 “Skill” 可以通过集成一个 MCP 服务器来实现。简单理解MCP 是通用的“电源插座”标准而 Skill/Plugin 是具体的“电器”很多“电器”会选择使用标准的“插座”来获取电力能力。3. 从零搭建一个 MCP 服务器的完整实操理论懂了我们动手建一个。这里我将以搭建一个“本地文件系统浏览器” MCP 服务器为例这是最实用、最能体现 MCP 价值的场景之一。我们将使用TypeScript/Node.js和官方modelcontextprotocol/sdk来实现。3.1 环境准备与项目初始化首先确保你的开发环境已经就绪node --version # 推荐 Node.js 18 npm --version # 或 yarn/pnpm然后创建项目并安装核心依赖mkdir mcp-file-server cd mcp-file-server npm init -y npm install modelcontextprotocol/sdk npm install -D typescript ts-node types/node初始化 TypeScript 配置npx tsc --init在生成的tsconfig.json中确保target设置为ES2022或更高module设置为NodeNext。3.2 核心服务器代码实现创建src/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 * as fs from fs/promises; import * as path from path; // 1. 创建 Server 实例 const server new Server( { name: local-file-system-server, version: 1.0.0, }, { capabilities: { resources: {}, // 声明支持资源功能 tools: {}, // 声明支持工具功能 }, } ); // 2. 定义安全的根目录。这是关键的安全边界 const SAFE_ROOT process.env.MCP_FILE_ROOT || path.resolve(process.cwd(), ./safe_data); // 建议在启动前确保目录存在或在此处创建 // await fs.mkdir(SAFE_ROOT, { recursive: true }); // 辅助函数将系统路径转换为安全的资源 URI并防止路径遍历攻击 function toSafeUri(filePath: string): string { const resolvedPath path.resolve(SAFE_ROOT, filePath); // 安全检查确保请求的路径在安全根目录之下 if (!resolvedPath.startsWith(path.resolve(SAFE_ROOT))) { throw new Error(Access denied: Path traversal attempt detected.); } // 使用自定义协议如 file:// 可能与其他冲突这里用 fs:// 示意 return fs://${path.relative(SAFE_ROOT, resolvedPath)}; } function fromSafeUri(uri: string): string { const prefix fs://; if (!uri.startsWith(prefix)) { throw new Error(Invalid URI scheme. Expected ${prefix}); } const relativePath uri.substring(prefix.length); return path.resolve(SAFE_ROOT, relativePath); } // 3. 实现 resources/list 处理程序列出目录下的文件和子目录 server.setRequestHandler(ListResourcesRequestSchema, async (request) { // 这里我们可以定义一个根资源或者根据请求参数列出特定目录。 // 为了简单我们总是列出安全根目录的内容。 try { const items await fs.readdir(SAFE_ROOT, { withFileTypes: true }); const resources await Promise.all( items.map(async (item) { const itemPath path.join(SAFE_ROOT, item.name); const uri toSafeUri(item.name); const stat await fs.stat(itemPath); return { uri: uri, mimeType: item.isDirectory() ? application/x-directory : text/plain, // 简化实际应根据扩展名判断 name: item.name, description: item.isDirectory() ? Directory: ${item.name} : File: ${item.name} (${stat.size} bytes), }; }) ); return { resources }; } catch (error) { console.error(Failed to list directory ${SAFE_ROOT}:, error); return { resources: [] }; } }); // 4. 实现 resources/read 处理程序读取文件内容 server.setRequestHandler(ReadResourceRequestSchema, async (request) { const { uri } request.params; try { const filePath fromSafeUri(uri); const stat await fs.stat(filePath); if (stat.isDirectory()) { throw new Error(Cannot read a directory as a resource.); } // 可选添加文件大小限制防止读取超大文件 const MAX_FILE_SIZE 10 * 1024 * 1024; // 10MB if (stat.size MAX_FILE_SIZE) { throw new Error(File too large (${stat.size} bytes). Maximum allowed is ${MAX_FILE_SIZE} bytes.); } // 读取文件内容这里假设是文本文件。二进制文件需要不同的处理如base64编码。 const content await fs.readFile(filePath, utf-8); return { contents: [{ uri: uri, mimeType: text/plain, // 应动态检测 text: content, }], }; } catch (error: any) { console.error(Failed to read resource ${uri}:, error); throw new Error(Failed to read resource: ${error.message}); } }); // 5. 实现 tools/list 处理程序声明我们提供的工具 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ { name: search_in_files, description: Search for a text pattern within files under the safe directory., inputSchema: { type: object, properties: { pattern: { type: string, description: The text or regex pattern to search for., }, fileExtension: { type: string, description: Optional. Filter files by extension (e.g., .md, .txt)., }, }, required: [pattern], }, }, { name: get_file_info, description: Get metadata (size, modified time) of a specific file., inputSchema: { type: object, properties: { fileUri: { type: string, description: The URI of the file (e.g., fs://myfile.txt)., }, }, required: [fileUri], }, }, ], }; }); // 6. 实现 tools/call 处理程序执行具体的工具 server.setRequestHandler(CallToolRequestSchema, async (request) { const { name, arguments: args } request.params; if (name search_in_files) { const { pattern, fileExtension } args as { pattern: string; fileExtension?: string }; // 实现一个简单的递归文件搜索示例生产环境需优化性能 const results: Array{uri: string; line: number; content: string} []; async function searchDir(dir: string) { const items await fs.readdir(dir, { withFileTypes: true }); for (const item of items) { const fullPath path.join(dir, item.name); if (item.isDirectory()) { await searchDir(fullPath); } else { if (fileExtension !item.name.endsWith(fileExtension)) { continue; } const uri toSafeUri(path.relative(SAFE_ROOT, fullPath)); try { const content await fs.readFile(fullPath, utf-8); const lines content.split(\n); lines.forEach((line, index) { if (line.includes(pattern)) { // 简单包含匹配可升级为正则 results.push({ uri, line: index 1, content: line.trim(), }); } }); } catch (e) { // 忽略无法读取的文件如二进制文件 } } } } await searchDir(SAFE_ROOT); return { content: [{ type: text, text: results.length 0 ? Found pattern ${pattern} in ${results.length} location(s):\n results.map(r - ${r.uri}:${r.line}: ${r.content}).join(\n) : Pattern ${pattern} not found in any readable files., }], }; } else if (name get_file_info) { const { fileUri } args as { fileUri: string }; try { const filePath fromSafeUri(fileUri); const stat await fs.stat(filePath); if (stat.isDirectory()) { throw new Error(URI points to a directory, not a file.); } return { content: [{ type: text, text: File Info for ${fileUri}:\n - Size: ${stat.size} bytes\n - Created: ${stat.birthtime.toISOString()}\n - Modified: ${stat.mtime.toISOString()}, }], }; } catch (error: any) { return { content: [{ type: text, text: Error getting file info: ${error.message}, }], isError: true, }; } } else { throw new Error(Unknown tool: ${name}); } }); // 7. 启动服务器使用 stdio 传输层 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP File Server running on stdio...); } main().catch((error) { console.error(Server fatal error:, error); process.exit(1); });3.3 编译与运行在package.json中添加启动脚本{ scripts: { build: tsc, start: node dist/server.js, dev: ts-node src/server.ts } }运行开发版本npm run dev此时服务器会启动并等待来自 stdio 的输入。它本身不会输出到控制台除了错误信息因为它的输出是给 MCP 客户端的 JSON-RPC 消息。4. 在 AI 客户端中配置与使用你的 MCP 服务器服务器建好了怎么让 AI 用上它这里以Claude Desktop和Cursor为例。4.1 在 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你需要编辑这个 JSON 文件在mcpServers对象中添加你的服务器配置{ mcpServers: { local-files: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-file-server/dist/server.js ], env: { MCP_FILE_ROOT: /ABSOLUTE/PATH/TO/YOUR/SAFE/DATA/DIR } } // ... 可以配置其他服务器 } }关键提示必须使用绝对路径相对路径在桌面应用的上下文中可能无法解析。MCP_FILE_ROOT环境变量是我们代码中定义的安全根目录。务必将其设置为你希望 AI 能够访问的目录例如~/Documents/ai_safe。切勿设置为/或~等敏感目录保存配置后需要完全重启 Claude Desktop 应用配置才会生效。重启后当你与 Claude 对话时它应该能自动发现新的工具。你可以尝试让它“请列出我文件服务器根目录下的内容”或者“搜索所有.md文件中关于‘项目总结’的文字”。4.2 在 Cursor 中配置Cursor 的配置更灵活可以在项目级别或全局级别设置。推荐在项目根目录创建.cursor/mcp.json文件进行配置{ mcpServers: { local-files: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-file-server/dist/server.js ], env: { MCP_FILE_ROOT: ${workspaceFolder}/ai_accessible } } } }这里${workspaceFolder}是 Cursor 的内置变量指向当前打开的项目根目录这样配置更便携。同样配置后需要重启 Cursor 或重新加载项目。4.3 验证与交互配置成功后在 AI 对话界面你通常能看到新工具的出现例如在 Claude Desktop 的输入框上方会有工具图标。你可以直接指示 AI 使用这些工具“使用文件搜索工具在我可访问的文档里找一下‘第一季度财报’这个词。”“帮我看看fs://project_plan.md这个文件的大小和修改时间。”AI 会理解你的指令自动调用对应的 MCP 工具并将执行结果融入它的回复中。5. 进阶构建更复杂的 MCP 服务器基础的文件服务器只是开始。MCP 的威力在于连接万物。下面探讨几个进阶方向5.1 数据库服务器以 SQLite 为例你可以构建一个服务器允许 AI 安全地查询你的 SQLite 数据库。关键在于严格控制权限。核心思路服务器连接到指定的 SQLite 数据库文件。暴露的工具可以是run_query。安全设计只读连接 在连接字符串中使用modero。查询白名单/黑名单 在服务器端解析 SQL禁止INSERT,UPDATE,DELETE,DROP等危险语句或者只允许执行预定义的、参数化的查询模板。资源限制 设置查询超时时间如 5 秒和最大返回行数如 1000 行。工具设计run_query工具接收一个sql参数仅限 SELECT和一个可选的params数组用于参数化查询防止 SQL 注入。5.2 Web 搜索/API 集成服务器类似 Tavily、Brave Search 的 MCP 服务器其核心是封装一个搜索引擎的 API。核心思路 服务器内集成搜索引擎的 SDK 或直接调用其 REST API。暴露search工具。实现要点API 密钥管理 密钥应通过环境变量传入服务器绝对不要硬编码在代码或客户端配置中。结果格式化 将 API 返回的 JSON 数据整理成 AI 易于理解和引用的文本格式并附上来源链接。错误处理 妥善处理网络超时、API 限额、无效查询等情况返回友好的错误信息。5.3 浏览器自动化服务器使用 Playwright这是一个非常强大的场景让 AI 可以控制浏览器进行网页抓取、表单填写、截图等操作。核心思路 服务器启动一个无头浏览器实例如 Chromium通过 Playwright 库进行控制。暴露如navigate,screenshot,extract_text,click_element等工具。安全与性能挑战沙箱隔离 每个工具调用应在独立的浏览器上下文或页面中进行操作结束后及时清理防止会话间污染和内存泄漏。超时控制 严格设置页面加载和操作执行的超时时间。资源限制 限制并发操作数量防止服务器过载。风险提示 明确告知用户此工具将访问外部网站可能存在不可控内容。6. 开发、调试与部署中的核心问题在实际搭建和运行 MCP 服务器时你会遇到一些典型问题。6.1 调试技巧MCP 服务器运行在 stdio 模式下直接调试可能困难。以下是有效方法启用服务器端日志 在代码关键位置如请求处理开始/结束、错误捕获处使用console.error()输出日志。这些信息会打印到 stderr你可以在启动命令时重定向到文件查看。node server.js 2 server.log使用 MCP Inspector 这是官方提供的强大调试工具。首先全局安装npm install -g modelcontextprotocol/inspector。然后通过 Inspector 启动你的服务器mcp-inspector node server.js它会启动一个本地 Web 界面让你可以直观地看到所有 JSON-RPC 请求和响应是调试协议通信的利器。模拟客户端测试 可以写一个简单的测试脚本模拟客户端向你的服务器发送初始化、列表工具、调用工具等请求来验证服务器逻辑。6.2 常见错误与排查问题现象可能原因排查步骤客户端无法连接/超时1. 服务器启动失败或立即崩溃。2. 命令或路径错误。3. 服务器未正确处理 stdio。1. 单独在终端运行服务器命令看是否有错误输出。2. 检查配置文件中的命令和路径特别是绝对路径。3. 确保服务器代码正确调用了server.connect(transport)且没有提前退出。客户端提示“未知工具”或“资源列表为空”1. 服务器未正确注册请求处理器。2.ListToolsRequest或ListResourcesRequest的响应格式错误。3. 初始化失败能力协商未通过。1. 使用 MCP Inspector 查看初始化交换和列表请求/响应。2. 检查setRequestHandler是否绑定正确返回的 JSON 结构是否符合协议定义。工具调用失败或返回意外结果1. 工具参数验证失败。2. 服务器端逻辑错误或异常未捕获。3. 权限问题如文件不可读。1. 查看服务器 stderr 日志中的错误堆栈。2. 在工具处理函数内部添加详细的 try-catch并返回包含isError: true的响应。3. 检查工具输入模式schema是否与客户端发送的参数匹配。性能低下如搜索慢服务器实现效率低如递归遍历大量文件未做优化。1. 对耗时操作添加索引、缓存或分页机制。2. 考虑使用更高效的库或算法。3. 在工具描述中提醒用户此操作可能较慢。6.3 安全最佳实践这是自建 MCP 服务器的生命线。最小权限原则 服务器进程应以最低必要权限运行。为文件服务器设置专用的、权限受限的目录。数据库服务器使用只读用户。输入验证与净化 对所有来自客户端的输入如文件路径、SQL 查询片段、URL进行严格验证和净化防止路径遍历、SQL 注入、命令注入等攻击。环境变量管理 API 密钥、数据库密码等敏感信息必须通过环境变量传递切勿写入代码或配置文件并提交到版本库。资源与速率限制 对工具执行时间、内存使用、返回数据大小、调用频率进行限制防止服务器被意外或恶意请求拖垮。网络隔离 如果服务器需要访问内部网络服务确保其网络访问范围是受限的避免成为跳板。6.4 部署考量进程管理 对于长期运行的服务考虑使用systemd(Linux)、launchd(macOS) 或进程管理器如 PM2来保证其稳定运行和自动重启。更新与版本化 当你的服务器能力升级时注意维护协议版本的兼容性。可以在服务器信息中声明版本号客户端可以据此调整行为。跨平台兼容性 如果你的服务器涉及文件路径操作要处理好 Windows 和 Unix-like 系统之间的路径分隔符差异使用path模块。搭建自己的 MCP 服务器是一个从“使用 AI”到“塑造 AI 能力”的质变点。它要求你不仅理解 AI 如何思考更要设计好 AI 与真实世界交互的接口与边界。这个过程充满挑战但当你看到 AI 能流畅地操作你为其定制的工具时那种“它真的能帮我干活了”的成就感是无与伦比的。从最简单的文件浏览器开始逐步尝试连接数据库、集成 API、控制硬件你将一步步构建起属于你自己的、拥有无限扩展能力的智能体生态系统。
1. 项目概述为什么我们需要 MCP最近在折腾 AI 应用开发的朋友估计都绕不开一个词MCP也就是 Model Context Protocol。这玩意儿听起来挺唬人协议、标准啥的但说白了它就是一个让大模型比如 Claude、GPT能安全、方便地调用外部工具和数据的“接线员”和“翻译官”。想象一下你有一个能力超强的 AI 助手但它被困在一个封闭的房间里房间里只有几本固定的参考书。你想让它帮你查一下最新的股价、控制一下家里的智能灯或者分析一下你数据库里的销售数据它都无能为力。MCP 要做的就是给这个房间开一扇扇安全可控的“窗户”每扇窗户都连接着一个特定的外部能力——可能是搜索引擎、数据库、文件系统甚至是一个代码执行环境。AI 助手通过 MCP 这扇“窗户”就能看到外面的世界并动手操作。所以“从零搭建 MCP 服务”这个事核心价值就在于赋予 AI 真正的“动手能力”和“感知能力”。它不再是那个只会聊天的“鹦鹉”而变成了一个能帮你真正干活的“数字员工”。无论是通过 AI 一键分析本地文档、自动操作浏览器进行数据抓取还是连接公司内部的业务系统MCP 都是实现这些场景的关键桥梁。市面上像 Cursor、Claude Desktop、Windsurf 这些先进的 AI 编程或桌面助手其背后强大的插件生态很多都基于或兼容 MCP 协议。自己搭建 MCP 服务意味着你可以定制化地扩展 AI 的能力边界让它无缝融入你的个人工作流或企业技术栈而不再受限于官方或第三方提供的有限工具。2. MCP 核心原理与架构拆解要搭建先得弄明白它到底是怎么工作的。MCP 不是一个具体的软件而是一套通信协议和规范。它的架构非常清晰主要包含三个角色2.1 核心角色客户端、服务器与资源MCP 客户端 通常就是大模型应用本身。比如 Claude Desktop、Cursor IDE或者任何集成了 MCP 客户端库的应用。它的职责是发起请求比如“我想读一下/home/user/report.md这个文件”或者“请用搜索引擎查一下‘MCP 最新动态’”。MCP 服务器 这就是我们要搭建的核心。它是一个独立的进程封装了具体的功能逻辑。一个服务器可以提供一种或多种“工具”和“资源”。例如一个“文件系统服务器”提供了读写文件的工具一个“SQLite 服务器”提供了执行 SQL 查询的工具。服务器监听客户端的请求执行实际操作并返回结果。资源与工具 这是服务器暴露给客户端的能力实体。资源 通常指数据比如一个文件、一张数据库表、一个网页的 URL。资源有唯一的标识符URI和描述性的元数据MIME 类型、名称等。客户端可以“列出”和“读取”资源。工具 通常指可执行的操作比如“执行命令”、“运行搜索”、“发送 HTTP 请求”。工具需要输入参数执行后返回输出结果。2.2 通信流程基于 JSON-RPC 的会话MCP 客户端和服务器之间通过JSON-RPC 2.0协议进行通信这是一种轻量级的远程过程调用规范。通信通常建立在stdio标准输入/输出或SSE服务器发送事件之上这使得部署非常简单就像在命令行中调用一个脚本一样。一个典型的初始化会话流程如下客户端启动服务器进程或连接到服务器端点。双方交换initialize请求和响应协商协议版本、能力客户端声明它支持哪些特性服务器声明它提供了哪些资源和工具。服务器发送notifications告知客户端其初始的资源列表和工具列表。此后客户端就可以根据需要调用tools/call来执行工具或者发送resources/read请求来读取资源内容。2.3 设计精髓安全、标准化与可发现性MCP 协议的设计有几个关键优势这也是它迅速流行的原因安全性 工具的执行权限完全由服务器进程控制。AI 客户端只是发送请求它本身没有直接的系统权限。如果你搭建一个只读的文件服务器那么 AI 无论如何也无法通过它删除文件。这种沙箱化的设计至关重要。标准化 无论底层是操作文件、查询数据库还是调用天气 API对客户端AI而言交互方式都是统一的列出工具、调用工具。这极大地简化了 AI 应用集成外部能力的复杂度。可发现性 客户端可以在运行时动态发现服务器提供了哪些能力和资源无需预先硬编码。这使得插拔式扩展成为可能。注意 不要把 MCP 和 “Skill”、“Plugin” 等概念完全混淆。在某些平台如 Cursor的语境下“Skill” 可能特指其内部的一套功能模块系统而 MCP 是一种更底层、更通用的协议。一个 “Skill” 可以通过集成一个 MCP 服务器来实现。简单理解MCP 是通用的“电源插座”标准而 Skill/Plugin 是具体的“电器”很多“电器”会选择使用标准的“插座”来获取电力能力。3. 从零搭建一个 MCP 服务器的完整实操理论懂了我们动手建一个。这里我将以搭建一个“本地文件系统浏览器” MCP 服务器为例这是最实用、最能体现 MCP 价值的场景之一。我们将使用TypeScript/Node.js和官方modelcontextprotocol/sdk来实现。3.1 环境准备与项目初始化首先确保你的开发环境已经就绪node --version # 推荐 Node.js 18 npm --version # 或 yarn/pnpm然后创建项目并安装核心依赖mkdir mcp-file-server cd mcp-file-server npm init -y npm install modelcontextprotocol/sdk npm install -D typescript ts-node types/node初始化 TypeScript 配置npx tsc --init在生成的tsconfig.json中确保target设置为ES2022或更高module设置为NodeNext。3.2 核心服务器代码实现创建src/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 * as fs from fs/promises; import * as path from path; // 1. 创建 Server 实例 const server new Server( { name: local-file-system-server, version: 1.0.0, }, { capabilities: { resources: {}, // 声明支持资源功能 tools: {}, // 声明支持工具功能 }, } ); // 2. 定义安全的根目录。这是关键的安全边界 const SAFE_ROOT process.env.MCP_FILE_ROOT || path.resolve(process.cwd(), ./safe_data); // 建议在启动前确保目录存在或在此处创建 // await fs.mkdir(SAFE_ROOT, { recursive: true }); // 辅助函数将系统路径转换为安全的资源 URI并防止路径遍历攻击 function toSafeUri(filePath: string): string { const resolvedPath path.resolve(SAFE_ROOT, filePath); // 安全检查确保请求的路径在安全根目录之下 if (!resolvedPath.startsWith(path.resolve(SAFE_ROOT))) { throw new Error(Access denied: Path traversal attempt detected.); } // 使用自定义协议如 file:// 可能与其他冲突这里用 fs:// 示意 return fs://${path.relative(SAFE_ROOT, resolvedPath)}; } function fromSafeUri(uri: string): string { const prefix fs://; if (!uri.startsWith(prefix)) { throw new Error(Invalid URI scheme. Expected ${prefix}); } const relativePath uri.substring(prefix.length); return path.resolve(SAFE_ROOT, relativePath); } // 3. 实现 resources/list 处理程序列出目录下的文件和子目录 server.setRequestHandler(ListResourcesRequestSchema, async (request) { // 这里我们可以定义一个根资源或者根据请求参数列出特定目录。 // 为了简单我们总是列出安全根目录的内容。 try { const items await fs.readdir(SAFE_ROOT, { withFileTypes: true }); const resources await Promise.all( items.map(async (item) { const itemPath path.join(SAFE_ROOT, item.name); const uri toSafeUri(item.name); const stat await fs.stat(itemPath); return { uri: uri, mimeType: item.isDirectory() ? application/x-directory : text/plain, // 简化实际应根据扩展名判断 name: item.name, description: item.isDirectory() ? Directory: ${item.name} : File: ${item.name} (${stat.size} bytes), }; }) ); return { resources }; } catch (error) { console.error(Failed to list directory ${SAFE_ROOT}:, error); return { resources: [] }; } }); // 4. 实现 resources/read 处理程序读取文件内容 server.setRequestHandler(ReadResourceRequestSchema, async (request) { const { uri } request.params; try { const filePath fromSafeUri(uri); const stat await fs.stat(filePath); if (stat.isDirectory()) { throw new Error(Cannot read a directory as a resource.); } // 可选添加文件大小限制防止读取超大文件 const MAX_FILE_SIZE 10 * 1024 * 1024; // 10MB if (stat.size MAX_FILE_SIZE) { throw new Error(File too large (${stat.size} bytes). Maximum allowed is ${MAX_FILE_SIZE} bytes.); } // 读取文件内容这里假设是文本文件。二进制文件需要不同的处理如base64编码。 const content await fs.readFile(filePath, utf-8); return { contents: [{ uri: uri, mimeType: text/plain, // 应动态检测 text: content, }], }; } catch (error: any) { console.error(Failed to read resource ${uri}:, error); throw new Error(Failed to read resource: ${error.message}); } }); // 5. 实现 tools/list 处理程序声明我们提供的工具 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ { name: search_in_files, description: Search for a text pattern within files under the safe directory., inputSchema: { type: object, properties: { pattern: { type: string, description: The text or regex pattern to search for., }, fileExtension: { type: string, description: Optional. Filter files by extension (e.g., .md, .txt)., }, }, required: [pattern], }, }, { name: get_file_info, description: Get metadata (size, modified time) of a specific file., inputSchema: { type: object, properties: { fileUri: { type: string, description: The URI of the file (e.g., fs://myfile.txt)., }, }, required: [fileUri], }, }, ], }; }); // 6. 实现 tools/call 处理程序执行具体的工具 server.setRequestHandler(CallToolRequestSchema, async (request) { const { name, arguments: args } request.params; if (name search_in_files) { const { pattern, fileExtension } args as { pattern: string; fileExtension?: string }; // 实现一个简单的递归文件搜索示例生产环境需优化性能 const results: Array{uri: string; line: number; content: string} []; async function searchDir(dir: string) { const items await fs.readdir(dir, { withFileTypes: true }); for (const item of items) { const fullPath path.join(dir, item.name); if (item.isDirectory()) { await searchDir(fullPath); } else { if (fileExtension !item.name.endsWith(fileExtension)) { continue; } const uri toSafeUri(path.relative(SAFE_ROOT, fullPath)); try { const content await fs.readFile(fullPath, utf-8); const lines content.split(\n); lines.forEach((line, index) { if (line.includes(pattern)) { // 简单包含匹配可升级为正则 results.push({ uri, line: index 1, content: line.trim(), }); } }); } catch (e) { // 忽略无法读取的文件如二进制文件 } } } } await searchDir(SAFE_ROOT); return { content: [{ type: text, text: results.length 0 ? Found pattern ${pattern} in ${results.length} location(s):\n results.map(r - ${r.uri}:${r.line}: ${r.content}).join(\n) : Pattern ${pattern} not found in any readable files., }], }; } else if (name get_file_info) { const { fileUri } args as { fileUri: string }; try { const filePath fromSafeUri(fileUri); const stat await fs.stat(filePath); if (stat.isDirectory()) { throw new Error(URI points to a directory, not a file.); } return { content: [{ type: text, text: File Info for ${fileUri}:\n - Size: ${stat.size} bytes\n - Created: ${stat.birthtime.toISOString()}\n - Modified: ${stat.mtime.toISOString()}, }], }; } catch (error: any) { return { content: [{ type: text, text: Error getting file info: ${error.message}, }], isError: true, }; } } else { throw new Error(Unknown tool: ${name}); } }); // 7. 启动服务器使用 stdio 传输层 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP File Server running on stdio...); } main().catch((error) { console.error(Server fatal error:, error); process.exit(1); });3.3 编译与运行在package.json中添加启动脚本{ scripts: { build: tsc, start: node dist/server.js, dev: ts-node src/server.ts } }运行开发版本npm run dev此时服务器会启动并等待来自 stdio 的输入。它本身不会输出到控制台除了错误信息因为它的输出是给 MCP 客户端的 JSON-RPC 消息。4. 在 AI 客户端中配置与使用你的 MCP 服务器服务器建好了怎么让 AI 用上它这里以Claude Desktop和Cursor为例。4.1 在 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你需要编辑这个 JSON 文件在mcpServers对象中添加你的服务器配置{ mcpServers: { local-files: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-file-server/dist/server.js ], env: { MCP_FILE_ROOT: /ABSOLUTE/PATH/TO/YOUR/SAFE/DATA/DIR } } // ... 可以配置其他服务器 } }关键提示必须使用绝对路径相对路径在桌面应用的上下文中可能无法解析。MCP_FILE_ROOT环境变量是我们代码中定义的安全根目录。务必将其设置为你希望 AI 能够访问的目录例如~/Documents/ai_safe。切勿设置为/或~等敏感目录保存配置后需要完全重启 Claude Desktop 应用配置才会生效。重启后当你与 Claude 对话时它应该能自动发现新的工具。你可以尝试让它“请列出我文件服务器根目录下的内容”或者“搜索所有.md文件中关于‘项目总结’的文字”。4.2 在 Cursor 中配置Cursor 的配置更灵活可以在项目级别或全局级别设置。推荐在项目根目录创建.cursor/mcp.json文件进行配置{ mcpServers: { local-files: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-file-server/dist/server.js ], env: { MCP_FILE_ROOT: ${workspaceFolder}/ai_accessible } } } }这里${workspaceFolder}是 Cursor 的内置变量指向当前打开的项目根目录这样配置更便携。同样配置后需要重启 Cursor 或重新加载项目。4.3 验证与交互配置成功后在 AI 对话界面你通常能看到新工具的出现例如在 Claude Desktop 的输入框上方会有工具图标。你可以直接指示 AI 使用这些工具“使用文件搜索工具在我可访问的文档里找一下‘第一季度财报’这个词。”“帮我看看fs://project_plan.md这个文件的大小和修改时间。”AI 会理解你的指令自动调用对应的 MCP 工具并将执行结果融入它的回复中。5. 进阶构建更复杂的 MCP 服务器基础的文件服务器只是开始。MCP 的威力在于连接万物。下面探讨几个进阶方向5.1 数据库服务器以 SQLite 为例你可以构建一个服务器允许 AI 安全地查询你的 SQLite 数据库。关键在于严格控制权限。核心思路服务器连接到指定的 SQLite 数据库文件。暴露的工具可以是run_query。安全设计只读连接 在连接字符串中使用modero。查询白名单/黑名单 在服务器端解析 SQL禁止INSERT,UPDATE,DELETE,DROP等危险语句或者只允许执行预定义的、参数化的查询模板。资源限制 设置查询超时时间如 5 秒和最大返回行数如 1000 行。工具设计run_query工具接收一个sql参数仅限 SELECT和一个可选的params数组用于参数化查询防止 SQL 注入。5.2 Web 搜索/API 集成服务器类似 Tavily、Brave Search 的 MCP 服务器其核心是封装一个搜索引擎的 API。核心思路 服务器内集成搜索引擎的 SDK 或直接调用其 REST API。暴露search工具。实现要点API 密钥管理 密钥应通过环境变量传入服务器绝对不要硬编码在代码或客户端配置中。结果格式化 将 API 返回的 JSON 数据整理成 AI 易于理解和引用的文本格式并附上来源链接。错误处理 妥善处理网络超时、API 限额、无效查询等情况返回友好的错误信息。5.3 浏览器自动化服务器使用 Playwright这是一个非常强大的场景让 AI 可以控制浏览器进行网页抓取、表单填写、截图等操作。核心思路 服务器启动一个无头浏览器实例如 Chromium通过 Playwright 库进行控制。暴露如navigate,screenshot,extract_text,click_element等工具。安全与性能挑战沙箱隔离 每个工具调用应在独立的浏览器上下文或页面中进行操作结束后及时清理防止会话间污染和内存泄漏。超时控制 严格设置页面加载和操作执行的超时时间。资源限制 限制并发操作数量防止服务器过载。风险提示 明确告知用户此工具将访问外部网站可能存在不可控内容。6. 开发、调试与部署中的核心问题在实际搭建和运行 MCP 服务器时你会遇到一些典型问题。6.1 调试技巧MCP 服务器运行在 stdio 模式下直接调试可能困难。以下是有效方法启用服务器端日志 在代码关键位置如请求处理开始/结束、错误捕获处使用console.error()输出日志。这些信息会打印到 stderr你可以在启动命令时重定向到文件查看。node server.js 2 server.log使用 MCP Inspector 这是官方提供的强大调试工具。首先全局安装npm install -g modelcontextprotocol/inspector。然后通过 Inspector 启动你的服务器mcp-inspector node server.js它会启动一个本地 Web 界面让你可以直观地看到所有 JSON-RPC 请求和响应是调试协议通信的利器。模拟客户端测试 可以写一个简单的测试脚本模拟客户端向你的服务器发送初始化、列表工具、调用工具等请求来验证服务器逻辑。6.2 常见错误与排查问题现象可能原因排查步骤客户端无法连接/超时1. 服务器启动失败或立即崩溃。2. 命令或路径错误。3. 服务器未正确处理 stdio。1. 单独在终端运行服务器命令看是否有错误输出。2. 检查配置文件中的命令和路径特别是绝对路径。3. 确保服务器代码正确调用了server.connect(transport)且没有提前退出。客户端提示“未知工具”或“资源列表为空”1. 服务器未正确注册请求处理器。2.ListToolsRequest或ListResourcesRequest的响应格式错误。3. 初始化失败能力协商未通过。1. 使用 MCP Inspector 查看初始化交换和列表请求/响应。2. 检查setRequestHandler是否绑定正确返回的 JSON 结构是否符合协议定义。工具调用失败或返回意外结果1. 工具参数验证失败。2. 服务器端逻辑错误或异常未捕获。3. 权限问题如文件不可读。1. 查看服务器 stderr 日志中的错误堆栈。2. 在工具处理函数内部添加详细的 try-catch并返回包含isError: true的响应。3. 检查工具输入模式schema是否与客户端发送的参数匹配。性能低下如搜索慢服务器实现效率低如递归遍历大量文件未做优化。1. 对耗时操作添加索引、缓存或分页机制。2. 考虑使用更高效的库或算法。3. 在工具描述中提醒用户此操作可能较慢。6.3 安全最佳实践这是自建 MCP 服务器的生命线。最小权限原则 服务器进程应以最低必要权限运行。为文件服务器设置专用的、权限受限的目录。数据库服务器使用只读用户。输入验证与净化 对所有来自客户端的输入如文件路径、SQL 查询片段、URL进行严格验证和净化防止路径遍历、SQL 注入、命令注入等攻击。环境变量管理 API 密钥、数据库密码等敏感信息必须通过环境变量传递切勿写入代码或配置文件并提交到版本库。资源与速率限制 对工具执行时间、内存使用、返回数据大小、调用频率进行限制防止服务器被意外或恶意请求拖垮。网络隔离 如果服务器需要访问内部网络服务确保其网络访问范围是受限的避免成为跳板。6.4 部署考量进程管理 对于长期运行的服务考虑使用systemd(Linux)、launchd(macOS) 或进程管理器如 PM2来保证其稳定运行和自动重启。更新与版本化 当你的服务器能力升级时注意维护协议版本的兼容性。可以在服务器信息中声明版本号客户端可以据此调整行为。跨平台兼容性 如果你的服务器涉及文件路径操作要处理好 Windows 和 Unix-like 系统之间的路径分隔符差异使用path模块。搭建自己的 MCP 服务器是一个从“使用 AI”到“塑造 AI 能力”的质变点。它要求你不仅理解 AI 如何思考更要设计好 AI 与真实世界交互的接口与边界。这个过程充满挑战但当你看到 AI 能流畅地操作你为其定制的工具时那种“它真的能帮我干活了”的成就感是无与伦比的。从最简单的文件浏览器开始逐步尝试连接数据库、集成 API、控制硬件你将一步步构建起属于你自己的、拥有无限扩展能力的智能体生态系统。
