LanternFS - MCP de sistema de archivos seguro

LanternFS es un servidor MCP de sistema de archivos remoto que permite a clientes MCP como ChatGPT acceder a un directorio local controlado.

Protege el endpoint MCP remoto con OAuth, de modo que exponer el servidor a través de ngrok no significa que cualquiera que descubra la URL pública pueda acceder al sistema de archivos.

Modelo de seguridad

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

La contraseña se utiliza únicamente durante el paso de autorización OAuth. No se utiliza como token de acceso MCP y nunca se envía a las herramientas MCP.

Características

• Autorización OAuth para clientes MCP remotos.

• Diseñado para conexiones MCP OAuth de ChatGPT.

• Autenticación solo con contraseña o con usuario y contraseña opcionales.

• Flujo de código de autorización con PKCE S256.

• Tokens de acceso de corta duración.

• Tokens de actualización rotatorios de larga duración.

• Descubrimiento y metadatos OAuth a través del SDK de TypeScript de MCP.

• Endpoint MCP HTTP transmitible protegido.

• Raíces del sistema de archivos configurables.

• Soporte de túnel HTTPS de ngrok.

• Secretos excluidos de Git.

Configuración

1. Instalar Node.js

Usa una versión actual y compatible de Node.js.

node --version
npm --version

2. Clonar el repositorio

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

3. Crear el archivo de entorno

Copia el archivo de ejemplo:

Copy-Item .env.example .env

Ábrelo:

notepad .env

4. Configurar la raíz del sistema de archivos

La configuración ALLOW_ROOTS controla qué directorios puede acceder LanternFS.

Para una configuración segura, crea un espacio de trabajo dedicado:

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

Luego usa:

ALLOW_ROOTS=D:\mcp-workspace

Evita exponer una unidad completa a menos que la necesites intencionadamente:

ALLOW_ROOTS=D:\

OAuth controla quién puede conectarse, mientras que ALLOW_ROOTS controla a qué puede acceder un cliente autorizado. Debes usar ambos.

5. Configurar la contraseña OAuth

Establece una contraseña segura en .env:

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

La contraseña debe tener al menos 16 caracteres.

Opcionalmente, puedes configurar un usuario:

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

Si MCP_AUTH_USERNAME está vacío, LanternFS usa una página de inicio de sesión solo con contraseña.

Si se configura un usuario, tanto el usuario como la contraseña deben coincidir.

Cómo se utiliza la contraseña

No introduces esta contraseña en la configuración MCP de ChatGPT.

Cuando ChatGPT se conecta por primera vez, inicia el flujo de autorización OAuth y abre la página de inicio de sesión de LanternFS.

Introduce las mismas credenciales que configuraste en .env:

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

[ Authorize ]

Tras una autorización exitosa, ChatGPT recibe un código de autorización OAuth y lo canjea por un token de acceso y un token de actualización.

La contraseña no se envía a /mcp.

6. Configurar ngrok

LanternFS necesita una URL pública HTTPS para que ChatGPT pueda alcanzar el servidor MCP.

El proyecto puede usar un authtoken de ngrok desde cualquiera de estas ubicaciones:

Recomendado: configuración local de ngrok

Autentica ngrok normalmente en tu máquina usando la CLI de ngrok y mantén el token en la propia configuración de ngrok.

Por ejemplo:

ngrok config add-authtoken YOUR_NGROK_TOKEN

No necesitas poner el token de ngrok en .env si ya está configurado localmente.

Alternativa: archivo .token

LanternFS también admite un archivo local .token que contiene solo el authtoken de ngrok:

YOUR_NGROK_TOKEN

El archivo .token está ignorado por Git.

Alternativa: variable de entorno

También puedes proporcionar:

NGROK_AUTHTOKEN=YOUR_NGROK_TOKEN

Esto es opcional. No lo añadas a .env a menos que quieras específicamente que LanternFS reciba el token a través del entorno.

Configurar el dominio de ngrok

Para una URL estable, configura tu dominio de ngrok:

NGROK_DOMAIN=your-domain.ngrok-free.app

Si NGROK_DOMAIN está vacío, ngrok puede usar una URL efímera cuando tu cuenta/configuración lo admita. Se recomienda un dominio estable para una conexión MCP persistente con ChatGPT.

7. Ejemplo de .env

Una configuración recomendada tiene este aspecto:

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

Observa que NGROK_AUTHTOKEN no es necesario aquí cuando ngrok ya está autenticado localmente.

Nunca hagas commit de .env o .token.

Ejecutar LanternFS

Revisa el proyecto primero:

npm run build
npm test

Después inicia el servidor:

npm start

El servidor inicia el servicio HTTP MCP local y crea el túnel HTTPS de ngrok.

La consola imprime la URL pública.

Mantén el proceso en ejecución mientras ChatGPT necesite la conexión MCP.

Descripción recomendada para el cliente MCP

Al añadir LanternFS a un cliente MCP, usa la siguiente descripción para que el cliente sepa cuándo debe usar este servidor:

LanternFS proporciona acceso a mi sistema de archivos local y archivos de proyecto. Usa este MCP siempre que una tarea implique archivos, carpetas, código fuente, repositorios, documentos u otros datos que puedan existir en mi ordenador local. Prefiere LanternFS antes que adivinar o pedirme que pegue el contenido de los archivos cuando los archivos necesarios estén disponibles localmente. No lo uses para información que no requiera acceso a mi sistema de archivos local.

Esta descripción está pensada para la descripción del servidor del cliente MCP o para la guía de uso de las herramientas. Le indica al cliente que prefiera LanternFS para tareas con archivos locales, evitando a la vez. Uso innecesario para conocimiento general o tareas basadas en la web.

Conectar a ChatGPT

1. Inicia LanternFS con npm start.

2. Copia la URL MCP pública HTTPS que se imprime en la consola.

3. Añade un conector MCP remoto en ChatGPT.

4. Selecciona OAuth como método de autenticación.

5. Introduce la URL MCP de LanternFS.

6. ChatGPT realiza el descubrimiento OAuth.

7. Tu navegador abre la página de autorización de LanternFS.

8. Introduce el usuario y la contraseña de .env.

9. Haz clic en Authorize.

10. ChatGPT completa el flujo OAuth y se conecta a /mcp.

Solo necesitarás introducir la contraseña cuando se requiera una nueva autorización.

Conexión persistente

LanternFS no usa un token de acceso permanente.

La implementación actual utiliza:

• Tokens de acceso que caducan después de un corto período de tiempo.

• Tokens de actualización de larga duración que permiten al cliente obtener nuevos tokens de acceso.

• Rotación del token de actualización (refresco) cuando se usa uno.

• La contraseña configurada solo para la autorización inicial.

Esto permite que ChatGPT siga autorizado sin pedir la contraseña cada vez, a la vez que evita un token de acceso permanente al sistema de archivos.

Eliminar .oauth-state.json elimina el estado OAuth almacenado localmente y requiere que los clientes se autor.end de nuevo.

Endpoints OAuth

LanternFS usa las interfaces de autorización proporcionadas por el SDK de TypeScript de MCP instalado.

Recomendaciones de seguridad

Usar una contraseña segura

Usa una contraseña única y aleatoria y al menos 16 caracteres.

Por ejemplo, PowerShell puede generar bytes aleatorios:

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

No copies una contraseña de ejemplo para producción.

Restringir el sistema de archivos

Prefiere:

ALLOW_ROOTS=D:\mcp-workspace

sobre:

ALLOW_ROOTS=D:\

Proteger los secretos

Nunca hagas commit de:

.env
.token
.oauth-state.json

Antes de hacer push de los cambios:

git status
git diff --cached

Nunca fuerces la adición de estos archivos.

Proteger tu cuenta de ngrok

Si se expone un authtoken de, debes rotarlo a través de tu cuenta de ngrok.

Detén el acceso remoto cuando no sea necesario

Detener LanternFS detiene el endpoint HTTP MCP y el túnel de ngrok.

Solución de problemas

ChatGPT no puede completar el descubrimiento OAuth

Comprueba que:

• Está ejecutando LanternFS.

• ngrok está autenticado.

• El túnel ngrok esté activo.

• La URL pública use HTTPS.

• NGROK_DOMAIN es correcto si configuraste uno.

Se rechaza la contraseña

Revisa .env y reinicia LanternFS después de cambiarla.

Si hay un valor de MCP_AUTH_USERNAME, ambos usuario y contraseña deben coincidir.

ChatGPT pide autorización de nuevo

Verifica que .oauth-state.json exista y no haya sido eliminado o reemplazado.

Un restablecimiento del estado OAuth deliberadamente solicita autor otra vez.

No está disponible una ruta del sistema de archivos

Revisa ALLOW_ROOTS y asegúrate de que la ruta solicitada esté dentro de una de las raíces configuradas.

Desarrollo

npm install
npm run build
npm test
npm start

npm run build realiza una comprobación de tipos de TypeScript.

npm test ejecuta un autoimpr en el sistema de archivos.

Referencias

LanternFS se basa en la arquitectura de autorización proporcionada por el SDK de TypeScript del Protocolo Contexto de Modelo y en los estándares de OAuth relevantes.

• Especificación de autorización de MCP: https://modelcontextprotocol.io/specification/draft/basic/authorization

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

• Guía para el registro de clientes de MCP: https://blog.modelcontextprotocol.io/posts/client_registration/

• RFC 8414 - Metadatos del servidor (Authorization) de OAuth 2.0: https://www.rfc-editor.org/rfc/rfc8414

• RFC 9728 - Metadatos del recurso class protegido de OAuth 2.0: https://www.rfc-editor.org/rfc/rfc9728

• RFC 7636 - Clave de prueba para intercambio de código (PKCE): https://www.rfc-editor.org/rfc/rfc7636

• RFC 7009 - Revocación de tokens OAuth 2.0: <https://www.rfc-editor.org/rfc/}

Es importante mantenerse actualizado: el comportamiento de autorización de MCP puede cambiard the specification evolves.

Licencia

Añade un licencia antes de publicar LanternFS para su reutilización generalizada.