Filesystem MCP Server

Proporciona a los agentes de IA acceso seguro a operaciones del sistema de archivos local, como leer, escribir y gestionar archivos y directorios.

GitHub
53
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Sistema de Archivos

TypeScript Model Context Protocol Version License Status GitHub

Potencia a tus agentes de IA con capacidades robustas de sistema de archivos independientes de la plataforma, ahora con opciones de transporte STDIO y HTTP Streamable.

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 gestionar archivos y directorios, respaldado por una base TypeScript lista para producción que incluye registro integral, manejo de errores, medidas de seguridad y ahora soporta tanto transportes STDIO como HTTP.

Tabla de Contenidos

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 operaciones esenciales del sistema de archivos como herramientas, permitiendo a los agentes de IA:

  • Leer y analizar contenidos de archivos.
  • Crear, modificar o sobrescribir archivos.
  • Gestionar directorios y rutas de archivos.
  • Realizar actualizaciones específicas dentro de archivos.

Construido 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. Ahora soporta tanto STDIO para comunicación directa de procesos como HTTP para interacciones basadas en red.

Arquitectura

El servidor emplea una arquitectura en capas para mayor claridad y mantenibilidad:

flowchart TB
    subgraph TransportLayer["Transport Layer"]
        direction LR
        STDIO["STDIO Transport"]
        HTTP["HTTP Transport (Express, JWT Auth)"]
    end

    subgraph APILayer["API Layer"]
        direction LR
        MCP["MCP Protocol Interface"]
        Val["Input Validation (Zod)"]
        PathSan["Path Sanitization"]

        MCP --> Val --> PathSan
    end

    subgraph CoreServices["Core Services"]
        direction LR
        Config["Configuration (Zod-validated Env Vars)"]
        Logger["Logging (Winston, Context-aware)"]
        ErrorH["Error Handling (McpError, ErrorHandler)"]
        ServerLogic["MCP Server Logic"]
        State["Session State (Default Path)"]

        Config --> ServerLogic
        Logger --> ServerLogic & ErrorH
        ErrorH --> ServerLogic
        State --> ServerLogic
    end

    subgraph ToolImpl["Tool Implementation"]
        direction LR
        FSTools["Filesystem Tools"]
        Utils["Core Utilities (Internal, Security, Metrics, Parsing)"]

        FSTools --> ServerLogic
        Utils -- Used by --> FSTools
        Utils -- Used by --> CoreServices
        Utils -- Used by --> APILayer
    end

    TransportLayer --> MCP
    PathSan --> FSTools

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    class TransportLayer,APILayer,CoreServices,ToolImpl layer
    class STDIO,HTTP,MCP,Val,PathSan,Config,Logger,ErrorH,ServerLogic,State,FSTools,Utils component
  • Capa de Transporte: Maneja la comunicación a través de STDIO o HTTP (con Express.js y autenticación JWT).
  • Capa de API: Gestiona la comunicación MCP, valida entradas usando Zod y sanitiza rutas.
  • Servicios Principales: Supervisa la configuración (variables de entorno validadas con Zod), registro contextual, informes de errores estandarizados, estado de 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 un conjunto refactorizado de utilidades compartidas categorizadas en módulos internos, de seguridad, métricas y análisis.

Características

  • Operaciones Integrales de Archivos: Herramientas para leer, escribir, listar, eliminar, mover y copiar archivos y directorios.
  • Actualizaciones Específicas: La herramienta update_file permite operaciones precisas de buscar y reemplazar dentro de archivos, soportando texto plano 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.
  • Soporte de Doble Transporte:
    • STDIO: Para comunicación directa y eficiente cuando se ejecuta como proceso hijo.
    • HTTP: Para interacción basada en red, con endpoints RESTful, Eventos Enviados por el Servidor (SSE) para transmisión y autenticación basada en JWT.
  • Seguridad Primero:
    • La sanitización de rutas integrada previene ataques de traversal de directorios.
    • Autenticación JWT para transporte HTTP.
    • Validación de entradas con Zod.
  • Base Robusta: Incluye utilidades de grado de producción, ahora reorganizadas para mejor modularidad:
    • Utilidades Internas: Registro contextual (Winston), manejo de errores estandarizado (McpError, ErrorHandler), gestión de contexto de solicitudes.
    • Utilidades de Seguridad: Sanitización de entradas, limitación de velocidad, generación de UUID e IDs con prefijo.
    • Utilidades de Métricas: Conteo de tokens.
    • Utilidades de Análisis: Análisis de fechas en lenguaje natural, análisis de JSON parcial.
  • Configuración Mejorada: Variables de entorno validadas con Zod para una configuración segura de tipos y confiable.
  • Seguridad de Tipos: Implementado completamente en TypeScript para mayor confiabilidad y mantenibilidad.

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. Compilar el proyecto: 
    npm run build
    Esto compila el código TypeScript a JavaScript en el directorio dist/ y hace ejecutable el script principal. El ejecutable estará ubicado en dist/index.js.

Configuración

Configure el servidor usando variables de entorno (se admite un archivo .env):

Configuración Principal del Servidor:

  • MCP_LOG_LEVEL (Opcional): Nivel mínimo de registro (por ejemplo, debug, info, warn, error). El valor predeterminado es debug.
  • LOGS_DIR (Opcional): Directorio para archivos de registro. El valor predeterminado es ./logs en la raíz del proyecto.
  • NODE_ENV (Opcional): Entorno de ejecución (por ejemplo, development, production). El valor predeterminado es development.

Configuración de Transporte:

  • MCP_TRANSPORT_TYPE (Opcional): Transporte de comunicación (stdio o http). El valor predeterminado es stdio.
    • Si se selecciona http:
      • MCP_HTTP_PORT (Opcional): Puerto para el servidor HTTP. El valor predeterminado es 3010.
      • MCP_HTTP_HOST (Opcional): Host para el servidor HTTP. El valor predeterminado es 127.0.0.1.
      • MCP_ALLOWED_ORIGINS (Opcional): Lista separada por comas de orígenes CORS permitidos (por ejemplo, http://localhost:3000,https://example.com).
      • MCP_AUTH_SECRET_KEY (Requerido para Autenticación HTTP): Una clave secreta segura (de al menos 32 caracteres) para autenticación JWT. CRÍTICO para producción.

Seguridad del Sistema de Archivos:

  • FS_BASE_DIRECTORY (Opcional): Define el directorio raíz para todas las operaciones del sistema de archivos. Puede ser una ruta absoluta o una ruta relativa a la raíz del proyecto (por ejemplo, ./data_sandbox). Si se establece, las herramientas del servidor estarán restringidas a acceder solo a archivos y directorios dentro de esta ruta especificada (y resuelta como absoluta) y sus subdirectorios. Esta es una característica de seguridad crucial para prevenir el acceso no intencionado a otras partes del sistema de archivos. Si no se establece (lo cual no se recomienda para entornos de producción), se registrará una advertencia y las operaciones no estarán restringidas.

Integración de LLM y API (Opcional):

  • OPENROUTER_APP_URL: La URL de su aplicación para OpenRouter.
  • OPENROUTER_APP_NAME: El nombre de su aplicación para OpenRouter. El valor predeterminado es MCP_SERVER_NAME.
  • OPENROUTER_API_KEY: Clave de API para servicios de OpenRouter.
  • LLM_DEFAULT_MODEL: Modelo LLM predeterminado a usar (por ejemplo, google/gemini-2.5-flash-preview-05-20).
  • LLM_DEFAULT_TEMPERATURE, LLM_DEFAULT_TOP_P, LLM_DEFAULT_MAX_TOKENS, LLM_DEFAULT_TOP_K, LLM_DEFAULT_MIN_P: Parámetros predeterminados para llamadas LLM.
  • GEMINI_API_KEY: Clave de API para servicios de Google Gemini.

Integración de Proxy OAuth (Opcional, para escenarios avanzados):

  • OAUTH_PROXY_AUTHORIZATION_URL, OAUTH_PROXY_TOKEN_URL, OAUTH_PROXY_REVOCATION_URL, OAUTH_PROXY_ISSUER_URL, OAUTH_PROXY_SERVICE_DOCUMENTATION_URL, OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS: Configuración para un proxy OAuth.

Consulte src/config/index.ts y el archivo .clinerules para la lista completa y las definiciones de esquema Zod.

Uso con Clientes MCP

Para permitir que un cliente MCP (como un asistente de IA) use 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.

    Para Transporte STDIO (Predeterminado): Generalmente implica especificar:

    • Comando: node
    • Argumentos: La ruta absoluta al ejecutable del servidor compilado (por ejemplo, /path/to/filesystem-mcp-server/dist/index.js).
    • Variables de Entorno (Opcional): Establezca cualquier variable de entorno requerida de la sección Configuración.

    Ejemplo de Configuración MCP para STDIO (Conceptual):

    {
  "mcpServers": {
    "filesystem_stdio": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "debug"
        // Other relevant env vars
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

    Para Transporte HTTP: El cliente necesitará conocer la URL del servidor (por ejemplo, http://localhost:3010) y cómo autenticarse (por ejemplo, proporcionando un token Bearer JWT si MCP_AUTH_SECRET_KEY está establecido). Consulte la documentación de su cliente MCP para la configuración del servidor HTTP.

Una vez configurado y ejecutándose, el cliente detectará el servidor y sus herramientas disponibles.

Herramientas Disponibles

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

HerramientaDescripción
set_filesystem_defaultEstablece una ruta absoluta predeterminada para la sesión actual. Las rutas relativas utilizadas en llamadas posteriores a herramientas se resolverán con respecto a este valor predeterminado. Se restablece al reiniciar el servidor.
read_fileLee el contenido completo de un archivo especificado como texto UTF-8. Acepta rutas relativas (resueltas con respecto al valor predeterminado) o absolutas.
write_fileEscribe contenido en un archivo especificado. Crea el archivo (y los directorios padre necesarios) si no existe, o lo sobrescribe si ya existe. Acepta rutas relativas o absolutas.
update_fileRealiza operaciones de búsqueda y reemplazo específicas dentro de un archivo existente utilizando una matriz de bloques {search, replace}. Ideal para cambios localizados. Admite búsqueda de texto plano o regex (useRegex: true) y reemplazo de todas las apariciones (replaceAll: true). Acepta rutas relativas o absolutas. El archivo debe existir.
list_filesLista 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_fileElimina permanentemente un archivo específico. Acepta rutas relativas o absolutas.
delete_directoryElimina permanentemente un directorio. Utilice recursive: true para eliminar directorios no vacíos y su contenido (¡úsese con precaución!). Acepta rutas relativas o absolutas.
create_directoryCrea un nuevo directorio en la ruta especificada. De forma predeterminada (create_parents: true), también crea los directorios padre necesarios. Acepta rutas relativas o absolutas.
move_pathMueve o renombra un archivo o directorio de una ruta de origen a una ruta de destino. Acepta rutas relativas o absolutas para ambas.
copy_pathCopia un archivo o directorio de una ruta de origen a una ruta de destino. Para directorios, copia de forma recursiva de manera predeterminada (recursive: true). Acepta rutas relativas o absolutas.

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

Estructura del Proyecto

El código base está organizado para mayor claridad y mantenibilidad:

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, tool registration, transport handling
│   │   ├── 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.)
│   │   └── transports/   # Communication transport implementations
│   │       ├── authentication/ # Auth middleware for HTTP
│   │       │   └── authMiddleware.ts
│   │       ├── httpTransport.ts
│   │       └── stdioTransport.ts
│   ├── types-global/     # Shared TypeScript types and interfaces
│   │   ├── errors.ts     # Custom error classes and codes (McpError, BaseErrorCode)
│   │   ├── mcp.ts        # MCP related types
│   │   └── tool.ts       # Tool definition types
│   ├── utils/            # Reusable utility modules, categorized
│   │   ├── internal/     # Core internal utilities (errorHandler, logger, requestContext)
│   │   ├── metrics/      # Metrics-related utilities (tokenCounter)
│   │   ├── parsing/      # Parsing utilities (dateParser, jsonParser)
│   │   ├── security/     # Security-related utilities (idGenerator, rateLimiter, sanitization)
│   │   └── index.ts      # Barrel export for all utilities
│   └── index.ts          # Main application entry point
├── .clinerules           # Cheatsheet for LLM assistants
├── .dockerignore
├── Dockerfile
├── LICENSE
├── mcp.json              # MCP server manifest (generated by SDK or manually)
├── package.json
├── package-lock.json
├── README.md             # This file
├── repomix.config.json
├── smithery.yaml         # Smithery configuration (if used)
└── tsconfig.json         # TypeScript compiler options

Para una vista detallada y en vivo de la estructura actual, ejecute: npm run tree (Es posible que este script deba actualizarse si src/scripts/tree.ts fue parte de los cambios).

Nota para desarrolladores: Este repositorio incluye un archivo .clinerules. Esta hoja de referencia proporciona a su asistente de codificación LLM contexto esencial sobre patrones del código base, ubicaciones de archivos y ejemplos de uso. ¡Manténgala actualizada a medida que el servidor evolucione!

Licencia

Este proyecto está licenciado bajo la Apache License 2.0. Consulte el archivo LICENSE para obtener más detalles.

Construido con ❤️ y el Model Context Protocol