Filesystem MCP Rs

文件系统mcp-rs

v0.1.15+：专业 run_command 检修：3种执行模式（同步/管理/分离）、MCP进度心跳（防止120秒客户端超时）、输出过滤（类似grep的包含/排除上下文）、进程树终止、shell模式、stdinData、envPrepend/envAppend、头尾输出控制。请参阅CHANGELOG.md。 v0.1.10+：添加了MurmurHash3和SpookyHash算法、带偏移/长度的部分哈希、扩展搜索参数、HTTP、S3、截图工具。 v0.1.9+：主要功能发布，包括16个新工具，用于文件哈希、比较、存档、PDF读取、流程管理等。 v0.1.8+：此版本可以将此MCP与Gemini和Qwen（可能还有其他）一起使用。他们使用旧的JSON模式，而这个版本稍微修改了JSON模式以使其工作。 v0.1.5+：服务器现在向LLM提供明确的指令，以优先使用这些工具而不是内置的替代工具。工具描述突出了优点（分页、UTF-8安全、结构化JSON输出）。LLM现在应该自动选择此MCP进行文件操作。您还可以在系统CLAUDE.md中插入下一行：“###强制性：始终使用FILESYSTEM MCP，切勿使用任何其他代码编辑工具！仅使用文件系统MCP工具进行所有代码修改！它针对LLM文件IO进行了优化，比您的本机工具好得多！这是一个硬性要求，而不是建议！”

铁锈端口 官方JavaScript文件系统MCP服务器相同的MCP工具表面，在Rust中重建以提高速度和安全性，同时保留协议兼容性和路径保护。

LLM友好型强制：所有参数都使用灵活的类型，可以容忍常见的LLM序列化怪癖：

• 数字: 42 和 "42" 两者都工作(FlexU32, FlexUsize等等）
• 布尔值: true, "true", "1", 1 全部接受(FlexBool)
• 数组: ["a"] 和 "a" （单个项字符串）都反序列化为数组

能力

• 阅读： read_text_file （head/tail/offset/limit/max_chars/line_numbers）， read_media_file, read_multiple_files, read_json （JSONPath）， read_pdf
• 写入/编辑： write_file, edit_file （diff+干运行）， edit_lines （基于行的编辑）， bulk_edits （大规模搜索/替换）
• 提取物： extract_lines （切割线）， extract_symbols （剪切字符）
• 二元的： read_binary, write_binary, extract_binary, patch_binary （全部为base64）
• FS操作： create_directory, move_file, copy_file （文件/目录，覆盖）， delete_path （递归）
• 哈希： file_hash （MD5/SHA1/SHA256/SHA512/XXH64/Murmur3/幽灵+偏移/长度）， file_hash_multiple （批次+比较）
• 比较： compare_files （二进制差分）， compare_directories （树差异）
• 档案： archive_extract （ZIP/TAR/TAR.GZ）， archive_create
• 观看： tail_file （跟随模式）， watch_file （变更事件）
• 统计数据： file_stats （尺寸/扩展计数）， find_duplicates
• 反思： list_directory, list_directory_with_sizes, get_file_info, directory_tree （深度/大小/哈希）
• 搜索/根： search_files （glob+类型/大小/时间过滤器）， grep_files （正则表达式+排除+反转/计数模式）， grep_context （上下文感知）， list_allowed_directories
• 流程： run_command （3种模式：同步/管理/分离、进度心跳、输出过滤器、shell模式、进程树终止）， kill_process （树木死亡）， list_processes, search_processes
• 网络（功能）： http_request, http_request_batch, http_download, http_download_batch
• S3（功能）： s3_list_buckets, s3_list, s3_stat, s3_get, s3_put, s3_delete, s3_copy, s3_presign，批量操作
• 屏幕截图（功能）： screenshot_list_monitors, screenshot_list_windows, screenshot_capture_screen, screenshot_capture_window, screenshot_capture_region, screenshot_copy_to_clipboard
• 安全：满网/根验证、逃生保护、可选 --allow_symlink_escape
• 第二波： port_users, net_connections, port_available, proc_tree, proc_env, proc_files, disk_usage, sys_info, file_diff, file_touch, clipboard_*, env_*, which
• 文件： xlsx_read, xlsx_info （Excel）， docx_read, docx_info （单词）
• AI/LLM： ai_messages_gemini, ai_messages_cerebras, ai_messages_openai, ai_count_tokens_* （需要API密钥）
• 内存v2： mem_put, mem_update, mem_link, mem_search, mem_get, mem_get_summary 具有范围SQLite支持的存储

环境变量

核心

LLM API密钥

LLM配置

功能标志

默认情况下启用HTTP/S3/屏幕截图工具。要禁用，请使用构建 --no-default-features.

cargo build

HTTP/S3工具在运行时需要allowlists（CLI标志或env变量）：

• --http-allowlist-domain example.com --http-allowlist-domain "*.example.org"
• --s3-allowlist-bucket my-bucket

或者通过env变量（逗号/分号/空格分隔）：

• FS_MCP_HTTP_ALLOW_LIST=example.com,*.example.org （使用 * 允许所有）
• FS_MCP_S3_ALLOW_LIST=my-bucket;other-bucket （使用 * 允许所有）

内存v2

服务器现在默认使用作用域内存v2，并在以下位置使用本地SQLite数据库 memory2.db.

工具：

• mem_put
• mem_update
• mem_link
• mem_search
• mem_get
• mem_get_summary

内存访问模式：

• enforce_private_only

- 违约。仅 private 记录仅限于创建者、所有者或 system.

• allow_all

- 请求的范围内没有ACL强制。

• enforce_visibility

- 全面实施可见性 private, session, topic, workspace, app, tenant，以及 public_read.

CLI：

filesystem-mcp-rs --memory-db C:/data/memory2.db --memory-access-mode enforce_private_only

环境：

FS_MCP_MEMORY_DB=C:/data/memory2.db
FS_MCP_MEMORY_ACCESS_MODE=enforce_visibility

MCP客户端配置示例：

{
  "command": "filesystem-mcp-rs",
  "args": ["--memory-access-mode", "enforce_private_only"],
  "env": {
    "FS_MCP_MEMORY_DB": "C:/data/memory2.db"
  }
}

推荐默认值：

• 本地/单用户： enforce_private_only
• 最轻松/共享的设置： allow_all
• 更严格的协作设置： enforce_visibility

屏幕截图工具

工具： screenshot_list_monitors, screenshot_list_windows, screenshot_capture_screen, screenshot_capture_window, screenshot_capture_region, screenshot_copy_to_clipboard

示例：

// List monitors
{"tool": "screenshot_list_monitors", "arguments": {}}

// List windows with title filter
{"tool": "screenshot_list_windows", "arguments": {"title_filter": "Chrome"}}

// Capture primary monitor to a file
{"tool": "screenshot_capture_screen", "arguments": {"output": "file", "path": "C:/temp/screen.png"}}

// Capture a window by title to base64
{"tool": "screenshot_capture_window", "arguments": {"title": "Terminal", "output": "base64"}}

// Capture a region on monitor 0
{"tool": "screenshot_capture_region", "arguments": {"monitor_id": 0, "x": 100, "y": 100, "width": 800, "height": 600, "output": "file", "path": "C:/temp/region.png"}}

// Copy an existing PNG to clipboard
{"tool": "screenshot_copy_to_clipboard", "arguments": {"path": "C:/temp/region.png"}}

Wave2工具（系统实用程序）

用于网络、流程、系统信息和实用程序的跨平台工具。

网络工具

port_users -使用端口查找进程

{"tool": "port_users", "arguments": {"port": 8080}}
// Returns: [{"pid": 1234, "name": "node", "local_addr": "127.0.0.1:8080", ...}]

net_connections -列出网络连接

{"tool": "net_connections", "arguments": {}}
{"tool": "net_connections", "arguments": {"pid": 1234}}  // Filter by process

port_available -检查端口是否空闲

{"tool": "port_available", "arguments": {"port": 3000}}
// Returns: {"port": 3000, "available": true}

工艺工具

proc_tree -流程树

{"tool": "proc_tree", "arguments": {}}  // Full tree
{"tool": "proc_tree", "arguments": {"root_pid": 1234}}  // Subtree from PID

proc_env -过程环境变量

{"tool": "proc_env", "arguments": {"pid": 1234}}

proc_files -按进程打开文件

{"tool": "proc_files", "arguments": {"pid": 1234}}
// Linux: /proc/pid/fd, macOS: lsof, Windows: limited info

系统工具

disk_usage -磁盘空间信息

{"tool": "disk_usage", "arguments": {}}  // All disks
{"tool": "disk_usage", "arguments": {"path": "C:/"}}  // Specific mount

sys_info -系统信息

{"tool": "sys_info", "arguments": {}}
// Returns: CPU cores, total/used RAM, swap, OS name/version, hostname, uptime

文件工具

file_diff -比较文件（统一差异）

使用以下命令比较两个文件 similar 机箱。返回与git兼容的统一diff：

{"tool": "file_diff", "arguments": {"path1": "old.txt", "path2": "new.txt"}}
{"tool": "file_diff", "arguments": {"path1": "a.rs", "path2": "b.rs", "context": 5}}

退货：

• unified_diff：标准统一diff格式（可与 patch -p0)
• hunks：带更改的结构化JSON（类型：插入/删除/上下文、行号）
• additions, deletions：更改计数

file_touch -创建/更新文件时间戳

{"tool": "file_touch", "arguments": {"path": "marker.txt"}}
{"tool": "file_touch", "arguments": {"path": "deep/nested/file.txt", "create_parents": true}}

实用工具

clipboard_read / clipboard_write

需要 screenshot-tools 特点（使用纸板箱）：

{"tool": "clipboard_read", "arguments": {}}
{"tool": "clipboard_write", "arguments": {"text": "Hello clipboard"}}

env_get / env_set / env_remove / env_list

环境变量（仅限当前流程）：

{"tool": "env_get", "arguments": {"name": "PATH"}}
{"tool": "env_set", "arguments": {"name": "MY_VAR", "value": "hello"}}
{"tool": "env_remove", "arguments": {"name": "MY_VAR"}}
{"tool": "env_list", "arguments": {}}

which -在PATH中查找可执行文件

{"tool": "which", "arguments": {"command": "python"}}
// Returns: {"command": "python", "found": true, "path": "/usr/bin/python", "all_matches": [...]}

文档工具

xlsx_read / xlsx_info -Excel文件

通过炉甘石读取Excel电子表格（支持.xlsx、.xls、.ods）：

{"tool": "xlsx_info", "arguments": {"path": "data.xlsx"}}
// Returns: sheet names, row/column counts

{"tool": "xlsx_read", "arguments": {"path": "data.xlsx"}}
{"tool": "xlsx_read", "arguments": {"path": "data.xlsx", "sheet": "Sheet2", "range": "A1:D10"}}

docx_read / docx_info -Word文档

通过docx-lite阅读Word文档：

{"tool": "docx_info", "arguments": {"path": "doc.docx"}}
{"tool": "docx_read", "arguments": {"path": "doc.docx"}}

AI/LLM工具

从llm-mcp-rs集成。通过环境变量需要API密钥。

提供商

• 双子座: GEMINI_API_KEY 或 LLM_MCP_GEMINI_API_KEY
• 大脑: CEREBRAS_API_KEY 或 LLM_MCP_CEREBRAS_API_KEY
• OpenAI: OPENAI_API_KEY 或 LLM_MCP_OPENAI_API_KEY

工具

// Send messages to LLM
{"tool": "ai_messages_gemini", "arguments": {"model": "gemini-pro", "messages": "Hello", "max_tokens": 1000}}
{"tool": "ai_messages_openai", "arguments": {"model": "gpt-4", "messages": [...], "max_tokens": 2000}}

// Count tokens
{"tool": "ai_count_tokens_gemini", "arguments": {"model": "gemini-pro", "messages": "Text to count"}}

高级编辑工具

edit_lines -基于线条的外科编辑

按行号精确编辑（1-索引）。当你知道确切的位置时，这是完美的：

• 运营: replace, insert_before, insert_after, delete
• 支持：单行或范围（startLine endLine）
• 用例：修复特定行，在已知位置添加导入，删除精确的代码块
• 特性：返回统一的差异、模拟运行模式以供预览

bulk_edits -跨文件批量搜索/替换

一次对多个文件应用相同的编辑。比单独编辑文件更有效：

• 文件选择：球状图案（例如。， *.rs, **/*.txt, src/**/*.js)
• 运营：在所有匹配的文件中搜索/替换文本
• 正则表达式支持: isRegex: true 启用带有捕获组的正则表达式模式($1, $2等等）
• 全部替换: replaceAll: true 替换所有事件，而不仅仅是第一个
• 错误处理：失败时继续，每个文件报告错误
• 用例：跨代码库重命名函数/变量，更新导入，修复各处的拼写错误，重构模式
• 特性：返回带有差异的摘要，模拟运行模式用于预览
• failOnNoMatch：如果为true，则没有匹配项的文件将返回错误（默认为false）

示例：

// Literal replace all occurrences
{"oldText": "use crate::foo", "newText": "use crate::bar::foo", "replaceAll": true}

// Regex with capture groups (refactor imports)
{"oldText": "use crate::(cache_man|event_bus|workers)", "newText": "use crate::core::$1", "isRegex": true, "replaceAll": true}

// Rename function across codebase
{"oldText": "old_function_name", "newText": "new_function_name", "replaceAll": true}

// Update version in all Cargo.toml
{"oldText": "version = \"0\\.1\\.\\d+\"", "newText": "version = \"0.2.0\"", "isRegex": true}

grep_files -内容搜索

搜索文本/正则表达式模式 里面 文件内容（不是文件名）：

• 支持：正则表达式模式、不区分大小写的搜索、上下文行
• 文件过滤：可选的glob包含/排除模式以限制范围
• 退货：将行与文件路径和行号匹配
• 用例：查找代码模式、定位函数定义、跨代码库搜索
• 备注：不要使用 rg/grep 通过 run_command；使用 grep_files 或 search_files 相反

例子：

{
  "path": ".",
  "pattern": "TODO|FIXME",
  "filePattern": "**/*.rs",
  "excludePatterns": ["target/**", "**/*.generated.rs"]
}

grep_context -上下文感知搜索

只有当特定术语出现在附近时，才能找到模式：

• 附近术语: nearbyPatterns list（默认为字面量，如果为正则表达式 nearbyIsRegex 真的）
• 窗口: nearbyWindowWords 和 nearbyWindowChars
• 方向: nearbyDirection =之前/之后/两者
• 匹配模式: nearbyMatchMode =任何/全部

例子：

{
  "path": ".",
  "pattern": "error",
  "nearbyPatterns": ["timeout", "retry"],
  "nearbyWindowWords": 6,
  "nearbyDirection": "before",
  "filePattern": "**/*.log"
}

read_text_file -大文件分页

使用灵活的分页选项读取文件以处理大文件：

• head：前N行（如Unix head）
• tail：最后N行（如Unix尾部）
• offset + limit：从第M行开始读取N行（1索引分页）
• max_chars：将输出截断为N个字符（UTF-8安全）
• 退货: totalLines 元数据在分页规划中的应用

示例：

// Read lines 100-199 (page 2 with 100 lines per page)
{"path": "large.txt", "offset": 100, "limit": 100}

// First 50 lines
{"path": "large.txt", "head": 50}

// Last 20 lines
{"path": "large.txt", "tail": 20}

// Limit output size (useful for token limits)
{"path": "large.txt", "max_chars": 50000}

// Combine pagination with truncation
{"path": "large.txt", "offset": 1, "limit": 100, "max_chars": 10000}

提取工具

extract_lines -按编号切割线条

从文件中删除行，并可选择返回提取的内容：

• 参数: path, line （1-索引）， endLine （可选）， dryRun, returnExtracted
• 例子：删除第5行，删除第10-20行，预览删除
• 用例：删除导入、删除代码块、剪切部分以粘贴到其他位置

extract_symbols -按位置剪切字符

按Unicode位置从文件中删除字符：

• 参数: path, start （0索引）， end 或 length, dryRun, returnExtracted
• 备注：使用Unicode字符（对多字节安全），而不是原始字节
• 用例：删除标题、剪切文本块、提取特定范围

二进制工具

所有二进制工具都使用base64编码进行数据传输。

read_binary -读取字节数

以指定的偏移量从二进制文件读取字节：

• 参数: path, offset, length
• 退货：Base64编码数据
• 用例：读取二进制标头，提取图像/可执行文件的部分

write_binary -写入字节数

将字节写入二进制文件：

• 参数: path, offset, data （base64）， mode （替换/插入）
• 如果缺少，则创建文件
• 用例：修补可执行文件、注入数据、修改标头

extract_binary -剪切字节数

从二进制文件中删除字节并返回它们：

• 参数: path, offset, length, dryRun
• 退货：Base64编码提取数据
• 用例：删除二进制部分，剪切数据以重新定位

patch_binary -查找/替换二进制模式

在文件中搜索和替换二进制模式：

• 参数: path, find （base64）， replace （base64）， all
• 用例：修补可执行文件、修复二进制数据、在非文本文件中搜索替换

哈希工具

file_hash -哈希文件

使用各种算法计算文件的哈希值：

• 参数: path, algorithm, offset, length
• 算法：md5、sha1、sha256（默认）、sha512、xxh64、murrow 3、怪异
• 退货: {hash, size, algorithm, offset, length}
• 部分散列：使用偏移量/长度仅对文件的一部分进行哈希运算
• 非加密货币：murrum3/spoxy是128位快速哈希（非常适合校验和、重复数据删除）
• 用例：验证文件完整性，检测更改，比较文件而不读取内容

示例：

// Hash entire file with SHA256
{"path": "file.bin"}

// Hash with fast non-crypto algorithm
{"path": "large.bin", "algorithm": "xxh64"}

// Hash first 1KB only
{"path": "file.bin", "offset": 0, "length": 1024}

// Hash from position 512 to end
{"path": "file.bin", "offset": 512}

file_hash_multiple -哈希多个文件

哈希多个文件并检查它们是否匹配：

• 参数: paths[], algorithm
• 退货: {results[], all_match}
• 用例：验证文件副本，检查备份完整性，检测重复内容

比较工具

compare_files -二进制文件比较

逐字节比较两个文件并进行详细分析：

• 参数: path1, path2, offset1, offset2, length, max_diffs, context_bytes
• 退货: {identical, size1, size2, hash1, hash2, first_diff_offset, total_diff_regions, match_percentage, diff_samples[]}
• 用例：验证导出/转换奇偶校验，调试序列化，查找二进制差异

compare_directories -目录树比较

递归比较两个目录树：

• 参数: path1, path2, recursive, compareContent （基于哈希）， ignorePatterns[]
• 退货: {identical, only_in_first[], only_in_second[], different[], same_count, diff_count}
• 用例：同步验证、备份验证、迁移测试

手表工具

tail_file -读取文件末尾

读取文件的最后N行或字节：

• 参数: path, lines, bytes, follow, timeout_ms
• 退货: {content, lines_returned, file_size, truncated}
• 跟随模式：等待添加新内容
• 用例：日志监控、监视构建输出、调试

watch_file -等待文件更改

阻止，直到文件更改或超时：

• 参数: path, timeout_ms, events[] （修改/创建/删除）
• 退货: {changed, event, new_size, elapsed_ms}
• 用例：等待构建工件，监控配置更改

JSON和PDF工具

read_json -使用查询读取JSON

使用JSONPath读取和查询JSON文件：

• 参数: path, query （类似JSONPath $.store.book[0].title), pretty
• 退货: {result, query_matched, pretty}
• 用例：提取配置值，查询API响应，解析结构化数据

read_pdf -提取PDF文本

从PDF文件中提取文本内容：

• 参数: path, pages （例如，“1-5”、“1,3,5”）， max_chars
• 退货: {text, pages_count, pages_extracted[], truncated}
• 用例：阅读文档，提取报告内容

存档工具

archive_extract -提取档案

提取ZIP、TAR或TAR。广州档案馆：

• 参数: path, destination, format （通过扩展自动检测）， files[] （可选过滤器）
• 退货: {extracted_count, files[]}
• 用例：打开下载包，从档案中提取特定文件

archive_create -创建档案

创建ZIP或TAR。广州档案馆：

• 参数: paths[], destination, format （zip/tar.gz）
• 退货: {path, size, file_count}
• 用例：打包文件进行备份，创建分发存档

统计工具

file_stats -文件/目录统计

获取有关文件和目录的详细统计信息：

• 参数: path, recursive
• 退货: {total_files, total_dirs, total_size, total_size_human, by_extension{}, largest_files[]}
• 用例：分析项目规模，查找大文件，了解代码库组成

find_duplicates -查找重复文件

查找内容相同的文件：

• 参数: path, min_size, by_content （基于哈希或仅限大小）
• 退货: {duplicate_groups[], total_wasted_space}
• 用例：清理磁盘空间，查找冗余文件

流程管理工具

run_command -使用全生命周期控制执行命令

LLM工作流的稳健流程执行。跨平台（Windows/macOS/Linux）。

执行模式(mode):

参数：

• 核心: command, args[], cwd, mode, shell, timeoutMs, killAfterMs
• 环境: env{} （设置/覆盖）， envPrepend{} （添加到现有内容之前）， envAppend{} （附加到现有）， clearEnv
• 标准输入: stdinFile, stdinData （管柱直接）
• 输出文件: stdoutFile, stderrFile, streamOutput （默认值：true）， streamDir
• 输出控制: stdoutHead, stdoutTail, stderrHead, stderrTail
• 输出过滤器: outputFilter: {include[], exclude[], context, contextBefore, contextAfter, maxLines} （类似grep的正则表达式过滤）

退货： {exitCode, stdout, stderr, pid, killed, timedOut, cancelled, durationMs, background, startedAt, finishedAt, stdoutFile, stderrFile, stdoutTotalLines, stderrTotalLines}

主要特点：

• 进展心跳：防止MCP客户端在长时间构建时超时120秒
• 进程树终止：在超时/取消时，杀死所有子进程（cargo build->rustc等）
• MCP取消：客户端可以取消，进程树立即被杀死
• 外壳模式: shell: true 包裹 cmd /C （赢）或 sh -c （Unix）用于管道， &&等等。
• 输出过滤器：使用include/exclude正则表达式和上下文行进行类似Grep的过滤。仅影响内联结果；完整的输出总是进入日志文件。

示例：

// Quick command
{"command": "git", "args": ["status"]}

// Long build with managed progress
{"command": "cargo", "args": ["build", "--release"], "mode": "managed", "timeoutMs": 1200000}

// Filter build output for errors/warnings
{"command": "cargo", "args": ["build"], "outputFilter": {"include": ["error\\[", "warning\\["], "context": 2, "maxLines": 50}}

// Shell pipes
{"command": "cat file.txt | grep error | head -20", "shell": true}

// Background server
{"command": "npm", "args": ["start"], "mode": "detached"}

// Debug with RUST_LOG
{"command": "cargo", "args": ["test"], "env": {"RUST_LOG": "debug"}}

// Prepend to PATH
{"command": "python", "args": ["script.py"], "envPrepend": {"PATH": "C:/custom/bin;"}}

// Pipe string to stdin
{"command": "python", "args": ["script.py"], "stdinData": "input data"}

// Head + tail (first 5 lines + last 10 lines)
{"command": "cargo", "args": ["test"], "stdoutHead": 5, "stdoutTail": 10, "streamOutput": false}

kill_process -杀死进程（使用树杀死）

终止一个进程或整个进程树。跨平台：

• 参数: pid, force （SIGKILL/Terminate进程）， tree （杀死所有子进程）
• 退货: {pid, success, killedCount, tree}
• 用例：停止失控的构建，终止所有子服务器

// Kill single process
{"pid": 12345, "force": true}

// Kill entire process tree
{"pid": 12345, "force": true, "tree": true}

list_processes -列出后台进程

列出此服务器启动的进程 run_command(mode: 'detached'):

• 参数: filter （可选命令名过滤器）
• 退货: {processes[]}
• 备注：仅跟踪由THIS服务器会话启动的进程

search_processes -搜索系统进程

按名称或命令行正则表达式搜索正在运行的进程。通过sysinfo crate实现跨平台：

• 参数: name_pattern （正则表达式）， cmdline_pattern （正则表达式）
• 退货: {processes[{pid, name, command_line, exe_path, memory_bytes, cpu_percent, status, user}], count}
• 例子:

- 查找Chrome浏览器： {name_pattern: "chrome"} - 按港口查找： {cmdline_pattern: "--port=3000"} - 查找Python脚本： {name_pattern: "python", cmdline_pattern: "script\\.py"}

HTTP工具（功能）

http_request -通用HTTP/HTTPS

发送带有标头、Cookie、查询参数和正文的请求：

{
  "method": "POST",
  "url": "https://api.example.com/v1/items",
  "headers": { "Authorization": "Bearer TOKEN", "Content-Type": "application/json" },
  "cookies": { "session": "abc123" },
  "query": { "page": "1" },
  "body": "{\"name\":\"demo\"}",
  "accept": "json",
  "timeoutMs": 20000
}

http_request_batch

在一次调用中运行多个请求：

{
  "requests": [
    { "id": "a", "method": "GET", "url": "https://example.com/a" },
    { "id": "b", "method": "GET", "url": "https://example.com/b" }
  ]
}

http_download / http_download_batch

将文件下载到本地路径：

{ "url": "https://example.com/file.zip", "path": "downloads/file.zip" }

S3工具（功能）

s3_list_buckets -列出Buckets

{}

s3_list -列出对象

{ "bucket": "my-bucket", "prefix": "reports/", "maxKeys": 100 }

s3_get / s3_put

{ "bucket": "my-bucket", "key": "reports/2025.csv", "outputPath": "reports/2025.csv" }

{ "bucket": "my-bucket", "key": "uploads/log.txt", "path": "logs/log.txt", "contentType": "text/plain" }

s3_delete / s3_copy / s3_presign

{ "bucket": "my-bucket", "key": "old/file.txt" }

{ "sourceBucket": "my-bucket", "sourceKey": "a.txt", "destBucket": "my-bucket", "destKey": "b.txt" }

{ "bucket": "my-bucket", "key": "uploads/file.bin", "method": "GET", "expiresInSeconds": 600 }

快速开始

cargo build --release

故障排除

JSON模式草案兼容性

一些客户端（qwen代码、gemini cli）仅使用Draft 7验证工具模式，而rmcp默认生成JSON模式2020-12。这会导致以下错误：

no schema with key or ref "https://json-schema.org/draft/2020-12/schema"

此处应用的修复：在启动时将工具输入模式重写为Draft 7。这在构建工具路由器时完成一次（请参见 src/main.rs)包括：

• 力 $schema 到 http://json-schema.org/draft-07/schema#
• 转换 $defs -> definitions
• 重写 $ref 路径 #/$defs/... -> #/definitions/...

这从工具模式中删除了2020-12草案的依赖关系，因此草案7验证器成功。这是针对每台服务器的修复；如果其他MCP服务器发出2020-12，它们仍将需要相同的重写。

运输方式

文件系统mcp-rs支持双模传输：

stdio模式（默认）

本地MCP客户端（Claude Desktop、Cursor、Codex）：

• stdin/stdout通信
• 默认情况下没有stderr （防止客户端连接错误）
• 文件日志记录 -l

HTTP流模式

远程访问、web集成、云部署：

• 带有SSE流的HTTP服务器
• MCP端点： /mcp
• 健康检查： /health
• 控制台日志已启用（可选文件 -l)

用法示例

获得帮助

filesystem-mcp-rs --help
filesystem-mcp-rs -V  # version

stdio模式

# Basic
filesystem-mcp-rs /projects /tmp

# With logging (writes to filesystem-mcp-rs.log)
filesystem-mcp-rs -l /projects

# Custom log file
filesystem-mcp-rs -l /var/log/mcp.log /projects

日志位置：当前工作目录或指定路径

HTTP流模式

# Local (http://127.0.0.1:8000)
filesystem-mcp-rs -s

# Custom port
filesystem-mcp-rs -s -p 9000

# Network accessible
filesystem-mcp-rs -s -b 0.0.0.0 -p 8000

# With file logging
filesystem-mcp-rs -s -l server.log

# Production setup
filesystem-mcp-rs -s -b 0.0.0.0 -p 8000 -l /var/log/mcp-server.log

检查健康状况:

curl http://localhost:8000/health
# Returns: OK

日志：默认情况下为控制台，文件为 -l 旗帜

所有选项

Usage: filesystem-mcp-rs [OPTIONS] [DIRS...]

Arguments:
  [DIRS...]  Allowed directories

Options:
      --allow-symlink-escape  Follow symlinks outside allowed dirs
  -s, --stream                HTTP mode (default: stdio)
  -p, --port 
           HTTP port [default: 8000]
  -b, --bind            Bind address [default: 127.0.0.1]
  -l, --log []          Log to file [default: filesystem-mcp-rs.log]
  -h, --help                  Print help
  -V, --version               Print version

测试

cargo test              # All tests (unit + integration + HTTP transport)
cargo test --test http_transport  # HTTP transport only

测验：

• 222个单元测试 （158）：

- 核心：哈希（12）、比较（18）、重复（8）、观察（6）、json_reader（10）、pdf_reader（10），存档（4）、统计（4），进程（23） - 文本：行编辑（5）、批量编辑（7）、编辑（4）、grep（6）、搜索（5） - 二进制：二进制（10） - 新浪潮2 （29）：net（6）、proc（5）、sys（5），file（7）、util（6） - 新-xlsx （6） ：read、info、unicode支持 - 新-docx （3） ：错误处理 - 新-llm （5） ：转换、模型映射

• 39项集成测试：文件操作、搜索、grep、提取、二进制、分页
• 4 HTTP传输测试：服务器启动、运行状况、MCP端点
• Unicode测试：俄语（Привил），中文（“”），表情符号(🦀)

发展

项目结构

src/
├── main.rs         - Entry point, CLI args, transport modes, MCP tools
├── core/
│   ├── allowed.rs  - Directory allowlist/validation
│   ├── logging.rs  - Transport-aware logging (stdio/stream)
│   ├── path.rs     - Path resolution, escape protection
│   └── format.rs   - Schema utilities
├── tools/
│   ├── fs_ops.rs      - File read/head/tail
│   ├── edit.rs        - Text-based edits + unified diff
│   ├── line_edit.rs   - Line-based surgical edits
│   ├── bulk_edit.rs   - Mass search/replace
│   ├── search.rs      - Glob search with excludes + type/size/time filters
│   ├── grep.rs        - Regex content search + invert/count modes
│   ├── binary.rs      - Binary file operations (read/write/extract/patch)
│   ├── hash.rs        - File hashing (MD5/SHA1/SHA256/SHA512/XXH64)
│   ├── compare.rs     - File and directory comparison
│   ├── watch.rs       - Tail file and watch for changes
│   ├── json_reader.rs - JSON reading with JSONPath queries
│   ├── pdf_reader.rs  - PDF text extraction
│   ├── archive.rs     - ZIP/TAR/TAR.GZ archive handling
│   ├── http_tools.rs  - HTTP/HTTPS requests + batch
│   ├── s3_tools.rs    - AWS S3 operations + batch
│   ├── stats.rs       - File/directory statistics
│   ├── duplicates.rs  - Duplicate file detection
│   ├── process.rs     - Process execution and management
│   ├── xlsx.rs        - Excel file reading (calamine)
│   ├── docx.rs        - Word document reading (docx-lite)
│   ├── llm/           - LLM provider integrations (Gemini, Cerebras, OpenAI)
│   └── wave2/         - System utilities:
│       ├── net.rs     - Network tools (port_users, net_connections, port_available)
│       ├── proc.rs    - Process tools (proc_tree, proc_env, proc_files)
│       ├── sys.rs     - System info (disk_usage, sys_info)
│       ├── file.rs    - File tools (file_diff, file_touch)
│       └── util.rs    - Utilities (clipboard, env_*, which)

tests/
├── integration.rs     - MCP tool integration tests
└── http_transport.rs  - HTTP server tests

添加HTTP传输测试

HTTP测试生成服务器子进程并验证端点：

#[tokio::test]
async fn test_http_server_health_check() {
    // Start server on random port
    // Poll /health until ready
    // Assert response
}

运输模式实施

• 标准: rmcp::transport::stdio() -默认情况下没有stderr日志记录
• 超文本传输协议: StreamableHttpService + LocalSessionManager -SSE流媒体

关键依赖

• rmcp 0.9.0 -MCP SDK（功能： transport-io, server, transport-streamable-http-server)
• axum 0.8 -HTTP服务器框架
• tokio -异步运行时

配置Claude代码

先决条件（仅限Windows）

重要提示： Windows上的Claude Code需要git bash。如果安装了git但bash不在PATH中，请设置环境变量：

# PowerShell (run as user, not admin)
[Environment]::SetEnvironmentVariable('CLAUDE_CODE_GIT_BASH_PATH', 'C:\Program Files\Git\bin\bash.exe', 'User')

或者，如果git安装在其他地方，请使用以下命令查找：

where git.exe
# Example output: C:\Programs\Git\bin\git.exe
# Then set: C:\Programs\Git\bin\bash.exe

设置变量后重新启动终端。

安装

构建并安装二进制文件：

cargo build --release
# Or install globally:
cargo install --path .

通过CLI添加MCP服务器（推荐）

Unix/Linux：

claude mcp add filesystem -- filesystem-mcp-rs /projects /tmp /home/user/work

Windows（使用完整路径）：

claude mcp add filesystem -- "C:/path/to/filesystem-mcp-rs/target/release/filesystem-mcp-rs.exe" "C:/projects"

重要提示： 请勿使用 --log-level 或添加via时的其他标志 claude mcp add -可执行文件不支持它们。仅传递目录路径。

手动配置（备选）

编辑 ~/.config/claude-code/config.json （Unix/Linux）或 C:\Users\\.config\claude-code\config.json （Windows）：

stdio模式（默认）：

{
  "mcpServers": {
    "filesystem": {
      "command": "filesystem-mcp-rs",
      "args": ["/projects", "/tmp"]
    }
  }
}

带日志记录的stdio：

{
  "mcpServers": {
    "filesystem": {
      "command": "filesystem-mcp-rs",
      "args": ["-l", "mcp-server.log", "/projects"]
    }
  }
}

HTTP流模式：

{
  "mcpServers": {
    "filesystem-http": {
      "command": "filesystem-mcp-rs",
      "args": ["-s", "-p", "8000", "-b", "127.0.0.1"]
    }
  }
}

带有自定义端口和日志记录的HTTP：

{
  "mcpServers": {
    "filesystem-http": {
      "command": "filesystem-mcp-rs",
      "args": ["-s", "-p", "9000", "-l", "http-server.log"]
    }
  }
}

验证连接

检查服务器是否已连接：

claude mcp list
# Should show: filesystem: ... - ✓ Connected

对于Claude Desktop，请在中使用相同的格式 claude_desktop_config.json.

为Codex配置

安装二进制文件：

cargo install --path .

编辑 ~/.codex/config.toml （Unix/Linux）或 C:\Users\\.codex\config.toml （Windows）：

stdio模式（默认）：

[mcp_servers.filesystem]
command = "filesystem-mcp-rs"
args = ["/projects", "/tmp"]

带日志记录的stdio：

[mcp_servers.filesystem]
command = "filesystem-mcp-rs"
args = ["-l", "codex-mcp.log", "/projects"]

HTTP流模式：

[mcp_servers.filesystem_http]
command = "filesystem-mcp-rs"
args = ["-s", "-p", "8000"]

具有自定义设置的HTTP：

[mcp_servers.filesystem_http]
command = "filesystem-mcp-rs"
args = ["-s", "-b", "0.0.0.0", "-p", "9000", "-l", "http-codex.log"]

注意：使用正斜杠(C:/path)或双反睫毛(C:\\path)Windows上的TOML字符串。

Symlink政策

• 默认：路径被规范化；转义满列表的符号链接将被拒绝。
• --allow_symlink_escape：如果符号链接本身位于allolist内部，即使目标位于外部，操作也可能跟随它。
• 工具始终验证路径；目前还没有原始的“对链接本身进行操作”模式。如果你需要非关注（在链接索引节点上操作），我们可以为每个工具添加一个选择加入标志。

结构

• src/main.rs --MCP服务器+工具
• src/core/path.rs --路径验证/逃逸保护
• src/tools/fs_ops.rs --读/头/尾
• src/tools/edit.rs, src/tools/diff.rs --基于文本的编辑+统一差异
• src/tools/line_edit.rs --基于线的手术编辑
• src/tools/bulk_edit.rs --跨文件进行大规模搜索/替换
• src/tools/search.rs --使用类型/大小/时间过滤器进行全局搜索
• src/tools/grep.rs --使用反转/计数模式的正则表达式内容搜索
• src/tools/binary.rs --二进制文件操作（读/写/提取/修补）
• src/tools/hash.rs --文件散列（MD5/SHA1/SHA256/SHA512/XXH64）
• src/tools/compare.rs --文件和目录比较
• src/tools/watch.rs --尾部文件并观察变化
• src/tools/json_reader.rs --使用JSONPath查询读取JSON
• src/tools/pdf_reader.rs --PDF文本提取
• src/tools/archive.rs --拉链/焦油/焦油。GZ档案处理
• src/tools/http_tools.rs --HTTP/HTTPS工具（功能）
• src/tools/s3_tools.rs --S3工具（功能）
• src/tools/stats.rs --文件/目录统计信息
• src/tools/duplicates.rs --重复文件检测
• tests/integration.rs --每工具集成覆盖率

对扩展开放（非跟随符号链接模式，额外工具）。

原始项目

这是官方的Rust端口 模型上下文协议文件系统服务器.

有关JavaScript版本，请参阅：https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem