使用说明

MCP文件系统

🚀 用于文件系统操作的安全模型上下文协议（MCP）服务器

该项目提供了一个MCP服务器，允许通过与Claude Desktop和其他MCP客户端兼容的标准接口对文件系统进行控制访问。

✨ 功能

🔧 可用工具（11 总）

工具	描述
`read_text_file` 阅读带有head/tail选项的文本文件
`read_multiple_files` 同时读取多个文件
`write_file` 将内容写入文件。
`edit_file` 使用 find/replace + dry-run 操作编辑文件
`create_directory` 创建目录。
`list_directory` 目录内容列表（简单）
`list_directory_with_sizes`	具有详细信息的目录列表
`get_file_info` 从文件/目录获取元数据
`search_files` 按模式搜索文件（glob/regex）
`move_file` 移动/重命名文件
`delete_file`	删除文件/目录（带递归支持）

🔒 安全资源

控制允许的目录 可通过配置 --allowed-dirs
严格的路径验证 防止未经授权的访问
通过stdio进行通信 （无网络曝光）
输入验证 所有参数的 Pydantic

📦 安装和配置

快速开始

# 1. Configurar ambiente de desenvolvimento
make setup-dev

# 2. Executar testes
make test

# 3. Iniciar servidor em modo desenvolvimento
make start-dev-env

先决条件

Python 3.12+
诗歌
pyenv（推荐）

Make 可用命令

设置和依赖关系

make setup-dev - 配置完整的环境（Python，依赖关系，钩子）
make install - 使用Poetry安装依赖关系
make check-deps 检查 pyenv 和 poetry 是否已安装
make install-deps - 显示工具的安装说明
make set-pre-commit -Instala钩子做预提交

开发

make start-dev-env 在开发模式下启动 MCP 服务器
make run 运行应用程序 CLI

代码质量和测试

make format -código格式（黑色+等角）
make lint -执行者门楣（flake8+mypy）
make test - 运行覆盖测试
make test-verbose - 以丰富模式运行测试

码头工人

make build-docker 建立 Docker 映像

清洁

make clean 删除临时文件
make clean-all - 完全清洁（包括.venv）

🚀 谎言

命令行

# Iniciar com diretório atual
mcp-filesystem start

# Especificar diretórios permitidos
mcp-filesystem start --allowed-dirs /home/user/projects --allowed-dirs /tmp

# Validar diretórios
mcp-filesystem validate-dirs /path/to/dir1 /path/to/dir2

# Verificar versão
mcp-filesystem version

🧩 自动配置 MCP 客户端

该项目现在有一个单一的命令来交互式配置流行的MCP客户端（Copilot，Gemini，Cline等）。

用户配置

基础执行人：

make config-client

交互式流程将：

询问您想要配置的客户端
建议配置文件的默认路径
允许自动搜索或手动输入路径
请求 MCP 允许的目录
以安全和非破坏性的方式更新客户端配置文件

运行后，按照显示的说明重新加载 VS Code 或所选客户端。

配置脚本结构

脚本被组织成：

scripts/config_paths.py选择和检测配置路径
scripts/file_search.py自动搜索配置文件
scripts/mcp_config.py生成和更新 MCP 块
scripts/main.py：交互式流程编排

验证新结构后，可以从目录中删除旧/冗余文件 scripts.

🧪 测试

# Testes unitários com coverage
make test

# Linting
make lint

初始设置

# Setup completo
make setup-dev

# Apenas dependências
make install

# Hooks pre-commit
make set-pre-commit

格式和质量

# Formatar código
make format

# Verificar qualidade
make lint

📝 使用范例

正在读取文件

{
  "name": "read_text_file",
  "arguments": {
    "path": "/tmp/example.txt",
    "head": 10
  }
}

写入文件

{
  "name": "write_file",
  "arguments": {
    "path": "/tmp/new_file.txt",
    "content": "Hello, MCP Filesystem!"
  }
}

列出目录

{
  "name": "list_directory_with_sizes",
  "arguments": {
    "path": "/tmp"
  }
}

📄 许可证

麻省理工学院许可证 - 详情请参阅许可证文件。

🤝 贡献

Fork 仓库
创建分支： git checkout -b feat/nova-feature
进行更改和测试： make test
执行格式： make format
检查质量： make lint
承诺： git commit -m 'feat: adiciona nova feature'
推： git push origin feat/nova-feature
打开 Pull Request