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.

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

Clonar el repositorio:
git clone https://github.com/cyanheads/filesystem-mcp-server.git cd filesystem-mcp-server
Instalar dependencias:
npm install
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:

Ejecutar el servidor: Inicie el servidor desde su terminal:
node dist/index.js # Or if you are in the project root: # npm start
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:

Herramienta	Descripción
`set_filesystem_default`	Establece una ruta absoluta predeterminada para la sesión actual. Las rutas relativas utilizadas en las llamadas subsiguientes a la herramienta se resolverán con esta ruta predeterminada. Se restablece al reiniciar el servidor.
`read_file`	Lee todo el contenido de un archivo especificado como texto UTF-8. Acepta rutas relativas (resueltas con respecto a la predeterminada) o absolutas.
`write_file`	Escribe contenido en un archivo específico. Si no existe, lo crea (y los directorios principales necesarios) o lo sobrescribe si existe. Acepta rutas relativas o absolutas.
`update_file`	Realiza operaciones de búsqueda y reemplazo específicas dentro de un archivo existente mediante una matriz de bloques `{search, replace}` . Ideal para cambios localizados. Admite búsquedas de texto plano o expresiones regulares ( `useRegex: true` ) y reemplazo de todas las ocurrencias ( `replaceAll: true` ). Acepta rutas relativas o absolutas. El archivo debe existir.
`list_files`	Enumera archivos y directorios dentro de una ruta especificada. Las opciones incluyen listado recursivo ( `includeNested: true` ) y limitación del número de entradas ( `maxEntries` ). Devuelve una estructura de árbol formateada. Acepta rutas relativas o absolutas.
`delete_file`	Elimina permanentemente un archivo específico. Acepta rutas relativas o absolutas.
`delete_directory`	Elimina permanentemente un directorio. Use `recursive: true` para eliminar directorios no vacíos y su contenido (¡úselo con precaución!). Acepta rutas relativas o absolutas.
`create_directory`	Crea un nuevo directorio en la ruta especificada. Por defecto ( `create_parents: true` ), también crea los directorios principales necesarios. Acepta rutas relativas o absolutas.
`move_path`	Mueve o renombra un archivo o directorio de una ruta de origen a una de destino. Acepta rutas relativas o absolutas para ambas.
`copy_path`	Copia un archivo o directorio de una ruta de origen a una de destino. Para directorios, copia recursivamente por defecto ( `recursive: true` ). Acepta rutas relativas o absolutas.

Consulte los archivos de registro de herramientas ( src/mcp-server/tools/*/registration.ts ) para obtener esquemas de entrada/salida detallados (esquema Zod/JSON).

Estructura del proyecto

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

filesystem-mcp-server/
├── dist/                 # Compiled JavaScript output (after npm run build)
├── logs/                 # Log files (created at runtime)
├── node_modules/         # Project dependencies
├── src/                  # TypeScript source code
│   ├── config/           # Configuration loading (index.ts)
│   ├── mcp-server/       # Core MCP server logic
│   │   ├── server.ts     # Server initialization and tool registration
│   │   ├── state.ts      # Session state management (e.g., default path)
│   │   └── tools/        # Individual tool implementations (one subdir per tool)
│   │       ├── readFile/
│   │       │   ├── index.ts
│   │       │   ├── readFileLogic.ts
│   │       │   └── registration.ts
│   │       └── ...       # Other tools (writeFile, updateFile, etc.)
│   ├── types-global/     # Shared TypeScript types and interfaces
│   │   ├── errors.ts     # Custom error classes and codes
│   │   ├── mcp.ts        # MCP related types
│   │   └── tool.ts       # Tool definition types
│   ├── utils/            # Reusable utility modules
│   │   ├── errorHandler.ts
│   │   ├── idGenerator.ts
│   │   ├── index.ts
│   │   ├── logger.ts
│   │   ├── rateLimiter.ts
│   │   ├── requestContext.ts
│   │   └── sanitization.ts
│   └── index.ts          # Main application entry point
├── .clinerules           # Cheatsheet for LLM assistants
├── .gitignore
├── LICENSE
├── package.json
├── package-lock.json
├── README.md             # This file
└── tsconfig.json         # TypeScript compiler options

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.

Filesystem MCP Server

Integrations