fsext-mcp-server-python

Un servidor MCP completo y seguro para operaciones locales del sistema de archivos, con herramientas integradas de procesamiento de imágenes, OCR y medios.

GitHubPrueba este MCPPatrocinado

Documentación

FsExt-MCP-Server (Python)

Visión general

Un servidor MCP seguro y completo para operaciones de sistema de archivos local, con herramientas integradas de procesamiento de imágenes, OCR y multimedia. Totalmente compatible con la especificación oficial del Protocolo de Contexto de Modelo (Model Context Protocol), que ofrece esquemas estandarizados de solicitud/respuesta, E/S de transmisión para archivos grandes, despliegue remoto multi-transporte y funcionalidad integral de búsqueda y reemplazo de texto para la integración de agentes LLM.

Características principales

Gestión completa de archivos y directorios: Soporte para creación, eliminación, copia, movimiento, consulta de metadatos y verificación de existencia de archivos; copia y movimiento recursivos de árboles de directorios completos con controles de seguridad contra sobrescritura.
Lectura/Escritura de archivos en streaming: Integra lectura de texto completo, lectura de texto segmentada por líneas, lectura binaria por fragmentos, escritura de sobrescritura y anexado de texto/binario, optimizado para evitar cargar archivos grandes completos en memoria.
Potente búsqueda y reemplazo: Soporte para búsqueda recursiva de contenido en archivos de todo un directorio, coincidencia contextual en archivos individuales/múltiples con líneas de coincidencia previas/posteriores configurables, coincidencia con expresiones regulares, búsqueda sin distinción de mayúsculas/minúsculas y reemplazo de texto en el lugar con estadísticas de recuento de coincidencias.
Herramientas de procesamiento de imágenes: Kit de herramientas de imágenes de alto rendimiento integrado, impulsado por Pillow, que incluye redimensionamiento (bloqueo de relación de aspecto + soporte de relleno de lienzo), recorte y rotación en el sentido de las agujas del reloj en ángulos arbitrarios.
Reconocimiento OCR nativo con Tesseract: Extracción fiable de texto de imágenes que depende de la instalación local del binario de Tesseract. Sin respaldo WASM; un argumento de ruta de binario vacío no activará motores OCR alternativos basados en JS. Soporte de recursos tessdata multilingües con rutas de binario y datos configurables.
Validación estricta de entrada y formato de respuesta unificado: Cada herramienta habilita la validación estricta de esquema additionalProperties: false para bloquear campos de entrada inesperados. Todas las operaciones comparten una estructura universal de envoltura de éxito/error para un análisis consistente por parte del cliente.
Soporte multi-transporte: Compatible con los transportes MCP estándar oficiales: stdio (integración con clientes de escritorio locales), sse (flujo remoto ligero heredado) y Streamable HTTP (transporte de transmisión remota bidireccional moderno).
Aislamiento de seguridad del espacio de trabajo: Proporciona capacidad de restricción de directorio --lock-root. Todas las operaciones de archivos/directorios están estrictamente confinadas al espacio de trabajo raíz especificado para prevenir ataques de escape de ruta entre directorios no autorizados.

Inicio rápido: Ejecutar directamente con uvx (sin instalación previa)

uvx descarga automáticamente el paquete PyPI publicado e inicia un entorno de ejecución aislado, eliminando la instalación manual de dependencias o la configuración de entornos virtuales.

1. Comandos básicos de inicio con uvx

Comando corto (recomendado)

# Default stdio mode, unrestricted full filesystem access
uvx fsext-mcp-server

# Lock all operations to a dedicated workspace (production security recommended)
uvx fsext-mcp-server --lock-root /your/workspace

Comando completo

# Stdio mode with workspace isolation
uvx fsext-mcp-server --transport stdio --lock-root /your/workspace

# Remote SSE streaming service
uvx fsext-mcp-server --transport sse --host 0.0.0.0 --port 8000 --lock-root /your/workspace

# Modern Streamable HTTP remote service
uvx fsext-mcp-server --transport http --host 0.0.0.0 --port 8000 --lock-root /your/workspace

2. Integrar las herramientas FsExt con frameworks LLM

No se requiere pre-despliegue en máquinas host; uvx instancia dinámicamente el servidor cuando un cliente MCP establece una conexión.

Ejemplo de configuración de cliente (Claude Desktop / Cursor MCP json)

{
  "mcpServers": {
    "fsext": {
      "command": "uvx",
      "args": [
        "fsext-mcp-server",
        "--lock-root",
        "/your/workspace"
      ],
      "env": {"PYTHONUTF8": "1"}
    }
  }
}

Fragmento de integración central de LangChain / LangGraph

Existen limitaciones de ciclo de vida de sesión dentro del langchain-mcp-adapters oficial; la lógica completa de conexión larga estable requiere personalización adicional del adaptador. A continuación se muestra la plantilla mínima estándar de conexión:

# Core config: Connect to FsExt MCP via uvx stdio transport
server_config = {
    "fsext": {
        "transport": "stdio",
        "command": "uvx",
        "args": ["fsext-mcp-server", "--lock-root", r"/your/workspace"],
        "env": {"PYTHONUTF8": "1"}
    }
}

# Load all exposed filesystem MCP tools
client = MultiServerMCPClient(server_config)
async with client.session("fsext") as session:
    mcp_tools = await load_mcp_tools(session)

# Bind loaded MCP tools to LLM instance for agent workflows
llm = ChatOpenAI(base_url="your-local-llm-api").bind_tools(mcp_tools)

Instalación tradicional e inicio mediante pip

Instalar el paquete PyPI publicado

pip install fsext-mcp-server

Comandos de inicio después de la instalación con pip

# Default stdio local mode
fsext-mcp-server-py
fsext-mcp-server

# Short alias
fsext-py
fsext

# Secure workspace locked mode
fsext --lock-root /your/workspace

# Remote SSE streaming server
fsext --transport sse --port 8000

Configuración de desarrollo con repositorio fuente local

Se recomienda usar uv para un despliegue de entorno rápido y determinista:

# Clone official source repository
git clone https://github.com/kurtzhi/fsext-mcp-server-python
cd fsext-mcp-server-python

# Install full runtime + dev dependencies
uv sync

Descripción de dependencias principales de ejecución

chardet: Detección automática de codificación de archivos de texto
Pillow: Backend central de procesamiento de imágenes para los flujos de redimensionamiento, recorte y rotación
python-magic: Identificación precisa multiplataforma del tipo MIME de archivos
fastmcp: Framework oficial de servidor MCP para Python
uvicorn / starlette: Entorno de ejecución del servidor de transporte HTTP/SSE
pydantic: Validación estricta de esquema para todos los parámetros de entrada de herramientas
tesseract: Enlaces nativos para el binario local de Tesseract OCR

Uso de inicio

El servidor soporta tres modos de transporte MCP oficiales y una configuración flexible de aislamiento de la raíz del espacio de trabajo mediante banderas de CLI.

Tabla de referencia de parámetros de inicio

Parámetro	Valor predeterminado	Descripción
`--transport`	stdio	Tipo de transporte MCP: `stdio` / `sse` / `http`
`--host`	127.0.0.1	Dirección de enlace de red (ignorada en el transporte stdio)
`--port`	8000	Puerto de enlace del servicio (ignorado en el transporte stdio)
`--lock-root`	None	Restringe todas las operaciones del sistema de archivos a este directorio raíz; acceso completo sin restricciones si se omite

Comandos comunes de inicio en producción

1. Modo Stdio local predeterminado (para clientes de IA Claude Desktop / Cursor)

uv run -m fsext

2. Modo Stdio con bloqueo obligatorio del espacio de trabajo (uso seguro de agentes locales)

uv run -m fsext --lock-root /your/workspace/path

3. Modo de transporte SSE remoto

uv run -m fsext --transport sse --host 0.0.0.0 --port 8000

Puntos de acceso

Canal de suscripción de flujo SSE de larga duración (empuje de eventos del servidor): http://<host>:<port>/sse
Canal de envío de solicitudes JSON-RPC del cliente: http://<host>:<port>/messages

Configuración de conexión del Inspector MCP

Tipo de transporte: SSE
Dirección de conexión de entrada: http://127.0.0.1:8000/sse

4. Transporte remoto Streamable HTTP estándar (bidireccional moderno)

uv run -m fsext --transport http --host 0.0.0.0 --port 8000

Punto de acceso bidireccional unificado

Punto de entrada único compartido tanto para solicitudes del cliente como para transmisión del servidor: http://<host>:<port>/mcp

Configuración de conexión del Inspector MCP

Tipo de transporte: Streamable HTTP
Dirección de conexión de entrada: http://127.0.0.1:8000/mcp

5. Comparación de características de transporte SSE vs Streamable HTTP

Característica	Transporte SSE de doble punto final	Transporte Streamable HTTP de punto final único
Arquitectura de puntos finales	Dos puntos finales separados: suscripción de flujo GET + envío de mensajes POST	Una única URL unificada maneja todo el tráfico bidireccional
Patrón de comunicación	Solo empuje de eventos unidireccional del servidor al cliente	Capacidad híbrida completa bidireccional de solicitud/flujo
Fiabilidad de conexión	Pérdida frecuente de sesiones, gestión compleja de estado entre puntos finales	Recuperación automática de sesiones, optimizado para conexiones remotas de alta concurrencia
Estado de la especificación oficial	Implementación compatible heredada, no recomendada para nuevos despliegues	Estándar MCP oficial actual para integraciones de red remotas

Especificación global de respuesta unificada

Todas las herramientas MCP comparten una estructura JSON de envoltura de nivel superior idéntica tanto para la ejecución exitosa como para los estados de fallo en tiempo de ejecución. La carga útil de negocio de cada herramienta está anidada dentro del sub-objeto info bajo el campo raíz res.

Definición de la estructura central

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

success: Indicador global del estado de la operación
- true: La lógica de la herramienta se ejecutó sin excepciones; info contiene los datos de retorno específicos de la herramienta
- false: La operación falló (bloqueo de escape del espacio de trabajo, archivo faltante, error de E/S, esquema de entrada no válido, permiso denegado, etc.)
Comportamiento dual del campo info:
1. Modo de éxito (success: true): Carga útil de negocio estructurada personalizada y única para cada herramienta
2. Modo de fallo (success: false): Objeto de error estandarizado fijo con código de error legible por máquina y explicación legible por humanos
```
"info": {
  "code": "ERROR_CODE_IDENTIFIER",
  "message": "Detailed human-readable failure description"
}
```

Ejemplos completos de respuestas

1. Muestra de respuesta exitosa (fs_list_directory)

{
  "res": {
    "success": true,
    "info": {
      "paths": [
        "/tmp/tests/test_util.py",
        "/tmp/tests/__init__.py",
        "/tmp/tests/img/cochem_castle.jpg"
      ]
    }
  }
}

2. Muestra de respuesta de fallo (restricción de escape de ruta del espacio de trabajo)

{
  "res": {
    "success": false,
    "info": {
      "code": "WORKSPACE_ESCAPE_FORBIDDEN",
      "message": "Access restricted: Path `/tmp/test2` is outside allowed workspace `/tmp/tests`"
    }
  }
}

Todas las herramientas aplican el aislamiento de la raíz del espacio de trabajo y siguen completamente las definiciones estandarizadas de esquema de entrada/salida que se enumeran a continuación.

Referencia completa de herramientas MCP

Todos los esquemas de entrada de herramientas habilitan la validación estricta additionalProperties: false para rechazar parámetros no reconocidos y prevenir vectores maliciosos de inyección de rutas.

1. Herramientas de operaciones de directorio

fs_list_directory

Descripción: Escanea el directorio de destino de forma recursiva o superficial, devuelve una lista filtrada de rutas absolutas del sistema de archivos con controles de filtrado por tipo de archivo y extensión. Parámetros:

source_dir (cadena, obligatorio): Ruta del directorio raíz para escanear
recursive (booleano, obligatorio): Habilitar el recorrido recursivo completo de todos los subdirectorios
only_files (booleano, obligatorio): Filtrar la salida para devolver solo archivos regulares, excluir directorios
file_extension (cadena, opcional, predeterminado=""): Filtrar los resultados a archivos que coincidan con la extensión de sufijo especificada Carga útil de respuesta exitosa:

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

fs_copy_directory

Descripción: Copia recursivamente un árbol de directorios completo, con comportamiento de sobrescritura configurable para directorios de destino preexistentes. Parámetros:

source_dir (cadena, obligatorio): Ruta del árbol de directorio fuente
copy_dest_dir (cadena, obligatorio): Ruta del directorio de salida de destino
overwrite (booleano, opcional, predeterminado=false): Limpiar y sobrescribir el contenido del directorio de destino existente Carga útil de respuesta exitosa:

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

fs_move_directory

Descripción: Mueve atómicamente un árbol de directorios completo a una nueva ruta de destino. Falla inmediatamente si el destino existe, a menos que la sobrescritura esté explícitamente habilitada para evitar la pérdida accidental de datos. Parámetros:

source_dir (cadena, obligatorio): Ruta del directorio fuente
dest_dir (cadena, obligatorio): Ruta del directorio de destino
overwrite (booleano, opcional, predeterminado=false): Permitir sobrescribir directorios de destino en conflicto Carga útil de respuesta exitosa: Envoltura de objeto info vacía con indicador de éxito.

2. Herramientas básicas de operaciones con archivos individuales

fs_create_file

Descripción: Crea un nuevo archivo de texto, genera automáticamente los directorios principales faltantes, soporta codificación de texto configurable y contenido inicial del archivo. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta del archivo de destino
content (cadena, opcional, predeterminado=""): Contenido de texto inicial escrito en el nuevo archivo
charset (cadena, opcional, predeterminado="utf-8"): Valor de enumeración de codificación de texto (lista completa de conjuntos de caracteres a continuación) Valores de enumeración de conjuntos de caracteres soportados: utf-8, utf-16, latin-1, iso-8859-1, cp1252, Windows-1252, gbk, gb2312, shift_jis, euc_jp, euc_kr Carga útil de respuesta exitosa: Envoltura de objeto info vacía con indicador de éxito.

fs_delete_file

Descripción: Elimina permanentemente solo un archivo regular; rechaza entradas de rutas de directorio para bloquear riesgos de eliminación recursiva masiva. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta del archivo regular de destino Carga útil de respuesta exitosa: Envoltura de objeto info vacía con indicador de éxito.

fs_copy_file

Descripción: Copia un solo archivo conservando los metadatos originales del sistema de archivos, con sobrescritura configurable para archivos de destino en conflicto. Parámetros:

source_file_path (cadena, obligatorio): Ruta absoluta del archivo fuente
dest_file_path (cadena, obligatorio): Ruta absoluta del archivo de salida de destino
overwrite (booleano, opcional, predeterminado=false): Sobrescribir el archivo de destino preexistente Carga útil de respuesta exitosa: Envoltura de objeto info vacía con indicador de éxito.

fs_move_file

Descripción: Mueve atómicamente un solo archivo a una nueva ruta absoluta, con comportamiento de sobrescritura configurable para archivos de destino en conflicto. Parámetros:

source_file_path (cadena, obligatorio): Ruta absoluta del archivo fuente
dest_file_path (cadena, obligatorio): Ruta absoluta del archivo de destino
overwrite (booleano, opcional, predeterminado=false): Permitir sobrescribir archivos de destino en conflicto Carga útil de respuesta exitosa: Envoltura de objeto info vacía con indicador de éxito.

fs_get_file_info

Descripción: Recupera metadatos completos de archivos o directorios, con cálculo opcional de digest criptográfico SHA-256 para verificación de integridad. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta de la entrada del sistema de archivos
calc_digest (booleano, opcional, predeterminado=false): Calcular hash SHA-256 del contenido del archivo Carga útil de respuesta exitosa:

{
  "res": {
    "success": true,
    "info": {
      "absolute_path": "C:\\Users\\zhigu\\Documents\\My Games\\fsext-mcp-server\\pyproject.toml",
      "is_readable": true,
      "is_writable": true,
      "size": 1672,
      "is_regular_file": true,
      "is_directory": false,
      "is_symbolic_link": false,
      "creation_millis": 1782288135574.7114,
      "last_modified_millis": 1782279393020.1187,
      "last_access_millis": 1782644004556.3462,
      "sha256_digest": "59614cf5f8ecff38de37637f1d5b6f607d885bd277815786f5ce4bb2ee5b73a6"
    }
  }
}

fs_is_file_exists

Descripción: Verificación ligera de existencia para cualquier entrada del sistema de archivos (archivo o directorio) sin cargar metadatos completos. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta de destino a verificar Carga útil de respuesta exitosa:

{
  "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 de un archivo de destino con codificación de texto especificada por el usuario. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta del archivo de texto de destino
charset (cadena, opcional, predeterminado="utf-8"): Valor de enumeración de codificación de texto Carga útil de respuesta exitosa:

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

fs_read_text_range

Descripción: Lectura de texto segmentada en streaming optimizada para archivos grandes; omite líneas iniciales y limita el total de líneas leídas para evitar sobrecarga de memoria. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta del archivo de texto de destino
lines_to_skip (entero, obligatorio, mínimo=0): Número de líneas iniciales a omitir durante la lectura
max_lines_to_read (entero, obligatorio, mínimo=0): Máximo total de líneas a extraer del archivo
line_separator (cadena, opcional, predeterminado="\n"): Carácter delimitador de salto de línea
charset (cadena, opcional, predeterminado="utf-8"): Valor de enumeración de codificación de texto Carga útil de respuesta exitosa:

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

fs_read_binary_chunk

Descripción: Lectura en streaming por fragmentos para archivos binarios; devuelve cargas útiles de bytes codificadas en Base64 para transmisión segura JSON-RPC por red con detección de marcador de fin de flujo. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta del archivo binario de destino
bytes_to_skip (entero, obligatorio, mínimo=0): Número de bytes iniciales a omitir antes de leer el fragmento
max_bytes_to_read (entero, obligatorio, mínimo=0): Longitud máxima de bytes a leer en un solo fragmento Carga útil de respuesta exitosa:

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

fs_write_text

Descripción: Escribe contenido de texto UTF o multi-codificado en el archivo de destino, con soporte para sobrescritura completa o modos de escritura solo anexar. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta del archivo de salida de destino
text (cadena, obligatorio, minLength=1): Contenido de texto sin procesar a persistir
append (booleano, opcional, predeterminado=false): Indicador de modo anexar (false = sobrescribir archivo completo)
charset (cadena, opcional, predeterminado="utf-8"): Valor de enumeración de codificación de texto Carga útil de respuesta exitosa: Envoltorio de objeto info vacío con indicador de éxito.

fs_write_binary

Descripción: Decodifica carga útil binaria codificada en Base64 y escribe bytes sin procesar en el archivo de destino, con soporte para modo anexar en cargas binarias de múltiples fragmentos. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta del archivo de salida de destino
base64_data (cadena, obligatorio, minLength=1): Carga útil de bytes binarios sin procesar codificada en Base64
append (booleano, opcional, predeterminado=false): Anexar datos binarios al final del archivo (false = sobrescribir) Carga útil de respuesta exitosa: Envoltorio de objeto info vacío con indicador de éxito.

4. Herramientas de Búsqueda de Contenido y Reemplazo en el Lugar

fs_search_files_by_content

Descripción: Escanea recursivamente el árbol de directorios y devuelve rutas absolutas de todos los archivos que contienen el patrón de texto de destino; admite coincidencia regex, insensibilidad a mayúsculas y filtrado por extensión de archivo. Parámetros:

dir_path (cadena, obligatorio): Directorio raíz para escaneo de contenido recursivo
recursive (booleano, obligatorio): Habilitar recursión completa en subdirectorios
search_term (cadena, obligatorio): Palabra clave de texto plano o patrón de expresión regular
is_regex (booleano, opcional, predeterminado=false): Tratar search_term como patrón regex cuando es true
ignore_case (booleano, opcional, predeterminado=true): Coincidencia de patrones insensible a mayúsculas
file_extension (cadena, opcional, predeterminado=""): Filtrar archivos escaneados por sufijo de extensión
charset (cadena, opcional, predeterminado="utf-8"): Valor de enumeración de codificación de texto para análisis de archivos

fs_search_in_files_by_content

Descripción: Coincidencia de contenido masiva en múltiples directorios, devuelve resultados de coincidencia estructurados con líneas de contexto precedentes y posteriores configurables alrededor del contenido coincidente, más limitación global del recuento de resultados. Parámetros:

dir_path (cadena, obligatorio): Ruta absoluta del directorio raíz de escaneo
recursive (booleano, obligatorio): Habilitar recorrido recursivo completo de subdirectorios
search_term (cadena, obligatorio): Palabra clave de búsqueda o patrón regex
limit (entero, obligatorio): Límite máximo estricto en el total de entradas coincidentes devueltas
is_regex (booleano, opcional, predeterminado=false): Habilitar coincidencia de expresiones regulares
ignore_case (booleano, opcional, predeterminado=true): Deshabilitar coincidencia sensible a mayúsculas
lines_before (entero, opcional, predeterminado=0): Número de líneas de contexto precedentes a cada línea coincidente
lines_after (entero, opcional, predeterminado=0): Número de líneas de contexto posteriores a cada línea coincidente
file_extension (cadena, opcional, predeterminado=""): Filtrar archivos escaneados por sufijo de extensión
charset (cadena, opcional, predeterminado="utf-8"): Valor de enumeración de codificación de texto para análisis de archivos Carga útil de respuesta exitosa:

{
  "res": {
    "success": true,
    "info": {
      "results": [
        {
          "file_path": "/absolute/path/source.py",
          "start_line": 1,
          "end_line": 1,
          "text": "full-matched-line-content-with-context"
        }
      ]
    }
  }
}

fs_search_in_file_by_content

Descripción: Búsqueda de contenido de precisión en un solo archivo, devuelve segmentos coincidentes estructurados con líneas de contexto pre/post configurables para flujos de trabajo de inspección de código y documentos. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta del archivo único de destino
search_term (cadena, obligatorio): Palabra clave de búsqueda o patrón regex
is_regex (booleano, opcional, predeterminado=false): Habilitar lógica de coincidencia de expresiones regulares
ignore_case (booleano, opcional, predeterminado=true): Alternar coincidencia insensible a mayúsculas
lines_before (entero, opcional, predeterminado=0): Líneas de contexto precedentes para cada coincidencia
lines_after (entero, opcional, predeterminado=0): Líneas de contexto posteriores para cada coincidencia
charset (cadena, opcional, predeterminado="utf-8"): Valor de enumeración de codificación de texto para análisis de archivos Carga útil de respuesta exitosa: Matriz estructurada de objetos de coincidencia de línea idéntica al formato de salida de búsqueda en múltiples archivos.

fs_file_replace

Descripción: Realiza reemplazo de texto global en el lugar dentro de un solo archivo de destino; devuelve el recuento total de segmentos de texto coincidentes y reemplazados después de la escritura. Parámetros:

file_path (cadena, obligatorio): Ruta absoluta del archivo editable de destino
search_term (cadena, obligatorio): Subcadena de texto a localizar y reemplazar
replacement (cadena, obligatorio): Nueva carga útil de texto de reemplazo
line_separator (cadena, opcional, predeterminado="\n"): Delimitador de salto de línea para análisis de archivos Carga útil de respuesta exitosa:

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

5. Herramientas de Procesamiento de Imágenes

fs_image_resize

Descripción: Redimensiona la imagen de origen a las dimensiones de ancho/alto especificadas, con soporte nativo para preservación de relación de aspecto y relleno de lienzo para completar las dimensiones exactas de resolución de destino. Parámetros:

source_path (cadena, obligatorio): Ruta absoluta de la imagen de entrada de origen
dest_path (cadena, obligatorio): Ruta absoluta de la imagen de salida redimensionada
width (entero, obligatorio, exclusiveMinimum=0): Dimensión de ancho de píxel de destino
height (entero, obligatorio, exclusiveMinimum=0): Dimensión de alto de píxel de destino
keep_aspect_ratio (booleano, opcional, predeterminado=true): Bloquear relación de aspecto original de la imagen durante el escalado
pad_to_target (booleano, opcional, predeterminado=true): Agregar relleno transparente para completar ancho/alto exacto de destino cuando la relación de aspecto está bloqueada Carga útil de respuesta exitosa: Envoltorio de objeto info vacío con indicador de éxito.

fs_image_crop

Descripción: Extrae una región de píxeles rectangular de la imagen de origen y la exporta como archivo de imagen de salida independiente. Parámetros:

source_path (cadena, obligatorio): Ruta absoluta de la imagen de entrada de origen
dest_path (cadena, obligatorio): Ruta absoluta de la imagen de salida recortada
x (entero, obligatorio, mínimo=0): Coordenada de píxel izquierda del origen de la región de recorte
y (entero, obligatorio, mínimo=0): Coordenada de píxel superior del origen de la región de recorte
width (entero, obligatorio, exclusiveMinimum=0): Ancho de píxel de la región rectangular recortada
height (entero, obligatorio, exclusiveMinimum=0): Alto de píxel de la región rectangular recortada Carga útil de respuesta exitosa: Envoltorio de objeto info vacío con indicador de éxito.

fs_image_rotate

Descripción: Rota la imagen de origen en sentido horario por valores arbitrarios de grados de punto flotante; expande automáticamente las dimensiones del lienzo de salida para retener el contenido completo de la imagen sin recortar bordes. Parámetros:

source_path (cadena, obligatorio): Ruta absoluta de la imagen de entrada de origen
dest_path (cadena, obligatorio): Ruta absoluta de la imagen de salida rotada
degrees (número, obligatorio): Ángulo de rotación en sentido horario en grados Carga útil de respuesta exitosa: Envoltorio de objeto info vacío con indicador de éxito.

6. Herramienta de Extracción de Texto OCR

fs_ocr_extract_text

Descripción: Extrae texto legible por humanos de archivos de imagen rasterizados mediante la instalación binaria local de Tesseract OCR. No existe implementación de respaldo JavaScript WASM; un argumento tesseract_bin_path vacío no inicializará motores OCR alternativos basados en web. Parámetros:

image_path (cadena, obligatorio): Ruta absoluta de la imagen de entrada para reconocimiento de texto
tesseract_bin_path (cadena, opcional, predeterminado=""): Ruta absoluta al binario ejecutable local de Tesseract; valor vacío usa solo búsqueda en PATH del sistema
tessdata_path (cadena, opcional, predeterminado=""): Ruta de directorio absoluta que contiene archivos de datos de entrenamiento de idioma de Tesseract
lang (cadena, opcional, predeterminado="eng"): Prefijo de código de idioma que coincide con archivos de entrenamiento tessdata disponibles Carga útil de respuesta exitosa:

{
  "res": {
    "success": true,
    "info": {
      "content": "full-ocr-extracted-text-from-input-image"
    }
  }
}

Scripts de Desarrollo y Compilación del Proyecto

Todos los scripts de desarrollo uv estandarizados equivalentes a npm para contribuyentes del repositorio fuente:

# Clean compiled build artifacts and temporary output directories
uv run -m scripts.clean

# Compile source code and type validation
uv run -m scripts.build

# Watch source files for incremental development rebuilds
uv run -m scripts.dev

# Full rebuild pipeline: clean artifacts + full source compilation
uv run -m scripts.rebuild

# Launch remote SSE transport server instance
uv run -m scripts.server

# FastMCP interactive development mode
uv run -m scripts.fastmcp

# MCP Inspector debug connection launcher
uv run -m scripts.inspect

# Execute full test suite with compiled test artifacts
uv run -m scripts.test

Dependencias de Tiempo de Ejecución Principales

fastmcp: Marco de trabajo oficial de tiempo de ejecución del servidor MCP Python
Pillow: Backend de procesamiento de imágenes multiplataforma para pipelines de redimensionamiento, recorte y rotación
tesseract: Enlaces nativos de Python para el binario local de Tesseract OCR
chardet: Detección de archivos de texto multi-codificación
Backends equivalentes a iconv-lite: Utilidades de conversión de codificación de texto multiplataforma
cors: Middleware CORS para servidores de transporte remoto HTTP/SSE
Analizador CLI equivalente a minimist: Análisis de argumentos de línea de comandos para indicadores de inicio
pydantic: Validación estricta de esquema tipado para todos los esquemas de entrada de herramientas MCP
uvicorn / starlette: Tiempo de ejecución del servidor HTTP ASGI para implementaciones de transporte remoto

Licencia

Este proyecto se publica bajo la Licencia Apache 2.0. Consulte el archivo LICENSE ubicado en el directorio raíz del proyecto para conocer los términos y condiciones legales completos de la licencia.

Licencias de Componentes de Terceros

Este proyecto integra múltiples bibliotecas de dependencias de código abierto, incluyendo chardet, Pillow, python-magic y enlaces de Tesseract. Todas las bibliotecas de terceros conservan sus respectivos acuerdos de licencia de código abierto originales y declaraciones de derechos de autor.

Nota importante: No se incluyen artefactos binarios de FFmpeg en esta distribución. Los usuarios finales deben cumplir con los términos de licencia oficiales de FFmpeg por separado si las extensiones de procesamiento de medios se habilitan externamente.

Repositorio y Seguimiento de Problemas

Repositorio Fuente de GitHub: https://github.com/kurtzhi/fsext-mcp-server-python
Informes de Errores y Solicitudes de Funciones: https://github.com/kurtzhi/fsext-mcp-server-python/issues