Better MCP File Server

](https://mseep.ai/app/martinschlott-bettermcpfileserver)

更好的MCPFileServer

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

为什么选择BetterMCPFileServer？

最初的MCP文件服务器功能正常，但没有针对LLM与文件系统的实际交互方式进行优化。该项目提供了一个完整的重新设计，专注于简单性、隐私性和效率。

关键创新

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

快速开始

# Install from source (npm package coming soon)
git clone https://github.com/martinschlott/BetterMCPFileServer.git
cd BetterMCPFileServer
npm install
npm run build

# Run with aliases
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 （图案=“\*”）

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

2.分组功能降低复杂性

我们没有为每个单独的文件或目录操作设置单独的功能，而是整合了相关操作：

• manageFile 带着一个 action 参数替换单独 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.更高效的联合作战

我们增加了战略联合行动，以减少往返行程并简化常见任务：

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

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

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

设计理念

这种重新设计遵循了几个核心原则：

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

优化搜索功能

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

searchFilesAndFolders({
  pattern: "**/*.js",                   // Find all JavaScript files
  includeMetadata: true,                // Include file sizes and dates (use sparingly)
  ignore: ["node_modules", "*.min.js"]  // Skip unwanted matches
})

关键模式：

• "*" -列出顶级项目（如简单的目录列表）
• "projects/*.js" -项目目录中的所有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
})

使用示例

使用虚拟根

// List all available aliases
searchFilesAndFolders({ pattern: "*" })

// Result:
[
  { path: "projects", type: "directory" },
  { path: "docs", type: "directory" }
]

基本文件操作

// Read a file
const content = await readFileContent({ filePath: "projects/README.md" });

// Write a file
await writeFile({
  filePath: "projects/notes.txt",
  content: "Important meeting notes."
});

// Edit a file
await editFile({
  filePath: "projects/config.json",
  edits: [
    {
      oldText: '"version": "1.0.0"',
      newText: '"version": "1.0.1"'
    }
  ]
});

目录操作

// Create a new directory
await manageFolder({
  action: "create",
  folderPath: "projects/new-feature"
});

// List directory contents
const files = await searchFilesAndFolders({
  pattern: "projects/src/*"
});

安装

# From npm (coming soon)
npm install -g BetterMCPFileServer  # Not yet available

# From source (current method)
git clone https://github.com/martinschlott/BetterMCPFileServer.git
cd BetterMCPFileServer
npm install
npm run build
npm link  # Optional, makes command available globally

用法

使用至少一个别名启动服务器：目录对：

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

示例：

# Single directory
BetterMCPFileServer code:~/projects

# Multiple directories
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:directory
• 错误：目录不存在：指定的目录必须存在
• 拒绝访问错误：试图在允许的目录之外访问
• 未知别名：服务器启动时未定义引用的别名

鸣谢

这个项目是Martin Schlott（概念和设计）和人工智能助手之间的合作：

• Claude 3.7 Sonnet（API设计咨询和文件）
• 光标AI（实现）

*Claude 3.7 Sonnet编写的自述文件*

许可证

MIT许可证