文件管理工具

📁 文件管理MCP项目

🔧 一个轻量级的Python项目，演示了一个使用 模型上下文协议（MCP）。它提供目录扫描、文件重命名和 具有安全检查和可重用实用程序的组织功能。

🚀 这个项目做什么

此存储库实现了一个小型应用程序，允许用户执行 以受控的方式进行文件系统操作。核心能力包括：

• 🔍 正在扫描目录 以及预览文件内容。
• ✏️ 重命名文件 在批准的路径内。
• 📂 移动文件 根据其扩展名，将其添加到特定的子文件夹中。
• ✅ 所有操作都由路径验证器保护，以保持操作在 允许的目录，防止未经授权的访问。

这些功能通过一组MCP工具公开，因此可以集成 通过HTTP或其他协议端点进入更大的系统。

📂 项目结构

EX1_MCP/
├── fastmcp.json          # MCP configuration
├── main.py               # Entry point (if any)
├── models/
│   └── models.py         # Pydantic input models for the tools
├── services/
│   ├── file_service.py   # Core file operation logic
│   └── path_validator.py # Security helper to keep paths safe
├── utils/
│   ├── utils.py          # Generic misc helpers
│   └── validation.py     # Input/filename/directory validators
├── settings.py           # Environment settings loader
├── logs/                 # Empty folder reserved for log files
└── README.md             # This documentation

▫️ 模型/ –定义输入的形状(RenameFileIn, ScanFilesIn, MoveFilesIn)使用Pydantic。

▫️ 服务/ –包含业务逻辑。 file_service 执行操作 并问 path_validator 是否允许目录。

▫️ utils/ –杂项助手，包括路径和字符串验证。

▫️ settings.py –阅读便利码 .env 价值观。

🛠 MCP工具可用

这些方法适合作为MCP服务器中的端点：

每个工具都需要一个Pydantic模型 models/models.py 作为 输入并返回结构化结果或简单的错误消息。

📦 安装

1. 克隆存储库：

   复制

   git clone <repo-url> EX1_MCP
   cd EX1_MCP
   

2. 创建并激活虚拟环境：

   复制

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1    # Windows PowerShell
   

3. 安装依赖项（如果中列出了任何依赖项 pyproject.toml 或手动）：

   复制

   pip install -r requirements.txt  # or `poetry install` if using Poetry
   

4. 可选择在 .env 文件旁边 settings.py.

▶️ 用法

作为一个图书馆

导入服务并直接调用它们：

from services.file_service import FileService
from models.models import ScanFilesIn

svc = FileService(allowed_directories=[r"C:\Users\User\Downloads\TRY"])
result = svc.scan_files(ScanFilesIn(dir_path=r"C:\Users\User\Downloads\TRY"))
print(result)

作为MCP服务器

配置MCP服务器（例如，使用 fastmcp.json)并注册 FileService 方法作为工具。示例 fastmcp.json 已经得分 在 services/file_service.py.通过HTTP运行MCP主机和调用工具 根据MCP协议。

日志记录

任何运行时日志都可以写入 logs/ 目录。目前 空的，但保留供将来使用。

📝 备注

• 🛡️ 路径验证是中心：仅列出以下目录 allowed_directories 可能被操纵。
• 📦 该项目规模很小，旨在作为演示或启动 用于构建基于MCP的文件实用程序的模板。

🤝 贡献

请随时打开问题或提交pull请求。对新工具或 欢迎进行额外验证！