手写MCP文件读写Server：为AI大模型打造安全可控的本地文件操作能力

最新推荐文章于 2026-08-24 15:56:25 发布

原创

最新推荐文章于 2026-08-24 15:56:25 发布 · 445 阅读

AI 时代程序员必备技能

Claude Code 完整实战，MCP 与子代理工程化落地，让 AI 接管脏活累活

一键订阅

1. 项目概述：为什么大模型需要“手”去“触摸”硬盘？

最近在折腾大模型应用开发的朋友，估计都绕不开一个词：MCP Server。你可能已经用上了各种现成的MCP工具，比如读取网页、查询天气，但有没有想过，如果能让大模型直接、安全地操作你本地硬盘上的文件，会是什么场景？想象一下，你只需要对大模型说“帮我把上周的会议纪要整理成摘要，并保存到‘工作总结’文件夹”，它就能自动完成——这不再是科幻。今天，我们就来动手实现这个核心能力：手写一个文件读写的MCP Server，让大模型真正拥有“触摸”你硬盘的“手”。

简单来说，MCP（Model Context Protocol）是大模型与外部工具和数据的“接线员”。一个MCP Server就是一个专门的服务，它定义了一套标准接口，让大模型可以安全、可控地调用它背后的功能。我们这次要做的，就是一个专门处理文件读、写、列表等操作的Server。这不仅仅是调用一个API那么简单，它涉及到权限边界、安全沙箱、数据格式转换等一系列工程问题。为什么非要自己写？因为现成的文件操作MCP可能不符合你的具体安全策略，或者你想深度定制操作逻辑（比如只允许操作特定目录、自动备份修改前的文件等）。自己动手，才能完全掌控大模型与你的数据世界交互的每一道关卡。

这个项目适合谁？如果你是对大模型应用开发感兴趣的开发者，已经了解了基本的API调用，想深入Agent或工具调用层；或者你是某个垂直领域的从业者，希望将大模型能力深度集成到自己的文件管理、知识库构建等 workflows 中，那么跟着走一遍这个从零到一的构建过程，会让你对MCP的机制、安全设计和系统集成有透彻的理解。我们将使用最通用的技术栈（TypeScript/Node.js）来构建，确保思路可以平移到Python、Go等其他语言。核心不是语法，而是设计理念和避坑经验。

2. 核心设计：在安全笼子里给大模型一把“钥匙”

在让大模型操作你的文件之前，第一个蹦进脑子的问题肯定是：这安全吗？太危险了吧！没错，直接给大模型一个 rm -rf / 的权限无疑是灾难。因此，我们整个MCP Server的设计核心，就是**“最小权限原则” 和 “操作透明化”**。我们不是给大模型开放一个终端，而是为它精心打造一套仅包含几个特定动作的、有严格边界和审计日志的“工具套件”。

2.1 协议与接口设计：定义大模型能“说”的话

MCP协议的核心是工具（Tools）和资源（Resources）。对于文件读写Server，我们主要定义工具。

工具定义 ：我们需要告诉大模型，我这个Server提供了哪些“手部动作”。至少需要三个：
- read_file ：读取文件内容。输入是文件路径（ path ），输出是文件内容字符串。
- write_file ：写入或创建文件。输入是文件路径（ path ）和内容（ content ），输出是操作成功状态。
- list_directory ：列出目录内容。输入是目录路径（ path ），输出是文件/子目录列表。
在设计工具输入时，要尽可能明确和受限。例如， path 参数可以设计为只接受相对路径（相对于一个预先配置好的根目录），或者必须匹配某个白名单模式，从源头杜绝跨目录访问。
通信协议 ：MCP Server通常通过stdio（标准输入输出）或HTTP与MCP客户端（如Claude Desktop、支持MCP的AI应用）通信。我们选择stdio，因为它部署简单，适合本地一体化应用。通信消息是JSON-RPC格式。这意味着我们的Server需要持续监听 process.stdin ，解析收到的JSON-RPC请求，调用对应的工具函数，再将结果封装成JSON-RPC响应写入 process.stdout 。

2.2 安全沙箱设计：划定不可逾越的边界

这是项目的重中之重。我们需要在代码层面构建多道防线。

根目录锁定（Chroot思想） ：Server启动时，从一个配置项或环境变量中读取一个绝对路径作为 BASE_DIR （例如 /Users/YourName/AIManagedDocs ）。所有文件操作的工具函数，在解析完路径参数后，第一件事就是将用户传入的路径与 BASE_DIR 进行解析和校验，确保最终的操作路径不会逃逸出 BASE_DIR 。这可以通过Node.js的 path.resolve 和 path.relative 方法来实现。如果解析后的路径不在 BASE_DIR 下，直接返回错误。
```
const path = require('path');
const BASE_DIR = process.env.MCP_FILE_BASE || '/safe/root';

function resolveSafePath(userPath) {
    const resolvedPath = path.resolve(BASE_DIR, userPath);
    const relativePath = path.relative(BASE_DIR, resolvedPath);
    // 检查是否试图向上穿越根目录
    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
        throw new Error('Access denied: Path outside of allowed directory.');
    }
    return resolvedPath;
}
```
操作白名单与黑名单 ：可以在 BASE_DIR 内进一步限制。例如，通过一个配置文件，设置禁止写入的目录（如 /system ， /backup ），或只允许读取特定扩展名的文件（如 .txt , .md , .json ）。在工