使用说明

项目简介

这是一个基于 Model Context Protocol (MCP) 的文件服务器示例，展示了如何通过MCP向大型语言模型（LLM）客户端提供文件系统访问能力。它托管了一系列工具和资源，允许LLM安全地执行文件和文件夹操作，所有操作都被限制在预设的基础路径内，以确保安全性。

主要功能点

文件操作：支持读取、写入、删除、复制、移动文件。
文件信息：获取文件大小、修改时间等元数据。
文件夹操作：创建新目录、删除空目录、列出目录内容、深入分析文件夹结构（包括文件列表、大小汇总等）。
文件搜索：根据文件名模式在指定目录及其子目录中搜索文件（支持通配符）。
文件比较：比较两个文本文件的内容差异，生成统一差异格式的输出。
压缩/解压：创建ZIP档案或从ZIP档案中提取文件。
安全路径管理：所有文件系统操作都强制限定在服务器配置的特定本地文件夹路径内，防止客户端访问服务器上的其他敏感区域。
日志与进度报告：服务器在执行耗时操作时，会向客户端报告操作日志和进度状态。

安装步骤

克隆仓库：将该GitHub仓库克隆到你的本地计算机。
进入目录：使用终端或命令行工具进入克隆下来的仓库目录。
环境准备：确保你的系统安装了 Python 3.12 或更高版本，以及 'uv' 包管理器。

创建并激活虚拟环境：运行以下命令创建并激活一个Python虚拟环境：

uv venv
source .venv/bin/activate  # 在 Windows 系统上，可能使用 .venv\Scripts\activate

安装依赖：安装项目所需的所有依赖库：

uv pip install -r requirements.txt

配置基础路径：复制仓库根目录下的 '.env.example' 文件，重命名为 '.env'。编辑 '.env' 文件，设置 'ALLOWED_BASE_PATH' 变量为你希望MCP服务器能够访问的本地文件系统的根路径（例如，设置为 'E:\Test' 或 '/home/user/mcp_files'）。确保该路径存在。

服务器配置

该仓库包含了多个MCP服务器示例。以 'learning/Servers/enhanced_folder_server.py' 文件服务器为例，它是一个独立的Python脚本，由兼容的MCP客户端根据需要启动。MCP客户端通常通过配置文件的形式指定如何连接到服务器。以下是连接到此文件服务器所需的配置信息示例（JSON格式）：

{
  "name": "folder_server",
  "description": "Provides file system access within a restricted base path.",
  "command": "python",
  "args": ["path/to/your/cloned/repo/learning/Servers/enhanced_folder_server.py"],
  "transport": "stdio"
}

'name': 为此服务器指定的唯一名称，方便客户端识别和管理。
'description': 服务器功能的简要描述。
'command': 启动服务器脚本所使用的命令行程序（例如 'python'）。
'args': 传递给 'command' 的参数列表。第一个参数是服务器脚本（如 'enhanced_folder_server.py'）在你本地文件系统中的完整或相对路径。
'transport': 客户端与服务器通信所使用的传输协议。根据 'enhanced_folder_server.py' 脚本中的 'if name == "main":' 段，该服务器配置为使用 'stdio' 传输。

基本使用方法

启动客户端：使用一个支持MCP协议并配置了此服务器的MCP客户端（例如，该仓库中也包含了一些客户端示例，或者使用其他兼容的MCP客户端应用）。客户端会自动读取配置并尝试启动/连接服务器。
LLM交互：通过LLM客户端与服务器进行交互。LLM可以识别服务器提供的工具（如 'file_read', 'folder_analysis', 'file_write' 等）及其功能描述。
调用工具：当LLM需要执行文件操作时，它会根据用户的指令，通过MCP协议调用服务器上相应的工具，并传递所需的参数（如文件路径、写入内容等）。
处理响应：服务器执行操作后，会将结果（如文件内容、操作状态、分析列表等）通过MCP协议返回给客户端。客户端接收到响应后，可以将其提供给LLM进行进一步处理或向用户展示。

例如，用户可能通过LLM客户端发起一个请求：“列出我的文件目录 'documents' 下的所有文件”。LLM客户端（或其内置逻辑）识别出这需要调用 'folder_list' 工具，然后向MCP文件服务器发送一个 'call_tool' 请求，参数为 '{"path": "documents"}'。服务器执行 'os.listdir' 等操作，并将结果（一个文件和文件夹列表）返回给客户端，LLM再将这个列表格式化后呈现给用户。

关键词