MCP工具：文件系统、分析和执行
概述
该项目为文件编辑、备份、代码分析和执行提供了强大的、包含工作区的工具，专为人工智能驱动的代码助手和自动化而设计。所有工具都返回结构化字典，便于编程使用。
______________________________________________________________________
环境和容器设置
需求
- Python 3.11+
- Docker（用于容器化使用）
- 推荐：
black,flake8,vulture,mutmut用于代码格式化和分析
在Docker中运行
- 塑造形象：
docker build -t mcp-tools .- 运行容器：
docker run --rm -it -v $(pwd):/app code_exec_mcp-mcp-server- 要映射自定义工作区，请使用 -v /your/workspace:/app/.workspace.
- 在容器内运行测试：
pytest -v test/scripts______________________________________________________________________
文件系统工具(tools/filesystem.py)
工作空间管理
- set_workspace（workspace_name:str）->字典
- 设置活动工作区目录（创建于 .workspace/). - 如果工作区不存在，则创建它。为了安全起见，所有文件操作都包含在此工作区中。 - 退货： { "status": "success", "old_workspace": ..., "new_workspace": ..., "message": ... }
- get_workspace（）->字典
- 获取当前工作区路径和状态。 - 退货： { "status": "success", "workspace": ..., "exists": ..., "is_dir": ... }
______________________________________________________________________
文件编辑与差异
- edit_file（文件路径，内容=无，create_backup=真，模式=无，diff_text=无，line_number=无，new_content=无，start_line=无，end_line=没有）->dict
- 原子编辑文件。支持多种模式： - 覆盖：将文件替换为 content （默认模式）。 - 标准差异：应用统一的差异(mode="unified_diff", diff_text). - 编辑线：替换一条线(mode="line_edit", line_number, new_content). - 跨度编辑：替换一系列线路(mode="span_edit", start_line, end_line, new_content). - 如果 create_backup 如果为True，则在编辑之前会进行备份。 - 所有更改都是原子性的（写入临时文件，然后移动）。 - 退货： { "status": "success"|"error", "filepath": ..., "mode": ..., "changes_made": ..., "preview": ..., ... } - 边缘案例： - 如果文件在工作区之外，或者所选模式缺少必需的参数，则返回错误。 - 稳健地处理编码问题和大文件。
- preview_edit（…）/validate_endit（…）
- 预览或验证编辑而不应用它。 - 退货： 带有状态、预览和/或验证错误的骰子。 - 用途： 使用前 edit_file 检查会发生什么变化或验证参数。
______________________________________________________________________
备份和恢复
- 备份文件（文件路径）->字典
- 在中创建文件的带时间戳的备份 .mcp_backups/ 在工作空间内。 - 存储文件和JSON元数据文件。 - 退货： { "status": "success"|"error", "backup_file": ..., "timestamp": ..., ... } - 边缘案例： - 如果文件不存在或位于工作区之外，则返回错误。
- restore_file（文件路径，backup_timestamp=无）->dict
- 从备份中还原文件（按时间戳）。如果没有给出时间戳，则还原最新备份。 - 退货： { "status": "success"|"error", "restored_from": ..., ... } - 边缘案例： - 如果不存在备份或时间戳无效，则返回错误。
- list_backups（文件路径=无）->dict
- 列出文件的所有备份或工作区中的所有文件。 - 退货： { "status": "success", "backups": [...], "total_backups": ... } - 每个备份条目都包括文件路径、时间戳、提交状态和元数据。
- commit-changes（文件路径，commit_message=“”）->dict
- 通过消息将最新备份标记为已提交。 - 退货： { "status": "success"|"error", ... } - 边缘案例： - 如果文件不存在备份，则返回错误。
______________________________________________________________________
差异和格式
- compare_versions（文件路径，backup_timestamp=None）->dict
- 显示当前文件和备份之间的统一差异（按时间戳）。 - 退货： { "status": "success"|"error", "diff": ..., ... } - 边缘案例： - 如果文件或备份不存在，则返回错误。
- generate_diff（text1，text2，filename=“file.txt”）->dict
- 在两个文本blob之间生成统一的差异。 - 退货： { "status": "success"|"error", "diff": ... }
- format_code（文件路径）->dict
- 使用格式化Python文件 black （必须安装在环境中）。 - 退货： { "status": "success"|"error", "message": ... } - 边缘案例： - 如果出现以下情况，则返回错误 black 未安装或文件不是有效的Python。
______________________________________________________________________
文件系统列表和文件切片
- list_path（path=“.”）->dict
- 列出给定路径下的文件和目录（非递归）。 - 退货： { "status": "success"|"error", "entries": [ {name, is_dir, size, mtime}, ... ] } - 边缘案例： - 如果路径不存在或不是目录，则返回错误。
- list_path_re草书（path=“.”）->字典
- 递归列出路径下的所有文件和目录。 - 退货： { "status": "success"|"error", "entries": [ {path, is_dir, size, mtime}, ... ] }
- get_head（文件路径，n=10）->字典
- 获取第一个 n 文件的行数（默认值为10）。 - 退货： { "status": "success"|"error", "lines": [...] } - 边缘案例： - 如果文件小于，则返回所有行 n 线。 - 如果文件不存在，则返回错误。
- get_tail（文件路径，n=10）->dict
- 获取最后一个 n 文件的行数（默认值为10）。 - 退货： { "status": "success"|"error", "lines": [...] } - 边缘案例： - 如果文件小于，则返回所有行 n 线。 - 如果文件不存在，则返回错误。
- get_lines（文件路径、开始、结束）->dict
- 从以下位置获取行 start 到 end （含1）。 - 退货： { "status": "success"|"error", "lines": [...] } - 边缘案例： - 如果范围无效或文件不存在，则返回错误。
______________________________________________________________________
分析工具(tools/analysis.py)
- check_syntax（文件路径）->列表\[str\]
- 检查Python语法。如果有效，则返回空列表，否则返回错误消息列表（每个错误一个）。 - 边缘案例： - 处理语法错误、文件丢失和编码问题。
- check_syntax_multiple_files（文件路径）->Dict\[str，List\[str\]\]
- 检查多个文件的语法。返回一个将文件路径映射到错误列表的字典。
- lint_file（文件路径）->str
- 跑 flake8 文件上的门楣。以字符串形式返回linter输出。 - 边缘案例： - 如果出现以下情况，则返回错误消息 flake8 未安装或文件丢失。
- run_mutation_tests（文件路径，test_file=无）->str
- 使用以下命令运行突变测试 mutmut。可选择指定测试文件。 - 退货： 突变测试运行的输出。
- **search_code（模式，目录=“.”，文件模式=“\*.py”）->列表\[Dict\]**
- 在目录下的代码文件中搜索正则表达式模式。 - 退货： 包含文件、行号和代码行的字典列表。
- search_symbols（name，kind=“function”，directory=“.”）->列表\[str\]
- 按名称查找函数或类定义。 - 退货： 文件列表：找到符号的行字符串。
- find_unused_code（directory=“.”）->列表\[str\]
- 使用查找未使用的代码 vulture. - 退货： 未使用的代码行或错误消息列表。
- extract_docstring（文件路径）->Dict\[str，str\]
- 从文件中的所有函数和类中提取文档字符串。 - 退货： 将函数/类名映射到文档字符串。
- suggest_test_cases（文件路径，函数=无）->str
- 为函数或文件生成测试骨架。 - 退货： 带有测试函数或文件模板的字符串。
______________________________________________________________________
执行和调试工具(tools/exec_debug.py)
- execute_python（代码，超时=30）->Dict
- 在子进程中执行Python代码（作为字符串），并有超时。 - 退货： 带有状态、stdout、stderr、返回代码和执行时间的Dict。 - 边缘案例： - 如果执行失败或超时，则返回错误状态和消息。
- execute_python_file（文件，超时=30）->Dict
- 在子进程中执行Python文件，但有超时。 - 退货： 带有状态、stdout、stderr、返回代码和执行时间的Dict。
- debug_python_file（文件，断点，超时=60）->str
- 在下运行Python文件 pdb 在指定的行号处有断点。 - 退货： 完整的会话记录为字符串。 - 边缘案例： - 如果文件不存在，则引发FileNotFoundError。 - 捕获异常并将其打印在成绩单中。
______________________________________________________________________
用法
- 所有函数都设计为从Python导入和调用，或用作AI代理工具集的一部分。
- 为了安全起见，所有文件操作都包含在工作区中。
- 所有结果都以字典（或某些分析函数的列表）的形式返回
"status": "success"或"error"以及详细的字段。
______________________________________________________________________