Filesystem MCP Server

文件系统 MCP 服务

一个用于文件系统操作的安全模型上下文协议（MCP）服务实现。

概述

文件系统 MCP 服务通过模型上下文协议，为与本地文件系统交互提供标准化接口。它允许客户端以安全且受控的方式执行常见文件操作，例如列出目录、读取文件和搜索文件内容。

功能

该服务提供以下 MCP 工具：

1. list：列出文件和目录及其元数据
2. read：使用多种编码选项读取文件内容
3. write：创建或更新文件内容
4. mkdir：创建目录
5. delete：删除文件或目录
6. copy：复制文件或目录
7. move：移动或重命名文件或目录
8. info：获取文件／目录的详细信息
9. search：搜索文件内容（类似 grep 的功能）
10. list_allowed_dirs：列出服务上配置的所有允许目录
11. edit：对文件进行局部编辑，而无需重写全部内容

出于安全考虑，所有操作都限制在可配置的允许目录内。

安全性

所有文件系统操作都限制在一组可配置的允许目录内。服务会验证路径，以防止目录遍历攻击和其他安全问题。任何试图访问允许目录之外文件的操作都会被拒绝，并返回相应的错误消息。

路径要求

提供给服务的所有文件和目录路径都必须是完整的绝对路径。这些路径必须位于某个已配置的允许目录内，才能访问。

安装

先决条件：

• Rust 工具链（1.70.0 或更高版本）
• Cargo 包管理器

构建服务：

cargo build --release

用法

运行服务

# Run with current directory as the allowed directory
./target/release/fs-mcp-server

# Specify allowed directories (comma-separated)
./target/release/fs-mcp-server --allowed-dirs /path/to/dir1,/path/to/dir2

# Use a configuration file listing allowed directories
./target/release/fs-mcp-server --config-file /path/to/config.txt

# Set maximum file size
./target/release/fs-mcp-server --max-file-size 5242880  # 5MB

配置文件

你可以在配置文件中指定允许的目录，每行一个目录：

# This is a comment
/path/to/directory1
/path/to/directory2
/another/path

环境变量

可以使用以下环境变量配置服务：

• FS_ALLOWED_DIRS：文件系统操作允许的目录列表，以逗号分隔
• FS_CONFIG_FILE：列出允许目录的配置文件路径
• FS_MAX_FILE_SIZE：读取操作允许的最大文件大小（以字节为单位）
• FS_REQUEST_TIMEOUT：请求超时时间，以秒为单位
• FS_LOG_LEVEL：日志级别（error、warn、info、debug、trace）
• FS_LOG_FILE：日志文件路径

示例：

FS_ALLOWED_DIRS=/data,/home/user/docs FS_LOG_LEVEL=debug ./target/release/fs-mcp-server

协议工具

该服务提供以下 MCP 工具：

list

列出指定路径下的文件和目录。

参数：

• path：要列出文件的目录完整路径
• pattern：用于筛选文件的可选 glob 模式（默认值："*"）
• recursive：是否递归列出文件（默认值：false）
• include_hidden：是否包含隐藏文件（默认值：false）
• metadata：是否包含文件元数据（默认值：true）

read

读取文件内容，支持不同编码和分段读取。

参数：

• path：要读取的文件完整路径
• encoding：文件编码（utf8、base64、binary）（默认值：utf8）
• start_line：分段读取的起始行（从 0 开始计数）
• end_line：分段读取的结束行（包含该行）
• max_size：读取的最大字节数（默认值：1MB）

search

搜索文件内容，查找匹配的模式（类似 grep 的功能）。

参数：

• root_path：要开始搜索的根目录完整路径
• pattern：要在文件中搜索的文本模式
• regex：是否将 pattern 视为正则表达式（默认：false）
• file_pattern：用于筛选要搜索的文件的可选 glob 模式（默认："*"）
• recursive：是否递归搜索目录（默认：true）
• case_sensitive：搜索是否区分大小写（默认：false）
• max_results：返回的最大结果数（默认：100）
• max_file_size：要搜索的最大文件大小（默认：10MB）
• context_lines：要包含的上下文行数（默认：0）
• timeout_secs：搜索的最长时间（默认：30s）

edit

对文件进行局部编辑，无需重写全部内容。

参数：

• path：要编辑的文件完整路径
• operations：要执行的编辑操作列表（按顺序执行）
  • 替换操作：
    • type："replace"
    • find：要查找的文本（精确匹配）
    • replace：要插入以替换的文本
    • occurrence：要替换的匹配项（从 0 开始，-1 表示全部）（默认：0）
    • case_sensitive：搜索是否区分大小写（默认：true）
  • 插入操作：
    • type："insert"
    • position：要插入的位置（字符位置，从 0 开始）
    • content：要插入的文本
  • 删除操作：
    • type："delete"
    • start：起始字符位置（从 0 开始，包含）
    • end：结束字符位置（从 0 开始，不包含）
  • 替换行操作：
    • type："replace_lines"
    • start_line：起始行号（从 0 开始，包含）
    • end_line：结束行号（从 0 开始，包含）
    • content：要插入以替换的文本
• create_if_missing：如果文件不存在，则创建文件（默认：false）
• backup：编辑前创建原始文件的备份（默认：false）

示例：

{
  "path": "/path/to/file.txt",
  "operations": [
    {
      "type": "replace",
      "find": "hello",
      "replace": "hello world",
      "occurrence": 0,
      "case_sensitive": true
    },
    {
      "type": "insert",
      "position": 100,
      "content": "new text at position 100"
    },
    {
      "type": "replace_lines",
      "start_line": 5,
      "end_line": 7,
      "content": "new line 6\nnew line 7\nnew line 8"
    }
  ],
  "backup": true
}

list_allowed_dirs

列出已配置为允许访问的所有目录。

参数：

• 无

客户端集成

要将此服务与 MCP 客户端配合使用：

1. 导入适用于你所用语言的 MCP 客户端库
2. 使用 stdio 传输连接到服务
3. 使用 MCP 协议调用可用工具

客户端代码示例（使用 Rust MCP 客户端）：

use mcp_client::{ClientBuilder, transport::StdioTransport};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    // Path to the server executable
    let server_path = "path/to/fs-mcp-server";
    
    // Create and connect to server
    let (transport, mut receiver) = StdioTransport::new(server_path, vec![]);
    
    let client = ClientBuilder::new("fs-client", "0.1.0")
        .with_transport(transport)
        .build()?;
    
    // Start message handling
    let client_for_handler = client.clone();
    tokio::spawn(async move {
        while let Some(message) = receiver.recv().await {
            if let Err(e) = client_for_handler.handle_message(message).await {
                eprintln!("Error handling message: {}", e);
            }
        }
    });
    
    // Initialize the client
    let init_result = client.initialize().await?;
    println!("Connected to: {} v{}", init_result.server_info.name, init_result.server_info.version);
    
    // List all allowed directories
    let allowed_dirs_result = client.call_tool("list_allowed_dirs", &json!({})).await?;
    println!("Allowed directories: {:?}", allowed_dirs_result);
    
    // List files in a directory
    let list_result = client.call_tool("list", &json!({
        "path": "/path/to/directory"
    })).await?;
    
    // Process result
    println!("List result: {:?}", list_result);
    
    // Edit a file by replacing text
    let edit_result = client.call_tool("edit", &json!({
        "path": "/path/to/file.txt",
        "operations": [
            {
                "type": "replace",
                "find": "TODO",
                "replace": "DONE",
                "occurrence": -1
            }
        ],
        "backup": true
    })).await?;
    
    // Process result
    println!("Edit result: {:?}", edit_result);
    
    // Shutdown
    client.shutdown().await?;
    
    Ok(())
}

开发

项目结构

• src/main.rs：服务入口和初始化
• src/tools/：工具实现（list、read、search、edit 等）
• src/utils/：实用函数（路径验证等）

添加新工具

要添加新的文件系统工具：

1. 在 src/tools/ 中为你的工具创建一个新文件
2. 实现该工具的 schema 和 execute 函数
3. 在 main.rs 的 build_server() 中将该工具添加到服务构建器

为不同平台构建

# Build for Linux
cargo build --release --target x86_64-unknown-linux-gnu

# Build for macOS
cargo build --release --target x86_64-apple-darwin

# Build for Windows
cargo build --release --target x86_64-pc-windows-msvc

许可证

MIT