基于 MCP 协议实现本地文件读取工具服务开发实践

一、什么是 MCP 文件处理服务

MCP 全称 Model Context Protocol，是面向大模型上下文交互的标准化通信协议，核心作用是打通大模型与本地系统资源（文件、数据库、接口等）的调用通道。传统大模型仅能处理输入文本，无法直接读写本地磁盘文件；而基于 MCP 协议开发的文件处理服务，可作为独立中间服务，通过标准 IO 流与大模型客户端双向通信，让 LLM 具备本地文件读取、解析能力。

本文基于 Node.js 生态，结合官方 MCP SDK、Zod 数据校验库与 Node 原生 fs 异步模块，从零搭建一套可直接运行的read_file文件读取 MCP 服务，完整覆盖协议通信、参数校验、文件 IO 异常处理全流程。

二、核心技术栈说明

本次开发依赖三类核心依赖，各司其职构建完整 MCP 服务能力：

@modelcontextprotocol/sdk MCP 官方标准 SDK，封装服务实例、传输通道、工具注册、协议报文编解码全套逻辑，内置McpServer服务实例与StdioServerTransport标准输入输出传输层，实现客户端与服务端基于 stdin/stdout 的进程间通信，无需手动处理底层 TCP、HTTP 报文。
Zod强类型数据校验库，替代手动编写 JSON Schema。在注册 MCP 工具时直接通过 Zod 声明参数类型、描述，SDK 会自动完成入参校验，非法参数直接拦截并返回标准化错误，简化参数校验逻辑。
**fs/promises（Node 原生）**Node.js 异步文件系统 API，基于 Promise 封装文件读写操作，搭配 async/await 实现无回调地狱的文件读取，统一捕获文件不存在、权限不足、路径非法等异常。

整体通信链路完整流程

客户端交互完整链路清晰可追溯：客户端提示词 (Prompt) → LLM 大模型解析需求 → 识别需要调用本地文件能力 → 发起 MCP 工具调用请求 → 客户端 Stdio 传输通道 (StdioServerTransport) → 进程标准输入 stdin 传递至 MCP 服务端 → 服务执行文件读取逻辑 → 读取结果 / 错误信息通过 stdout 输出 → 回传给客户端传输层 → 数据返回 LLM → 模型结合文件内容生成最终回复。

三、完整服务代码实现解析

项目核心文件为server.js，是 MCP 文件读取服务唯一入口，下面分段拆解实现逻辑：

1. 模块导入与服务初始化

javascript

运行

javascript 复制代码

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import fs from 'fs/promises';

// 初始化MCP服务实例，定义服务名称与版本标识
const server = new McpServer({
  name: 'simple-read-mcp',
  version: '1.0.0'
});

McpServer：MCP 服务核心实例，承载所有自定义工具注册、协议响应逻辑；
StdioServerTransport：标准 IO 传输通道，是本地单机 MCP 服务最常用传输方式，无需额外端口占用；
服务名称与版本用于客户端识别多 MCP 服务，区分不同能力插件。

2. 注册文件读取工具 read_file

MCP 通过server.tool()方法注册可被 LLM 调用的工具，参数包含工具名称、功能描述、参数校验 Schema、异步执行回调：

javascript

运行

javascript 复制代码

server.tool(
  "read_file",
  "读取指定路径的本地文件内容",
  {
    path: z.string().describe("文件的绝对或相对路径")
  },
  async ({ path }) => {
    try {
      // 以UTF-8编码读取文本文件
      const content = await fs.readFile(path, 'utf-8');
      return {
        content: [{ type: "text", text: content }]
      };
    } catch (err) {
      // 文件读取异常统一捕获，返回MCP标准错误结构
      return {
        isError: true,
        content: [{ type: "text", text: `读取文件失败：${err.message}` }]
      };
    }
  }
);

关键设计亮点：

Zod 自动参数校验 ：使用z.string()约束 path 必须为字符串，搭配 describe 生成工具参数说明，LLM 调用时会自动识别参数含义，无需手动维护 JSON Schema；
标准化返回结构 ：成功 / 失败均遵循 MCP 规范返回content数组，文本内容统一封装type: "text"；
全局异常捕获 ：捕获文件不存在、权限拒绝、目录路径、编码错误等全部 IO 异常，通过isError标记错误状态，客户端可直观区分调用成功与失败。

3. 启动标准 IO 传输服务

javascript

运行

javascript 复制代码

async function main() {
  // 实例化标准IO传输通道
  const transport = new StdioServerTransport();
  // 服务绑定传输通道，开始监听stdin输入
  await server.connect(transport);
  // 使用console.error打印启动日志（stdout会被MCP协议占用，不能用普通console.log）
  console.error("MCP read_file 服务已启动(stdio模式)");
}
// 捕获服务启动全局异常
main().catch(console.error);

这里有一个关键开发细节：MCP 协议会占用进程标准输出 stdout 传输报文，因此服务日志、打印信息必须使用console.error输出至标准错误流 stderr，否则会破坏协议通信，导致客户端解析报文失败。

四、项目开发规范与扩展优化方案

1. 基础开发规范（源自 readme.md 设计规范）

工具能力必须通过 Schema 声明函数名、入参、路径描述，保证 LLM 能理解调用规则；
所有服务必须完整兼容 MCP 官方通信协议，优先使用 SDK 内置 Transport，不自定义底层通信；
文件操作统一使用异步 Promise API，避免同步 fs 阻塞 MCP 服务通信；
所有外部 IO 操作（文件、网络）必须添加 try/catch 异常捕获，返回标准化错误信息。

2. 可新增扩展功能（原文基础上拓展）

现有服务仅支持单一文件读取，在生产场景可基于同一架构快速拓展能力，无需重构底层通信逻辑：

新增 list_dir 目录浏览工具 基于fs.readdir实现，接收文件夹路径参数，返回目录下所有文件、子文件夹列表，让 LLM 可遍历本地目录；
新增 write_file 文件写入工具增加 path、content 两个 Zod 参数，支持文本覆盖写入、追加写入，实现模型修改本地文件；
文件类型限制与安全校验新增路径白名单校验，禁止读取系统敏感目录（/etc、C:\Windows 等），防止越权文件访问；增加文件大小限制，拒绝读取超大文件避免内存溢出；
多传输通道兼容除 Stdio 本地模式外，拓展 WebSocket、HTTP Transport，支持远程客户端调用 MCP 文件服务；
日志分级与持久化替换简单 console.error，引入日志库区分 INFO、ERROR、WARN 日志，将读取失败、非法调用记录写入本地日志文件，便于问题排查。

五、服务使用与运行流程

环境准备初始化 Node 项目，安装依赖：

bash

运行
bash 复制代码
```
npm install @modelcontextprotocol/sdk zod
```
启动服务 执行node server.js，终端输出MCP read_file 服务已启动(stdio模式)代表服务就绪；
客户端对接 大模型客户端（支持 MCP 协议的 AI 编辑器、客户端）通过子进程拉起本服务，基于 stdin/stdout 建立通信；LLM 在需要读取本地文件时，自动调用read_file工具并传入文件路径，服务返回文件文本内容供模型分析。

六、总结

本文实现的基于 MCP 协议的文件读取服务，是 LLM 本地工具插件的最小可行模板。依托 MCP 标准化协议，我们无需为不同大模型客户端单独开发适配层，一套服务可对接所有兼容 MCP 的 AI 应用；搭配 Zod 简化参数校验、Node 异步 fs 保证文件 IO 性能，同时预留充足扩展空间。

该方案解决了大模型无法访问本地资源的核心痛点，可延伸应用于本地知识库读取、配置文件解析、项目代码查看等场景，是搭建本地 AI 工具生态的基础核心组件。遵循 MCP 协议标准化开发规范，后续新增文件、数据库、命令行等本地能力均可复用这套服务架构，大幅降低 AI 本地插件开发成本。