Filesystem MCP Server for WSL

⚠️ ВАЖНАЯ ИНФОРМАЦИЯ:
Исходный сервер файловой системы MCP уже может получать доступ к файлам WSL, просто используя сетевой путь \\wsl.localhost\DistributionName в качестве параметра в конфигурации.
Пример:

{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "\\\\wsl.localhost\\Debian", "C:\\path\\to\\other\\allowed\\dir" ] } } }

Однако этот проект предлагает альтернативную реализацию, специально оптимизированную для дистрибутивов WSL Linux .

В то время как официальный сервер работает путем рекурсивного обхода каталогов с использованием модуля fs Node.js, эта реализация использует собственные команды Linux внутри WSL (такие как find , grep и т. д.), что значительно ускоряет операции по листингу файлов и поиску контента .

Это может быть особенно полезно при работе с большими деревьями каталогов или когда производительность поиска имеет решающее значение.

Таким образом, хотя собственный сетевой путь может быть проще для многих случаев использования, этот проект остается ценным решением для пользователей WSL, которым нужна более высокая производительность или более индивидуальный контроль над логикой индексации и поиска.

Файловая система MCP-сервер для WSL

Сервер Node.js, реализующий протокол контекста модели (MCP), специально разработанный для операций файловой системы в подсистеме Windows для Linux (WSL).
Этот проект является ответвлением оригинального сервера Filesystem MCP , но полностью переработанным для сред WSL.
В отличие от оригинального проекта, который обрабатывает общие файловые операции, эта версия фокусируется исключительно на бесперебойном взаимодействии между дистрибутивами Windows и Linux под управлением WSL.
Оба проекта совместимы и могут работать параллельно в одной системе.

Функции

• Доступ к любому дистрибутиву WSL из Windows
• Чтение/запись файлов в WSL с хоста Windows
• Создание/перечисление/удаление каталогов в WSL
• Перемещение файлов/каталогов по файловой системе WSL
• Поиск файлов в WSL
• Получить метаданные файла из файловой системы WSL
• Поддержка нескольких дистрибутивов WSL

Примечание : сервер допускает операции только в пределах каталогов, указанных с помощью args .

API

Ресурсы

• wsl -d <distrib> : Команда для операций с дистрибутивами WSL

Инструменты

• прочитанный_файл
  • Прочитать полное содержимое файла из WSL
  • Ввод: path (строка)
  • Читает содержимое как текст UTF-8
• чтение_нескольких_файлов
  • Чтение нескольких файлов одновременно из WSL
  • Ввод: paths (string[])
  • Неудачные чтения не остановят всю операцию.
• запись_файла
  • Создать или перезаписать файл в WSL (использовать с осторожностью)
  • Входные данные:
    • path (строка)
    • content (строка)
• редактировать_файл
  • Выборочное редактирование с расширенным сопоставлением шаблонов и форматированием
  • Входные данные:
    • path (строка)
    • edits (массив { oldText, newText } )
    • dryRun (логическое значение, необязательно)
  • Функции:
    • Многострочное сопоставление
    • Сохранение отступов
    • Предварительный просмотр изменений в стиле Git
    • Неразрушающий режим холостого хода
• создать_каталог
  • Создать или обеспечить существование каталога в WSL
  • Ввод: path (строка)
• список_каталогов
  • Список содержимого каталога с префиксами [FILE] или [DIR]
  • Ввод: path (строка)
• дерево_каталогов
  • Рекурсивное представление содержимого в виде дерева JSON
  • Ввод: path (строка)
• переместить_файл
  • Переместить или переименовать файлы/каталоги
  • Входные данные:
    • source (строка)
    • destination (строка)
• поиск_файлов
  • Рекурсивный поиск по имени
  • Входные данные:
    • path (строка)
    • pattern (строка)
    • excludePatterns (строка[], необязательно)
• получить_информацию_о_файле
  • Подробные метаданные
  • Ввод: path (строка)
  • Возвращает: размер, временные метки, тип, разрешения.
• список_разрешенных_каталогов
  • Перечисляет все каталоги, доступные серверу
• список_wsl_distributions
  • Перечисляет доступные дистрибутивы и показывает активный

Требования

• Подсистема Windows для Linux (WSL) настроена правильно
• В WSL установлен как минимум один дистрибутив Linux

Для пользователей Claude Desktop:
Никакой дополнительной установки не требуется — просто настройте claude_desktop_config.json .

Для разработки:

• Node.js (v14.0.0 или выше)
• TypeScript (включен как зависимость разработки)

Установка Node.js на Windows

1. Загрузите установщик с nodejs.org
2. Запустите его и следуйте инструкциям.
3. Проверить версии:

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

Перед запуском сервера необходимо собрать проект TypeScript:

Запустите сервер, указав, какой дистрибутив WSL использовать (необязательно) и какие каталоги предоставлять:

Если дистрибутив не указан, будет использоваться дистрибутив WSL по умолчанию.

Примеры

Доступ к дистрибутиву Ubuntu-20.04:

Использовать дистрибутив по умолчанию:

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

Добавьте это в ваш claude_desktop_config.json :

Вариант 1: Использование определенного дистрибутива WSL

Вариант 2: использование дистрибутива WSL по умолчанию

Во втором примере система будет использовать ваш дистрибутив WSL по умолчанию без необходимости его указания.

Отличия от оригинального проекта

Этот форк адаптирует исходный сервер файловой системы MCP для работы с WSL следующим образом:

1. Замена прямых вызовов файловой системы Node.js на выполнение команд WSL
2. Добавление поддержки выбора определенных дистрибутивов WSL
3. Реализация трансляции путей между форматами Windows и Linux
4. Улучшение обработки содержимого файлов для кроссплатформенной совместимости
5. Добавление специализированных инструментов для управления WSL

Лицензия

Этот проект является ответвлением оригинального сервера Filesystem MCP, созданного командой Model Context Protocol.

Этот сервер MCP для WSL лицензирован по лицензии MIT, следуя лицензии исходного проекта. Это означает, что вы можете свободно использовать, изменять и распространять программное обеспечение в соответствии с условиями и положениями лицензии MIT. Для получения более подробной информации см. файл LICENSE в исходном репозитории проекта.