关键词

文件系统访问资源管理工具调用LLM应用数据集成

使用说明

项目简介

本项目 'mcp-filesystem-server' 是一个使用 Go 语言实现的 MCP (Model Context Protocol) 服务器，旨在为 LLM (大型语言模型) 应用提供安全、可控的文件系统访问能力。它允许 LLM 客户端通过标准化的 MCP 协议，读取服务器端允许目录下的文件信息、文件内容，以及进行文件系统的相关操作。

主要功能点

  • 安全的文件访问控制：只允许访问服务器预先配置的目录，防止 LLM 客户端访问未授权的文件系统路径，增强安全性。
  • 文件信息查询：获取文件或目录的详细信息，如大小、创建时间、修改时间、权限等。
  • 目录浏览：列出目录下的文件和子目录，方便 LLM 理解文件系统结构。
  • 目录树形展示：以 JSON 格式返回目录的树形结构，方便程序化处理。
  • 文件内容读取：读取文本文件、图片文件等内容，并根据文件类型返回 TextContent、ImageContent 或 BlobResourceContent 等不同类型的 MCP 内容。对于大文件，提供资源 URI 引用，避免一次性加载过多内容。
  • 文件搜索：在指定目录下根据文件名模式搜索文件。
  • 目录创建：创建新的目录。
  • 文件移动：移动文件到新的位置。
  • 文件写入：创建、追加或覆盖文件内容。
  • 资源注册：将允许目录下的文件注册为 MCP 资源，允许客户端通过资源 URI 访问文件。
  • 多种内容格式支持：根据文件类型，支持返回文本、图片、二进制等多种格式的内容，并自动进行 Base64 编码（在大小限制内）。

安装步骤

  1. 安装 Go 环境：确保你的机器上已安装 Go 语言环境 (建议 Go 1.16 或更高版本)。
  2. 安装服务器：打开终端，运行以下命令安装 'mcp-filesystem-server'： 
    go install github.com/qiangmzsx/mcp-filesystem-server
    安装成功后，'mcp-filesystem-server' 可执行文件通常会位于 '$GOPATH/bin' 目录下，请确保该目录已添加到系统的 'PATH' 环境变量中。

服务器配置

MCP 客户端需要配置 'mcpServers' 字段来连接本文件系统服务器。以下是一个 'claude_desktop_config.json' 的配置示例，展示了如何配置名为 "filesystem" 的服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem-server",
      "args": [
        "/Users/username/Desktop",  // 允许访问的根目录1：例如用户桌面
        "/path/to/other/allowed/dir" // 允许访问的根目录2：例如其他允许的目录
      ]
    }
  }
}

配置说明:

  • '"filesystem"': 服务器名称，客户端使用此名称引用该服务器。可以自定义，例如 "my_filesystem_server"。
  • '"command": "mcp-filesystem-server"': 启动 MCP 服务器的命令。假设 'mcp-filesystem-server' 已正确安装并添加到 PATH 环境变量。
  • '"args": [...]"': 传递给 'mcp-filesystem-server' 命令的参数，用于指定允许 LLM 客户端访问的根目录。可以配置一个或多个根目录。请将示例中的目录路径替换为你希望允许 LLM 访问的实际目录路径。 例如，你可以设置为你的文档目录、下载目录等。

启动服务器: 服务器无需手动启动，MCP 客户端（如 Claude Desktop）在需要使用文件系统功能时，会自动根据配置启动 'mcp-filesystem-server' 进程。

基本使用方法

配置完成后，在支持 MCP 协议的 LLM 客户端中，你就可以通过工具调用 (Tools Call) 的方式使用文件系统服务器提供的功能。

常用工具 (Tools) 及其功能：

  • 'get_file_info': 获取文件或目录的详细信息。
    • 参数 'path': 要查询的文件或目录路径。
  • 'create_directory': 创建新的目录。
    • 参数 'path': 要创建的目录路径。
  • 'list_allowed_directories': 列出服务器允许访问的所有根目录 (无需参数)。
  • 'list_directory': 列出指定目录下的文件和子目录。
    • 参数 'path': 要列出的目录路径。
  • 'tree_directory': 以 JSON 格式返回指定目录的树形结构。
    • 参数 'path': 要展示树形结构的根目录路径。
    • 参数 'pretty': 是否格式化 JSON 输出 (布尔值，可选)。
    • 参数 'max_depth': 最大目录深度 (整数，可选，默认 3)。
  • 'move_file': 移动文件或目录。
    • 参数 'source': 源文件或目录路径。
    • 参数 'destination': 目标路径。
  • 'read_file': 读取文件内容。
    • 参数 'path': 要读取的文件路径。
  • 'search_files': 在指定目录下搜索文件。
    • 参数 'path': 搜索的根目录路径。
    • 参数 'pattern': 文件名搜索模式 (支持简单的通配符)。
  • 'write_file': 写入内容到文件。
    • 参数 'path': 要写入的文件路径。
    • 参数 'content': 要写入的文件内容。
    • 参数 'mode': 写入模式，可选 "create" (创建新文件), "append" (追加内容), "overwrite" (覆盖文件)。

示例工具调用 (JSON-RPC 请求，客户端自动处理):

以下是一些工具调用的示例，展示了客户端如何向 MCP 服务器发送请求 (实际使用中，客户端会根据用户指令自动构建和发送这些请求)：

  • 获取文件信息: 
    {"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_file_info","arguments":{"path":"/Users/username/Desktop/example.txt"}},"id":1}
  • 列出桌面目录: 
    {"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_directory","arguments":{"path":"/Users/username/Desktop"}},"id":2}
  • 读取文件内容: 
    {"jsonrpc":"2.0","method":"tools/call","params":{"name":"read_file","arguments":{"path":"/Users/username/Desktop/example.txt"}},"id":3}

客户端会解析服务器返回的 JSON-RPC 响应，并将结果以自然语言或其他合适的形式呈现给用户。

安全性提示: 请务必谨慎配置允许访问的根目录，避免将整个文件系统根目录或敏感目录暴露给 LLM 客户端，以确保数据安全。

信息

分类

数据库与文件

访问项目