filesystem-mcp

Файловая система MCP-сервера (@sylphlab/filesystem-mcp)

Предоставьте своим агентам ИИ (например, Клайну/Клоду) безопасный, эффективный и экономящий токены доступ к файлам вашего проекта. Этот сервер Node.js реализует протокол контекста модели (MCP) для предоставления надежного набора инструментов файловой системы, работающих безопасно в определенном корневом каталоге проекта.

Установка

Существует несколько способов использования сервера файловой системы MCP:

1. Рекомендуется: npx (или bunx ) через MCP Host Configuration

Самый простой способ — через npx или bunx , настроенные непосредственно в вашей среде хоста MCP (например, mcp_settings.json Roo/Cline). Это гарантирует, что вы всегда будете использовать последнюю версию из npm без необходимости локальной установки или Docker.

Пример ( npx ):

Пример ( bunx ):

Важно: Сервер использует свой собственный Текущий рабочий каталог ( cwd ) в качестве корня проекта. Убедитесь, что ваш MCP Host (например, Cline/VSCode) настроен на запуск команды с cwd , установленным на корневой каталог вашего активного проекта.

2. Докер

Используйте официальный образ Docker для контейнеризированных сред.

Пример конфигурации хоста MCP:

Не забудьте заменить /path/to/your/project на правильный абсолютный путь.

3. Локальная сборка (для разработки)

1. Клон: git clone https://github.com/sylphlab/filesystem-mcp.git
2. Установка: cd filesystem-mcp && pnpm install (сейчас использую pnpm)
3. Сборка: pnpm run build
4. Настройте хост MCP:
   { "mcpServers": { "filesystem-mcp": { "command": "node", "args": ["/path/to/cloned/repo/filesystem-mcp/dist/index.js"], // Updated build dir "name": "Filesystem (Local Build)" } } }
   Примечание: Запустите команду node из каталога, который вы планируете использовать в качестве корневого каталога проекта.

Быстрый старт

После настройки сервера на хосте MCP (см. Установка) ваш агент ИИ может немедленно начать использовать инструменты файловой системы.

Пример взаимодействия агента (концептуальный):

Почему стоит выбрать этот проект?

• 🛡️ Безопасный и удобный фокус на корне проекта: операции ограничены корнем проекта ( cwd при запуске).
• ⚡ Оптимизированные и консолидированные инструменты: пакетные операции сокращают количество обращений ИИ-сервера, экономя токены и задержку. Надежные результаты для каждого элемента в пакете.
• 🚀 Простая интеграция: быстрая настройка через npx / bunx .
• 🐳 Контейнерный вариант: доступен в виде образа Docker.
• 🔧 Комплексная функциональность: охватывает широкий спектр задач файловой системы.
• ✅ Надежная проверка: использует схемы Zod для проверки аргументов.

Преимущества производительности

(Заполнитель: добавьте сюда результаты тестов и сравнений, демонстрирующие преимущества по сравнению с альтернативными методами, такими как отдельные команды оболочки.)

• Пакетные операции: значительно сокращают накладные расходы по сравнению с одиночными операциями.
• Прямое использование API: более эффективно, чем создание процессов оболочки для каждой команды.
• (Добавьте конкретные контрольные данные, если они доступны)

Функции

Этот сервер оснащает вашего ИИ-агента мощным и эффективным набором инструментов файловой системы:

• 📁 Исследование и проверка ( list_files , stat_items ): составление списка файлов/каталогов (рекурсивно, статистика), получение подробного статуса для нескольких элементов.
• 📄 Чтение и запись содержимого ( read_content , write_content ): чтение/запись/добавление нескольких файлов, создание родительских каталогов.
• ✏️ Точное редактирование и поиск ( edit_file , search_files , replace_content ): оперативное редактирование (вставка, замена, удаление) в нескольких файлах с сохранением отступов и выводом различий; поиск по регулярным выражениям с контекстом; поиск/замена в нескольких файлах.
• 🏗️ Управление каталогами ( create_directories ): создание нескольких каталогов, включая промежуточные родительские.
• 🗑️ Безопасное удаление ( delete_items ): рекурсивное удаление нескольких файлов/каталогов.
• ↔️ Перемещение и копирование ( move_items , copy_items ): перемещение/переименование/копирование нескольких файлов/каталогов.
• 🔒 Управление разрешениями ( chmod_items , chown_items ): изменение разрешений POSIX и владельца для нескольких элементов.

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

Философия дизайна

(Заполнитель: Объясните основные принципы дизайна.)

• Безопасность прежде всего: отдайте приоритет предотвращению доступа за пределами корневого каталога проекта.
• Эффективность: минимизация накладных расходов на связь и использование токенов для взаимодействия с ИИ.
• Надежность: предоставление подробных результатов и отчетов об ошибках для пакетных операций.
• Простота: предлагайте понятный и последовательный API через MCP.
• Соответствие стандартам: строго придерживайтесь протокола модельного контекста.

Сравнение с другими решениями

(Заполнитель: Объективно сравните с альтернативами.)

Планы на будущее

(Заполнитель: список предстоящих функций или улучшений.)

• Изучите возможности наблюдения за файлами.
• Изучите поддержку потоковой передачи очень больших файлов.
• Повышение производительности конкретных операций.
• Добавить более расширенные параметры фильтрации для list_files .

Документация

(Заполнитель: Добавьте ссылку на сайт с полной документацией, как только она станет доступна.)

Полная документация, включая подробные ссылки на API и примеры, будет доступна по адресу: [Ссылка на сайт документации]

Внося вклад

Вклады приветствуются! Пожалуйста, откройте issue или отправьте pull request в репозитории GitHub .

Лицензия

Этот проект выпущен под лицензией MIT .

Разработка

1. Клон: git clone https://github.com/sylphlab/filesystem-mcp.git
2. Установить: cd filesystem-mcp && pnpm install
3. Сборка: pnpm run build (компилирует TypeScript в dist/ )
4. Смотреть: pnpm run dev (необязательно, перекомпилирует при сохранении)

Публикация (через GitHub Actions)

Этот репозиторий использует GitHub Actions ( .github/workflows/publish.yml ) для автоматической публикации пакета в npm и сборки/отправки образа Docker в Docker Hub при отправке тегов версий ( v*.*.* ) в main ветку. Требуются секреты NPM_TOKEN , DOCKERHUB_USERNAME и DOCKERHUB_TOKEN , настроенные в настройках репозитория GitHub.