MCP Filesystem Server

Servidor MCP (Model Context Protocol) para operaciones de sistema de archivos. Este servidor implementa el protocolo MCP JSON-RPC y proporciona herramientas para navegar, leer, escribir y gestionar archivos y directorios.

Características

• Implementación del protocolo MCP JSON-RPC
• 5 herramientas de filesystem:
  • filesystem_list_directory - Listar contenido de directorio
  • filesystem_read_file - Leer contenido de archivo
  • filesystem_write_file - Escribir contenido en archivo
  • filesystem_create_directory - Crear directorio
  • filesystem_delete - Eliminar archivo o directorio
• Validación de rutas permitidas
• Límite de tamaño de archivo
• Logging de operaciones

Instalación

cd mcp-server
npm install

Configuración

Variables de entorno (opcionales):

• PORT - Puerto del servidor (default: 3000)
• ALLOWED_PATHS - Rutas permitidas separadas por comas (default: /)
• MAX_FILE_SIZE - Tamaño máximo de archivo en bytes (default: 10485760 = 10MB)

Ejemplo:

export PORT=3000
export ALLOWED_PATHS=/,/home/user,/tmp
export MAX_FILE_SIZE=10485760

Desarrollo

# Compilar TypeScript
npm run build

# Ejecutar en modo desarrollo
npm run dev

# Ejecutar en producción
npm start

# Modo watch para desarrollo
npm run watch

API

Endpoint Principal

POST / - Recibe requests JSON-RPC MCP

Formato de request:

{
  "jsonrpc": "2.0",
  "method": "filesystem_list_directory",
  "params": {
    "path": "/"
  },
  "id": 1
}

Formato de response:

{
  "jsonrpc": "2.0",
  "result": {
    "path": "/",
    "items": [
      {
        "name": "file.txt",
        "path": "/file.txt",
        "type": "file",
        "size": 1024,
        "modifiedDate": "2024-01-01T00:00:00.000Z"
      }
    ]
  },
  "id": 1
}

Health Check

GET /health - Verifica estado del servidor

Response:

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Herramientas MCP

filesystem_list_directory

Lista el contenido de un directorio.

Parámetros:

• path (string) - Ruta del directorio

Response:

• path (string) - Ruta del directorio
• items (array) - Lista de archivos y directorios
  • name (string) - Nombre del archivo/directorio
  • path (string) - Ruta completa
  • type (string) - "file" o "directory"
  • size (number) - Tamaño en bytes
  • modifiedDate (string) - Fecha de modificación ISO 8601

filesystem_read_file

Lee el contenido de un archivo.

Parámetros:

• path (string) - Ruta del archivo

Response:

• path (string) - Ruta del archivo
• content (string) - Contenido del archivo

filesystem_write_file

Escribe contenido en un archivo.

Parámetros:

• path (string) - Ruta del archivo
• content (string) - Contenido a escribir

Response:

• path (string) - Ruta del archivo
• success (boolean) - Indica si la operación fue exitosa

filesystem_create_directory

Crea un directorio.

Parámetros:

• path (string) - Ruta del directorio

Response:

• path (string) - Ruta del directorio
• success (boolean) - Indica si la operación fue exitosa

filesystem_delete

Elimina un archivo o directorio.

Parámetros:

• path (string) - Ruta del archivo/directorio

Response:

• path (string) - Ruta del archivo/directorio
• success (boolean) - Indica si la operación fue exitosa

Seguridad

• Validación de rutas permitidas
• Límite de tamaño de archivo
• Solo se permiten rutas dentro de los directorios configurados en ALLOWED_PATHS

Estructura del Proyecto

mcp-server/
├── src/
│   ├── handlers/
│   │   └── filesystem.handler.ts  # Implementación de operaciones de filesystem
│   ├── types/
│   │   ├── mcp.types.ts           # Tipos MCP generales
│   │   └── filesystem.types.ts    # Tipos específicos de filesystem
│   ├── config.ts                  # Configuración del servidor
│   ├── server.ts                  # Servidor MCP principal
│   └── index.ts                   # Punto de entrada
├── package.json
├── tsconfig.json
└── README.md

Licencia

MIT