1. 项目概述为什么我们需要一个能读本地文件的服务最近在折腾一些AI应用开发发现一个挺普遍的需求如何让大语言模型LLM安全、可控地访问我电脑上的本地文件比如我想让AI帮我分析一份刚下载的销售数据CSV或者总结几篇PDF技术文档的核心观点。直接把文件内容一股脑儿贴进聊天窗口文件大了不行格式乱了更头疼。用现成的云服务或API又涉及到数据隐私和网络依赖的问题。这时候MCPModel Context Protocol就进入了我的视野。简单来说MCP是一个新兴的开放协议它定义了一套标准让各种“工具”比如文件读取器、数据库连接器能够以一种统一的方式被不同的AI应用或“客户端”比如Claude Desktop、Cursor等发现和调用。你可以把它想象成AI世界的“USB标准”——只要设备工具符合USB协议MCP就能插到不同的电脑客户端上即插即用。所以“写一个能读本地文件的极简服务”这个项目本质上就是在创建一个符合MCP协议的“文件读取工具”。这个工具本身是一个独立的服务器进程它暴露出“读取文件”的能力。任何支持MCP的AI客户端都可以通过标准的“握手”流程连接到这个服务器然后像调用本地函数一样让它去读取指定路径的文件内容并将结果安全地返回给AI模型使用。这个项目的价值在于解耦和安全。工具服务和AI应用客户端是分离的你可以独立维护和升级这个文件读取服务。更重要的是你可以通过配置精确控制这个服务能访问文件系统的哪些范围比如仅限于某个工作目录避免了让AI应用本身获得过高的、不受控的文件系统权限从架构上提升了安全性。接下来我就带你从零开始手把手实现一个这样的极简MCP服务。2. MCP核心概念与项目设计思路在动手写代码之前我们必须先吃透MCP的几个核心概念这样才能理解我们到底要构建什么。2.1 MCP协议的三要素MCP的交互主要涉及三个角色理解它们之间的关系是成功的关键客户端 (Client)通常是最终用户直接交互的AI应用例如Claude Desktop、Cursor IDE或者你自己写的AI助手前端。它的核心职责是向模型如GPT-4、Claude 3提供上下文Context并执行模型选择的工具Tool。服务器 (Server)也就是我们要构建的“文件读取服务”。它是一个独立的进程负责实现具体的功能逻辑如读文件、查数据库。服务器向客户端宣告自己提供了哪些“工具”Tools和“资源”Resources。协议 (Protocol)连接客户端和服务器的“语言”和“规则”。MCP协议基于JSON-RPC 2.0定义了一系列标准的请求Request和通知Notification用于初始化连接、列出工具、调用工具、传输数据等。在我们的项目中我们将扮演服务器的开发者。我们需要创建一个程序它启动后监听某个端口等待MCP客户端比如配置好的Claude Desktop来连接。一旦连接建立客户端会询问“嘿你有什么能力” 我们的服务器就回答“我能提供一个叫read_file的工具。” 当用户在客户端中要求AI读文件时AI模型就会通过客户端发送一个请求“请调用read_file工具参数是path/home/user/doc.txt。” 我们的服务器收到请求后执行读取文件的操作然后将文件内容或错误信息封装成标准格式回复给客户端。2.2 工具Tools与资源Resources辨析这是两个容易混淆但至关重要的概念工具 (Tool)代表一个可执行的动作或函数。它有自己的名称、描述、参数列表。调用工具会产生一个结果。在我们的文件服务里read_file就是一个工具它接受一个文件路径参数执行“读取”这个动作返回文件内容。资源 (Resource)代表一个可被读取或引用的数据实体。它有自己的URI、MIME类型和内容。资源通常用于提供静态或动态的上下文信息而不需要“执行”动作。例如你可以设计一个file://资源客户端可以直接请求某个URI对应的文件内容。MCP客户端通常能更原生地处理资源比如直接将其内容作为上下文喂给模型。对于这个入门项目我们从更直观、更通用的“工具”入手。实现一个read_file工具足够简单并且能清晰地展示MCP的完整调用流程。未来扩展时你可以考虑同时提供资源file://和工具read_file让客户端根据场景选择最合适的方式。2.3 极简服务的设计蓝图基于以上理解我们的项目设计思路如下技术选型使用Node.js和官方modelcontextprotocol/sdk库。Node.js生态成熟SDK封装了底层的JSON-RPC通信细节让我们能专注于业务逻辑。这是最快速、最稳妥的入门路径。核心功能实现一个单一的read_file工具。它接收一个path字符串参数读取该路径对应的文本文件如.txt,.md,.json,.js等并以字符串形式返回内容。对于二进制文件或非文本文件我们暂时返回错误。安全边界服务启动时通过命令行参数或环境变量指定一个允许访问的根目录rootDir。所有传入的path参数都会被解析并限制在这个根目录之下防止目录穿越攻击如../../../etc/passwd。这是生产环境必须考虑的安全措施。通信方式采用stdio标准输入/输出作为传输层。这是MCP服务器最常见的部署方式。客户端如Claude Desktop会启动我们的服务器进程并通过管道pipe与其stdin/stdout进行通信。这种方式无需处理网络端口更简单、更通用。整个架构的流程图在脑海中是这样的用户输入 - AI客户端 - MCP请求 - 我们的Node.js服务器 - 读取本地文件 - MCP响应 - AI客户端 - 呈现给用户。下面我们就进入具体的实现环节。3. 开发环境准备与项目初始化工欲善其事必先利其器。我们先来把开发环境搭好。3.1 安装Node.js与包管理工具首先确保你的系统上安装了Node.js (版本18或以上)和npm。打开终端运行以下命令检查node --version npm --version如果未安装请前往 Node.js 官网下载并安装LTS版本。我个人习惯使用nvm(Node Version Manager) 来管理多个Node.js版本这在同时维护多个不同项目时非常方便。接下来创建一个新的项目目录并初始化mkdir mcp-file-server cd mcp-file-server npm init -y这会在当前目录生成一个package.json文件。3.2 安装MCP SDK依赖我们将使用 Anthropic 官方维护的 JavaScript/TypeScript SDK。它极大地简化了服务器和客户端的开发。npm install modelcontextprotocol/sdk同时为了获得更好的开发体验类型提示、自动补全我强烈建议安装 TypeScript 及相关类型定义。即使你写的是纯JavaScripttypes/node也能提供Node.js API的类型提示。npm install --save-dev typescript types/node npx tsc --init # 生成tsconfig.json配置文件生成的tsconfig.json可以保持默认或者根据你的喜好调整。一个适合本项目的简单配置如下{ compilerOptions: { target: ES2022, module: NodeNext, moduleResolution: NodeNext, outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src/**/*], exclude: [node_modules] }3.3 项目结构规划让我们规划一个清晰的项目结构mcp-file-server/ ├── src/ │ ├── index.ts # 服务器主入口文件 │ └── tools/ │ └── fileReader.ts # 文件读取工具的具体实现 ├── dist/ # TypeScript编译输出目录自动生成 ├── package.json └── tsconfig.json现在package.json中的scripts字段可以更新一下方便我们编译和运行{ scripts: { build: tsc, start: node dist/index.js, dev: tsx src/index.ts // 如果你使用tsx进行直接运行 } }实操心得在开发初期我更喜欢使用tsx或ts-node这样的工具它们能直接运行TypeScript文件省去手动编译的步骤非常适合快速迭代调试。你可以通过npm install --save-dev tsx来安装它。4. 核心实现构建文件读取工具服务器环境就绪现在开始编写核心代码。我们将从定义工具开始逐步构建出完整的服务器。4.1 定义read_file工具首先在src/tools/fileReader.ts中我们创建这个核心工具。根据MCP SDK的规范一个工具需要定义其输入参数的模式JSON Schema和一个异步的执行函数。// src/tools/fileReader.ts import { Tool } from modelcontextprotocol/sdk/server.js; import * as fs from fs/promises; import * as path from path; /** * 创建文件读取工具 * param rootDir 允许访问的文件系统根目录用于安全限制 */ export function createReadFileTool(rootDir: string): Tool { return { name: read_file, description: 读取指定路径的文本文件内容。路径必须是绝对路径或相对于服务根目录的路径。, inputSchema: { type: object, properties: { path: { type: string, description: 要读取的文件的路径。, }, }, required: [path], additionalProperties: false, }, handler: async (args: { path?: string }) { const filePath args.path; if (!filePath) { throw new Error(必须提供文件路径参数“path”。); } // 1. 安全检查解析路径并限制在rootDir内 const resolvedPath path.resolve(rootDir, filePath); const normalizedRoot path.resolve(rootDir); const normalizedResolved path.resolve(resolvedPath); if (!normalizedResolved.startsWith(normalizedRoot)) { throw new Error(禁止访问根目录之外的路径${filePath}。); } // 2. 检查路径是否存在且为文件 let stats; try { stats await fs.stat(normalizedResolved); } catch (error: any) { if (error.code ENOENT) { throw new Error(文件不存在${normalizedResolved}); } throw new Error(无法访问文件${error.message}); } if (!stats.isFile()) { throw new Error(路径不是一个文件${normalizedResolved}); } // 3. 读取文件内容这里假设是文本文件使用utf-8编码 try { const content await fs.readFile(normalizedResolved, utf-8); return { content: [ { type: text, text: 成功读取文件${normalizedResolved}\n\n文件内容如下\n\\\\n${content}\n\\\, }, ], }; } catch (error: any) { // 处理读取错误例如权限不足或二进制文件 throw new Error(读取文件失败${error.message}); } }, }; }关键点解析输入模式 (inputSchema)我们定义了一个名为path的必需字符串参数。additionalProperties: false表示不接受未定义的额外参数这有助于避免错误。安全处理 (handler)路径解析与限制使用path.resolve将用户输入的相对路径与预设的rootDir合并并解析为绝对路径。然后检查解析后的路径是否以rootDir的绝对路径开头。这是防止目录穿越攻击的关键。存在性与类型检查使用fs.stat检查路径是否存在以及是否是普通文件。避免尝试读取目录或不存在的路径。错误处理对每一步可能出现的错误文件不存在、非文件、读取失败都进行了捕获并抛出带有明确信息的错误。这些错误会被SDK捕获并转化为标准的MCP错误响应返回给客户端。返回值handler返回一个包含content数组的对象。我们返回一个类型为text的内容块将文件内容用代码块包裹便于客户端尤其是AI模型清晰识别。4.2 创建MCP服务器并注册工具接下来在src/index.ts中我们创建服务器实例并将上面定义的工具注册进去。// src/index.ts import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { createReadFileTool } from ./tools/fileReader.js; async function main() { // 1. 获取根目录参数默认为当前工作目录 const rootDirArg process.argv[2]; const rootDir rootDirArg ? path.resolve(rootDirArg) : process.cwd(); console.error([MCP File Server] 启动根目录限制为${rootDir}); // 2. 创建Server实例 const server new Server( { name: mcp-file-server, version: 0.1.0, }, { capabilities: { tools: {}, // 声明我们支持工具 }, } ); // 3. 创建并注册工具 const readFileTool createReadFileTool(rootDir); server.setToolHandler(readFileTool.name, readFileTool.handler); // 同时需要将工具信息告知客户端 server.registerTool(readFileTool); // 4. 创建传输层使用标准输入输出 const transport new StdioServerTransport(); await server.connect(transport); console.error([MCP File Server] 已连接并等待请求...); } main().catch((error) { console.error([MCP File Server] 致命错误:, error); process.exit(1); });关键点解析根目录参数我们通过process.argv[2]获取命令行第一个参数作为安全根目录。这给了使用者灵活性。如果不提供则默认使用Node.js进程的当前工作目录process.cwd()。生产环境强烈建议显式指定一个狭窄的目录。服务器配置Server构造函数接受服务器元信息名称、版本和功能声明。这里我们声明了capabilities.tools表示本服务器提供工具。工具注册这里有两个步骤server.setToolHandler(toolName, handlerFunction)这是核心将工具名称与我们之前定义的handler函数绑定。当调用请求到来时SDK会根据名称找到这个处理函数并执行。server.registerTool(tool)这会将工具的定义名称、描述、参数模式发送给客户端。这样客户端在初始化时就知道这个服务器提供了哪些可用的工具。传输层StdioServerTransport是用于stdio通信的传输层实现。调用server.connect(transport)后服务器就开始监听stdin的输入并将输出写到stdout。4.3 编译与运行测试现在让我们测试一下这个服务器是否能独立运行。编译TypeScriptnpm run build这会在dist/目录下生成编译后的JavaScript文件。直接运行服务器测试stdio模式 由于MCP服务器设计为通过stdio与父进程通信直接运行node dist/index.js会启动并等待输入看起来像是“卡住”了。这是正常的。你可以按CtrlC退出。为了测试我们可以传递一个根目录参数node dist/index.js /Users/YourName/Documents你应该能看到启动日志输出到stderr控制台。一个重要的调试技巧在开发初期你可以编写一个简单的测试脚本模拟客户端向服务器的stdin发送一个JSON-RPC请求比如initialize请求来验证服务器的响应。不过更直观的方法是直接与真实的MCP客户端如Claude Desktop集成测试我们接下来就做这件事。5. 与Claude Desktop集成实战让我们的服务器“活”起来最好的方式就是把它接入一个真正的MCP客户端。Anthropic的Claude Desktop应用是目前最方便的选择之一。5.1 配置Claude DesktopClaude Desktop允许通过配置文件来添加自定义的MCP服务器也称为“本地工具”。找到配置文件位置macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在手动创建即可。编辑配置文件 打开或创建claude_desktop_config.json文件添加如下配置{ mcpServers: { my-file-server: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-file-server/dist/index.js, /ABSOLUTE/PATH/TO/YOUR/ALLOWED/DIRECTORY ] } } }请务必替换上述路径为你的实际路径command: 启动服务器的命令这里是node。args: 传递给命令的参数数组。第一个参数是我们编译好的服务器入口文件index.js的绝对路径。第二个参数是我们希望服务器能访问的根目录的绝对路径例如你的文档文件夹或某个项目文件夹。注意事项路径必须使用绝对路径。使用相对路径或~家目录符号可能会导致Claude Desktop启动服务器失败。在macOS/Linux上你可以使用pwd命令获取当前目录的绝对路径。5.2 测试与验证重启Claude Desktop修改配置文件后完全退出并重新启动Claude Desktop应用。观察连接启动时Claude Desktop会尝试运行你配置的服务器命令。如果配置正确服务器进程会被启动。你可以在系统活动监视器或任务管理器中看到相关的Node.js进程。在对话中使用新建一个对话。尝试输入“请读取/ALLOWED/DIRECTORY下的example.txt文件内容。” 或者更自然地说“帮我看看项目目录里的README.md写了什么。”Claude应该会识别到可用的read_file工具并在后台调用它。你会看到它回复文件的内容。如果失败检查Claude Desktop的应用日志。在macOS上你可以通过运行Console.app控制台在左侧选择你的设备然后搜索“Claude”来查看相关日志。错误信息通常会在这里显示例如node命令未找到、脚本路径错误、权限问题等。检查你的服务器代码是否有语法错误确保npm run build成功。尝试在终端中手动运行配置的命令行看是否能正常启动服务器虽然会“卡住”。5.3 进阶配置使用环境变量与更复杂的参数有时你可能需要传递环境变量给服务器进程或者使用更复杂的启动逻辑。MCP配置支持env字段。{ mcpServers: { my-file-server: { command: node, args: [ /path/to/dist/index.js ], env: { FILE_SERVER_ROOT_DIR: /path/to/allowed/directory, NODE_ENV: production } } } }然后你需要在服务器代码中修改rootDir的获取方式从process.env.FILE_SERVER_ROOT_DIR读取。这种方式更清晰尤其是当参数较多时。// 在 src/index.ts 的 main 函数中 const rootDir process.env.FILE_SERVER_ROOT_DIR || process.cwd();6. 功能扩展与高级特性实现一个基础的只读文本文件服务已经完成。但实际需求往往更复杂。下面我们来探讨几个实用的扩展方向。6.1 支持更多文件类型与编码目前的read_file工具假设所有文件都是UTF-8编码的文本文件。对于其他编码如GBK或非文本文件如图片我们需要扩展。方案一自动检测编码针对文本文件可以使用jschardet或iconv-lite库来检测和转换编码。但注意自动检测并非100%准确。npm install iconv-lite// 在 handler 函数中修改读取部分 import * as iconv from iconv-lite; import * as fs from fs; try { // 先以二进制Buffer形式读取 const buffer await fs.readFile(normalizedResolved); // 尝试用iconv-lite解码这里假设是GBK可扩展为检测 // 更复杂的方案可以集成 jschardet 先检测编码 const detectedEncoding gbk; // 简化示例实际应检测 const content iconv.decode(buffer, detectedEncoding); return { content: [{ type: text, text: content }] }; } catch (decodeError) { // 如果解码失败可能不是文本文件 throw new Error(文件可能不是纯文本或编码不支持。); }方案二处理二进制文件Base64编码对于图片、PDF等二进制文件直接返回文本会乱码。MCP协议支持返回image或resource类型但最简单的方式是将二进制数据转换为Base64字符串返回并注明MIME类型。import * as mime from mime-types; // 需要安装 npm install mime-types // 在 handler 函数中 const buffer await fs.readFile(normalizedResolved); const mimeType mime.lookup(normalizedResolved) || application/octet-stream; if (mimeType.startsWith(text/)) { // 文本文件处理... } else { // 二进制文件返回Base64和MIME类型 const base64Content buffer.toString(base64); return { content: [ { type: text, text: 文件类型: ${mimeType} (二进制文件已Base64编码), }, { // 注意MCP协议目前主要定义text和image类型。 // 返回base64数据供客户端处理。更高级的做法是声明为resource。 type: text, text: data:${mimeType};base64,${base64Content}, }, ], }; }6.2 实现文件列表与搜索工具除了读单个文件列出目录内容或搜索文件也是常见需求。工具list_directory{ name: list_directory, description: 列出指定目录下的文件和子目录。, inputSchema: { type: object, properties: { path: { type: string, description: 目录路径默认为根目录。 }, recursive: { type: boolean, description: 是否递归列出子目录, default: false } }, required: [], }, handler: async (args) { const targetDir args.path ? path.resolve(rootDir, args.path) : rootDir; // ... 安全检查确保在rootDir内... const items await fs.readdir(targetDir, { withFileTypes: true }); const list items.map(dirent ({ name: dirent.name, type: dirent.isDirectory() ? directory : file, path: path.join(targetDir, dirent.name) })); // 格式化输出... return { content: [{ type: text, text: formattedList }] }; } }工具search_files结合fs.readdir递归和文件名过滤或使用glob模式可以实现简单的文件搜索功能。6.3 添加资源Resources支持如前所述资源是MCP中另一个核心概念。我们可以让文件不仅作为工具调用的结果也能作为可直接引用的资源。声明资源模板在服务器初始化时告诉客户端我们支持file://这种URI模式的资源。server.registerResourceTemplate( { uriTemplate: file://{path}, name: 本地文件, description: 访问本地文件系统中的文件, mimeType: text/plain, // 可以更智能地根据扩展名判断 }, async (uri, variables) { // variables.path 对应URI中的 {path} 部分 const filePath variables.path; // 同样的安全检查和文件读取逻辑... const content await fs.readFile(safePath, utf-8); // 返回Resource对象 return { contents: [{ uri: uri, mimeType: text/plain, text: content, }] }; } );客户端使用配置了资源后用户可能在客户端中直接引用file:///project/README.md这样的URI客户端会自动请求我们的服务器获取该资源的内容并将其作为上下文提供给AI模型。这比通过工具调用更直接适合预先加载文档。7. 错误处理、调试与性能优化一个健壮的服务离不开完善的错误处理和调试手段。7.1 增强错误处理与日志我们已经在工具handler中进行了基本的错误抛出。在服务器层面我们可以监听错误事件。// 在 src/index.ts 的 main 函数中创建server后 server.onerror (error) { // 处理服务器级别的错误如协议错误 console.error([MCP Server Error], error); }; // 在工具handler中除了throw也可以考虑返回结构化的错误信息 // 但MCP SDK会将抛出的Error对象转换为标准的JSON-RPC错误响应。日志策略生产环境中应将日志写入文件并区分级别info, warn, error。可以使用winston或pino等日志库。在开发时我们打印到console.error即可因为stdio的stdout需要用于协议通信调试信息应避免写入。7.2 调试技巧使用VS Code调试在.vscode/launch.json中配置调试任务模拟Claude Desktop的启动方式。{ version: 0.2.0, configurations: [ { type: node, request: launch, name: Debug MCP Server, program: ${workspaceFolder}/src/index.ts, args: [${workspaceFolder}/test_dir], // 指定测试根目录 runtimeArgs: [--inspect], // 启用调试器 console: integratedTerminal, internalConsoleOptions: neverOpen, skipFiles: [node_internals/**], runtimeExecutable: node, outFiles: [${workspaceFolder}/dist/**/*.js] } ] }这样你可以打断点单步调试工具处理逻辑。手动模拟客户端请求编写一个简单的测试脚本通过child_process.spawn启动服务器并向其stdin写入格式化的JSON-RPC请求如tools/list或tools/call然后从stdout读取响应。这是验证服务器逻辑的终极手段。7.3 性能考量与优化文件大小限制防止用户意外或故意读取一个巨大的文件如数GB的日志导致内存耗尽或响应超时。可以在读取前检查文件大小 (fs.stat)如果超过阈值如10MB则直接返回错误或提供摘要如读取前几行。if (stats.size 10 * 1024 * 1024) { // 10MB throw new Error(文件过大${stats.size}字节出于性能考虑拒绝读取。); }并发处理Node.js是单线程异步IO对于文件读取这类IO密集型操作并发能力本身很强。但要注意如果你的工具逻辑复杂如全文搜索可能需要使用工作线程Worker Threads来避免阻塞事件循环。对于简单的读文件通常不需要。缓存对于频繁读取的、不常变化的文件如配置文件可以考虑在内存中增加一个简单的缓存使用Map或node-cache库并设置合理的TTL生存时间。但要注意缓存一致性如果文件可能被其他进程修改则需要更复杂的机制或直接禁用缓存。8. 部署、安全考量与后续演进8.1 打包与分发为了让其他人方便使用你可以将项目打包。编译为单一可执行文件使用pkg或nexe可以将Node.js项目打包成一个独立的可执行二进制文件无需目标机器安装Node.js。npm install -g pkg pkg . --targets node18-linux-x64,node18-macos-x64,node18-win-x64 --output dist/mcp-file-server然后在Claude Desktop配置中command就可以直接指向这个可执行文件args只需传根目录参数。发布到npm如果你希望开发者通过npm安装可以发布你的包。在package.json中设置bin字段指向编译后的入口文件。用户可以通过npx your-mcp-file-server /path/to/root来运行。8.2 安全加固建议严格的根目录限制这是最重要的防线。永远不要以/或用户家目录等宽泛路径作为根目录。应该限定在项目所需的最小范围内。输入验证与净化除了检查路径穿越还应过滤或拒绝包含特殊字符如空字符、控制字符的路径。可以使用path.normalize并结合白名单正则表达式。权限最小化运行此服务的系统用户应该只有对rootDir的读取权限没有写入或执行权限。审计日志记录所有工具调用请求路径、时间、结果状态便于事后审计和问题排查。速率限制考虑对来自同一客户端的请求频率做限制防止滥用。8.3 项目演进思路这个极简服务是一个起点你可以根据需求将它扩展成一个功能丰富的“个人知识库助手”或“项目上下文提供者”。支持更多协议除了文件系统可以连接数据库SQLite, PostgreSQL、Notion、Confluence、Git仓库等成为聚合信息的桥梁。内容预处理在返回文件内容前进行智能处理。例如自动提取Markdown的标题大纲、从代码文件中提取函数列表、对大型文本进行分块摘要等。与其他MCP工具组合你的文件服务器可以与其他MCP服务器如网络搜索、代码执行协同工作由AI客户端灵活调度完成更复杂的任务。开发图形化配置界面对于不熟悉命令行的用户可以开发一个简单的本地Web界面用于配置根目录、管理允许的文件类型等。通过这个项目你不仅实现了一个实用的工具更深入理解了MCP协议如何作为AI与外部世界连接的“桥梁”。这种解耦、标准化、可组合的设计思想正是构建下一代AI应用生态的关键。