手把手搭建MCP文件读取服务 让AI能读文件

1. 开篇：AI 为何需要具备读取文件的能力？

想象一个典型场景：当你借助 AI 进行代码编写，希望它协助重构一个项目时，你尝试将代码片段粘贴进去，AI 却回应“这个函数看起来存在一些问题，但我需要查看完整的上下文”。你继续粘贴更多代码，AI 又提示“我还需要相关的配置文件”。在如此来回反复粘贴十几轮后，你已疲惫不堪，而 AI 始终未能建立起完整的项目视角。

这不正是“盲人摸象”的困境吗？AI 好比那个摸象的盲人，每次只能触碰到局部，永远无法窥得全貌。

是否存在一种方法，能让 AI 自主“走过去”审视整个项目？如同为它赋予一双眼睛，使其能够自行读取文件？

答案是肯定的：那就是 MCP（模型上下文协议，Model Context Protocol）。

2. MCP 究竟是什么？—— 助力 AI 突破认知边界

在阐述 MCP 之前，先分享一个小故事。

你是否还记得小时候玩过的“传话游戏”？第一个人说出一句话，依次传递给第二个人、第三个人……最终，最初那句话往往已面目全非。AI 与外部世界的交互，本质上也是一个类似的传话过程——用户将信息传递给 AI，AI 再通过用户去执行具体操作。

MCP 的使命正是打破这个冗长的传话链条。它让 AI 能够直接与工具对话，省去中间“传话人”的角色。

MCP 的核心设计思想

MCP 是一个协议，它定义了 AI 如何调用外部工具。简单来说，它解决了三个关键问题：

1. “我能做什么？” —— 工具向 AI 声明其自身能力（包括工具名称、描述及参数）
2. “如何调用我？” —— AI 通过标准协议发送调用请求
3. “结果是什么？” —— 工具返回结构化的执行结果

MCP 架构概览

┌─────────────────────────────────────────────────────────────────┐
│ AI / LLM                                                       │
│   ┌─────────────┐                                              │
│   │   思考模块    │ ← 决定是否调用工具                           │
│   └──────┬──────┘                                              │
│          │                                                     │
│          ▼                                                     │
│   ┌─────────────┐                                              │
│   │   工具调用    │ ← 生成工具调用请求                           │
│   └──────┬──────┘                                              │
│          │                                                     │
│          ▼                                                     │
├────────┼────────────────────────────────────────────────────────┤
│        │   CC (Client Coordinator)                             │
│        │   ┌──────────────────────────────────────┐            │
│        │   │ 工具发现 → 参数校验 → 协议转换 → 分发 │            │
│        │   └──────────────────────────────────────┘            │
│        │                                                       │
├────────┼────────────────────────────────────────────────────────┤
│        │                                                       │
│        ▼                                                       │
│   ┌─────────────────┐   ┌─────────────────┐   ┌───────────┐   │
│   │ MCP Server 1    │   │ MCP Server 2    │   │   ...     │   │
│   │ (文件读取)       │   │ (网络搜索)       │   │           │   │
│   └────────┬────────┘   └────────┬────────┘   └─────┬─────┘   │
│            │                     │                 │          │
│            ▼                     ▼                 ▼          │
│      ┌─────────┐          ┌─────────┐       ┌─────────┐      │
│      │文件系统  │          │  网络   │       │   其他   │      │
│      └─────────┘          └─────────┘       └─────────┘      │
└─────────────────────────────────────────────────────────────────┘

此架构的精妙之处在于实现了高度解耦：

• AI 无需了解工具的具体实现细节 —— 它只需清楚“有哪些工具可用”以及“如何进行调用”
• 工具也无需知晓 AI 的身份 —— 只要遵循 MCP 协议，便能够被任何兼容的 AI 调用
• CC 作为中间协调层 —— 负责协调与路由，确保整个系统具有良好的可扩展性

本项目的定位

我们今天要深入拆解的 simple-read-mcp，正是这个架构中的一个“关键组件”——一个专门负责读取本地文件的 MCP Server。它虽然小巧，但功能完备，是理解 MCP 协议的一个绝佳切入点。

3. 项目骨架解析：package.json 与 mcp.json

在分析核心代码之前，先来审视项目的基础设施。一个 Node.js 项目好比一栋建筑，package.json 是其“房产证”，而 mcp.json 则是“门牌标识”。

package.json —— 项目的身份档案

{
  "name": "simple-read-mcp",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.29.0",
    "zod": "^4.4.3",
    "zod-to-json-schema": "^3.25.2"
  }
}

这里有三个关键的依赖项：

1. @modelcontextprotocol/sdk —— MCP 协议的官方 SDK，提供了 McpServer 和 StdioServerTransport 等核心类
2. zod —— 新一代数据验证库，用于定义工具参数的校验规则
3. zod-to-json-schema —— 可将 zod schema 自动转换成 JSON Schema，便于 AI 理解参数结构

注意 "type": "module" 这一行配置，它指示 Node.js 使用 ESM 模块系统，因此我们可以在代码中使用 import 语法。

mcp.json —— 面向客户端的“使用说明书”

{
  "mcpServers": {
    "simple-read-mcp": {
      "version": "1.0.0",
      "description": "一个简单的读取文件的工具",
      "command": "node",
      "args": [
        "C:\Users\DMYX\Desktop\workspace\lesson_zp\ai\mcp\simple-read-mcp\server.js"
      ]
    }
  }
}

这个文件是提供给 CC（客户端协调器，Client Coordinator） 查阅的，它向 CC 明确了：

• 服务名称：simple-read-mcp
• 版本：1.0.0
• 描述：一个简单的读取文件的工具（AI 将依据此描述来理解工具的用途）
• 启动方式：使用 node 命令执行 server.js

为什么需要这个文件？

试想一下，你的电脑上可能安装了众多 MCP 服务——文件读取、网络搜索、数据库查询……CC 需要清楚地知道它们位于何处、如何启动以及能够执行什么任务。mcp.json 正扮演着这个“服务注册表”的角色。

4. 核心实现：server.js 逐行深度剖析

终于来到了最核心的部分。这短短 40 行代码，浓缩了一个完整 MCP 服务的所有精华。让我们逐行进行深入解析。

4.1 导入依赖（第 1-4 行）

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';

这四个 import 语句各司其职：

为何选择 Stdio？

进程间通信有多种方式：网络 socket、命名管道、共享内存……为什么最终选择了最简单的标准输入输出？

• 零配置：无需端口号，也无需 IP 地址
• 跨平台：在 Windows 和 Unix 系统中均能良好支持
• 安全性高：不会暴露在网络上，只有父进程可以访问

4.2 创建服务器实例（第 7-10 行）

const server = new McpServer({
  name: 'simple-read-mcp',
  version: '1.0.0'
});

这一步看似简单，但背后有讲究：

• name 和 version 必须与 mcp.json 中的定义保持一致，否则 CC 将无法成功匹配
• 这是服务的“身份标识”，AI 通过这些信息来识别并选择合适的工具

4.3 注册工具（第 13-32 行）—— 核心中的核心

server.tool(
  "read_file",
  "读取指定路径的本地文件内容",
  {
    path: z.string().describe("文件的绝对或相对路径")
  },
  async ({ path }) => {
    try {
      const content = await fs.readFile(path, 'utf-8');
      return {
        content: [{ type: "text", text: content }]
      };
    } catch (err) {
      return {
        isError: true,
        content: [{ type: "text", text: `读取文件失败：${err.message}` }]
      };
    }
  }
);

这是整个文件中最关键的部分，server.tool() 方法接收四个参数：

参数一：工具名称（"read_file"）

这是工具的唯一标识符，AI 通过这个名称来调用该工具。命名时建议使用下划线分隔的小写字母，保持语义清晰。

参数二：工具描述（"读取指定路径的本地文件内容"）

这是提供给 AI 的“使用说明”，AI 将根据这个描述来判断何时应该调用此工具。描述的质量将直接影响 AI 的调用决策，写得越清晰，AI 越能准确判断使用时机。

参数三：参数 Schema（{ path: z.string().describe(...) }）

这是新版 SDK 的一个重要特性——直接使用 zod schema 定义参数，无需再手动编写 JSON Schema。

{
  path: z.string().describe("文件的绝对或相对路径")
}

z.string() 表示 path 参数的类型必须是字符串。.describe() 方法则为参数添加了描述信息，AI 将通过这个描述来理解参数的具体含义。

zod 是如何工作的？

当 AI 调用工具时，传入的参数会经过 zod 的校验：

• 如果 path 不是字符串类型，会自动返回错误信息
• 如果缺少 path 参数，也会自动返回错误
• 只有校验通过后，参数才会被传递给执行函数

参数四：执行函数（async ({ path }) => { ... }）

这是工具实际执行逻辑所在，接收经过校验的参数，并返回执行结果。

执行流程解析：

AI 请求 → CC 校验参数 → server.tool() 接收 → 执行函数调用
    │                          │                    │
    │                          │                    ▼
    │                          │               zod 验证失败
    │                          │                    │
    │                          │                    ▼
    │                          │               fs.readFile()
    │                          │                    │
    │                          │                    ▼
    │                          │               返回错误信息     返回文件内容
    │                          │                    │            │
    ▼                          ▼                    ▼            ▼
CC 返回给 AI

返回值格式：

成功时返回：

{
  content: [{ type: "text", text: content }]
}

失败时返回：

{
  isError: true,
  content: [{ type: "text", text: `读取文件失败：${err.message}` }]
}

为什么要采用 content: [{ type: "text", text: ... }] 这种格式？

这是 MCP 协议定义的统一返回格式，支持多种内容类型：

这种设计使得工具可以返回多种类型的结果，AI 能够根据不同的类型进行相应的处理。

4.4 启动服务（第 34-40 行）

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP read_file 服务已启动（stdio模式）");
}
main().catch(console.error);

这部分代码启动服务并等待请求：

1. 创建 StdioServerTransport 实例 —— 建立标准输入输出通道
2. server.connect(transport) —— 让服务器绑定到这个通道上
3. 通过 console.error 输出启动信息 —— 为什么不用 console.log？ 因为 console.log 的输出会被 CC 当作协议数据读取，所以日志信息必须写到 stderr

完整数据流图：

┌─────────────────────────────────────────────────────────────────────┐
│ 用户提问                                                           │
│ "帮我读一下 package.json"                                          │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ AI / LLM                                                            │
│ 分析问题 → 决定调用 read_file 工具 → 生成调用请求                   │
│ { name: "read_file", arguments: { path: "package.json" } }        │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ CC                                                                  │
│ 读取 mcp.json → 找到 simple-read-mcp → 启动进程 → 发送请求到 stdin │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ simple-read-mcp                                                    │
│ StdioServerTransport 接收请求 → McpServer 处理                     │
│ → 执行 read_file 函数 → fs.readFile("package.json")               │
│ → 返回结果到 stdout                                                 │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ CC                                                                  │
│ 接收 stdout 输出 → 解析结果 → 返回给 AI                           │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ AI / LLM                                                            │
│ 接收工具返回结果 → 整合到回答中 → 返回给用户                       │
└─────────────────────────────────────────────────────────────────────┘

5. 安全性思考：一个“危险”的玩具

现在我们已经完成了代码的拆解，但有一个问题必须严肃对待：这个工具安全吗？

当前实现的安全隐患

让我们仔细审视一下这个工具的实现：

async ({ path }) => {
  const content = await fs.readFile(path, 'utf-8');
  return { content: [{ type: "text", text: content }] };
};

这里没有进行任何路径检查，这意味着用户（或者说 AI）可以读取系统上的任意文件：

• read_file("/etc/passwd") —— 读取系统用户信息
• read_file("C:\Windows\System32\config\SAM") —— 读取 Windows 密码哈希
• read_file("~/.ssh/id_rsa") —— 读取 SSH 私钥

这是一个巨大的安全漏洞！ 如果这个工具被恶意利用，后果将不堪设想。

如何修复？

一个生产级的文件读取工具，至少应该包含以下安全措施：

方案一：路径白名单

只允许读取特定目录下的文件：

const ALLOWED_DIRS = [
  process.cwd(),
  '/path/to/project'
];
async ({ path }) => {
  const resolvedPath = path.resolve(path);
  const isAllowed = ALLOWED_DIRS.some(dir => resolvedPath.startsWith(path.resolve(dir)));
  if (!isAllowed) {
    return {
      isError: true,
      content: [{ type: "text", text: `访问被拒绝：${path}` }]
    };
  }
  // ... 后续逻辑
};

方案二：文件大小限制

防止读取超大文件导致内存溢出：

const MAX_FILE_SIZE = 1024 * 1024; // 1MB
async ({ path }) => {
  const stat = await fs.stat(path);
  if (stat.size > MAX_FILE_SIZE) {
    return {
      isError: true,
      content: [{ type: "text", text: `文件过大：${stat.size} bytes` }]
    };
  }
  // ... 后续逻辑
};

方案三：文件类型限制

只允许读取特定类型的文件：

const ALLOWED_EXTENSIONS = ['.txt', '.md', '.json', '.js', '.ts'];
async ({ path }) => {
  const ext = path.extname(path);
  if (!ALLOWED_EXTENSIONS.includes(ext)) {
    return {
      isError: true,
      content: [{ type: "text", text: `不支持的文件类型：${ext}` }]
    };
  }
  // ... 后续逻辑
};

为什么这个项目没有安全措施？

这个项目是一个教学示例，其目的在于展示 MCP 的核心概念，而非提供一个生产环境可用的工具。在实际使用时，你必须根据自己的具体需求添加适当的安全防护机制。

6. 进阶方向：从玩具到生产

如果你希望将这个简单的示例转变为一个真正可用的工具，可以考虑以下改进方向：

6.1 添加更多工具

一个文件读取服务不应该仅限于 read_file：

• list_files —— 列出目录内容
• write_file —— 写入文件（需要更严格的安全控制）
• read_binary_file —— 读取二进制文件
• get_file_info —— 获取文件元信息

6.2 添加流式支持

对于大文件，可以返回流式结果，避免一次性读取整个文件占用过多内存：

async ({ path }) => {
  const stream = fs.createReadStream(path);
  return {
    content: [{ type: "stream", stream }]
  };
};

6.3 添加缓存机制

对于频繁读取的文件，可以引入缓存机制，减少磁盘 I/O 开销：

const cache = new Map();
const CACHE_TTL = 60 * 1000; // 1分钟
async ({ path }) => {
  const now = Date.now();
  const cached = cache.get(path);
  if (cached && now - cached.timestamp < CACHE_TTL) {
    return { content: [{ type: "text", text: cached.content }] };
  }
  const content = await fs.readFile(path, 'utf-8');
  cache.set(path, { content, timestamp: now });
  return { content: [{ type: "text", text: content }] };
};

结尾：AI 的第三只手

回到开头那个“盲人摸象”的故事。MCP 就像是为盲人赋予了第三只手——不仅能触摸，还能“拿取”、能“观察”、能“操作”。

今天，我们用 40 行代码搭建了一个简单的文件读取工具，但这仅仅是 MCP 能力的冰山一角。请想象一下：

• 一个能查询数据库的 MCP 服务
• 一个能调用 API 的 MCP 服务
• 一个能控制智能家居的 MCP 服务
• 一个能操作 Excel 的 MCP 服务

当这些服务组合在一起，就能让 AI 拥有近乎无限的能力。唯一的限制，就是你的想象力。

最后，留给你一个问题：如果你要为 AI 打造一个“超级工具箱”，你会添加哪些工具？又是什么原因呢？