JinDaGe - mcp-file-tools MCP Details

article

README

🚀 MCP文件工具

MCP文件工具是一个支持非UTF - 8编码的文件操作服务器。它能够自动检测并转换22种编码（包括西里尔文、Windows - 125x、ISO - 8859、KOI8、UTF - 16等），让AI助手在读写旧文件时不会破坏数据。该工具非常适合Delphi/Pascal项目、旧的VB6应用程序、老的PHP/HTML网站以及包含非UTF - 8文本的配置文件。

🚀 快速开始

安装完成后，你只需向Claude提出相关需求，例如：

"列出此目录下所有的.pas文件"
"读取config.ini并检测其编码"
"显示所有支持的编码"
"使用CP1251编码读取MainForm.dfm"

安全说明：服务器仅访问你明确允许的目录：

自动方式：Claude Desktop/Code会自动提供工作区目录
手动方式：在配置文件的args: ["/path/to/project"]中指定目录

✨ 主要特性

提供19种文件操作工具，支持自动编码转换。
支持22种编码，涵盖Unicode、西里尔文、西欧、中欧、希腊、土耳其等多种编码类型。
所有操作都限制在允许的目录内，保障安全性。

📦 安装指南

MCP注册表

该服务器已列入官方MCP注册表，方便发现。

Windows x64

注意：请在PowerShell中运行以下命令，而非CMD。

# 下载
mkdir -Force "$env:LOCALAPPDATA\Programs\mcp-file-tools"
iwr "https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_windows_amd64.exe" -OutFile "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe"
# 使用Claude Code + VSCode安装（允许访问D:\Projects）
claude mcp add --scope user file-tools -- "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe" "D:\Projects"

Linux x64

# 下载
mkdir -p ~/.local/bin
curl -L "https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_linux_amd64" -o ~/.local/bin/mcp-file-tools
chmod +x ~/.local/bin/mcp-file-tools
# 使用Claude Code + VSCode安装（允许访问~/Projects）
claude mcp add --scope user file-tools -- ~/.local/bin/mcp-file-tools ~/Projects

macOS ARM64

# 下载
mkdir -p ~/.local/bin
curl -L "https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_darwin_arm64" -o ~/.local/bin/mcp-file-tools
chmod +x ~/.local/bin/mcp-file-tools
# 使用Claude Code + VSCode安装（允许访问~/Projects）
claude mcp add --scope user file-tools -- ~/.local/bin/mcp-file-tools ~/Projects

Go Install（所有平台）

# 使用Go安装（需要Go 1.23+）
go install github.com/dimitar-grigorov/mcp-file-tools/cmd/mcp-file-tools@latest
# 添加到Claude Code + VSCode（Linux/macOS）
claude mcp add --scope user file-tools -- $(go env GOPATH)/bin/mcp-file-tools ~/Projects

# 添加到Claude Code + VSCode（Windows PowerShell）
claude mcp add --scope user file-tools -- "$(go env GOPATH)\bin\mcp-file-tools.exe" "D:\Projects"

其他客户端

对于Claude Desktop、VSCode或Cursor，在配置中使用下载的二进制文件路径：

Claude Desktop（Windows上的%APPDATA%\Claude\claude_desktop_config.json，macOS上的~/Library/Application Support/Claude/claude_desktop_config.json）：

Windows:

{
  "mcpServers": {
    "file-tools": {
      "command": "C:\\Users\\YOUR_NAME\\AppData\\Local\\Programs\\mcp-file-tools\\mcp-file-tools.exe",
      "args": ["D:\\Projects", "C:\\Users\\YOUR_NAME\\Documents"]
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "file-tools": {
      "command": "/Users/YOUR_NAME/.local/bin/mcp-file-tools",
      "args": ["/Users/YOUR_NAME/Projects", "/Users/YOUR_NAME/Documents"]
    }
  }
}

args数组指定服务器可以访问的允许目录，你可以根据需要添加多个目录。

VSCode / Cursor（Claude Code扩展） 如果你已经在上述安装步骤中运行了claude mcp add --scope user，则服务器已在VSCode中可用，无需额外配置。

若要单独为VSCode配置：

claude mcp add --scope user file-tools -- "%LOCALAPPDATA%\Programs\mcp-file-tools\mcp-file-tools.exe" "D:\Projects"

或者，通过在项目根目录添加.mcp.json创建项目级配置：

{
  "mcpServers": {
    "file-tools": {
      "type": "stdio",
      "command": "C:\\Users\\YOUR_NAME\\AppData\\Local\\Programs\\mcp-file-tools\\mcp-file-tools.exe",
      "args": ["D:\\Projects", "D:\\Other\\Directory"]
    }
  }
}

注意：type: "stdio"字段是必需的。args数组指定允许的目录，VSCode扩展不会自动添加工作区目录，因此你必须列出所有要访问的目录。若要稍后添加更多目录，请重新运行claude mcp add命令并列出所有目录（它会覆盖之前的配置）。

自动批准所有工具（Claude Code）

若要跳过所有文件工具命令的权限提示，可在项目根目录创建.claude/settings.local.json：

{
  "permissions": {
    "allow": [
      "Bash(ls *)",
      "Bash(grep *)",
      "Bash(sort *)",
      "Bash(wc *)",
      "Bash(find *)",
      "Bash(echo *)",
      "Grep",
      "Glob",
      "WebSearch",
      "mcp__file-tools__read_text_file",
      "mcp__file-tools__read_multiple_files",
      "mcp__file-tools__write_file",
      "mcp__file-tools__edit_file",
      "mcp__file-tools__copy_file",
      "mcp__file-tools__list_directory",
      "mcp__file-tools__tree",
      "mcp__file-tools__directory_tree",
      "mcp__file-tools__search_files",
      "mcp__file-tools__grep_text_files",
      "mcp__file-tools__detect_encoding",
      "mcp__file-tools__convert_encoding",
      "mcp__file-tools__detect_line_endings",
      "mcp__file-tools__list_encodings",
      "mcp__file-tools__get_file_info",
      "mcp__file-tools__create_directory",
      "mcp__file-tools__list_allowed_directories"
    ]
  }
}

这将自动批准安全的只读和编辑文件工具操作，以及常见的shell命令和网络搜索。破坏性操作（delete_file、move_file）和WebFetch有意排除在外，Claude在使用它们之前会询问。你可以根据需要进行调整。

验证与卸载

# 检查服务器是否已配置
claude mcp list

# 移除服务器
claude mcp remove file-tools

💻 使用示例

基础用法

例如，你可以向Claude提出如下需求：

User: 读取config.ini并将标题更改为 "Настройки"
Assistant: [使用cp1251编码读取文件] → [以UTF - 8格式修改内容] → [使用cp1251编码写入文件]

这样可以保留原始编码，确保文件与旧工具兼容。

📚 详细文档

工具列表

提供19种用于文件操作的工具，支持自动编码转换：

read_text_file - 自动检测并转换编码后读取文件
read_multiple_files - 并发读取多个文件，支持编码转换
write_file - 以特定编码写入文件
edit_file - 基于行的编辑，提供差异预览和灵活的空格匹配
copy_file - 将文件复制到新位置
delete_file - 删除文件
list_directory - 按模式过滤浏览目录
tree - 紧凑的缩进树视图（比JSON少85%的令牌）
directory_tree - 以JSON格式获取递归树视图（已弃用，使用tree）
search_files - 递归搜索匹配通配符模式的文件
grep_text_files - 在文件内容中进行正则搜索，支持编码转换
detect_encoding - 自动检测文件编码并给出置信度分数
convert_encoding - 在不同编码之间转换文件
detect_line_endings - 检测行结束样式（CRLF/LF/混合）
list_encodings - 显示所有支持的编码
get_file_info - 获取文件/目录元数据
create_directory - 递归创建目录（类似于mkdir -p）
move_file - 移动或重命名文件和目录
list_allowed_directories - 显示可访问的目录

支持的编码（共22种）

Unicode：UTF - 8、UTF - 16 LE、UTF - 16 BE（支持UTF - 16和UTF - 32的BOM检测）
西里尔文：Windows - 1251、KOI8 - R、KOI8 - U、CP866、ISO - 8859 - 5
西欧：Windows - 1252、ISO - 8859 - 1、ISO - 8859 - 15
中欧：Windows - 1250、ISO - 8859 - 2
希腊：Windows - 1253、ISO - 8859 - 7
土耳其：Windows - 1254、ISO - 8859 - 9
其他：希伯来文（1255）、阿拉伯文（1256）、波罗的海文（1257）、越南文（1258）、泰文（874）

详细参数和示例请参考TOOLS.md。

配置说明

服务器可以通过环境变量进行配置： | 变量 | 描述 | 默认值 | |------|------|---------| | MCP_DEFAULT_ENCODING | write_file未指定编码时的默认编码 | cp1251 | | MCP_MEMORY_THRESHOLD | 内存阈值（字节）。小于该阈值的文件将加载到内存中以实现更快的I/O；较大的文件使用流式处理。也会影响编码检测模式。 | 67108864（64MB） |

若要覆盖默认值，可在配置中设置环境变量（以Claude Desktop为例）：

{
  "mcpServers": {
    "file-tools": {
      "command": "C:\\Users\\YOUR_NAME\\AppData\\Local\\Programs\\mcp-file-tools\\mcp-file-tools.exe",
      "args": ["D:\\Projects"],
      "env": {
        "MCP_DEFAULT_ENCODING": "utf-8"
      }
    }
  }
}

🔧 技术细节

开发环境

前提条件：Go 1.23+

# 运行测试
go test ./...

# 构建
go build -o mcp-file-tools ./cmd/mcp-file-tools

使用MCP Inspector进行调试

MCP Inspector提供了一个Web UI，用于测试MCP服务器。

前提条件：Node.js v18+

# 运行并指定允许的目录（必需）
npx @modelcontextprotocol/inspector go run ./cmd/mcp-file-tools -- /path/to/allowed/dir

# 或者使用已构建的二进制文件
npx @modelcontextprotocol/inspector ./mcp-file-tools.exe C:\Projects

运行后会打开一个浏览器，你可以在其中查看工具、使用自定义参数调用工具并检查响应。

手动调试

运行服务器并指定允许的目录，然后通过stdin发送JSON - RPC命令：

# 指定允许的目录
go run ./cmd/mcp-file-tools /path/to/project

示例命令（粘贴到终端）：

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_directory","arguments":{"path":"/path/to/project","pattern":"*.go"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_text_file","arguments":{"path":"/path/to/project/main.pas","encoding":"cp1251"}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"detect_encoding","arguments":{"path":"/path/to/project/file.txt"}}}

📄 许可证

本项目采用GPL - 3.0许可证，详情请参阅LICENSE。

mcp-file-tools