fsext-mcp-server-python

Um servidor MCP completo e seguro para operações no sistema de arquivos local, com processamento de imagem integrado, OCR e ferramentas de mídia.

GitHubExperimente este MCPPatrocinado

Documentação

FsExt-MCP-Server (Python)

Visão Geral

Um servidor MCP seguro e completo para operações locais de sistema de arquivos, com ferramentas integradas de processamento de imagens, OCR e mídia. Totalmente compatível com a especificação oficial do Model Context Protocol, oferecendo esquemas padronizados de requisição/resposta, I/O de streaming para arquivos grandes, implantação remota multi-transporte e funcionalidade abrangente de busca e substituição de texto para integração com agentes LLM.

Funcionalidades Principais

Gerenciamento Completo de Arquivos e Diretórios: Suporte para criação, exclusão, cópia, movimentação, consulta de metadados e verificação de existência de arquivos; cópia e movimentação recursiva de árvores de diretórios com controles de segurança contra sobrescrita.
Leitura/Escrita de Arquivos em Streaming: Integra leitura de texto completo, leitura de texto segmentada por linhas, leitura binária em blocos, sobrescrita de texto/binário e escrita por anexação, otimizadas para evitar carregar arquivos grandes inteiros na memória.
Busca e Substituição Poderosas: Suporte para busca recursiva de conteúdo em arquivos em todo o diretório, correspondência contextual em arquivos únicos/múltiplos com linhas de pré/pós-correspondência configuráveis, correspondência por expressões regulares, busca sem diferenciar maiúsculas de minúsculas e substituição de texto no local com estatísticas de contagem de correspondências.
Ferramentas de Processamento de Imagens: Kit de ferramentas de imagem de alto desempenho integrado, alimentado por Pillow, incluindo redimensionamento (com bloqueio de proporção + suporte a preenchimento de tela), recorte e rotação em sentido horário em ângulo arbitrário.
Reconhecimento OCR Nativo com Tesseract: Extração confiável de texto de imagens, dependente da instalação local do binário Tesseract. Sem fallback WASM; um argumento de caminho binário vazio não acionará mecanismos OCR alternativos baseados em JS. Suporte a múltiplos recursos de idioma tessdata com caminhos de binário e dados configuráveis.
Validação Estrita de Entrada e Formato de Resposta Unificado: Cada ferramenta habilita validação estrita de esquema additionalProperties: false para bloquear campos de entrada inesperados. Todas as operações compartilham uma estrutura universal de encapsulamento de sucesso/erro para análise consistente pelo cliente.
Suporte Multi-Transporte: Compatível com os transportes MCP padrão oficiais: stdio (integração com clientes desktop locais), sse (stream remoto leve legado) e Streamable HTTP (transporte moderno de streaming remoto bidirecional).
Isolamento de Segurança do Workspace: Fornece capacidade de restrição de diretório --lock-root. Todas as operações de arquivo/diretório são estritamente confinadas ao diretório raiz do workspace especificado para prevenir ataques não autorizados de escape de caminho entre diretórios.

Início Rápido: Execute diretamente com uvx (Sem pré-instalação necessária)

uvx baixa automaticamente o pacote PyPI publicado e inicia um ambiente de execução isolado, eliminando a necessidade de instalação manual de dependências ou configuração de ambiente virtual.

1. Comandos básicos de inicialização com uvx

Comando curto (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. Integre as ferramentas FsExt com frameworks LLM

Sem pré-implantação necessária em máquinas host; uvx instancia dinamicamente o servidor quando um cliente MCP estabelece uma conexão.

Exemplo de configuração do cliente (Claude Desktop / Cursor MCP json)

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

Trecho de integração com LangChain / LangGraph core

Existem limitações de ciclo de vida de sessão dentro do langchain-mcp-adapters oficial; a lógica completa de conexão estável de longa duração requer adaptação adicional personalizada. Abaixo está o modelo mínimo padrão de conexão:

# 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)

Instalação tradicional e inicialização via pip

Instalar pacote PyPI publicado

pip install fsext-mcp-server

Comandos de inicialização após instalação via 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

Configuração de desenvolvimento com repositório de código-fonte local

Recomenda-se usar uv para implantação de ambiente rápida e determinística:

# 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

Descrição das Dependências Principais de Runtime

chardet: Detecção automática de codificação de arquivos de texto
Pillow: Backend principal de processamento de imagens para pipelines de redimensionamento, recorte e rotação
python-magic: Identificação precisa de tipo MIME de arquivos entre plataformas
fastmcp: Framework oficial de servidor MCP Python
uvicorn / starlette: Runtime do servidor de transporte HTTP/SSE
pydantic: Validação estrita de esquema para todos os parâmetros de entrada das ferramentas
tesseract: Bindings nativos para o binário OCR Tesseract local

Uso de Inicialização

O servidor suporta três modos de transporte MCP oficiais e configuração flexível de isolamento da raiz do workspace via flags de CLI.

Tabela de Referência de Parâmetros de Inicialização

Parâmetro	Valor Padrão	Descrição
`--transport`	stdio	Tipo de transporte MCP: `stdio` / `sse` / `http`
`--host`	127.0.0.1	Endereço de bind de rede (ignorado no transporte stdio)
`--port`	8000	Porta de bind do serviço (ignorada no transporte stdio)
`--lock-root`	None	Restringe todas as operações do sistema de arquivos a este diretório raiz; acesso total irrestrito se omitido

Comandos Comuns de Inicialização em Produção

1. Modo Stdio Local Padrão (para clientes Claude Desktop / Cursor AI)

uv run -m fsext

2. Modo Stdio com Bloqueio Obrigatório do Workspace (Uso Seguro com Agentes Locais)

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

Endpoints de Acesso

Canal de assinatura de stream de longa duração SSE (push de eventos do servidor): http://<host>:<port>/sse
Canal de envio de requisições JSON-RPC do cliente: http://<host>:<port>/messages

Configuração de Conexão do MCP Inspector

Tipo de transporte: SSE
Entrada do endereço de conexão: http://127.0.0.1:8000/sse

4. Transporte Remoto HTTP Streamable Padrão (Bidirecional Moderno)

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

Endpoint de Acesso Bidirecional Unificado

Ponto de entrada único compartilhado para requisições do cliente e streaming do servidor: http://<host>:<port>/mcp

Configuração de Conexão do MCP Inspector

Tipo de transporte: Streamable HTTP
Entrada do endereço de conexão: http://127.0.0.1:8000/mcp

5. Comparação de Recursos de Transporte SSE vs Streamable HTTP

Recurso	Transporte SSE de Dois Endpoints	Transporte Streamable HTTP de Endpoint Único
Arquitetura de Endpoints	Dois endpoints separados: assinatura de stream GET + envio de mensagens POST	URL única unificada lida com todo o tráfego bidirecional
Padrão de Comunicação	Apenas push unidirecional de eventos servidor-para-cliente	Capacidade híbrida completa de requisição/stream bidirecional
Confiabilidade da Conexão	Perdas de sessão frequentes, gerenciamento complexo de estado entre endpoints	Recuperação automática de sessão, otimizado para conexões remotas de alta concorrência
Status da Especificação Oficial	Implementação legada compatível, não recomendado para novas implantações	Padrão MCP oficial atual para integrações de rede remotas

Especificação Global Unificada de Resposta

Todas as ferramentas MCP compartilham uma estrutura JSON de encapsulamento de nível superior idêntica para estados de execução bem-sucedidos e de falha em runtime. O payload de negócios de cada ferramenta está aninhado dentro do sub-objeto info sob o campo raiz res.

Definição da Estrutura Principal

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

success: Flag de status global da operação
- true: A lógica da ferramenta foi executada sem exceções; info contém dados de retorno específicos da ferramenta
- false: A operação falhou (bloqueio de escape do workspace, arquivo ausente, erro de I/O, esquema de entrada inválido, permissão negada, etc.)
Comportamento duplo do campo info:
1. Modo de sucesso (success: true): Payload de negócios estruturado personalizado exclusivo de cada ferramenta
2. Modo de falha (success: false): Objeto de erro padronizado fixo com código de erro legível por máquina e explicação legível por humanos
```
"info": {
  "code": "ERROR_CODE_IDENTIFIER",
  "message": "Detailed human-readable failure description"
}
```

Exemplos Completos de Respostas

1. Exemplo de Resposta de Sucesso (fs_list_directory)

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

2. Exemplo de Resposta de Falha (Restrição de Escape de Caminho do Workspace)

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

Todas as ferramentas aplicam isolamento da raiz do workspace e seguem totalmente os esquemas padronizados de entrada/saída listados abaixo.

Referência Completa de Ferramentas MCP

Todos os esquemas de entrada das ferramentas habilitam validação estrita additionalProperties: false para rejeitar parâmetros não reconhecidos e prevenir vetores maliciosos de injeção de caminho.

1. Ferramentas de Operação de Diretório

fs_list_directory

Descrição: Escaneia o diretório alvo recursivamente ou superficialmente, retorna lista filtrada de caminhos absolutos do sistema de arquivos com controles de filtragem por tipo de arquivo e extensão. Parâmetros:

source_dir (string, obrigatório): Caminho do diretório raiz para escaneamento
recursive (booleano, obrigatório): Habilita travessia recursiva completa de todos os subdiretórios
only_files (booleano, obrigatório): Filtra a saída para retornar apenas arquivos regulares, exclui diretórios
file_extension (string, opcional, padrão=""): Filtra resultados para arquivos que correspondem à extensão de sufixo especificada Payload de Resposta de Sucesso:

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

fs_copy_directory

Descrição: Copia recursivamente uma árvore de diretórios inteira, com comportamento de sobrescrita configurável para diretórios alvo pré-existentes. Parâmetros:

source_dir (string, obrigatório): Caminho da árvore de diretórios de origem
copy_dest_dir (string, obrigatório): Caminho do diretório de saída alvo
overwrite (booleano, opcional, padrão=false): Limpa e sobrescreve o conteúdo do diretório de destino existente Payload de Resposta de Sucesso:

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

fs_move_directory

Descrição: Move atomicamente uma árvore de diretórios inteira para um novo caminho alvo. Falha imediatamente se o destino existir, a menos que a sobrescrita seja explicitamente habilitada para evitar perda acidental de dados. Parâmetros:

source_dir (string, obrigatório): Caminho do diretório de origem
dest_dir (string, obrigatório): Caminho do diretório alvo
overwrite (booleano, opcional, padrão=false): Permite sobrescrever diretórios de destino conflitantes Payload de Resposta de Sucesso: Encapsulamento de objeto info vazio com flag de sucesso.

2. Ferramentas Básicas de Operação de Arquivo Único

fs_create_file

Descrição: Cria um novo arquivo de texto, gera automaticamente diretórios pai ausentes, suporta codificação de texto configurável e conteúdo inicial do arquivo. Parâmetros:

file_path (string, obrigatório): Caminho absoluto do arquivo alvo
content (string, opcional, padrão=""): Conteúdo de texto inicial gravado no novo arquivo
charset (string, opcional, padrão="utf-8"): Valor enum de codificação de texto (lista completa de conjuntos de caracteres abaixo) Valores Enum de Conjuntos de Caracteres Suportados: utf-8, utf-16, latin-1, iso-8859-1, cp1252, Windows-1252, gbk, gb2312, shift_jis, euc_jp, euc_kr Payload de Resposta de Sucesso: Encapsulamento de objeto info vazio com flag de sucesso.

fs_delete_file

Descrição: Exclui permanentemente um único arquivo regular; rejeita entradas de caminho de diretório para bloquear riscos de exclusão recursiva em massa. Parâmetros:

file_path (string, obrigatório): Caminho absoluto do arquivo regular alvo Payload de Resposta de Sucesso: Encapsulamento de objeto info vazio com flag de sucesso.

fs_copy_file

Descrição: Copia um único arquivo retendo os metadados originais do sistema de arquivos, com sobrescrita configurável para arquivos alvo conflitantes. Parâmetros:

source_file_path (string, obrigatório): Caminho absoluto do arquivo de origem
dest_file_path (string, obrigatório): Caminho absoluto do arquivo de saída alvo
overwrite (booleano, opcional, padrão=false): Sobrescreve arquivo de destino pré-existente Payload de Resposta de Sucesso: Encapsulamento de objeto info vazio com flag de sucesso.

fs_move_file

Descrição: Move atomicamente um único arquivo para um novo caminho absoluto, com comportamento de sobrescrita configurável para arquivos de destino conflitantes. Parâmetros:

source_file_path (string, obrigatório): Caminho absoluto do arquivo de origem
dest_file_path (string, obrigatório): Caminho absoluto do arquivo alvo
overwrite (booleano, opcional, padrão=false): Permite sobrescrever arquivos de destino conflitantes Payload de Resposta de Sucesso: Encapsulamento de objeto info vazio com flag de sucesso.

fs_get_file_info

Descrição: Recupera metadados completos de arquivos ou diretórios, com cálculo opcional de digest criptográfico SHA-256 para verificação de integridade. Parâmetros:

file_path (string, obrigatório): Caminho absoluto da entrada do sistema de arquivos
calc_digest (booleano, opcional, padrão=false): Calcula o hash SHA-256 do conteúdo do arquivo Payload de Resposta de Sucesso:

{
  "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

Descrição: Verificação leve de existência para qualquer entrada do sistema de arquivos (arquivo ou diretório) sem carregar metadados completos. Parâmetros:

file_path (string, obrigatório): Caminho absoluto alvo a ser verificado Payload de Resposta de Sucesso:

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

3. Ferramentas de Leitura e Escrita de Arquivos

fs_read_full_text

Descrição: Lê o conteúdo de texto completo de um arquivo alvo com codificação de texto especificada pelo usuário. Parâmetros:

file_path (string, obrigatório): Caminho absoluto do arquivo de texto alvo
charset (string, opcional, padrão="utf-8"): Valor enum de codificação de texto Payload de Resposta de Sucesso:

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

fs_read_text_range

Descrição: Leitura de texto segmentada em fluxo otimizada para arquivos grandes; pula linhas iniciais e limita o total de linhas lidas para evitar sobrecarga de memória. Parâmetros:

file_path (string, obrigatório): Caminho absoluto do arquivo de texto alvo
lines_to_skip (inteiro, obrigatório, mínimo=0): Número de linhas iniciais a pular durante a leitura
max_lines_to_read (inteiro, obrigatório, mínimo=0): Máximo total de linhas a extrair do arquivo
line_separator (string, opcional, padrão="\n"): Caractere delimitador de quebra de linha
charset (string, opcional, padrão="utf-8"): Valor enum de codificação de texto Payload de Resposta de Sucesso:

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

fs_read_binary_chunk

Descrição: Leitura em fluxo segmentada para arquivos binários; retorna payloads de bytes codificados em Base64 para transmissão segura via JSON-RPC em rede com detecção de marcador de fim de fluxo. Parâmetros:

file_path (string, obrigatório): Caminho absoluto do arquivo binário alvo
bytes_to_skip (inteiro, obrigatório, mínimo=0): Número de bytes iniciais a pular antes de ler o segmento
max_bytes_to_read (inteiro, obrigatório, mínimo=0): Comprimento máximo de bytes a ler em um único segmento Payload de Resposta de Sucesso:

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

fs_write_text

Descrição: Escreve conteúdo de texto codificado em UTF ou múltiplas codificações no arquivo alvo, suportando modos de sobrescrita completa ou somente anexação. Parâmetros:

file_path (string, obrigatório): Caminho absoluto do arquivo de saída alvo
text (string, obrigatório, comprimentoMínimo=1): Conteúdo de texto bruto a persistir
append (booleano, opcional, padrão=false): Sinalizador de modo anexar (false = sobrescrever arquivo inteiro)
charset (string, opcional, padrão="utf-8"): Valor enum de codificação de texto Payload de Resposta de Sucesso: Invólucro de objeto info vazio com sinalizador de sucesso.

fs_write_binary

Descrição: Decodifica payload binário codificado em Base64 e escreve bytes brutos no arquivo alvo, suportando modo anexar para uploads binários em múltiplos segmentos. Parâmetros:

file_path (string, obrigatório): Caminho absoluto do arquivo de saída alvo
base64_data (string, obrigatório, comprimentoMínimo=1): Payload de bytes binários brutos codificado em Base64
append (booleano, opcional, padrão=false): Anexa dados binários ao final do arquivo (false = sobrescrever) Payload de Resposta de Sucesso: Invólucro de objeto info vazio com sinalizador de sucesso.

4. Ferramentas de Busca de Conteúdo e Substituição no Local

fs_search_files_by_content

Descrição: Escaneia recursivamente a árvore de diretórios e retorna caminhos absolutos de todos os arquivos contendo o padrão de texto alvo correspondente; suporta correspondência regex, insensibilidade a maiúsculas/minúsculas e filtragem por extensão de arquivo. Parâmetros:

dir_path (string, obrigatório): Diretório raiz para escaneamento recursivo de conteúdo
recursive (booleano, obrigatório): Habilita recursão completa em subdiretórios
search_term (string, obrigatório): Palavra-chave de texto simples ou padrão de expressão regular
is_regex (booleano, opcional, padrão=false): Trata termo_de_busca como padrão regex quando verdadeiro
ignore_case (booleano, opcional, padrão=true): Correspondência de padrão insensível a maiúsculas/minúsculas
file_extension (string, opcional, padrão=""): Filtra arquivos escaneados por sufixo de extensão
charset (string, opcional, padrão="utf-8"): Valor enum de codificação de texto para análise de arquivos

fs_search_in_files_by_content

Descrição: Correspondência de conteúdo em massa em múltiplos diretórios, retorna resultados de correspondência estruturados com linhas de contexto anteriores e posteriores configuráveis ao redor do conteúdo correspondente, além de limitação global da contagem de resultados. Parâmetros:

dir_path (string, obrigatório): Caminho absoluto do diretório raiz para escaneamento
recursive (booleano, obrigatório): Habilita travessia recursiva completa em subdiretórios
search_term (string, obrigatório): Palavra-chave de busca ou padrão regex
limit (inteiro, obrigatório): Limite máximo rígido no total de entradas correspondentes retornadas
is_regex (booleano, opcional, padrão=false): Habilita correspondência com expressões regulares
ignore_case (booleano, opcional, padrão=true): Desabilita correspondência sensível a maiúsculas/minúsculas
lines_before (inteiro, opcional, padrão=0): Número de linhas de contexto anteriores a cada linha correspondente
lines_after (inteiro, opcional, padrão=0): Número de linhas de contexto posteriores a cada linha correspondente
file_extension (string, opcional, padrão=""): Filtra arquivos escaneados por sufixo de extensão
charset (string, opcional, padrão="utf-8"): Valor enum de codificação de texto para análise de arquivos Payload de Resposta de Sucesso:

{
  "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

Descrição: Busca de conteúdo de precisão em arquivo único, retorna segmentos correspondentes estruturados com linhas de contexto pré/pós configuráveis para fluxos de trabalho de inspeção de código e documentos. Parâmetros:

file_path (string, obrigatório): Caminho absoluto do arquivo único alvo
search_term (string, obrigatório): Palavra-chave de busca ou padrão regex
is_regex (booleano, opcional, padrão=false): Habilita lógica de correspondência com expressões regulares
ignore_case (booleano, opcional, padrão=true): Alternância de correspondência insensível a maiúsculas/minúsculas
lines_before (inteiro, opcional, padrão=0): Linhas de contexto anteriores para cada correspondência
lines_after (inteiro, opcional, padrão=0): Linhas de contexto subsequentes para cada correspondência
charset (string, opcional, padrão="utf-8"): Valor enum de codificação de texto para análise de arquivos Payload de Resposta de Sucesso: Matriz estruturada de objetos de correspondência de linha idêntica ao formato de saída de busca em múltiplos arquivos.

fs_file_replace

Descrição: Executa substituição global de texto no local dentro de um único arquivo alvo; retorna a contagem total de segmentos de texto correspondentes e substituídos após a escrita. Parâmetros:

file_path (string, obrigatório): Caminho absoluto do arquivo editável alvo
search_term (string, obrigatório): Substring de texto a localizar e substituir
replacement (string, obrigatório): Novo payload de texto de substituição
line_separator (string, opcional, padrão="\n"): Delimitador de quebra de linha para análise de arquivos Payload de Resposta de Sucesso:

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

5. Ferramentas de Processamento de Imagens

fs_image_resize

Descrição: Redimensiona a imagem de origem para as dimensões de largura/altura especificadas, com suporte nativo para preservação da proporção e preenchimento de tela para preencher exatamente as dimensões de resolução alvo. Parâmetros:

source_path (string, obrigatório): Caminho absoluto da imagem de entrada de origem
dest_path (string, obrigatório): Caminho absoluto da imagem de saída redimensionada
width (inteiro, obrigatório, mínimoExclusivo=0): Dimensão de largura em pixels alvo
height (inteiro, obrigatório, mínimoExclusivo=0): Dimensão de altura em pixels alvo
keep_aspect_ratio (booleano, opcional, padrão=true): Bloqueia a proporção da imagem original durante o redimensionamento
pad_to_target (booleano, opcional, padrão=true): Adiciona preenchimento transparente para preencher exatamente a largura/altura alvo quando a proporção está bloqueada Payload de Resposta de Sucesso: Invólucro de objeto info vazio com sinalizador de sucesso.

fs_image_crop

Descrição: Extrai uma região retangular de pixels da imagem de origem e exporta como um arquivo de imagem de saída independente. Parâmetros:

source_path (string, obrigatório): Caminho absoluto da imagem de entrada de origem
dest_path (string, obrigatório): Caminho absoluto da imagem de saída recortada
x (inteiro, obrigatório, mínimo=0): Coordenada de pixel esquerda da origem da região de recorte
y (inteiro, obrigatório, mínimo=0): Coordenada de pixel superior da origem da região de recorte
width (inteiro, obrigatório, mínimoExclusivo=0): Largura em pixels da região retangular recortada
height (inteiro, obrigatório, mínimoExclusivo=0): Altura em pixels da região retangular recortada Payload de Resposta de Sucesso: Invólucro de objeto info vazio com sinalizador de sucesso.

fs_image_rotate

Descrição: Rotaciona a imagem de origem no sentido horário por valores arbitrários de graus em ponto flutuante; expande automaticamente as dimensões da tela de saída para reter o conteúdo completo da imagem sem cortar bordas. Parâmetros:

source_path (string, obrigatório): Caminho absoluto da imagem de entrada de origem
dest_path (string, obrigatório): Caminho absoluto da imagem de saída rotacionada
degrees (número, obrigatório): Ângulo de rotação no sentido horário em graus Payload de Resposta de Sucesso: Invólucro de objeto info vazio com sinalizador de sucesso.

6. Ferramenta de Extração de Texto OCR

fs_ocr_extract_text

Descrição: Extrai texto legível por humanos de arquivos de imagem raster via instalação binária local do Tesseract OCR. Não existe implementação de fallback JavaScript WASM; um argumento tesseract_bin_path vazio não inicializará mecanismos OCR alternativos baseados na web. Parâmetros:

image_path (string, obrigatório): Caminho absoluto da imagem de entrada para reconhecimento de texto
tesseract_bin_path (string, opcional, padrão=""): Caminho absoluto para o binário executável local do Tesseract; valor vazio usa apenas a busca no PATH do sistema
tessdata_path (string, opcional, padrão=""): Caminho absoluto do diretório contendo os arquivos de dados de treinamento de idioma do Tesseract
lang (string, opcional, padrão="eng"): Prefixo do código de idioma correspondente aos arquivos de treinamento tessdata disponíveis Payload de Resposta de Sucesso:

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

Scripts de Desenvolvimento e Build do Projeto

Todos os scripts de desenvolvimento uv padronizados equivalentes ao npm para contribuidores do repositório de origem:

# 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

Dependências Principais de Runtime

fastmcp: Framework oficial de runtime do servidor MCP Python
Pillow: Backend de processamento de imagens multiplataforma para pipelines de redimensionamento, recorte e rotação
tesseract: Bindings Python nativos para o binário local do Tesseract OCR
chardet: Detecção de codificação de arquivos de texto múltipla
Backends equivalentes ao iconv-lite: Utilitários de conversão de codificação de texto multiplataforma
cors: Middleware CORS para servidores de transporte remoto HTTP/SSE
Parser CLI equivalente ao minimist: Análise de argumentos de linha de comando para sinalizadores de inicialização
pydantic: Validação estrita de esquema tipado para todos os esquemas de entrada de ferramentas MCP
uvicorn / starlette: Runtime de servidor HTTP ASGI para implantações de transporte remoto

Licença

Este projeto é de código aberto sob a Apache License 2.0. Consulte o arquivo LICENSE localizado no diretório raiz do projeto para os termos e condições legais completos da licença.

Licenças de Componentes de Terceiros

Este projeto integra múltiplas bibliotecas de dependências de código aberto, incluindo chardet, Pillow, python-magic e bindings do Tesseract. Todas as bibliotecas de terceiros mantêm seus respectivos acordos de licença de código aberto originais e declarações de direitos autorais.

Nota Importante: Nenhum artefato binário do FFmpeg está incluído nesta distribuição. Os usuários finais devem cumprir os termos de licenciamento oficiais do FFmpeg separadamente se extensões de processamento de mídia forem habilitadas externamente.

Repositório e Rastreamento de Problemas

Repositório de Origem no GitHub: https://github.com/kurtzhi/fsext-mcp-server-python
Relatórios de Bugs e Solicitações de Recursos: https://github.com/kurtzhi/fsext-mcp-server-python/issues