shutil-mcp

MCP-сервер, предоставляющий асинхронные утилиты для работы с файловой системой с использованием aioshutil.

Этот проект предлагает набор инструментов для работы с файловой системой, предназначенных для AI-агентов, возвращающих структурированный JSON-вывод вместо обычного текста. Это позволяет более точно и напрямую потреблять данные файловой системы моделями ИИ.

Возможности

• Асинхронные операции: использует aioshutil и исполнители потоков для неблокирующих задач файловой системы.

• JSON-вывод: все инструменты возвращают минифицированный JSON, оптимизированный для AI-агентов.

• Поддержка изоляции (jail): ограничение доступа к файловой системе конкретным деревом каталогов для безопасности.

• Проверка и целостность: mv и cp проверяют данные назначения перед удалением или завершением, предотвращая потерю данных при частичных сбоях.

• Обратимые изменения и отмена: chmod и chown возвращают предыдущие режимы и владельцев для облегчения немедленной отмены/повтора, с автоматическим откатом при сбое.

• Мягкое удаление и восстановление: rm поддерживает мягкое удаление с trash=True и соответствующий инструмент restore.

• Защита от Zip-Slip: unpack_archive проверяет все пути членов архива на атаки обхода каталогов / zip-slip.

• Подробные метаданные: такие инструменты, как ls и stat, предоставляют исчерпывающую информацию (размер, mtime, режим, владелец и т.д.).

• Поддержка HTTP-транспорта: включает встроенную поддержку SSE и потокового HTTP-транспорта.

Related MCP server: File Manager MCP Server

Доступные инструменты

• ls: список содержимого каталога с подробными метаданными.

• cp: копирование файлов или каталогов рекурсивно с проверкой.

• mv: перемещение/переименование файлов или каталогов с безопасной проверкой перед удалением.

• rm: удаление файлов или каталогов (поддерживает мягкое удаление с trash=True).

• restore: восстановление файлов или каталогов из корзины.

• chmod: изменение прав файлов/каталогов с откатом и предыдущим режимом.

• chown: изменение владельца файлов/каталогов с откатом и предыдущим владельцем.

• disk_usage: получение статистики использования диска для пути.

• which: поиск пути к исполняемому файлу.

• cat: чтение содержимого файла, опционально ограниченного диапазоном строк.

• glob: поиск файлов по шаблонам glob.

• grep: поиск содержимого файлов с использованием регулярных выражений.

• tree: получение рекурсивного дерева каталогов в виде вложенного JSON.

• make_archive: создание архивных файлов (zip, tar и т.д.) с защитой от перезаписи.

• unpack_archive: безопасное извлечение архивных файлов с защитой от zip-slip.

• get_archive_formats: список поддерживаемых форматов архивов.

Установка

pip install shutil-mcp

Использование

Запуск с stdio-транспортом

shutil-mcp --transport stdio

Запуск с ограничением jail

shutil-mcp --transport stdio --jail /path/to/projects

Запуск в качестве SSE-сервера

shutil-mcp --transport sse --jail /path/to/projects --port 8000

Разработка

См. DEVELOPMENT.md для подробных инструкций по разработке.

Лицензия

MIT