1. 项目缘起为什么我们需要一个“本地文件读取工具服务”在开发者的日常工作中与本地文件系统打交道是家常便饭。无论是读取配置文件、解析日志、加载静态资源还是处理用户上传的临时文件我们总是在重复编写类似的代码打开文件、读取流、处理编码、关闭资源还要小心翼翼地处理各种异常。当项目从单体应用演进到微服务架构或者需要构建一个前后端分离的、需要安全访问服务器特定目录文件的应用时这个问题就变得更加棘手。你可能会遇到这样的场景一个数据分析后台需要动态读取服务器上生成的报表文件一个内部文档管理系统需要安全地预览用户上传的各类文档或者你只是想为团队构建一个统一的、安全的文件访问网关避免每个服务都直接操作敏感的服务器路径。直接暴露文件系统路径给前端或不信任的服务是危险的而重复编写文件IO代码又是低效的。这时一个标准的、协议化的“文件读取工具服务”就显得尤为必要。它就像一个配备了标准接口和严格安保的文件管家外部请求通过定义好的协议“下单”管家根据指令安全地取回文件内容并封装成标准格式返回。而MCPModel Context Protocol协议正是为这类“工具”与“大脑”通常是AI智能体或核心服务之间的协作提供了一套优秀的“工作语言”。本次实践我们就来亲手打造这样一个基于MCP协议的本地文件读取工具服务让你在需要安全、高效、标准化地暴露文件读取能力时能有一个现成的、可复用的解决方案。2. 理解MCP协议工具与智能体间的“标准插座”在开始动手之前我们必须先搞清楚MCP是什么以及它为何适合这个场景。你可以把MCP想象成电器上的“标准插座”。你的房子核心服务或AI智能体里有电力计算和决策能力但你需要电热水壶文件读取、电视机数据库查询等工具来执行具体任务。MCP就是墙上那个统一的插座标准任何符合这个标准的工具都能即插即用房子无需为每个工具定制一套供电接口。MCP协议的核心思想是标准化工具的描述、调用和结果返回。它主要包含几个关键部分工具声明每个工具都需要向“大脑”注册告诉大脑“我叫什么名字”、“我能干什么描述”、“你需要给我提供哪些参数”。对于我们的文件读取工具就需要声明一个名为read_file的工具描述为“读取指定路径的文本文件内容”并定义一个必需的参数file_path。标准化调用“大脑”通过一个统一的JSON-RPC接口来调用工具。它不需要知道工具内部是用Python、Go还是Rust实现的它只需要按照协议格式发送请求即可。结构化结果工具执行完毕后必须按照协议规定的格式返回结果。这通常包括执行状态成功/失败、返回的内容如文件文本以及可能的结构化数据如元信息。MCP支持返回纯文本、图片甚至HTML片段非常灵活。资源管理MCP还定义了“资源”Resources的概念可以用于动态列出可用的文件列表这对于实现一个文件浏览器式的工具非常有用。选择MCP来实现我们的文件服务有以下几个压倒性优势解耦与标准化服务端工具实现和客户端调用者完全解耦。只要遵循MCP协议你可以用任何语言重写工具端或用任何兼容MCP的客户端如Claude Desktop、Cline IDE、自研AI智能体框架来调用它无需修改对方代码。安全性内建协议层不关心传输安全这允许我们在底层自由选择最安全的通信方式例如在本地使用SSEServer-Sent Events或WebSocket over localhost在生产环境使用带认证的HTTPS。生态友好MCP正在成为AI智能体工具生态的事实标准之一。基于它开发工具意味着你的工具能轻松接入一个快速增长的智能体生态圈潜力巨大。3. 技术选型与项目初始化打造我们的“工具车间”明确了目标和蓝图后我们开始搭建“车间”。技术选型需要平衡开发效率、性能、协议兼容性和部署便利性。服务端语言我们选择Node.js。原因有三一是MCP协议官方提供了完善的Node.js SDKmodelcontextprotocol/sdk能极大降低开发复杂度二是JavaScript/TypeScript在处理IO、JSON和网络请求方面非常高效三是其轻量级和庞大的npm生态便于快速集成和后期扩展。通信协议选择SSE。MCP支持多种传输方式stdio, SSE, WebSocket。对于本地的工具服务SSE是一个简单而高效的选择。它基于HTTP易于理解和调试并且SDK提供了开箱即用的支持。项目初始化mkdir mcp-file-server cd mcp-file-server npm init -y npm install modelcontextprotocol/sdk核心依赖除了MCP SDK我们还需要fsNode.js内置用于文件操作和path内置用于安全地处理路径。为了更好的开发体验我们可以安装TypeScript及相关类型定义npm install -D typescript types/node npx tsc --init在生成的tsconfig.json中确保target设置为ES2022或更高module设置为commonjs或NodeNext。4. 核心工具实现read_file的完整逻辑与安全边界这是本次实践最核心的部分。我们将实现一个健壮、安全的read_file工具。创建一个src/server.ts文件。4.1 工具声明与参数定义首先我们需要导入SDK并声明我们的工具。MCP SDK的核心是Server类我们通过它来注册工具。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ToolSchema, } from modelcontextprotocol/sdk/types.js; import * as fs from fs/promises; import * as path from path; // 1. 创建MCP服务器实例 const server new Server( { name: local-file-reader, version: 0.1.0, }, { capabilities: { tools: {}, // 声明我们将提供工具 }, } ); // 2. 定义 read_file 工具 const readFileTool: ToolSchema { name: read_file, description: 读取指定路径的文本文件内容。支持常见文本编码如utf-8。, inputSchema: { type: object, properties: { file_path: { type: string, description: 要读取的文件的绝对路径或相对于指定根目录的路径。, }, }, required: [file_path], }, };这里的关键是inputSchema它严格定义了客户端调用时必须传递的参数。我们只要求一个file_path。描述写得清晰能帮助调用者尤其是AI正确使用。4.2 实现工具处理函数安全是第一位接下来我们为工具实现处理逻辑并将其注册到服务器上。// 3. 设置一个安全的工作根目录非常重要 const SAFE_ROOT_DIR process.env.FILE_SERVER_ROOT || path.resolve(process.cwd(), safe_data); // 确保安全目录存在 await fs.mkdir(SAFE_ROOT_DIR, { recursive: true }); // 4. 实现工具处理函数 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name ! readFileTool.name) { throw new Error(Unknown tool: ${request.params.name}); } const args request.params.arguments as { file_path: string }; const userProvidedPath args.file_path; // **安全核心步骤1路径规范化与解析** // 防止目录遍历攻击如 ../../../etc/passwd const normalizedPath path.normalize(userProvidedPath); // 如果路径是绝对的直接使用如果是相对的则相对于安全根目录 const targetPath path.isAbsolute(normalizedPath) ? normalizedPath : path.resolve(SAFE_ROOT_DIR, normalizedPath); // **安全核心步骤2路径边界检查** // 确保目标路径在安全根目录之内对于相对路径情况 if (!targetPath.startsWith(path.resolve(SAFE_ROOT_DIR))) { return { content: [ { type: text, text: 错误访问路径 ${userProvidedPath} 被拒绝。出于安全考虑只能访问指定根目录下的文件。, }, ], }; } // **安全核心步骤3路径存在性与类型检查** let stats; try { stats await fs.stat(targetPath); } catch (error: any) { if (error.code ENOENT) { return { content: [ { type: text, text: 错误文件 ${userProvidedPath} 不存在于路径 ${targetPath}。, }, ], }; } throw error; // 抛出其他未知错误 } if (!stats.isFile()) { return { content: [ { type: text, text: 错误路径 ${userProvidedPath} 指向的不是一个普通文件可能是目录。, }, ], }; } // **安全核心步骤4文件大小限制防止读取超大文件导致内存溢出** const MAX_FILE_SIZE 10 * 1024 * 1024; // 10MB if (stats.size MAX_FILE_SIZE) { return { content: [ { type: text, text: 错误文件 ${userProvidedPath} 大小${stats.size}字节超过限制${MAX_FILE_SIZE}字节。, }, ], }; } // 5. 执行安全的文件读取 try { const content await fs.readFile(targetPath, { encoding: utf-8 }); return { content: [ { type: text, // 可以附加一些元信息如文件路径和大小 text: 成功读取文件${targetPath}\n文件大小${stats.size}字节\n--- 内容开始 ---\n${content}\n--- 内容结束 ---, }, ], }; } catch (error: any) { // 处理读取错误如权限不足、编码错误等 return { content: [ { type: text, text: 读取文件时发生错误${error.message}, }, ], }; } });这段代码是工具安全性的基石。我强烈建议你理解每一步path.normalize(): 处理掉路径中的..和.但仅靠它不够。path.resolve()和startsWith()检查这是防御目录遍历攻击的关键。我们将所有访问限制在SAFE_ROOT_DIR或其子目录下。文件类型和大小检查防止误操作目录和内存耗尽攻击。详细的错误返回给调用者明确的错误信息而不是一个晦涩的异常。4.3 注册工具并启动服务器最后将工具声明给服务器并启动传输层。// 6. 在服务器能力中注册工具声明 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [readFileTool], }; }); // 7. 创建传输层并连接这里使用Stdio适合被Claude Desktop等进程调用 const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Local File Reader server running on stdio...);如果你希望作为一个独立的HTTP/SSE服务器运行可以使用new SSEServerTransport(server, options)。为了测试我们先用Stdio。5. 进阶功能实现“资源”与“列表”能力一个只能读取已知路径文件的工具还不够智能。我们经常需要先“浏览”某个目录下有什么文件。MCP的“资源”Resources和“列表”List能力正是为此而生。这能让我们的工具服务更像一个文件浏览器。5.1 定义目录列表资源我们在src/server.ts中增加以下代码import { ListResourcesRequestSchema, ReadResourceRequestSchema, ResourceSchema, } from modelcontextprotocol/sdk/types.js; // 声明一个“目录列表”资源模板 server.setRequestHandler(ListResourcesRequestSchema, async (request) { // 我们可以定义一个资源模式例如 directory://{path} // 这里简单返回一个根目录资源 const resources: ResourceSchema[] [ { uri: directory://${SAFE_ROOT_DIR}, mimeType: application/json, // 我们将返回JSON格式的列表 name: 目录列表: ${SAFE_ROOT_DIR}, description: 显示安全根目录 ${SAFE_ROOT_DIR} 下的文件和子目录, }, ]; return { resources }; });5.2 实现资源内容读取列出文件当客户端请求读取directory:///some/path资源时我们返回该路径下的文件列表。server.setRequestHandler(ReadResourceRequestSchema, async (request) { const uri request.params.uri; if (uri.startsWith(directory://)) { const dirPath uri.slice(directory://.length); const safeDirPath path.resolve(SAFE_ROOT_DIR, dirPath); // 再次进行安全边界检查 if (!safeDirPath.startsWith(path.resolve(SAFE_ROOT_DIR))) { throw new Error(Access denied.); } try { const items await fs.readdir(safeDirPath, { withFileTypes: true }); const list items.map((item) ({ name: item.name, type: item.isDirectory() ? directory : file, path: path.join(dirPath, item.name), })); // 以结构化文本JSON字符串返回便于AI解析 return { contents: [{ uri, mimeType: application/json, text: JSON.stringify(list, null, 2), }], }; } catch (error: any) { return { contents: [{ uri, mimeType: text/plain, text: 无法读取目录 ${dirPath}: ${error.message}, }], }; } } // 如果不是我们处理的资源URI返回空 return { contents: [] }; });现在你的工具服务不仅可以通过read_file工具读取文件内容还能让客户端先“浏览”directory:///资源来获取文件列表然后再用获取到的路径去调用工具。这种组合极大地提升了工具的可用性和智能程度。6. 配置、运行与调试让服务转起来6.1 构建与运行脚本在package.json中添加脚本{ scripts: { build: tsc, start: node dist/server.js, dev: tsx watch src/server.ts } }如果你使用tsx或ts-node进行开发时热重载需要先安装npm install -D tsx。6.2 配置MCP客户端以Claude Desktop为例要让AI桌面应用如Claude Desktop发现并使用你的工具你需要创建一个MCP配置文件。在Claude Desktop的配置目录下macOS:~/Library/Application Support/Claude/claude_desktop_config.json Windows:%APPDATA%\Claude\claude_desktop_config.json添加你的工具服务器配置{ mcpServers: { local-file-reader: { command: node, args: [/ABSOLUTE/PATH/TO/YOUR/PROJECT/dist/server.js], env: { FILE_SERVER_ROOT: /ABSOLUTE/PATH/TO/YOUR/SAFE/DATA } } } }关键点command和args告诉Claude如何启动你的服务器。env设置了环境变量FILE_SERVER_ROOT这会被我们代码中的SAFE_ROOT_DIR使用。务必使用绝对路径。配置完成后重启Claude Desktop。6.3 测试与调试直接测试服务器你可以先不通过Claude直接运行npm run dev观察服务器是否正常启动没有报错。在Claude中验证重启Claude后新建一个对话。你应该能在Claude的“附件”或工具使用区域看到可用的工具。你可以尝试让Claude“使用 read_file 工具读取某个文件”。例如在SAFE_ROOT_DIR下创建一个test.txt文件然后对Claude说“请读取 test.txt 文件的内容。”调试技巧在工具处理函数中添加console.error()打印日志这些日志会输出到Claude Desktop的控制台或你启动服务器的终端。使用try...catch仔细捕获所有可能的异常并返回友好的错误信息。测试边界情况不存在的文件、目录、符号链接、超大文件、包含特殊字符的路径等。7. 生产环境考量与安全加固将这样一个服务用于生产环境需要更周全的考虑。7.1 传输安全与认证本地Stdio通信是安全的因为它是在同一机器上的进程间通信。但如果你部署为网络服务SSE/HTTP则必须考虑HTTPS使用Nginx或Caddy反向代理配置SSL/TLS证书。认证MCP协议本身不处理认证。你需要在服务器端实现。一种简单方式是通过HTTP Basic Auth或Bearer Token。在SSE连接初始化时检查请求头中的认证信息。// 伪代码在创建SSE传输时 import { SSEServerTransport } from modelcontextprotocol/sdk/server/sse.js; const transport new SSEServerTransport(server, { authCallback: async (req) { const token req.headers[authorization]?.replace(Bearer , ); if (token ! EXPECTED_TOKEN) { throw new Error(Unauthorized); } } });7.2 性能与扩展性大文件处理我们代码中设置了10MB限制。对于需要处理大文件的场景如日志文件不应一次性读入内存。可以考虑实现流式读取或者增加一个read_file_chunk工具支持指定偏移量和读取长度。并发与限流Node.js是单线程异步IO能处理较高并发。但对于公开服务仍需实施限流rate limiting防止滥用。可以使用express-rate-limit等中间件。扩展更多工具MCP服务器的优势在于可以轻松扩展。你可以基于相同模式添加write_file需极其谨慎、list_directory我们已通过资源实现、get_file_info等工具构建一个功能完整的文件管理服务。7.3 监控与日志使用winston或pino等日志库结构化记录所有工具调用请求、参数、执行结果和耗时。监控服务器的内存和CPU使用情况。记录所有失败访问的路径和来源用于安全审计。8. 踩坑实录从开发到部署的常见问题在实际开发和测试中我遇到了几个典型问题这里分享出来帮你避坑坑1路径解析导致的权限逃逸最初我直接使用了用户提供的路径path.resolve(userProvidedPath)。如果用户输入/etc/passwd这个绝对路径会直接通过path.isAbsolute()检查导致安全边界失效。教训即使对于绝对路径也应该将其与安全根目录进行解析和比较或者干脆禁止使用绝对路径强制所有路径都相对于SAFE_ROOT_DIR。我们最终的方案是更安全的相对路径基于安全根目录解析绝对路径也必须通过安全边界检查。坑2环境变量路径中的波浪号~在配置FILE_SERVER_ROOT时我习惯性地写了~/projects/safe_data。Node.js的path.resolve()和fs模块不会自动解析波浪号为家目录。这导致服务器启动时找不到目录。解决方案要么在配置中使用绝对路径/Users/username/projects/safe_data要么在代码中手动处理const rootDir process.env.FILE_SERVER_ROOT.replace(/^~(?$|\/|\\)/, require(os).homedir());坑3Claude Desktop 缓存了旧的工具列表在开发过程中你修改了工具的名称或参数但Claude Desktop似乎还在使用旧的工具列表。这是因为客户端可能缓存了服务器的工具声明。解决方法重启Claude Desktop通常可以解决。更彻底的方式是在开发时修改claude_desktop_config.json中服务器的args比如加一个虚拟参数[“dist/server.js”, “--dev”]然后重启Claude强制它重新获取工具列表。坑4文件编码问题我们使用fs.readFile(..., utf-8)。如果文件不是UTF-8编码比如Windows下常见的GBK编码的文本文件读取就会产生乱码。更健壮的做法可以尝试使用jschardet这类库检测编码或者提供一个可选的encoding参数给工具调用者。对于生产环境明确文档说明支持的编码或统一要求UTF-8。通过这个基于MCP协议的本地文件读取工具服务开发实践我们不仅得到了一个实用的工具更深入理解了如何设计一个安全、标准化的服务接口。MCP协议的魅力在于它的简洁和通用性这套模式可以复用到任何你想暴露给AI或其它服务的本地能力上比如数据库查询、调用内部API、发送邮件等。关键在于严谨的安全设计和清晰的工具定义。当你下次再需要让AI安全地触达你的本地环境时不妨考虑用MCP来搭这座桥。
基于MCP协议构建安全本地文件读取服务：Node.js实现与安全实践
1. 项目缘起为什么我们需要一个“本地文件读取工具服务”在开发者的日常工作中与本地文件系统打交道是家常便饭。无论是读取配置文件、解析日志、加载静态资源还是处理用户上传的临时文件我们总是在重复编写类似的代码打开文件、读取流、处理编码、关闭资源还要小心翼翼地处理各种异常。当项目从单体应用演进到微服务架构或者需要构建一个前后端分离的、需要安全访问服务器特定目录文件的应用时这个问题就变得更加棘手。你可能会遇到这样的场景一个数据分析后台需要动态读取服务器上生成的报表文件一个内部文档管理系统需要安全地预览用户上传的各类文档或者你只是想为团队构建一个统一的、安全的文件访问网关避免每个服务都直接操作敏感的服务器路径。直接暴露文件系统路径给前端或不信任的服务是危险的而重复编写文件IO代码又是低效的。这时一个标准的、协议化的“文件读取工具服务”就显得尤为必要。它就像一个配备了标准接口和严格安保的文件管家外部请求通过定义好的协议“下单”管家根据指令安全地取回文件内容并封装成标准格式返回。而MCPModel Context Protocol协议正是为这类“工具”与“大脑”通常是AI智能体或核心服务之间的协作提供了一套优秀的“工作语言”。本次实践我们就来亲手打造这样一个基于MCP协议的本地文件读取工具服务让你在需要安全、高效、标准化地暴露文件读取能力时能有一个现成的、可复用的解决方案。2. 理解MCP协议工具与智能体间的“标准插座”在开始动手之前我们必须先搞清楚MCP是什么以及它为何适合这个场景。你可以把MCP想象成电器上的“标准插座”。你的房子核心服务或AI智能体里有电力计算和决策能力但你需要电热水壶文件读取、电视机数据库查询等工具来执行具体任务。MCP就是墙上那个统一的插座标准任何符合这个标准的工具都能即插即用房子无需为每个工具定制一套供电接口。MCP协议的核心思想是标准化工具的描述、调用和结果返回。它主要包含几个关键部分工具声明每个工具都需要向“大脑”注册告诉大脑“我叫什么名字”、“我能干什么描述”、“你需要给我提供哪些参数”。对于我们的文件读取工具就需要声明一个名为read_file的工具描述为“读取指定路径的文本文件内容”并定义一个必需的参数file_path。标准化调用“大脑”通过一个统一的JSON-RPC接口来调用工具。它不需要知道工具内部是用Python、Go还是Rust实现的它只需要按照协议格式发送请求即可。结构化结果工具执行完毕后必须按照协议规定的格式返回结果。这通常包括执行状态成功/失败、返回的内容如文件文本以及可能的结构化数据如元信息。MCP支持返回纯文本、图片甚至HTML片段非常灵活。资源管理MCP还定义了“资源”Resources的概念可以用于动态列出可用的文件列表这对于实现一个文件浏览器式的工具非常有用。选择MCP来实现我们的文件服务有以下几个压倒性优势解耦与标准化服务端工具实现和客户端调用者完全解耦。只要遵循MCP协议你可以用任何语言重写工具端或用任何兼容MCP的客户端如Claude Desktop、Cline IDE、自研AI智能体框架来调用它无需修改对方代码。安全性内建协议层不关心传输安全这允许我们在底层自由选择最安全的通信方式例如在本地使用SSEServer-Sent Events或WebSocket over localhost在生产环境使用带认证的HTTPS。生态友好MCP正在成为AI智能体工具生态的事实标准之一。基于它开发工具意味着你的工具能轻松接入一个快速增长的智能体生态圈潜力巨大。3. 技术选型与项目初始化打造我们的“工具车间”明确了目标和蓝图后我们开始搭建“车间”。技术选型需要平衡开发效率、性能、协议兼容性和部署便利性。服务端语言我们选择Node.js。原因有三一是MCP协议官方提供了完善的Node.js SDKmodelcontextprotocol/sdk能极大降低开发复杂度二是JavaScript/TypeScript在处理IO、JSON和网络请求方面非常高效三是其轻量级和庞大的npm生态便于快速集成和后期扩展。通信协议选择SSE。MCP支持多种传输方式stdio, SSE, WebSocket。对于本地的工具服务SSE是一个简单而高效的选择。它基于HTTP易于理解和调试并且SDK提供了开箱即用的支持。项目初始化mkdir mcp-file-server cd mcp-file-server npm init -y npm install modelcontextprotocol/sdk核心依赖除了MCP SDK我们还需要fsNode.js内置用于文件操作和path内置用于安全地处理路径。为了更好的开发体验我们可以安装TypeScript及相关类型定义npm install -D typescript types/node npx tsc --init在生成的tsconfig.json中确保target设置为ES2022或更高module设置为commonjs或NodeNext。4. 核心工具实现read_file的完整逻辑与安全边界这是本次实践最核心的部分。我们将实现一个健壮、安全的read_file工具。创建一个src/server.ts文件。4.1 工具声明与参数定义首先我们需要导入SDK并声明我们的工具。MCP SDK的核心是Server类我们通过它来注册工具。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ToolSchema, } from modelcontextprotocol/sdk/types.js; import * as fs from fs/promises; import * as path from path; // 1. 创建MCP服务器实例 const server new Server( { name: local-file-reader, version: 0.1.0, }, { capabilities: { tools: {}, // 声明我们将提供工具 }, } ); // 2. 定义 read_file 工具 const readFileTool: ToolSchema { name: read_file, description: 读取指定路径的文本文件内容。支持常见文本编码如utf-8。, inputSchema: { type: object, properties: { file_path: { type: string, description: 要读取的文件的绝对路径或相对于指定根目录的路径。, }, }, required: [file_path], }, };这里的关键是inputSchema它严格定义了客户端调用时必须传递的参数。我们只要求一个file_path。描述写得清晰能帮助调用者尤其是AI正确使用。4.2 实现工具处理函数安全是第一位接下来我们为工具实现处理逻辑并将其注册到服务器上。// 3. 设置一个安全的工作根目录非常重要 const SAFE_ROOT_DIR process.env.FILE_SERVER_ROOT || path.resolve(process.cwd(), safe_data); // 确保安全目录存在 await fs.mkdir(SAFE_ROOT_DIR, { recursive: true }); // 4. 实现工具处理函数 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name ! readFileTool.name) { throw new Error(Unknown tool: ${request.params.name}); } const args request.params.arguments as { file_path: string }; const userProvidedPath args.file_path; // **安全核心步骤1路径规范化与解析** // 防止目录遍历攻击如 ../../../etc/passwd const normalizedPath path.normalize(userProvidedPath); // 如果路径是绝对的直接使用如果是相对的则相对于安全根目录 const targetPath path.isAbsolute(normalizedPath) ? normalizedPath : path.resolve(SAFE_ROOT_DIR, normalizedPath); // **安全核心步骤2路径边界检查** // 确保目标路径在安全根目录之内对于相对路径情况 if (!targetPath.startsWith(path.resolve(SAFE_ROOT_DIR))) { return { content: [ { type: text, text: 错误访问路径 ${userProvidedPath} 被拒绝。出于安全考虑只能访问指定根目录下的文件。, }, ], }; } // **安全核心步骤3路径存在性与类型检查** let stats; try { stats await fs.stat(targetPath); } catch (error: any) { if (error.code ENOENT) { return { content: [ { type: text, text: 错误文件 ${userProvidedPath} 不存在于路径 ${targetPath}。, }, ], }; } throw error; // 抛出其他未知错误 } if (!stats.isFile()) { return { content: [ { type: text, text: 错误路径 ${userProvidedPath} 指向的不是一个普通文件可能是目录。, }, ], }; } // **安全核心步骤4文件大小限制防止读取超大文件导致内存溢出** const MAX_FILE_SIZE 10 * 1024 * 1024; // 10MB if (stats.size MAX_FILE_SIZE) { return { content: [ { type: text, text: 错误文件 ${userProvidedPath} 大小${stats.size}字节超过限制${MAX_FILE_SIZE}字节。, }, ], }; } // 5. 执行安全的文件读取 try { const content await fs.readFile(targetPath, { encoding: utf-8 }); return { content: [ { type: text, // 可以附加一些元信息如文件路径和大小 text: 成功读取文件${targetPath}\n文件大小${stats.size}字节\n--- 内容开始 ---\n${content}\n--- 内容结束 ---, }, ], }; } catch (error: any) { // 处理读取错误如权限不足、编码错误等 return { content: [ { type: text, text: 读取文件时发生错误${error.message}, }, ], }; } });这段代码是工具安全性的基石。我强烈建议你理解每一步path.normalize(): 处理掉路径中的..和.但仅靠它不够。path.resolve()和startsWith()检查这是防御目录遍历攻击的关键。我们将所有访问限制在SAFE_ROOT_DIR或其子目录下。文件类型和大小检查防止误操作目录和内存耗尽攻击。详细的错误返回给调用者明确的错误信息而不是一个晦涩的异常。4.3 注册工具并启动服务器最后将工具声明给服务器并启动传输层。// 6. 在服务器能力中注册工具声明 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [readFileTool], }; }); // 7. 创建传输层并连接这里使用Stdio适合被Claude Desktop等进程调用 const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Local File Reader server running on stdio...);如果你希望作为一个独立的HTTP/SSE服务器运行可以使用new SSEServerTransport(server, options)。为了测试我们先用Stdio。5. 进阶功能实现“资源”与“列表”能力一个只能读取已知路径文件的工具还不够智能。我们经常需要先“浏览”某个目录下有什么文件。MCP的“资源”Resources和“列表”List能力正是为此而生。这能让我们的工具服务更像一个文件浏览器。5.1 定义目录列表资源我们在src/server.ts中增加以下代码import { ListResourcesRequestSchema, ReadResourceRequestSchema, ResourceSchema, } from modelcontextprotocol/sdk/types.js; // 声明一个“目录列表”资源模板 server.setRequestHandler(ListResourcesRequestSchema, async (request) { // 我们可以定义一个资源模式例如 directory://{path} // 这里简单返回一个根目录资源 const resources: ResourceSchema[] [ { uri: directory://${SAFE_ROOT_DIR}, mimeType: application/json, // 我们将返回JSON格式的列表 name: 目录列表: ${SAFE_ROOT_DIR}, description: 显示安全根目录 ${SAFE_ROOT_DIR} 下的文件和子目录, }, ]; return { resources }; });5.2 实现资源内容读取列出文件当客户端请求读取directory:///some/path资源时我们返回该路径下的文件列表。server.setRequestHandler(ReadResourceRequestSchema, async (request) { const uri request.params.uri; if (uri.startsWith(directory://)) { const dirPath uri.slice(directory://.length); const safeDirPath path.resolve(SAFE_ROOT_DIR, dirPath); // 再次进行安全边界检查 if (!safeDirPath.startsWith(path.resolve(SAFE_ROOT_DIR))) { throw new Error(Access denied.); } try { const items await fs.readdir(safeDirPath, { withFileTypes: true }); const list items.map((item) ({ name: item.name, type: item.isDirectory() ? directory : file, path: path.join(dirPath, item.name), })); // 以结构化文本JSON字符串返回便于AI解析 return { contents: [{ uri, mimeType: application/json, text: JSON.stringify(list, null, 2), }], }; } catch (error: any) { return { contents: [{ uri, mimeType: text/plain, text: 无法读取目录 ${dirPath}: ${error.message}, }], }; } } // 如果不是我们处理的资源URI返回空 return { contents: [] }; });现在你的工具服务不仅可以通过read_file工具读取文件内容还能让客户端先“浏览”directory:///资源来获取文件列表然后再用获取到的路径去调用工具。这种组合极大地提升了工具的可用性和智能程度。6. 配置、运行与调试让服务转起来6.1 构建与运行脚本在package.json中添加脚本{ scripts: { build: tsc, start: node dist/server.js, dev: tsx watch src/server.ts } }如果你使用tsx或ts-node进行开发时热重载需要先安装npm install -D tsx。6.2 配置MCP客户端以Claude Desktop为例要让AI桌面应用如Claude Desktop发现并使用你的工具你需要创建一个MCP配置文件。在Claude Desktop的配置目录下macOS:~/Library/Application Support/Claude/claude_desktop_config.json Windows:%APPDATA%\Claude\claude_desktop_config.json添加你的工具服务器配置{ mcpServers: { local-file-reader: { command: node, args: [/ABSOLUTE/PATH/TO/YOUR/PROJECT/dist/server.js], env: { FILE_SERVER_ROOT: /ABSOLUTE/PATH/TO/YOUR/SAFE/DATA } } } }关键点command和args告诉Claude如何启动你的服务器。env设置了环境变量FILE_SERVER_ROOT这会被我们代码中的SAFE_ROOT_DIR使用。务必使用绝对路径。配置完成后重启Claude Desktop。6.3 测试与调试直接测试服务器你可以先不通过Claude直接运行npm run dev观察服务器是否正常启动没有报错。在Claude中验证重启Claude后新建一个对话。你应该能在Claude的“附件”或工具使用区域看到可用的工具。你可以尝试让Claude“使用 read_file 工具读取某个文件”。例如在SAFE_ROOT_DIR下创建一个test.txt文件然后对Claude说“请读取 test.txt 文件的内容。”调试技巧在工具处理函数中添加console.error()打印日志这些日志会输出到Claude Desktop的控制台或你启动服务器的终端。使用try...catch仔细捕获所有可能的异常并返回友好的错误信息。测试边界情况不存在的文件、目录、符号链接、超大文件、包含特殊字符的路径等。7. 生产环境考量与安全加固将这样一个服务用于生产环境需要更周全的考虑。7.1 传输安全与认证本地Stdio通信是安全的因为它是在同一机器上的进程间通信。但如果你部署为网络服务SSE/HTTP则必须考虑HTTPS使用Nginx或Caddy反向代理配置SSL/TLS证书。认证MCP协议本身不处理认证。你需要在服务器端实现。一种简单方式是通过HTTP Basic Auth或Bearer Token。在SSE连接初始化时检查请求头中的认证信息。// 伪代码在创建SSE传输时 import { SSEServerTransport } from modelcontextprotocol/sdk/server/sse.js; const transport new SSEServerTransport(server, { authCallback: async (req) { const token req.headers[authorization]?.replace(Bearer , ); if (token ! EXPECTED_TOKEN) { throw new Error(Unauthorized); } } });7.2 性能与扩展性大文件处理我们代码中设置了10MB限制。对于需要处理大文件的场景如日志文件不应一次性读入内存。可以考虑实现流式读取或者增加一个read_file_chunk工具支持指定偏移量和读取长度。并发与限流Node.js是单线程异步IO能处理较高并发。但对于公开服务仍需实施限流rate limiting防止滥用。可以使用express-rate-limit等中间件。扩展更多工具MCP服务器的优势在于可以轻松扩展。你可以基于相同模式添加write_file需极其谨慎、list_directory我们已通过资源实现、get_file_info等工具构建一个功能完整的文件管理服务。7.3 监控与日志使用winston或pino等日志库结构化记录所有工具调用请求、参数、执行结果和耗时。监控服务器的内存和CPU使用情况。记录所有失败访问的路径和来源用于安全审计。8. 踩坑实录从开发到部署的常见问题在实际开发和测试中我遇到了几个典型问题这里分享出来帮你避坑坑1路径解析导致的权限逃逸最初我直接使用了用户提供的路径path.resolve(userProvidedPath)。如果用户输入/etc/passwd这个绝对路径会直接通过path.isAbsolute()检查导致安全边界失效。教训即使对于绝对路径也应该将其与安全根目录进行解析和比较或者干脆禁止使用绝对路径强制所有路径都相对于SAFE_ROOT_DIR。我们最终的方案是更安全的相对路径基于安全根目录解析绝对路径也必须通过安全边界检查。坑2环境变量路径中的波浪号~在配置FILE_SERVER_ROOT时我习惯性地写了~/projects/safe_data。Node.js的path.resolve()和fs模块不会自动解析波浪号为家目录。这导致服务器启动时找不到目录。解决方案要么在配置中使用绝对路径/Users/username/projects/safe_data要么在代码中手动处理const rootDir process.env.FILE_SERVER_ROOT.replace(/^~(?$|\/|\\)/, require(os).homedir());坑3Claude Desktop 缓存了旧的工具列表在开发过程中你修改了工具的名称或参数但Claude Desktop似乎还在使用旧的工具列表。这是因为客户端可能缓存了服务器的工具声明。解决方法重启Claude Desktop通常可以解决。更彻底的方式是在开发时修改claude_desktop_config.json中服务器的args比如加一个虚拟参数[“dist/server.js”, “--dev”]然后重启Claude强制它重新获取工具列表。坑4文件编码问题我们使用fs.readFile(..., utf-8)。如果文件不是UTF-8编码比如Windows下常见的GBK编码的文本文件读取就会产生乱码。更健壮的做法可以尝试使用jschardet这类库检测编码或者提供一个可选的encoding参数给工具调用者。对于生产环境明确文档说明支持的编码或统一要求UTF-8。通过这个基于MCP协议的本地文件读取工具服务开发实践我们不仅得到了一个实用的工具更深入理解了如何设计一个安全、标准化的服务接口。MCP协议的魅力在于它的简洁和通用性这套模式可以复用到任何你想暴露给AI或其它服务的本地能力上比如数据库查询、调用内部API、发送邮件等。关键在于严谨的安全设计和清晰的工具定义。当你下次再需要让AI安全地触达你的本地环境时不妨考虑用MCP来搭这座桥。