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

npm-версия Докер тянет

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

Установка

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

1. Рекомендуется:

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

Пример (

{ "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["@sylphlab/filesystem-mcp"], "name": "Filesystem (npx)" } } }

Пример (

{ "mcpServers": { "filesystem-mcp": { "command": "bunx", "args": ["@sylphlab/filesystem-mcp"], "name": "Filesystem (bunx)" } } }

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

2. Докер

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

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

{ "mcpServers": { "filesystem-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/path/to/your/project:/app", // Mount your project to /app "sylphlab/filesystem-mcp:latest" ], "name": "Filesystem (Docker)" } } }

Не забудьте заменить

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

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

Related MCP server: drupal-modules-mcp MCP Server

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

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

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

Agent: <use_mcp_tool> <server_name>filesystem-mcp</server_name> <tool_name>read_content</tool_name> <arguments>{"paths": ["src/index.ts"]}</arguments> </use_mcp_tool> Server Response: (Content of src/index.ts)

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

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

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

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

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

Функции

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

📁 Исследование и проверка ( составление списка файлов/каталогов (рекурсивно, статистика), получение подробного статуса для нескольких элементов.
📄 Чтение и запись содержимого ( чтение/запись/добавление нескольких файлов, создание родительских каталогов.
✏️ Точное редактирование и поиск ( оперативное редактирование (вставка, замена, удаление) в нескольких файлах с сохранением отступов и выводом различий; поиск по регулярным выражениям с контекстом; поиск/замена в нескольких файлах.
🏗️ Управление каталогами ( создание нескольких каталогов, включая промежуточные родительские.
🗑️ Безопасное удаление ( рекурсивное удаление нескольких файлов/каталогов.
↔️ Перемещение и копирование ( перемещение/переименование/копирование нескольких файлов/каталогов.
🔒 Управление разрешениями ( изменение разрешений POSIX и владельца для нескольких элементов.

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

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

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

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

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

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

Особенность/Аспект	Файловая система MCP-сервера	Отдельные команды оболочки (через агента)	Другие пользовательские скрипты
Безопасность	Высокий (ограничен корнем)	Низкий (Агенту необходим доступ к оболочке)	Переменная
Эффективность (токены)	Высокий (партионный)	Низкий (Одна команда на операцию)	Переменная
Задержка	Низкий (прямой API)	Высокий (раковины появляются над головой)	Переменная
Пакетные операции	Да (большинство инструментов)	Нет	Может быть
Сообщение об ошибках	Подробный (по каждому элементу)	Базовый (анализ stdout/stderr)	Переменная
Настраивать	Легко (npx/Docker)	Требуется настройка защищенной оболочки	Обычай

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

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

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

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

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

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

Внося вклад

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

Лицензия

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

Разработка

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

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

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

filesystem-mcp