fsext-mcp-server-typescript

Un servidor MCP completo y seguro para operaciones locales del sistema de archivos, con procesamiento de imágenes integrado, OCR y herramientas multimedia. Totalmente compatible con la especificación oficial de MCP, proporciona esquemas estandarizados de solicitud/respuesta, E/S de transmisión de archivos grandes, despliegue remoto con múltiples transportes y flujos de trabajo robustos de búsqueda y reemplazo de texto para la integración de agentes LLM.

GitHub

Prueba este MCPPatrocinado

Documentación

FsExt-MCP-Server (TypeScript)

Resumen

Un servidor de Model Context Protocol (MCP) de alto-rendimiento, seguro y de nivel de producción, construido con TypeScript, que proporciona operaciones integrales de sistema de archivos, búsqueda y reemplazo avanzado de texto, procesamiento de imágenes y capacidades de OCR Tesseract. Diseñado para la integración con agentes LLM, ofrece validación estricta de entrada, estructuras de respuesta estandarizadas, procesamiento de archivos grandes en streaming y soporte de despliegue remoto multi-transporte.

Este servidor cumple completamente con la especificación oficial de MCP, soportando integración local stdio, transporte de streaming heredado SSE y transporte bidireccional moderno Streamable HTTP, sirviendo como un backend universal de herramientas de sistema de archivos para agentes de IA y sistemas de flujo de trabajo automatizados.

Características Principales

CRUD completo de sistema de archivos y gestión de directorios: Creación, eliminación, copia, movimiento, consulta de metadatos y verificación de existencia de archivos/directorios. Soporta replicación recursiva de árboles de directorios completos y operaciones de movimiento seguras con protección de conflictos.
E/S de archivos en streaming para archivos grandes: Implementa lectura de texto segmentada, lectura de binarios por fragmentos, sobrescritura y anexado de texto/binario. Evita la carga completa en memoria, soportando perfectamente el procesamiento de archivos grandes de nivel GB.
Búsqueda avanzada de texto y reemplazo en el lugar: Búsqueda recursiva de contenido en todo el directorio, coincidencia contextual de archivos individuales/múltiples con líneas de vista previa, soporte de expresiones regulares, coincidencia sin distinción de mayúsculas y reemplazo preciso de texto en archivos con estadísticas de cambios.
Suite profesional de procesamiento de imágenes: Redimensionamiento de imágenes de alto rendimiento integrado (con bloqueo de relación de aspecto), recorte preciso y rotación de ángulo arbitrario basado en Sharp, cubriendo los escenarios principales de edición de imágenes.
OCR Tesseract multiplataforma: Reconocimiento OCR con prioridad WASM, con binarios Tesseract locales personalizables y rutas de tessdata, soportando extracción de texto multilingüe de imágenes sin dependencia de instalación de motor local.
Validación estricta de entrada y respuesta estandarizada: Todos los esquemas de herramientas habilitan la prohibición estricta de propiedades adicionales, con estructuras de respuesta de éxito/error unificadas para un análisis y manejo de errores consistente por parte del cliente.
Transportes MCP multi-estándar: Soporta nativamente los tres transportes oficiales de MCP: stdio (cliente local), SSE (stream remoto heredado), Streamable HTTP (transporte remoto bidireccional moderno).
Seguridad de tipos completa en TypeScript: Definiciones de tipos completas para todos los parámetros de herramientas, estructuras de respuesta y configuraciones de transporte, garantizando estabilidad en tiempo de ejecución y facilidad de desarrollo.

Inicio Rápido

Requisitos Previos

Node.js >=22.0.0 <27.0.0

Instalación

Instalación Global (Recomendada para uso CLI)

npm install -g fsext-mcp-server

Instalación Local en el Proyecto

npm install fsext-mcp-server

Comandos de Inicio

1. Modo Stdio Predeterminado (Para Claude Desktop / Cursor / Clientes MCP Locales)

# Default stdio transport for local agent integration
fsext-mcp-server-ts
fsext-mcp-server

# Short alias
fsext-ts
fsext

2. Modo de Transporte Remoto SSE

fsext-mcp-server --transport sse --host 0.0.0.0 --port 8000

Endpoints:

Suscripción al stream SSE: http://<host>:<port>/sse
Canal de solicitudes del cliente: http://<host>:<port>/messages

3. Modo de Transporte HTTP Streamable Moderno

fsext-mcp-server --transport http --host 0.0.0.0 --port 8000

Endpoint bidireccional unificado: http://<host>:<port>/mcp

Comparación de Modos de Transporte

Característica	Transporte SSE	HTTP Streamable
Arquitectura de endpoints	Dos endpoints (stream GET + mensaje POST)	Endpoint bidireccional unificado único
Modo de comunicación	Streaming unidireccional servidor-a-cliente	Streaming bidireccional completo y respuesta HTTP estándar
Estabilidad de conexión	Propenso a inconsistencias de sesión	Recuperación automática de sesión, optimizado para alta concurrencia
Estado de especificación	Compatibilidad heredada	Último estándar oficial de MCP

Ejemplo de Configuración de Cliente

Configuración JSON de Cliente MCP (Cursor / Claude Desktop)

{
  "mcpServers": {
    "fsext": {
      "command": "fsext-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Especificación de Respuesta Global Unificada

Todas las herramientas MCP adoptan una estructura de respuesta de nivel superior consistente tanto para escenarios de éxito como de error, permitiendo una lógica de análisis universal en el cliente.

Estructura General

{
  "res": {
    "success": boolean,
    "info": object
  }
}

Respuesta de Éxito

success: true - El campo info lleva los datos de negocio específicos de la herramienta.

Respuesta de Error (Estándar Unificado)

success: false - Todos los errores (fallo de E/S, parámetros inválidos, error de ruta, excepción en tiempo de ejecución) devuelven una estructura de error fija:

{
  "res": {
    "success": false,
    "info": {
      "code": "ERROR_CODE",
      "message": "Human-readable detailed error message"
    }
  }
}

Referencia Completa de Herramientas MCP

Todas las herramientas habilitan la validación estricta additionalProperties: false para rechazar parámetros de entrada ilegales, garantizando la seguridad de la invocación.

1. Herramientas de Operación de Directorios

fs_list_directory

Descripción: Escanea el directorio objetivo, devuelve una lista de rutas absolutas filtradas, soporta recorrido recursivo, filtrado de solo archivos y filtrado por sufijo.

Parámetros:

source_dir (string, obligatorio): Ruta del directorio objetivo a escanear
recursive (boolean, obligatorio): Habilitar escaneo recursivo de subdirectorios
only_files (boolean, obligatorio): Devolver solo archivos, excluir directorios
file_extension (string, opcional, predeterminado=""): Filtrar archivos por sufijo especificado

Respuesta de Éxito:

{
  "res": {
    "success": true,
    "info": {
      "paths": ["/absolute/path/file1.txt", "/absolute/path/file2.js"]
    }
  }
}

fs_copy_directory

Descripción: Copia recursivamente el árbol de directorios completo, soporta sobrescribir directorios objetivo existentes.

Parámetros:

source_dir (string, obligatorio): Ruta del directorio fuente
copy_dest_dir (string, obligatorio): Ruta del directorio objetivo
overwrite (boolean, opcional, predeterminado=false): Limpiar y sobrescribir el directorio objetivo existente

Respuesta de Éxito:

{
  "res": {
    "success": true,
    "info": {}
  }
}

fs_move_directory

Descripción: Mueve el árbol de directorios completo, falla rápidamente si la ruta objetivo existe para evitar sobrescrituras accidentales.

Parámetros:

source_dir (string, obligatorio): Ruta del directorio fuente
dest_dir (string, obligatorio): Ruta del directorio objetivo
overwrite (boolean, opcional, predeterminado=false): Permitir sobrescribir el directorio en conflicto

Respuesta de Éxito: Objeto de información vacío con indicador de éxito

2. Herramientas de Operación Básica de Archivos

fs_create_file

Descripción: Crea un archivo vacío o con contenido, crea automáticamente los directorios padre faltantes, soporta múltiples codificaciones.

Parámetros:

file_path (string, obligatorio): Ruta del archivo objetivo
content (string, opcional, predeterminado=""): Contenido de texto inicial
charset (string, opcional, predeterminado=utf-8): Codificación enumerada: utf-8, ucs-2, utf16le, latin1, ascii, base64, hex

Respuesta de Éxito: Objeto de información vacío con indicador de éxito

fs_delete_file

Descripción: Elimina solo un archivo regular individual; rechaza rutas de directorio para evitar riesgos de eliminación por lotes.

Parámetros:

file_path (string, obligatorio): Ruta del archivo objetivo

Respuesta de Éxito: Objeto de información vacío con indicador de éxito

fs_copy_file

Descripción: Copia un archivo individual con retención completa de metadatos, soporta control de sobrescritura.

Parámetros:

source_file_path (string, obligatorio): Ruta del archivo fuente
dest_file_path (string, obligatorio): Ruta del archivo objetivo
overwrite (boolean, opcional, predeterminado=false): Sobrescribir el archivo objetivo existente

Respuesta de Éxito: Objeto de información vacío con indicador de éxito

fs_move_file

Descripción: Mueve un archivo individual con comportamiento de sobrescritura configurable.

Parámetros:

source_file_path (string, obligatorio): Ruta del archivo fuente
dest_file_path (string, obligatorio): Ruta del archivo objetivo
overwrite (boolean, opcional, predeterminado=false): Sobrescribir el archivo en conflicto

Respuesta de Éxito: Objeto de información vacío con indicador de éxito

fs_get_file_info

Descripción: Obtiene los metadatos completos de un archivo/directorio, soporta cálculo opcional de digest SHA-256.

Parámetros:

file_path (string, obligatorio): Ruta de la entrada objetivo
calc_digest (boolean, opcional, predeterminado=false): Calcular hash SHA-256

Respuesta de Éxito:

{
  "res": {
    "success": true,
    "info": {
      "absolute_path": "string",
      "is_readable": true,
      "is_writable": true,
      "size": 1672,
      "is_regular_file": true,
      "is_directory": false,
      "is_symbolic_link": false,
      "creation_millis": 1782288135574,
      "last_modified_millis": 1782279393020,
      "last_access_millis": 1782644004556,
      "sha256_digest": "calculated-hash-string"
    }
  }
}

fs_is_file_exists

Descripción: Verificación ligera de existencia de archivo o directorio.

Parámetros:

file_path (string, obligatorio): Ruta objetivo

Respuesta de Éxito:

{
  "res": {
    "success": true,
    "info": {
      "exists": true
    }
  }
}

3. Herramientas de Lectura y Escritura de Archivos

fs_read_full_text

Descripción: Lee el contenido de texto completo del archivo objetivo con la codificación especificada.

Parámetros:

file_path (string, obligatorio): Ruta del archivo objetivo
charset (string, opcional, predeterminado=utf-8): Soporte de múltiples codificaciones

Respuesta de Éxito:

{
  "res": {
    "success": true,
    "info": {
      "content": "full-text-file-content"
    }
  }
}

fs_read_text_range

Descripción: Lectura de texto segmentada para archivos grandes, soporta omitir líneas iniciales y limitar líneas leídas.

Parámetros:

file_path (string, obligatorio): Ruta del archivo objetivo
lines_to_skip (integer, obligatorio): Número de líneas iniciales a omitir
max_lines_to_read (integer, obligatorio): Número máximo de líneas a leer
line_separator (string, opcional, predeterminado="\n"): Carácter de salto de línea
charset (string, opcional, predeterminado=utf-8): Codificación del archivo

Respuesta de Éxito:

{
  "res": {
    "success": true,
    "info": {
      "lines_count": 5,
      "content": "segmented-text-content"
    }
  }
}

fs_read_binary_chunk

Descripción: Lectura de archivos binarios por fragmentos, devuelve datos codificados en Base64 para transmisión segura por red, soporta detección de fin de stream.

Parámetros:

file_path (string, obligatorio): Ruta del archivo objetivo
bytes_to_skip (integer, obligatorio): Bytes iniciales a omitir
max_bytes_to_read (integer, obligatorio): Número máximo de bytes a leer

Respuesta de Éxito:

{
  "res": {
    "success": true,
    "info": {
      "data_base64": "base64-encoded-binary",
      "raw_bytes_length": 5,
      "end_of_stream": true
    }
  }
}

fs_write_text

Descripción: Escribe contenido de texto en un archivo, soporta modo de sobrescritura o anexado.

Parámetros:

file_path (string, obligatorio): Ruta del archivo objetivo
text (string, obligatorio, minLength=1): Contenido de texto a escribir
append (boolean, opcional, predeterminado=false): Interruptor de modo anexar
charset (string, opcional, predeterminado=utf-8): Codificación del archivo

Respuesta de Éxito: Objeto de información vacío con indicador de éxito

fs_write_binary

Descripción: Escribe datos binarios decodificados de Base64 en un archivo, soporta operación de anexado.

Parámetros:

file_path (string, obligatorio): Ruta del archivo objetivo
base64_data (string, obligatorio, minLength=1): Datos binarios codificados en Base64
append (boolean, opcional, predeterminado=false): Interruptor de modo anexar

Respuesta de Éxito: Objeto de información vacío con indicador de éxito

4. Herramientas de Búsqueda y Reemplazo

fs_search_files_by_content

Descripción: Escanea recursivamente el directorio, devuelve todas las rutas de archivos que contienen el contenido objetivo, soporta regex, ignorar mayúsculas, filtro de sufijo.

Parámetros:

dir_path (string, obligatorio): Directorio raíz de escaneo
recursive (boolean, obligatorio): Habilitar escaneo recursivo
search_term (string, obligatorio): Palabra clave de búsqueda o patrón regex
is_regex (boolean, opcional, predeterminado=false): Habilitar coincidencia regex
ignore_case (boolean, opcional, predeterminado=true): Coincidencia sin distinción de mayúsculas
file_extension (string, opcional, predeterminado=""): Filtro de sufijo de archivo
charset (string, opcional, predeterminado=utf-8): Codificación del archivo

fs_search_in_files_by_content

Descripción: Coincidencia de contenido en múltiples archivos, devuelve resultados estructurados con líneas de contexto personalizables y límite de resultados.

Parámetros:

dir_path (string, obligatorio): Directorio raíz de escaneo
recursive (boolean, obligatorio): Habilitar escaneo recursivo
search_term (string, obligatorio): Palabra clave/expresión regular de búsqueda
limit (integer, obligatorio): Número máximo de resultados coincidentes
is_regex (boolean, opcional, predeterminado=false): Habilitar regex
ignore_case (boolean, opcional, predeterminado=true): Ignorar mayúsculas
lines_before (integer, opcional, predeterminado=0): Líneas de contexto anteriores
lines_after (integer, opcional, predeterminado=0): Líneas de contexto posteriores
file_extension (string, opcional, predeterminado=""): Filtro de sufijo
charset (string, opcional, predeterminado=utf-8): Codificación del archivo

Respuesta de Éxito:

{
  "res": {
    "success": true,
    "info": {
      "results": [
        {
          "file_path": "/test/file.ts",
          "start_line": 1,
          "end_line": 1,
          "text": "matched-content-line"
        }
      ]
    }
  }
}

fs_search_in_file_by_content

Descripción: Búsqueda precisa de contenido en un solo archivo con vista previa de contexto de línea.

Parámetros: Similar a la búsqueda de múltiples archivos, entrada de ruta de archivo único

Respuesta exitosa: Resultados estructurados de coincidencias en un solo archivo

fs_file_replace

Descripción: Reemplazo de texto en el lugar dentro de un solo archivo, devuelve el recuento total de reemplazos.

Parámetros:

file_path (cadena, obligatorio): Ruta del archivo objetivo
search_term (cadena, obligatorio): Texto a reemplazar
replacement (cadena, obligatorio): Nuevo texto de reemplazo
line_separator (cadena, opcional, predeterminado="\n"): Separador de salto de línea

Respuesta exitosa:

{
  "res": {
    "success": true,
    "info": {
      "count": 1
    }
  }
}

5. Herramientas de procesamiento de imágenes

fs_image_resize

Descripción: Redimensiona imágenes con bloqueo de proporción de aspecto, genera un nuevo archivo de imagen de salida.

Parámetros:

source_path (cadena, obligatorio): Ruta de la imagen de origen
dest_path (cadena, obligatorio): Ruta de la imagen de salida
width (entero, obligatorio, >0): Ancho objetivo
height (entero, obligatorio, >0): Alto objetivo
keep_aspect_ratio (booleano, opcional, predeterminado=true): Bloquear proporción de aspecto original

Respuesta exitosa: Objeto de información vacío con indicador de éxito

fs_image_crop

Descripción: Recorta una región rectangular específica de la imagen de origen y exporta un nuevo archivo.

Parámetros:

source_path (cadena, obligatorio): Ruta de la imagen de origen
dest_path (cadena, obligatorio): Ruta de la imagen de salida
x (entero, obligatorio, ≥0): Coordenada X de inicio del recorte
y (entero, obligatorio, ≥0): Coordenada Y de inicio del recorte
width (entero, obligatorio, >0): Ancho de la región de recorte
height (entero, obligatorio, >0): Alto de la región de recorte

Respuesta exitosa: Objeto de información vacío con indicador de éxito

fs_image_rotate

Descripción: Rota la imagen en sentido horario por grados arbitrarios, expande automáticamente el lienzo para conservar el contenido completo.

Parámetros:

source_path (cadena, obligatorio): Ruta de la imagen de origen
dest_path (cadena, obligatorio): Ruta de la imagen de salida
degrees (número, obligatorio): Ángulo de rotación en sentido horario

Respuesta exitosa: Objeto de información vacío con indicador de éxito

6. Herramienta OCR

fs_ocr_extract_text

Descripción: Extrae texto de imágenes mediante Tesseract OCR, compatible con el tiempo de ejecución WASM (sin motor local) y una ruta binaria local personalizada.

Parámetros:

image_path (cadena, obligatorio): Ruta de la imagen objetivo
tesseract_bin_path (cadena, opcional, predeterminado=""): Ruta del ejecutable Tesseract personalizado
tessdata_path (cadena, opcional, predeterminado=""): Ruta de recursos de idioma tessdata personalizada
lang (cadena, opcional, predeterminado eng): Prefijo de idioma de reconocimiento

Respuesta exitosa:

{
  "res": {
    "success": true,
    "info": {
      "content": "extracted-ocr-text-content"
    }
  }
}

Compilación y desarrollo del proyecto

Scripts

# Clean build artifacts
npm run clean

# Compile TypeScript source
npm run build

# Watch mode for development
npm run dev

# Full rebuild (clean + build)
npm run rebuild

# Start SSE transport server
npm run server

# FastMCP dev mode
npm run fastmcp

# MCP Inspector debugging
npm run inspect

# Build and run test cases
npm run test

Dependencias

Dependencias principales del tiempo de ejecución

fastmcp: Marco de tiempo de ejecución oficial del servidor MCP
sharp: Motor de procesamiento de imágenes de alto rendimiento
tesseract.js: Motor OCR multiplataforma basado en WASM
winston: Sistema de registro estándar
zod: Validación estricta de esquemas para parámetros de herramientas
chardet / iconv-lite: Detección y conversión de múltiples codificaciones
cors: Soporte de intercambio de recursos entre orígenes para transporte HTTP
minimist: Análisis de parámetros de línea de comandos

Licencia

Este proyecto se publica bajo la Licencia Apache 2.0. Consulte el archivo LICENSE en la raíz del proyecto para obtener los detalles completos de la licencia.

Repositorio y problemas

GitHub: https://github.com/kurtzhi/fsext-mcp-server-typescript
Problemas: Informar errores o solicitar funciones