LanternFS — защищённый файловый MCP-сервер

LanternFS — это удалённый файловый MCP-сервер, который позволяет MCP-клиентам, таким как ChatGPT, получать доступ к контролируемой локальной папке.

Он защищает удалённую конечную точку MCP с помощью OAuth, поэтому публикация сервера через ngrok не означает, что любой, кто обнаружит публичный URL, сможет получить доступ к файловой системе.

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

ChatGPT
   |
   | OAuth
   v
LanternFS
   |
   | Valid access token
   v
MCP endpoint
   |
   v
Filesystem tools
   |
   v
ALLOW_ROOTS

Пароль используется только на этапе авторизации OAuth. Он не используется в качестве токена доступа MCP и никогда не отправляется в инструменты MCP.

Возможности

• Авторизация OAuth для удалённых MCP-клиентов.

• Рассчитан на OAuth-подключения MCP из ChatGPT.

• Аутентификация только по паролю или опционально с именем пользователя и паролем.

• Поток Authorization Code с PKCE S256.

• Недолговечные токены доступа.

• Долгоживущие обновляемые refresh-токены.

• OAuth discovery и метаданные через MCP TypeScript SDK.

• Защищённая конечная точка MCP Streamable HTTP.

• Настраиваемые корневые каталоги файловой системы.

• Поддержка HTTPS-туннеля ngrok.

• Секреты исключены из Git.

Настройка

1. Установите Node.js

Используйте актуальную поддерживаемую версию Node.js.

node --version
npm --version

2. Клонируйте репозиторий

git clone https://github.com/deviprasadshetty-dev/filesystem-mcp.git
cd filesystem-mcp
npm install

3. Создайте файл окружения

Скопируйте пример файла:

Copy-Item .env.example .env

Откройте его:

notepad .env

4. Настройте корневой каталог файловой системы

Параметр ALLOW_ROOTS определяет, к каким каталогам LanternFS может получить доступ.

Для безопасной настройки создайте отдельное рабочее пространство:

New-Item -ItemType Directory -Force D:\mcp-workspace

Затем укажите:

ALLOW_ROOTS=D:\mcp-workspace

Не открывайте доступ ко всему диску, если вам это не нужно намеренно:

ALLOW_ROOTS=D:\

OAuth управляет тем, кто может подключаться, а ALLOW_ROOTS — тем, к чему может обращаться авторизованный клиент. Используйте оба механизма.

5. Настройте пароль OAuth

Задайте надёжный пароль в файле .env:

MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

Пароль должен содержать не менее 16 символов.

При желании вы можете настроить имя пользователя:

MCP_AUTH_USERNAME=deviprasad
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

Если MCP_AUTH_USERNAME пуст, LanternFS использует страницу входа только с паролем.

Если имя пользователя настроено, должны совпадать и имя пользователя, и пароль.

Как используется пароль

Вы не вводите этот пароль в настройках MCP в ChatGPT.

При первом подключении ChatGPT запускает поток авторизации OAuth и открывает страницу входа LanternFS.

Введите те же учётные данные, которые вы указали в .env:

Username: deviprasad
Password: ********

[ Authorize ]

После успешной авторизации ChatGPT получает код авторизации OAuth и обменивает его на токен доступа и refresh-токен.

Пароль не отправляется в /mcp.

6. Настройте ngrok

Для доступа ChatGPT к MCP-серверу LanternFS необходим публичный HTTPS-URL.

Проект может использовать ngrok authtoken из любого из этих источников:

Рекомендуемый способ: локальная конфигурация ngrok

Выполните обычную аутентификацию ngrok на вашей машине с помощью CLI ngrok и храните токен в собственной конфигурации ngrok.

Например:

ngrok config add-authtoken YOUR_NGROK_TOKEN

Если ngrok уже настроен локально, добавлять токен в .env не нужно.

Альтернатива: файл .token

LanternFS также поддерживает локальный файл .token, содержащий только ngrok authtoken:

YOUR_NGROK_TOKEN

Файл .token игнорируется Git.

Альтернатива: переменная окружения

Вы также можете указать:

NGROK_AUTHTOKEN=YOUR_NGROK_TOKEN

Это необязательно. Не добавляйте её в .env, если вы специально не хотите, чтобы LanternFS получал токен из переменной окружения.

Настройка домена ngrok

Для стабильного URL задайте свой домен ngrok:

NGROK_DOMAIN=your-domain.ngrok-free.app

Если NGROK_DOMAIN пуст, ngrok может использовать временный URL, если это поддерживается вашей учётной записью и конфигурацией. Стабильный домен рекомендуется для постоянного MCP-подключения ChatGPT.

7. Пример .env

Рекомендуемая конфигурация выглядит так:

PORT=3000
ALLOW_ROOTS=D:\mcp-workspace
NGROK_DOMAIN=your-domain.ngrok-free.app

MCP_AUTH_USERNAME=deviprasad
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

Обратите внимание, что NGROK_AUTHTOKEN здесь не требуется, если ngrok уже аутентифицирован локально.

Никогда не коммитьте .env и .token.

Запуск LanternFS

Сначала проверьте проект:

npm run build
npm test

Затем запустите сервер:

npm start

Сервер запускает локальный HTTP-сервис MCP и создаёт HTTPS-туннель ngrok.

В консоль выводится публичный URL.

Держите процесс запущенным, пока ChatGPT требуется MCP-подключение.

Рекомендуемое описание сервера для MCP-клиента

При добавлении LanternFS в MCP-клиент используйте следующее описание, чтобы клиент знал, когда использовать этот сервер:

LanternFS предоставляет доступ к моей локальной файловой системе и файлам проекта. Используйте этот MCP всякий раз, когда задача связана с файлами, папками, исходным кодом, репозиториями, документами или другими данными, которые могут находиться на моём локальном компьютере. Если нужны файлы доступны локально, предпочитайте LanternFS, а не догадки или попытки попросить вставить содержимое файлов. Не используйте его для информации, для которой не требуется доступ к моей локальной файловой системе.

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

Подключение к ChatGPT

1. Запустите LanternFS с помощью npm start.

2. Скопируйте публичный HTTPS MCP-URL, выведенный в консоль.

3. Добавьте удалённый MCP-компенсатор в ChatGPT.

4. Выберите OAuth в качестве метода аутентификации.

5. Введите URL MCP LanternFS.

6. ChatGPT выполнит OAuth discovery.

7. В вашем браузере откроется страница авторизации LanernFS.

8. Введите имя пользователя и пароль из .env.

9. Нажмите Authorize.

10. ChatGPT завершенит поток OAuth и подключается к конечной точке MCP.

Пароль потребуется только тогда, когда потребуется новая авторизация.

Постоянное подключение

LanternFS не использует постоянный токен доступа.

Текущая реализация использует:

• Токены доступа, истекающие через короткое время.

• Долгоживущие refresh-токены, которые позволяют клиенту получать новые токены доступа.

• Ротацию refresh-токенов при использовании refresh-токена.

• Настроенный пароль, только для первичной авторизации.

Это позволяет ChatGPT оставаться авторизованным без ввода пароля каждый раз и при этом избегать постоянного токена доступа к файловой системе.

Удаление .oauth-state.json сбрасывает локально сохранённое состояние OAuth и требует от клиента повторной авторизации.

Конечные точки OAuth

Беспеки LanternFS реализует интерфейсы авторизации, предоставляемые установленным MCP TypeScript SDK.

Рекомендации по безопасности

Используйте надёжный пароль

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

Например, PowerShell может сгенерировать случайные байты:

[Convert]::ToBase64String((1..48 | ForEach-Object { Get-Random -Maximum 256 }))

Не копируйте пример пароля в рабочую среду.

Ограничьте доступ к файловой системе

Используйте:

ALLOW_ROOTS=D:\mcp-workspace

вместо:

ALLOW_ROOTS=D:\

Защищайте секреты

Никогда не коммитьте:

.env
.token
.oauth-state.json

Перед отправкой изменений:

git status
git diff --cached

Никогда не принуддительно добавляйте эти файлы (git add -f).

Защищайте учётную запись ngrok

Если ngrok authtoken стал известен, измените его через свою учётную запись ngrok.

Отключайте удалённый доступ, когда он не нужен

Остановка LanternFS останавливает его HTTP MCP-конечную точку и туннель ngrok.

Устранение неполадок

ChatGPT не может выполнить OAuth discovery

Проверьте, что:

• LanternFS запущен.

• ngrok аутентифицирован.

• туннель ngrok активен.

• публичный URL использует HTTPS.

• NGROK_DOMAIN корректный, если вы его задали.

Пароль отвергается

Проверьте .env и перезапустите LanternFS после изменения.

Если задан MCP_AUTH_USERNAME, и имя пользователя, и пароль должны совпадать.

ChatGPT снова запрашивает авторизацию

Проверьте, что .oauth-state.json по-прежнему существует и не был удалён или заменён.

Сброс состояния OAuth намеренно требует повторной авторизации.

Путь в файловой системе недоступен

Проверьте ALLOW_ROOTS и убедитесь, что запрошенный путь находится в одном из настроенных корневых каталогов.

Разработка

npm install
npm run build
npm test
npm start

npm run build выполняет проверку типов TypeScript.

npm test запускает самопроверку файловой системы.

Ссылки

LanternFS построен на архитектуре авторизации, предоставленной MCP TypeScript SDK, и соответствующих стандартах OAuth.

• Рекомендации авторизации MCP: https://modelcontextprotocol.io/specification/draft/basic/authorization

• MCP TypeScript SDK: https://ts.sdk.modelcontextprotocol.io/

• MCP client registration guidance: https://blog.modelcontextprotocol.io/posts/client_registration/

• RFC 8414 - OAuth 2.0 Authorization Server Metadata: https://www.rfc-editor.org/rfc/rfc8414

• RFC 9728 - OAuth 2.0 Protected Resource Metadata: https://www.rfc-editor.org/rfc/rfc9728

• RFC 7636 - Proof Key for Code Exchange (PKCE): https://www.rfc-editor.org/rfc/rfc7636

• RFC 7009 - OAuth 2.0 Token Revocation: https://www.rfc-editor.org/rfc/rfc7009

Поведение авторизации MCP может меняться по мере развития спецификации. Обновляйте MCP TypeScript SDK и при переходе на новую версию проекта проверяйте документацию по авторизации.

Лицензия

Перед публикацией LanternFS для широкого использования добавьте лицензию.