BetterMCPFileServer

重新构想的模型上下文协议 (MCP) 文件服务器，用于文件系统访问，具有保护隐私的路径别名和优化的 LLM 友好型 API。

为什么选择 BetterMCPFileServer？

原始的 MCP 文件服务器功能齐全，但未针对 LLM 实际与文件系统交互的方式进行优化。本项目提供了一个完整的重新设计，专注于简洁性、隐私性和效率。

主要创新

• 路径别名系统 - 通过隐藏完整的系统路径来保护隐私
• LLM 优化接口 - 在保持完整功能的同时，从 11 个函数减少到 6 个
• 更智能的搜索 - 用于目录列表和复杂文件搜索的统一工具
• 隐私优先设计 - 不再向 AI 模型暴露用户名或系统路径

快速开始

# 从源代码安装（npm 包即将推出）
git clone https://github.com/martinschlott/BetterMCPFileServer.git
cd BetterMCPFileServer
npm install
npm run build

# 使用别名运行
BetterMCPFileServer code:~/projects docs:~/documents

就是这样！现在 Claude 可以通过保护隐私的别名（如 code/src/main.js）而不是 /Users/yourusername/projects/src/main.js 访问您的文件。

路径别名系统

传统的文件服务器暴露完整的系统路径：

/home/martin/Documents/PrivateProject/financial-data.txt

我们的别名系统保持您的隐私完整：

projects/financial-data.txt

优点：

• 隐私保护：不暴露用户名或敏感目录名
• 简化：LLM 使用干净、逻辑的路径
• 安全性：文件系统访问的严格边界

API 设计原理

重新设计 MCP 文件服务器接口

本项目代表了对标准 MCP 文件服务器接口的重大重新设计。虽然原始实现提供了一个功能基础，但我们确定了几个需要改进的领域，以创建一个更直观、高效和 LLM 友好的接口。

主要改进

1. 直观的函数命名

原始接口使用 snake_case 命名，带有基本的动词，如 read_file 和 write_file。我们采用了更符合语言习惯的 camelCase 命名，并使用更清晰、更具体的函数名称：

• read_file → readFileContent
• write_file → writeFile
• list_directory → searchFilesAndFolders (with pattern="*")

这些名称明确地传达了它们的用途，并遵循标准的编程约定，使它们对于 AI 模型和人类开发人员来说都更加直观。

2. 分组功能以降低复杂性

我们没有为每个单独的文件或目录操作提供单独的函数，而是整合了相关操作：

• 带有 action 参数的 manageFile 替换了单独的 move_file、copy_file 和 delete_file 函数
• manageFolder 在一个函数中处理文件夹的创建、重命名和删除

这种方法减少了 API 表面积，同时增加了灵活性，使 LLM 更容易理解可用操作的完整范围。

3. 简洁、有目的的描述

原始接口包含冗长的描述，其中包含冗余信息，例如为每个函数重复声明“仅在允许的目录中工作”。我们重新设计的 API 具有简洁的描述，这些描述：

• 专注于函数的作用
• 避免陈述显而易见的事情
• 突出显示独特的功能
• 消除不提供技术价值的营销风格语言

4. 路径别名系统

最重要的改进之一是我们的路径别名系统。原始方法需要：

• 在启动时指定完整的允许目录
• LLM 在每个请求中使用完整的绝对路径
• 在目录路径中暴露潜在的敏感信息（如用户名）

我们的新方法将别名映射到真实路径：

~/Documents/MyProjects → projects
~/Documents/Letters → letters

优点包括：

• LLM 使用简单、逻辑的路径（projects/backend 而不是 /home/username/Documents/MyProjects/backend）
• 通过隐藏包含用户名或敏感目录结构的实际路径来增强隐私
• 系统配置可以更改，而不会影响 LLM 与服务器的交互方式

5. 更高效的组合操作

我们添加了战略性的组合操作，以减少往返次数并简化常见任务：

• 具有改进的描述和 includeMetadata 选项的 searchFilesAndFolders 完全取代了对单独的 readFolderContent 函数的需求
• editFile 保留了原始实现中有用的目标文本替换功能，但具有更清晰的参数结构

此重新设计的一个关键成就是将工具数量从 11 个减少到 6 个，同时保持完整的功能。这种简化：

• 使 API 更易于学习和记忆
• 减少 LLM 在选择适当工具时的认知负荷
• 最大限度地减少操作之间的冗余

设计理念

此重新设计遵循几个核心原则：

1. AI 优先接口：针对 LLM 的消费和使用模式进行了优化
2. 最小认知负荷：减少了函数数量，并具有一致的命名和行为
3. 信息隐藏：抽象了不使消费者受益的实现细节
4. 渐进式披露：简单操作很简单，高级功能在需要时可用

优化的搜索功能

我们重新设计的搜索功能既强大又易于使用：

searchFilesAndFolders({
  pattern: "**/*.js",                   // 查找所有 JavaScript 文件
  includeMetadata: true,                // 包括文件大小和日期（谨慎使用）
  ignore: ["node_modules", "*.min.js"]  // 跳过不需要的匹配项
})

关键模式：

• "*" - 列出顶级项目（如简单的目录列表）
• "projects/*.js" - projects 目录中的所有 JavaScript 文件
• "**/*.md" - 递归地跨所有目录的所有 markdown 文件

⚠️ 专业提示： 仅在您特别需要文件大小或日期时才设置 includeMetadata: true，以保持响应效率。

API 参考

BetterMCPFileServer 仅公开 6 个强大的函数，这些函数处理所有文件系统操作：

1. writeFile

创建或更新具有给定内容的文件。

writeFile({
  filePath: "projects/README.md",
  content: "# My Project\n\nThis is a readme file."
})

2. readFileContent

读取文件的内容。

readFileContent({
  filePath: "projects/README.md"
})

3. editFile

对文件的特定部分进行有针对性的更改。

editFile({
  filePath: "projects/README.md",
  edits: [
    {
      oldText: "# My Project",
      newText: "# Awesome Project"
    }
  ],
  dryRun: false
})

4. manageFile

执行诸如移动、重命名、复制或删除文件之类的操作。

manageFile({
  action: "move",
  filePath: "projects/old.js",
  newFilePath: "projects/new.js"
})

5. manageFolder

创建、重命名或删除文件夹。

manageFolder({
  action: "create",
  folderPath: "projects/new-directory"
})

6. searchFilesAndFolders

使用 glob 模式搜索文件和文件夹。

searchFilesAndFolders({
  pattern: "projects/**/*.ts",
  includeMetadata: false
})

使用示例

使用虚拟根目录

// 列出所有可用的别名
searchFilesAndFolders({ pattern: "*" })

// 结果：
[
  { path: "projects", type: "directory" },
  { path: "docs", type: "directory" }
]

基本文件操作

// 读取文件
const content = await readFileContent({ filePath: "projects/README.md" });

// 写入文件
await writeFile({
  filePath: "projects/notes.txt",
  content: "Important meeting notes."
});

// 编辑文件
await editFile({
  filePath: "projects/config.json",
  edits: [
    {
      oldText: '"version": "1.0.0"',
      newText: '"version": "1.0.1"'
    }
  ]
});

目录操作

// 创建新目录
await manageFolder({
  action: "create",
  folderPath: "projects/new-feature"
});

// 列出目录内容
const files = await searchFilesAndFolders({
  pattern: "projects/src/*"
});

安装

# 来自 npm（即将推出）
npm install -g BetterMCPFileServer  # 尚未可用

# 来自源代码（当前方法）
git clone https://github.com/martinschlott/BetterMCPFileServer.git
cd BetterMCPFileServer
npm install
npm run build
npm link  # 可选，使命令全局可用

用法

使用至少一个 alias:directory 对启动服务器：

BetterMCPFileServer alias:directory [alias2:directory2 ...]

示例：

# 单个目录
BetterMCPFileServer code:~/projects

# 多个目录
BetterMCPFileServer code:~/Development docs:~/Documents/Technical notes:~/Notes

高级配置

创建一个简单的 shell 脚本以实现一致的配置：

#!/bin/bash
# start-server.sh
BetterMCPFileServer \
  code:~/Development/MyProjects \
  docs:~/Documents/Technical \
  data:~/Data/Samples \
  config:~/Configuration

故障排除

• 错误：无效的 alias:path 格式：确保每个参数使用 alias:directory 格式
• 错误：目录不存在：指定的目录必须存在
• 访问被拒绝错误：尝试访问允许目录之外的内容
• 未知别名：引用的别名未在服务器启动时定义

鸣谢

本项目是 Martin Schlott（概念和设计）和 AI 助手之间的合作：

• Claude 3.7 Sonnet（API 设计咨询和文档）
• Cursor AI（实施）

README 由 Claude 3.7 Sonnet 制作

许可证

MIT 许可证