Servidor MCP del sistema de archivos (@sylphlab/filesystem-mcp)

Ofrezca a sus agentes de IA (como Cline/Claude) un acceso seguro, eficiente y con ahorro de tokens a los archivos de su proyecto. Este servidor Node.js implementa el Protocolo de Contexto de Modelo (MCP) para proporcionar un conjunto robusto de herramientas de sistema de archivos, que operan de forma segura dentro de un directorio raíz de proyecto definido.

Instalación

Hay varias formas de utilizar el servidor MCP del sistema de archivos:

1. Recomendado: npx (o bunx ) a través de la configuración del host MCP

La forma más sencilla es mediante npx o bunx , configurados directamente en el entorno de host de MCP (p. ej., mcp_settings.json de Roo/Cline). Esto garantiza que siempre uses la última versión de npm sin necesidad de instalación local ni Docker.

Ejemplo ( npx ):

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (npx)"
    }
  }
}

Ejemplo ( bunx ):

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "bunx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (bunx)"
    }
  }
}

Importante: El servidor utiliza su propio Directorio de Trabajo Actual ( cwd ) como raíz del proyecto. Asegúrese de que su host MCP (p. ej., Cline/VSCode) esté configurado para ejecutar el comando con el cwd configurado en el directorio raíz de su proyecto activo.

2. Docker

Utilice la imagen oficial de Docker para entornos en contenedores.

Ejemplo de configuración de host MCP:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app", // Mount your project to /app
        "sylphlab/filesystem-mcp:latest"
      ],
      "name": "Filesystem (Docker)"
    }
  }
}

Recuerde reemplazar /path/to/your/project con la ruta absoluta correcta.

3. Construcción local (para desarrollo)

Clonar: git clone https://github.com/sylphlab/filesystem-mcp.git
Instalar: cd filesystem-mcp && pnpm install (usando pnpm ahora)
Construir: pnpm run build
Configurar el host MCP:
{ "mcpServers": { "filesystem-mcp": { "command": "node", "args": ["/path/to/cloned/repo/filesystem-mcp/dist/index.js"], // Updated build dir "name": "Filesystem (Local Build)" } } }
Nota: Ejecute el comando node desde el directorio que desea utilizar como raíz del proyecto.

Inicio rápido

Una vez que el servidor esté configurado en su host MCP (ver Instalación), su agente AI puede comenzar a utilizar inmediatamente las herramientas del sistema de archivos.

Ejemplo de interacción del agente (conceptual):

Agent: <use_mcp_tool>
         <server_name>filesystem-mcp</server_name>
         <tool_name>read_content</tool_name>
         <arguments>{"paths": ["src/index.ts"]}</arguments>
       </use_mcp_tool>

Server Response: (Content of src/index.ts)

¿Por qué elegir este proyecto?

🛡️ Enfoque en la raíz del proyecto seguro y conveniente: Operaciones confinadas a la raíz del proyecto ( cwd en el lanzamiento).
⚡ Herramientas optimizadas y consolidadas: Las operaciones por lotes reducen los viajes de ida y vuelta del servidor de IA, lo que ahorra tokens y latencia. Resultados fiables para cada elemento de un lote.
🚀 Fácil integración: configuración rápida a través de npx / bunx .
🐳 Opción en contenedor: Disponible como una imagen de Docker.
🔧 Funcionalidad integral: cubre una amplia gama de tareas del sistema de archivos.
✅ Validación robusta: utiliza esquemas Zod para la validación de argumentos.

Ventajas de rendimiento

(Marcador de posición: agregue aquí resultados de referencia y comparaciones, demostrando ventajas sobre métodos alternativos como comandos de shell individuales).

Operaciones por lotes: reduce significativamente los gastos generales en comparación con las operaciones individuales.
Uso directo de API: más eficiente que generar procesos de shell para cada comando.
(Agregue datos de referencia específicos cuando estén disponibles)

Características

Este servidor equipa a su agente de IA con un conjunto de herramientas de sistema de archivos potente y eficiente:

📁 Explorar e inspeccionar ( list_files , stat_items ): enumera archivos/directorios (recursivo, estadísticas), obtiene el estado detallado de varios elementos.
📄 Leer y escribir contenido ( read_content , write_content ): lee, escribe y agrega varios archivos, crea directorios principales.
✏️ Edición y búsqueda de precisión ( edit_file , search_files , replace_content ): ediciones quirúrgicas (insertar, reemplazar, eliminar) en múltiples archivos con preservación de sangría y salida diferencial; búsqueda de expresiones regulares con contexto; búsqueda/reemplazo de múltiples archivos.
🏗️ Administrar directorios ( create_directories ): crea múltiples directorios, incluidos los padres intermedios.
🗑️ Eliminar de forma segura ( delete_items ): elimina varios archivos/directorios de forma recursiva.
↔️ Mover y copiar ( move_items , copy_items ): mover/renombrar/copiar varios archivos/directorios.
🔒 Permisos de control ( chmod_items , chown_items ): cambia los permisos POSIX y la propiedad de varios elementos.

Beneficio clave: todas las herramientas que aceptan múltiples rutas/operaciones procesan cada elemento individualmente y devuelven un informe de estado detallado.

Filosofía del diseño

(Marcador de posición: Explique los principios básicos de diseño).

Seguridad primero: priorice la prevención del acceso fuera de la raíz del proyecto.
Eficiencia: minimice la sobrecarga de comunicación y el uso de tokens para las interacciones de IA.
Robustez: proporcione resultados detallados e informes de errores para operaciones por lotes.
Simplicidad: ofrecer una API clara y consistente a través de MCP.
Cumplimiento estándar: adherirse estrictamente al Protocolo de contexto modelo.

Comparación con otras soluciones

(Marcador de posición: comparar objetivamente con alternativas).

Característica/Aspecto	Servidor MCP del sistema de archivos	Comandos de Shell individuales (a través del agente)	Otros scripts personalizados
Seguridad	Alto (confinado en las raíces)	Bajo (el agente necesita acceso al shell)	Variable
Eficiencia (Tokens)	Alto (Dosis)	Bajo (un comando por operación)	Variable
Estado latente	Bajo (API directa)	Alto (generación de caparazones en lo alto)	Variable
Operaciones por lotes	Sí (la mayoría de las herramientas)	No	Tal vez
Informe de errores	Detallado (por artículo)	Básico (análisis de stdout/stderr)	Variable
Configuración	Fácil (npx/Docker)	Requiere configuración de shell seguro	Costumbre

Planes futuros

(Marcador de posición: enumera las próximas características o mejoras).

Explora las capacidades de observación de archivos.
Investigar el soporte de transmisión para archivos muy grandes.
Mejorar el rendimiento para operaciones específicas.
Agregue opciones de filtrado más avanzadas para list_files .

Documentación

(Marcador de posición: agregar enlace al sitio web de la documentación completa una vez que esté disponible).

La documentación completa, incluidas referencias API detalladas y ejemplos, estará disponible en: [Enlace al sitio de documentos]

Contribuyendo

¡Agradecemos sus contribuciones! Abra un problema o envíe una solicitud de incorporación de cambios en el repositorio de GitHub .

Licencia

Este proyecto se publica bajo la licencia MIT .

Desarrollo

Clonar: git clone https://github.com/sylphlab/filesystem-mcp.git
Instalar: cd filesystem-mcp && pnpm install
Compilación: pnpm run build (compila TypeScript en dist/ )
Ver: pnpm run dev (opcional, se vuelve a compilar al guardar)

Publicación (a través de GitHub Actions)

Este repositorio usa GitHub Actions ( .github/workflows/publish.yml ) para publicar automáticamente el paquete en npm y compilar/enviar una imagen de Docker a Docker Hub al enviar las etiquetas de versión ( v*.*.* ) a la rama main . Requiere los secretos NPM_TOKEN , DOCKERHUB_USERNAME y DOCKERHUB_TOKEN configurados en la configuración del repositorio de GitHub.