FileManager MCP Server

MCP-сервер (Streamable HTTP) для read-only доступа ИИ-клиентов к файлам проектов. Проекты, разрешённые каталоги, расширения файлов и ключи доступа описываются в YAML-конфиге — всё, что не указано в конфиге явно, сервер прочитать не может.

Инструменты

Инструмент	Описание
list_projects	Проекты, доступные предъявленному API-ключу: id, название, описание, корневые папки, читаемые расширения, лимиты
list_files	Содержимое папки проекта; без path — список корней, с recursive: true — рекурсивный обход (только файлы)
read_file	Чтение текстового файла в UTF-8, с постраничной выдачей по строкам (offset / limit)
find_files	Поиск файлов по имени: glob (*, ?, **) или подстрока
search_content	Поиск по содержимому файлов (grep) с номерами строк и опциональным контекстом
file_info	Метаданные файла/папки: тип, размер, даты, расширение, доступность для чтения, число строк

Инструментов записи нет — сервер физически не умеет изменять файлы.

Требования

• Node.js 18+
• Доступ на чтение к каталогам, указанным в конфиге

Установка

npm install
cp .env.example .env                       # порт, лимиты, значения ключей
cp projects.example.yaml projects.yaml     # описание проектов
# отредактировать оба файла

Конфигурация проектов (projects.yaml)

Путь к файлу задаётся переменной PROJECTS_CONFIG (по умолчанию ./projects.yaml).

defaults:                        # необязательно, лимиты по умолчанию для всех проектов
  max_file_size: 1048576
  max_entries: 1000
  max_depth: 5

projects:
  - id: gve-server-data                     # ^[a-z0-9][a-z0-9_-]*$, уникален
    name: Данные игрового сервера
    description: |
      Конфиги, html-диалоги NPC и csv/yaml-таблицы игрового сервера GVE.
    paths:                                  # абсолютные пути, подпапки доступны автоматически
      - /root/Gve-Server-Data/data
    extensions: [.yaml, .yml, .xml, .html, .htm, .md, .json, .txt]
    exclude:                                # необязательно, glob по виртуальному пути
      - "**/secrets/**"
    list_unreadable: false                  # показывать ли файлы с чужими расширениями
    max_file_size: 2097152                  # необязательный override
    api_keys:
      - "${FM_KEY_GVE_DATA}"                # подстановка из окружения (рекомендуется)

Поле	Обязательное	Назначение
id	да	Идентификатор проекта, передаётся в аргументе project
name	нет	Человекочитаемое название (по умолчанию id)
description	нет	Описание для ИИ: что за данные и зачем они нужны
paths	да	Абсолютные пути к разрешённым корням; должны существовать и не быть вложены друг в друга
extensions	да	Расширения, доступные для чтения и поиска (yml нормализуется в .yml)
exclude	нет	Дополнительные исключения (glob по виртуальному пути)
list_unreadable	нет	Показывать в листингах файлы с неразрешёнными расширениями (readable: false)
max_file_size / max_entries / max_depth	нет	Переопределение лимитов проекта
api_keys	да	Ключи доступа к этому проекту, минимум 24 символа; ${VAR} берётся из окружения

Конфиг читается один раз при старте. Любая ошибка валидации (несуществующий путь, короткий ключ, дублирующийся id, вложенные корни) останавливает запуск — сервер никогда не поднимается с частично корректным списком разрешений. После изменения YAML нужен рестарт.

Переменные окружения (.env)

Переменная	По умолчанию	Назначение
PORT	3200	Порт MCP-сервера
PROJECTS_CONFIG	./projects.yaml	Путь к конфигу проектов
MAX_FILE_SIZE	1048576	Максимальный размер читаемого файла, байт
MAX_ENTRIES	1000	Максимум записей в одном листинге
MAX_DEPTH	5	Максимальная глубина рекурсивного обхода
MAX_LINE_LENGTH	2000	Длинные строки обрезаются до этой длины
SEARCH_MAX_FILES	2000	Максимум файлов, просматриваемых в search_content
SEARCH_MAX_MATCHES	200	Максимум совпадений в ответе search_content
SEARCH_TIMEOUT_MS	5000	Бюджет времени на один поиск
SEARCH_ALLOW_REGEX	true	Разрешать ли режим regex: true в search_content

Запуск

npm start        # прод
npm run dev      # с автоперезапуском (--watch)
npm test         # тесты модели безопасности (node --test)

• MCP endpoint: POST http://<host>:<PORT>/mcp (требует API-ключ)
• Health check: GET http://<host>:<PORT>/health — статус и доступность всех корней

Подключение MCP-клиента

{
  "mcpServers": {
    "filemanager": {
      "url": "http://<host>:<PORT>/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

Ключ можно передавать и в заголовке X-API-Key.

Модель безопасности

Клиент никогда не видит и не передаёт реальные пути файловой системы. Файлы адресуются виртуальным путём <корень>/<подпапка>/<файл>, где <корень> — имя (basename) одного из каталогов в paths.

1. Валидация ввода. Отклоняются пути с \0, обратным слэшем, двоеточием, сегментами ./.., длиной больше 1024 символов.
2. Канонизация и проверка вложенности. Путь разрешается через fs.realpath, и результат обязан находиться внутри канонизированного корня. Это закрывает и ../-обход, и побег по симлинку/junction — в том числе созданному уже после старта сервера. Каждая запись каталога при обходе тоже проходит realpath; всё, что указывает наружу, молча скрывается.
3. Allowlist расширений. Читать и искать можно только в файлах с расширениями из extensions.
4. Неотключаемый deny-list поверх allowlist: любые файлы и папки, начинающиеся с точки (.env, .git, .ssh), node_modules, ключевой материал (*.pem, *.key, id_rsa*, *.jks, …), shadow/passwd/authorized_keys, а также имена с credentials, api_key, private_key, access_token. Плюс пользовательские exclude-глобы.
5. Никаких exec/spawn. Поиск реализован на Node fs API, а не через grep/rg, поэтому командной инъекции нет в принципе.
6. Лимиты на размер файла, число записей, глубину обхода, число просматриваемых файлов, количество совпадений, время поиска, длину строки и размер тела HTTP-запроса (256 КБ). Бинарные файлы (NUL в первых 8 КБ) не отдаются.
7. Изоляция ключей. Ключ привязан к проектам; чужой проект не виден в list_projects и сообщает Unknown project во всех остальных инструментах. Сравнение ключей — timingSafeEqual по sha256, с полным проходом по индексу (без утечки по времени).
8. Без утечки путей. В ответах и ошибках фигурируют только виртуальные пути. «Вне корня», «запрещено» и «не существует» дают одинаковое сообщение Path not found, поэтому API нельзя использовать как оракул для разведки файловой системы. Неожиданные ошибки ФС логируются на сервере, а клиенту отдаётся обобщённое сообщение.
9. Аудит-лог в stdout: ключ (первые 6 символов хеша), инструмент, проект, виртуальный путь, статус, время. Содержимое файлов не логируется.

Рекомендации по эксплуатации: запускать под отдельным пользователем с правами только на чтение нужных каталогов, в Docker монтировать данные как :ro, ключи хранить в .env (в YAML — только ${VAR}).

Тесты

npm test (node --test) поднимает временное дерево-песочницу и проверяет модель безопасности: обход каталогов, абсолютные пути, симлинк наружу, dotfile/ключевой материал, неразрешённое расширение, превышение размера, бинарный файл, глубину обхода, изоляцию ключей и трансляцию glob.