Tools Enhancement for file operator

[xiyuanyang-code]

Introduction

实现本地文件 CRUD 操作的 MCP Server 工具，让 Agent 可以调用该组件工具在文件环境中进行交互

具体任务

• 完成若干 @mcp.tool() 的函数实现并且优化 Docstring
• 添加其他的工具，方便 Agent 可以在文件环境中进行交互
  • 具体可以是对不同文件格式的特殊处理，比如处理 PDF 文件，处理 xslx 文件，处理 csv/parquet 等文件，处理 PNG 文件等等
• 在 test/test_mcp_params 中添加对应的测试用例（每个工具至少要有一个来保证工具整体可用性）

[itray25]

针对本任务，作出以下规划：

1. 访问及权限控制系统 (Access & Permission System)

建立服务端沙箱与客户端人机交互的双重防线，确保安全性与用户隐私。

• 服务端沙箱 (Server-side Sandboxing):
  • 白名单机制: 仅允许 Agent 访问配置中指定的 ALLOWED_ROOTS（如工作区目录）。
  • 黑名单阻断: 强制禁止访问系统敏感目录（如 Windows 的 System32, Linux 的 /etc/passwd 等），即使该路径在白名单子目录中。
  • 路径穿越防御: 在执行任何读写操作前，强制解析绝对路径，拦截 ../ 等尝试逃逸沙箱的行为。
• 人机回环 (Human-in-the-Loop Interaction):
  • 意图拦截: 当 Agent 发起 read_file 或 write_file 工具调用时，Client 端 UI 暂停执行。
  • 用户授权: 弹窗展示 Agent 想要操作的文件路径和目的，用户选择「本次允许」、「始终允许此会话」或「拒绝」。
  • 动态规划: Agent 根据获得的权限和文件列表，初步判断是否拥有足够信息；若不足，可再次发起请求搜索其他文件。

2. 智能内容提取策略 (Smart Content Extraction)

针对不同文件类型，Agent 不应只做简单的二进制读取，而应根据文件特征返回最适合 LLM 理解的数据格式，同时优化 Token 消耗。

• 结构化数据 (Excel / CSV / JSON):
  • 问题: 直接读取会导致 Token 爆炸且难以理解。
  • 策略: 使用 pandas 生成数据的摘要视图。返回列名（Columns）、数据类型（Dtypes）以及前 20 行数据预览（Markdown Table）。如果 Agent 需要统计信息，可由 Agent 自行编写 Python 代码分析（配合 Python Interpreter 工具）。
• 文档型数据 (PDF / DOCX):
  • 策略: 优先提取纯文本。
  • 实现: 集成 pypdf 等库。针对 PDF，按页码分块返回内容，并在头部注明总页数。
  • 后续扩展: 标记无法解析的图片区域，为未来集成 OCR Agent 预留接口。
• 代码与纯文本 (Python / TS / MD / TXT):
  • 策略: 直接读取，但增加行数限制保护。
  • 实现: 如果文件超过一定大小（如 50KB），自动截断并提示 Agent 使用 grep 搜索或按行号分段读取（read_file_range）。
• 多媒体与二进制 (Images / Binaries):
  • 策略: 禁止直接读取二进制流。
  • 实现: 仅返回元数据（文件大小、修改时间、MIME类型），并提示 Agent 该文件无法作为文本阅读。

[xiyuanyang-code]

Cool! 我觉的可以
文件操作其实可以分成 CRUD 四个类别，你的“智能内容提取策略”主要是针对‘R’（Read）进行的，其实其他三个也可以额外想想并做一些安全性的设计

[xiyuanyang-code]

mcp_server/operate_file/server.py
应该只需要修改这个文件就行

然后在 test/test_mcp_params 新建一个 operate_file.json 文件 里面是一些测试用例
测试用例的格式可以看 test/test_mcp_params/base_toolkit.json

[xiyuanyang-code]

Finished