📂 MCP 文件服务器

MCP 文件服务器 是一个安全、隔离的文件服务器，通过 模型控制协议（MCP） 提供对文件系统操作的受控访问。它支持在可配置的工作目录内读取、写入、列出、创建和删除文件及目录，并强制执行严格的安全检查。

目录

• 特性
• 安装与快速开始
• 命令行选项
• 与 LM Studio 集成
• MCP API 概览
  • initialize
  • tools/list
  • tools/call
• 可用工具
  • read_file
  • write_file
  • list_files
  • create_directory
  • delete_file
  • delete_directory
  • search_in_file
• 安全特性

🎯 特性

• 隔离操作 – 所有路径都限制在一个用户指定的工作目录内。
• 防止路径遍历，文件大小限制以及阻止特定扩展名。
• 支持通过 Base64 编码传输二进制数据以确保非文本数据的安全传输。
• 简单的行分隔 JSON-RPC 协议，适合标准输入/输出集成。
• 只需最小的 mcp.json 配置即可与 LM Studio 无缝集成。

📦 安装与快速开始

# 克隆仓库（如果尚未完成）
git clone https://github.com/undici77/MCPFileServer.git
cd MCPFileServer

# 运行启动脚本 – 它会创建虚拟环境，
# 安装依赖项并启动服务器。
./run.sh -d /path/to/working/directory

该脚本将：

• 验证 Python 3 是否可用。
• 创建一个 .venv 虚拟环境（如果不存在）。
• 安装所需包（aiofiles）。
• 使用提供的工作目录启动 main.py。

📌 提示： 确保脚本具有执行权限：
chmod +x run.sh

⚙️ 命令行选项

选项	描述
-d, --directory	工作目录的路径。如果省略，则使用当前进程目录。该目录必须存在且可读写。

🤝 与 LM Studio 集成

在项目中的 mcp.json 添加文件服务器条目：

{
  "mcpServers": {
    "file-server": {
      "command": "/绝对路径/to/MCPFileServer/run.sh",
      "args": [
        "-d",
        "/绝对路径/to/工作目录"
      ],
      "env": {
        "WORKING_DIR": "."
      }
    }
  }
}

• 将路径替换为您机器上的绝对位置。
• 确保 run.sh 可执行（chmod +x run.sh）并且已安装依赖项。

📡 MCP API 概览

所有通信遵循 JSON-RPC 2.0 标准通过标准输入/输出进行。

initialize

客户端发送此请求以获取服务器功能。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

服务器响应包含协议版本、功能及其名称/版本。

tools/list

检索支持工具的机器可读列表。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

响应包含工具定义数组（名称、描述、输入模式）。

tools/call

调用特定工具。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { … }
  }
}

注意： 工具名称键是 name，而不是 tool。这符合服务器实现。

🛠️ 可用工具

工具	描述
read_file	读取文件内容（文本或二进制）。
write_file	写入文本或 Base64 编码的二进制数据到文件中。
list_files	列出文件和目录，可选过滤。
create_directory	创建新子目录（根据需要创建父目录）。
delete_file	删除单个文件。
delete_directory	移除目录；可选强制删除非空树。
search_in_file	在文件或递归地在目录中搜索字符串，返回上下文摘录。

read_file

读取工作目录内文件的内容。 参数

名称	类型	必填	描述
path	字符串	是	目标文件的相对路径。
binary	布尔值	否 (默认: false)	设置为 true 以读取文件为二进制；结果为 Base64 编码。
示例

{
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "example.txt",
      "binary": false
    }
  }
}

write_file

将内容写入文件（如有必要，创建中间目录）。 参数

名称	类型	必填	描述
path	字符串	是	目标文件的相对路径。
content	字符串	是	要写入的文本，或当 binary=true 时为 Base64 编码的二进制数据。
binary	布尔值	否 (默认: false)	设置为 true 以将 content 视为 Base64 编码的二进制。
示例

{
  "method": "tools/call",
  "params": {
    "name": "write_file",
    "arguments": {
      "path": "output.txt",
      "content": "Hello, world!",
      "binary": false
    }
  }
}

list_files

列出工作目录下的文件和目录。 参数

名称	类型	必填	描述
extensions	字符串数组	否	按文件扩展名过滤（例如，[".py", ".txt"]）。如未指定，则列出所有文件。
recursive	布尔值	否 (默认: true)	当 true 时递归搜索子目录。
show_empty_dirs	布尔值	否 (默认: true)	包括不包含匹配文件的目录。
示例

{
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
      "extensions": [".py", ".txt"],
      "recursive": true,
      "show_empty_dirs": false
    }
  }
}

响应列表条目前缀为 DIR: 或 FILE: 并包括总结行。

create_directory

创建新目录（包括任何缺失的父目录）。 参数

名称	类型	必填	描述
path	字符串	是	要创建的目录的相对路径。
示例

{
  "method": "tools/call",
  "params": {
    "name": "create_directory",
    "arguments": { "path": "new_folder/subfolder" }
  }
}

delete_file

删除工作目录内的文件。 参数

名称	类型	必填	描述
path	字符串	是	要删除的文件的相对路径。
示例

{
  "method": "tools/call",
  "params": {
    "name": "delete_file",
    "arguments": { "path": "temp.txt" }
  }
}

delete_directory

删除目录，可选强制移除其内容。 参数

名称	类型	必填	描述
path	字符串	是	要删除的目录的相对路径。
force	布尔值	否 (默认: false)	当 true 时递归删除非空目录。
示例

{
  "method": "tools/call",
  "params": {
    "name": "delete_directory",
    "arguments": { "path": "old_folder", "force": true }
  }
}

search_in_file

在文件或递归地在目录内的所有文件中搜索字符串，返回上下文摘录。 参数

名称	类型	必填	描述
path	字符串	是	文件 或 目录的相对路径。
search_string	字符串	是	要搜索的文本。
context_lines	整数	否 (默认: 3)	每个匹配前后要包含的行数。
case_sensitive	布尔值	否 (默认: false)	当 true 时执行大小写敏感搜索。
max_matches	整数	否 (默认: 50)	每个文件返回的最大匹配数。
示例

{
  "method": "tools/call",
  "params": {
    "name": "search_in_file",
    "arguments": {
      "path": "log.txt",
      "search_string": "ERROR",
      "context_lines": 2,
      "case_sensitive": false,
      "max_matches": 10
    }
  }
}

响应包含带有行号的格式化摘录和总匹配数的总结。

---

🔐 安全特性

• 防止路径遍历 – 所有路径都相对于工作目录解析；试图逃逸会导致错误。
• 阻止特定扩展名及敏感文件名 – 拒绝 .exe、.bat、passwd 等文件。
• 文件大小限制 – 超过 100 MiB (MAX_FILE_SIZE) 的读写操作被拒绝。
• 空字节和危险模式检查 – 防止畸形输入攻击。

---

© 2025 Undici77 – 保留所有权利。