企业官网建设流程全解析

Mastra 实战：为 Filesystem MCP 创建 Notes 目录，让 Agent 拥有持久化文件读写能力

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

本篇指南聚焦 Mastra 框架中接入 Filesystem MCP（Model Context Protocol）服务器的前置环节——在项目根目录创建notes笔记目录。你将掌握mkdir -p的用法、为什么必须为 Agent 划定专属文件读写边界，以及如何把该目录接入@mastra/mcp的 Stdio 配置、写进 Agent 的系统提示词，最终在 Playground 中验证 Agent 能真正创建待办清单和会议笔记。读完即可在自己的 Mastra 项目中复现一整套"可持久化记忆的本地文件助手"。

背景：为什么 Filesystem MCP 需要一块专属目录

在接入 Filesystem MCP 之前，先明确它的定位。参考 24-what-is-filesystem-mcp.md，Filesystem MCP 服务器为 Agent 提供与本地文件系统交互的工具集合，包括：

• 读取文件（Read files）
• 写入文件（Write to files）
• 创建目录（Create directories）
• 列出文件与目录（List files and directories）
• 管理持久化数据（Managing persistent data like notes and to-do lists）

它的核心价值在于：把 Agent 的能力从"一次性对话"扩展到"跨会话维护持久信息"。接入后，Agent 可以创建并管理笔记、待办清单等文档，这些文件在应用关闭后依然存在。这正是本课程中"个人助理"（Personal Assistant）Agent 管理笔记与待办事项的底层机制。

而要让这些能力安全落地，第一步就是为 Agent 划出一块专属于它的文件目录——即本课的主角notes目录。

第一步：用mkdir -p创建 Notes 目录

在项目根目录执行以下命令：

mkdir -p notes

这条命令会在你的项目根目录下创建一个名为notes的目录，Agent 后续创建或修改的所有文件都将存放在这里。关键点在于-p标志：

• 若目录不存在，mkdir -p会一次性创建它（包括路径中的各级父目录）；
• 若目录已存在，命令不会报错，而是静默成功退出。

这保证了初始化脚本可以重复执行而不会中断，是典型的幂等操作写法，非常适合写进项目的初始化脚本或文档步骤中。

目录位置的约定

在本课程后续的 MCP 配置中，notes目录的路径需要被传递给 Filesystem MCP 服务器。课程里给出的配置（见 26-updating-mcp-config-filesystem.md）使用path.join拼出绝对路径：

import path from 'path' const mcp = new MCPClient({ servers: { // ... 其他服务器（zapier / github / hackernews） textEditor: { command: 'pnpx', args: [ `@modelcontextprotocol/server-filesystem`, path.join(process.cwd(), '..', '..', 'notes'), // relative to output directory ], }, }, })

注意这里path.join(process.cwd(), '..', '..', 'notes')之所以向上回溯两级，是因为课程示例中应用是从构建输出目录运行的（注释relative to output directory说明了这一点）。在你的实际项目中，应当根据运行时的工作目录调整process.cwd()的拼接层级，确保最终解析到的就是根目录下的notes。用绝对路径而非硬编码相对路径，可以避免"从不同目录启动应用导致路径解析失败"这类问题。

从源码层面看，这种command + args的配置会被 packages/mcp/src/client/client.ts 解析为基于标准输入输出的StdioClientTransport（该文件第 29 行引入了StdioClientTransport，第 527 行用它构建传输层），随后通过MCPClient（定义于 packages/mcp/src/client/configuration.ts 第 98 行）管理整个服务器生命周期。也就是说，pnpx作为子进程被拉起，notes目录路径作为参数传给它——目录必须先存在，服务器启动后才能正常完成初始化并暴露读写工具。

为什么单独建目录是值得养成的习惯

原文档明确列出了为 Agent 文件建立专属目录的三点理由，这里结合 Mastra 项目的实际情况逐一展开：

1. 让 Agent 产生的文件与应用代码隔离笔记、待办清单等属于运行时产生的数据，与源码混放在一起会让项目结构混乱，也可能被误提交、误覆盖。独立目录让"代码"与"数据"的边界一目了然。

2. 便于备份与版本控制当你只需要备份或归档 Agent 积累的数据时，只需处理notes这一个目录即可。若目录纳入版本控制（或接入云同步），还能实现跨设备、跨会话的数据延续——这正是 Filesystem MCP"持久化数据"能力的工程保障。

3. 划定访问边界，增强安全性MCP 服务器被授予的文件系统访问范围，应当严格限定在它真正需要的目录内。把notes作为唯一可访问根，可以防止 Agent（或被恶意构造的提示词）读写项目其他敏感文件。最小权限原则在这里直接体现为"给 Filesystem MCP 一个尽可能小的沙箱目录"。从仓库中的相关课程 29-troubleshooting-filesystem.md 可以看到，路径配置错误正是常见故障来源之一，提前规划好目录边界能规避大量问题。

第二步：把目录路径告知 Agent（系统提示词）

创建好目录后，还需要让 Agent"知道"它拥有这个目录的读写权限。在 Agent 定义中（见 27-updating-agent-instructions-filesystem.md），把notes目录路径拼进instructions：

export const personalAssistantAgent = new Agent({ name: 'Personal Assistant', instructions: ` You are a helpful personal assistant that can help with various tasks such as email, monitoring github activity, scheduling social media posts, providing tech news, and managing notes and to-do lists. You have access to the following tools: ... 4. Filesystem: - You also have filesystem read/write access to a notes directory. - You can use that to store info for later use or organize info for the user. - You can use this notes directory to keep track of to-do list items for the user. - Notes dir: ${path.join(process.cwd(), 'notes')} ... `, tools: { ...mcpTools }, // ... })

这段提示词的价值在于：模型本身不"知道"目录路径，是提示词告诉它的。明确写出"你拥有对 notes 目录的读写权限"以及具体路径，模型才能在面对"记一下明天会议的要点"这类请求时，主动调用 Filesystem 工具的写入能力，并知道数据该落在哪里、从哪里读回。

这里使用的mcpTools来自 04-initializing-mcp-tools.md 中的初始化调用：

const mcpTools = await mcp.listTools()

listTools()会连接配置中的每个服务器（包括通过pnpx启动的 Filesystem 服务器）、拉取全部可用工具并返回给 Agent 使用。该调用在 packages/mcp/src/client/client.test.ts 中有大量测试覆盖，包括参数传递、超时等行为，属于经过验证的稳定接口。

第三步：在 Playground 中验证文件读写

目录、配置、提示词三步就绪后，按 28-testing-filesystem-integration.md 的步骤进行验证：

1. 用npm run dev启动开发服务器；
2. 打开 Playground：http://localhost:4111/；
3. 向 Agent 提出文件系统相关的任务，例如：
   • "Create a to-do list for me"（为我创建待办清单）
   • "Add 'Buy groceries' to my to-do list"（把"买日用品"加入待办清单）
   • "Create a note about the meeting tomorrow"（记录明天会议的笔记）
   • "What's on my to-do list?"（我的待办清单里有什么？）
   • "Read my meeting notes"（读取我的会议笔记）

需要留意的是：第一次请求文件系统相关功能时可能会有短暂延迟——pnpx需要下载并启动 Filesystem MCP 服务器；之后的请求会快得多。验证的核心判断标准是：Agent 是否能识别"创建/管理笔记与待办"这类需求、主动选用 Filesystem 工具，并正确读写notes目录中的文件。

常见问题排查

若 Agent 无法访问 Filesystem 工具，按 29-troubleshooting-filesystem.md 的清单逐一检查：

1. PNPX 是否安装且可用——Mastra 通过pnpx拉起服务器子进程，pnpm 缺失或版本异常会直接导致连接失败；
2. notes目录是否存在且位置正确——目录缺失或路径拼接与运行时工作目录不匹配是高频故障；
3. 工具是否真正加载——在 Playground 的 Tools 标签页中检查 Filesystem 相关工具是否出现在列表里。

最常见的三个问题分别是：PNPX 未安装或配置不当、notes目录不存在或权限不足、MCP 配置中的路径错误。如果怀疑问题出在服务器本身，可以在终端手动执行同款命令来隔离验证：

pnpx @modelcontextprotocol/server-filesystem ./notes

这条命令能直接判断：是pnpx执行环境的问题，还是它被嵌进 Mastra 配置后的使用方式问题。手动运行正常而集成后失败，问题通常就出在配置中的路径或参数传递上。

小结

创建notes目录看似只是一条mkdir -p notes命令，但它承载着 Filesystem MCP 接入中的三重工程考量：运行前提（服务器启动时目录必须存在）、安全边界（限定 Agent 的文件系统访问范围）、持久化语义（跨会话保留 Agent 产生的数据）。配合 MCP 配置、Agent 提示词 与 Playground 验证，你的 Mastra Agent 便拥有了"记得住、写得出、读得回"的本地文件能力。想进一步了解 MCP 与 Filesystem 服务器本身的机制，可回看 什么是 Filesystem MCP 与课程开篇的 MCP 入门。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra