Servidor MCP del sistema de archivos

Potencie a sus agentes de IA con capacidades de sistema de archivos robustas e independientes de la plataforma.

Este servidor de Protocolo de Contexto de Modelo (MCP) proporciona una interfaz segura y confiable para que los agentes de IA interactúen con el sistema de archivos local. Permite leer, escribir, actualizar y administrar archivos y directorios, con el respaldo de una base TypeScript lista para producción que incluye registro completo, gestión de errores y medidas de seguridad.

Tabla de contenido

• Descripción general

• Características

• Instalación

• Configuración

• Uso con clientes MCP

• Herramientas disponibles

• Estructura del proyecto

• Desarrollo

• Licencia

Descripción general

El Protocolo de Contexto de Modelo (MCP) es un marco estándar que permite a los modelos de IA interactuar de forma segura con herramientas externas y fuentes de datos (recursos). Este servidor implementa el estándar MCP para exponer las operaciones esenciales del sistema de archivos como herramientas, lo que permite a los agentes de IA:

• Leer y analizar el contenido de los archivos.

• Crear, modificar o sobrescribir archivos.

• Administrar directorios y rutas de archivos.

• Realizar actualizaciones específicas dentro de los archivos.

Creado con TypeScript, el servidor enfatiza la seguridad de tipos, la modularidad y el manejo robusto de errores, lo que lo hace adecuado para una integración confiable en flujos de trabajo de IA.

Arquitectura

El servidor emplea una arquitectura en capas para mayor claridad y facilidad de mantenimiento:

• Capa API : maneja la comunicación MCP, valida entradas usando Zod y desinfecta rutas.

• Servicios principales : administra la configuración, el registro, los informes de errores, el estado de la sesión (como el directorio de trabajo predeterminado) y la instancia principal del servidor MCP.

• Implementación de herramientas : contiene la lógica específica para cada herramienta del sistema de archivos, aprovechando utilidades compartidas.

Características

• Operaciones de archivos integrales : herramientas para leer, escribir, enumerar, eliminar, mover y copiar archivos y directorios.

• Actualizaciones específicas : la herramienta update_file permite operaciones precisas de búsqueda y reemplazo dentro de archivos, admitiendo texto simple y expresiones regulares.

• Gestión de rutas consciente de la sesión : la herramienta set_filesystem_default establece un directorio de trabajo predeterminado para resolver rutas relativas durante una sesión.

• Seguridad ante todo : La limpieza de rutas integrada previene ataques de cruce de directorios. La restricción opcional de directorios base mejora la seguridad.

• Base robusta : incluye utilidades de nivel de producción para:

  • Registro estructurado y consciente del contexto.

  • Manejo de errores estandarizado con códigos de error específicos.

  • Generación de ID único para seguimiento de solicitudes.

  • Sanitización de entrada.

  • Limitación de velocidad opcional (archivo de utilidad creado pero aún no integrado).

• Seguridad de tipos : totalmente implementado en TypeScript para mejorar la confiabilidad y la facilidad de mantenimiento.

Instalación

Pasos

1. Clonar el repositorio:

   git clone https://github.com/cyanheads/filesystem-mcp-server.git cd filesystem-mcp-server

2. Instalar dependencias:

   npm install

3. Construir el proyecto:

   npm run build

   Esto compila el código TypeScript a JavaScript en el directorio dist/ y convierte el script principal en ejecutable. El ejecutable se ubicará en dist/index.js .

Configuración

Configurar el servidor usando variables de entorno:

• FS_BASE_DIRECTORY (opcional, recomendado por seguridad ):

  • Si se establece como una ruta absoluta, todas las operaciones con archivos realizadas por el servidor se limitarán estrictamente a este directorio y sus subdirectorios. Esto impide que el agente de IA acceda a archivos fuera del alcance previsto.

  • Ejemplo: FS_BASE_DIRECTORY=/Users/casey/safe-agent-files

• LOG_LEVEL (opcional):

  • Controla el nivel de detalle de los registros. Opciones: error , warn , info , http , verbose , debug y silly .

  • El valor predeterminado es info .

• LOG_DIR (opcional):

  • Especifica el directorio donde se almacenarán los archivos de registro ( combined.log , error.log ).

  • El valor predeterminado es ./logs relativo al directorio de ejecución del servidor.

Uso con clientes MCP

Para permitir que un cliente MCP (como un asistente de IA) utilice este servidor:

1. Ejecutar el servidor: Inicie el servidor desde su terminal:

   node dist/index.js # Or if you are in the project root: # npm start

2. Configurar el cliente: Agregue el servidor a la configuración de su cliente MCP. El método exacto depende del cliente, pero normalmente implica especificar:

   • Comando: node

   • Argumentos: La ruta absoluta al ejecutable del servidor creado (por ejemplo, /path/to/filesystem-mcp-server/dist/index.js ).

   • Variables de entorno (opcional): configure FS_BASE_DIRECTORY , LOG_LEVEL o LOG_DIR según sea necesario.

   Ejemplo de configuración de MCP (conceptual):

   { "mcpServers": { "filesystem": { "command": "node", "args": ["/path/to/filesystem-mcp-server/dist/index.js"], "env": { "FS_BASE_DIRECTORY": "/path/to/base/directory", "LOG_LEVEL": "debug" }, "disabled": false, "autoApprove": [] } // ... other servers } }

Una vez configurado y en funcionamiento, el cliente detectará el servidor y sus herramientas disponibles.

Herramientas disponibles

El servidor expone las siguientes herramientas para la interacción del sistema de archivos:

Consulte los archivos de registro de herramientas (

Estructura del proyecto

El código base está organizado para mayor claridad y facilidad de mantenimiento:

Para obtener una vista detallada y en vivo de la estructura actual, ejecute: npm run tree

Nota para desarrolladores: Este repositorio incluye un archivo .clinerules . Esta hoja de referencia proporciona a tu asistente de programación LLM información esencial sobre patrones de código base, ubicaciones de archivos y ejemplos de uso. ¡Manténla actualizada a medida que el servidor evoluciona!

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0. Consulte el archivo de LICENCIA para más detalles.