fsext-mcp-server-typescript

Fsext-MCP-Server(Typescript): Um servidor MCP completo e seguro para operações no sistema de arquivos local, com processamento de imagens integrado, ferramentas de OCR e mídia. Totalmente compatível com a especificação oficial do MCP, fornecendo esquemas padronizados de requisição/resposta, streaming de I/O para arquivos grandes, implantação remota com múltiplos transportes e fluxos robustos de busca e substituição de texto para integração com agentes LLM.

GitHub

Experimente este MCPPatrocinado

Documentação

FsExt-MCP-Server (TypeScript)

Visão Geral

Um servidor Model Context Protocol (MCP) de alto desempenho, seguro e de nível de produção, construído com TypeScript, fornecendo operações abrangentes de sistema de arquivos, pesquisa avançada de texto e substituição, processamento de imagens e recursos de OCR Tesseract. Projetado para integração com agentes LLM, ele oferece validação rigorosa de entrada, estruturas de resposta padronizadas, processamento de grandes arquivos em streaming e suporte a implantação remota com múltiplos transportes.

Este servidor está totalmente em conformidade com a especificação oficial do MCP, suportando integração local stdio, transporte de streaming legado SSE e transporte bidirecional moderno Streamable HTTP, servindo como um backend universal de ferramentas de sistema de arquivos para agentes de IA e sistemas de fluxo de trabalho automatizados.

Recursos Principais

CRUD Completo de Sistema de Arquivos e Gerenciamento de Diretórios: Criação, exclusão, cópia, movimentação, consulta de metadados e verificação de existência completos de arquivos/diretórios. Suporta replicação recursiva de árvore de diretórios completa e operações de movimentação seguras com proteção contra conflitos.
I/O de Arquivos em Streaming para Arquivos Grandes: Implementa leitura de texto segmentada, leitura binária em blocos, sobrescrita e anexação de texto/binário. Evita carregamento completo na memória, suportando perfeitamente o processamento de arquivos grandes na escala de GB.
Pesquisa Avançada de Texto e Substituição no Local: Pesquisa recursiva de conteúdo em todo o diretório, correspondência contextual em arquivo único/múltiplo com linhas de pré-visualização, suporte a expressões regulares, correspondência sem diferenciar maiúsculas/minúsculas e substituição precisa de texto no arquivo com estatísticas de alterações.
Suíte Profissional de Processamento de Imagens: Redimensionamento de imagem de alto desempenho integrado (com bloqueio de proporção), recorte preciso e rotação em ângulo arbitrário baseado em Sharp, cobrindo cenários comuns de edição de imagens.
OCR Tesseract Multiplataforma: Reconhecimento OCR com prioridade WASM, com binário Tesseract local personalizável e caminhos de tessdata, suportando extração de texto multilíngue de imagens sem dependência de instalação de mecanismo local.
Validação Rigorosa de Entrada e Resposta Padronizada: Todos os esquemas de ferramentas habilitam a proibição estrita de propriedades adicionais, com estruturas de resposta de sucesso/erro unificadas para análise consistente e tratamento de erros pelo cliente.
Transportes MCP Multi-Padrão: Suporta nativamente três transportes MCP oficiais: stdio (cliente local), SSE (stream remoto legado), Streamable HTTP (transporte remoto bidirecional moderno).
Segurança Total de Tipos TypeScript: Definições de tipos completas para todos os parâmetros de ferramentas, estruturas de resposta e configurações de transporte, garantindo estabilidade em tempo de execução e facilidade de desenvolvimento.

Início Rápido

Pré-requisitos

Node.js >=22.0.0 <27.0.0

Instalação

Instalação Global (Recomendada para Uso via CLI)

npm install -g fsext-mcp-server

Instalação Local no Projeto

npm install fsext-mcp-server

Comandos de Inicialização

1. Modo Stdio Padrão (Para Claude Desktop / Cursor / Clientes MCP Locais)

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

Assinatura de Stream SSE: http://<host>:<port>/sse
Canal de Requisição do 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 Bidirecional Unificado: http://<host>:<port>/mcp

Comparação de Modos de Transporte

Recurso	Transporte SSE	HTTP Streamable
Arquitetura de Endpoints	Dois endpoints (GET stream + POST mensagem)	Endpoint bidirecional unificado único
Modo de Comunicação	Streaming unidirecional servidor-para-cliente	Streaming bidirecional completo e resposta HTTP padrão
Estabilidade da Conexão	Propenso a inconsistência de sessão	Recuperação automática de sessão, otimizado para alta concorrência
Status da Especificação	Compatível com legado	Padrão MCP oficial mais recente

Exemplo de Configuração do Cliente

Configuração JSON do Cliente MCP (Cursor / Claude Desktop)

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

Especificação de Resposta Global Unificada

Todas as ferramentas MCP adotam uma estrutura de resposta de nível superior consistente para cenários de sucesso e falha, permitindo lógica de análise universal no cliente.

Estrutura Geral

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

Resposta de Sucesso

success: true - O campo info carrega dados de negócios específicos da ferramenta.

Resposta de Erro (Padrão Unificado)

success: false - Todos os erros (falha de I/O, parâmetros inválidos, erro de caminho, exceção em tempo de execução) retornam uma estrutura de erro fixa:

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

Referência Completa de Ferramentas MCP

Todas as ferramentas habilitam a validação estrita additionalProperties: false para rejeitar parâmetros de entrada ilegais, garantindo segurança na invocação.

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

fs_list_directory

Descrição: Escaneia o diretório alvo, retorna lista de caminhos absolutos filtrados, suporta travessia recursiva, filtragem apenas de arquivos e filtragem por sufixo.

Parâmetros:

source_dir (string, obrigatório): Caminho do diretório alvo para escaneamento
recursive (boolean, obrigatório): Habilita escaneamento recursivo de subdiretórios
only_files (boolean, obrigatório): Retorna apenas arquivos, exclui diretórios
file_extension (string, opcional, padrão=""): Filtra arquivos por sufixo especificado

Resposta de Sucesso:

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

fs_copy_directory

Descrição: Copia recursivamente a árvore de diretórios completa, suporta sobrescrita de diretórios alvo existentes.

Parâmetros:

source_dir (string, obrigatório): Caminho do diretório de origem
copy_dest_dir (string, obrigatório): Caminho do diretório de destino
overwrite (boolean, opcional, padrão=false): Limpa e sobrescreve o diretório de destino existente

Resposta de Sucesso:

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

fs_move_directory

Descrição: Move a árvore de diretórios inteira, falha rapidamente se o caminho de destino existir para evitar sobrescrita acidental.

Parâmetros:

source_dir (string, obrigatório): Caminho do diretório de origem
dest_dir (string, obrigatório): Caminho do diretório de destino
overwrite (boolean, opcional, padrão=false): Permite sobrescrever diretório conflitante

Resposta de Sucesso: Objeto de informações vazio com sinalizador de sucesso

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

fs_create_file

Descrição: Cria arquivo vazio ou com conteúdo, cria automaticamente diretórios pai ausentes, suporta múltiplas codificações.

Parâmetros:

file_path (string, obrigatório): Caminho do arquivo alvo
content (string, opcional, padrão=""): Conteúdo de texto inicial
charset (string, opcional, padrão=utf-8): Enum de codificação: utf-8, ucs-2, utf16le, latin1, ascii, base64, hex

Resposta de Sucesso: Objeto de informações vazio com sinalizador de sucesso

fs_delete_file

Descrição: Exclui apenas arquivo regular único; rejeita caminhos de diretório para evitar riscos de exclusão em lote.

Parâmetros:

file_path (string, obrigatório): Caminho do arquivo alvo

Resposta de Sucesso: Objeto de informações vazio com sinalizador de sucesso

fs_copy_file

Descrição: Copia arquivo único com retenção completa de metadados, suporta controle de sobrescrita.

Parâmetros:

source_file_path (string, obrigatório): Caminho do arquivo de origem
dest_file_path (string, obrigatório): Caminho do arquivo de destino
overwrite (boolean, opcional, padrão=false): Sobrescreve arquivo de destino existente

Resposta de Sucesso: Objeto de informações vazio com sinalizador de sucesso

fs_move_file

Descrição: Move arquivo único com comportamento de sobrescrita configurável.

Parâmetros:

source_file_path (string, obrigatório): Caminho do arquivo de origem
dest_file_path (string, obrigatório): Caminho do arquivo de destino
overwrite (boolean, opcional, padrão=false): Sobrescreve arquivo conflitante

Resposta de Sucesso: Objeto de informações vazio com sinalizador de sucesso

fs_get_file_info

Descrição: Obtém metadados completos de arquivo/diretório, suporta cálculo opcional de digest SHA-256.

Parâmetros:

file_path (string, obrigatório): Caminho da entrada alvo
calc_digest (boolean, opcional, padrão=false): Calcula hash SHA-256

Resposta de Sucesso:

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

Descrição: Verificação leve de existência de arquivo ou diretório.

Parâmetros:

file_path (string, obrigatório): Caminho alvo

Resposta de Sucesso:

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

3. Ferramentas de Leitura e Escrita de Arquivo

fs_read_full_text

Descrição: Lê o conteúdo de texto completo do arquivo alvo com codificação especificada.

Parâmetros:

file_path (string, obrigatório): Caminho do arquivo alvo
charset (string, opcional, padrão=utf-8): Suporte a múltiplas codificações

Resposta de Sucesso:

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

fs_read_text_range

Descrição: Leitura de texto segmentada para arquivos grandes, suporta pular linhas iniciais e limitar linhas lidas.

Parâmetros:

file_path (string, obrigatório): Caminho do arquivo alvo
lines_to_skip (integer, obrigatório): Número de linhas iniciais a pular
max_lines_to_read (integer, obrigatório): Número máximo de linhas a ler
line_separator (string, opcional, padrão="\n"): Caractere de quebra de linha
charset (string, opcional, padrão=utf-8): Codificação do arquivo

Resposta de Sucesso:

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

fs_read_binary_chunk

Descrição: Leitura binária em blocos, retorna dados codificados em Base64 para transmissão segura pela rede, suporta detecção de fim de stream.

Parâmetros:

file_path (string, obrigatório): Caminho do arquivo alvo
bytes_to_skip (integer, obrigatório): Bytes iniciais a pular
max_bytes_to_read (integer, obrigatório): Número máximo de bytes a ler

Resposta de Sucesso:

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

fs_write_text

Descrição: Escreve conteúdo de texto em arquivo, suporta modo de sobrescrita ou anexação.

Parâmetros:

file_path (string, obrigatório): Caminho do arquivo alvo
text (string, obrigatório, minLength=1): Conteúdo de texto a escrever
append (boolean, opcional, padrão=false): Alternância de modo de anexação
charset (string, opcional, padrão=utf-8): Codificação do arquivo

Resposta de Sucesso: Objeto de informações vazio com sinalizador de sucesso

fs_write_binary

Descrição: Escreve dados binários decodificados de Base64 em arquivo, suporta operação de anexação.

Parâmetros:

file_path (string, obrigatório): Caminho do arquivo alvo
base64_data (string, obrigatório, minLength=1): Dados binários codificados em Base64
append (boolean, opcional, padrão=false): Alternância de modo de anexação

Resposta de Sucesso: Objeto de informações vazio com sinalizador de sucesso

4. Ferramentas de Pesquisa e Substituição

fs_search_files_by_content

Descrição: Escaneia recursivamente o diretório, retorna todos os caminhos de arquivo que contêm o conteúdo alvo, suporta regex, ignorar maiúsculas/minúsculas, filtro de sufixo.

Parâmetros:

dir_path (string, obrigatório): Diretório raiz de escaneamento
recursive (boolean, obrigatório): Habilita escaneamento recursivo
search_term (string, obrigatório): Palavra-chave de pesquisa ou padrão regex
is_regex (boolean, opcional, padrão=false): Habilita correspondência regex
ignore_case (boolean, opcional, padrão=true): Correspondência sem diferenciar maiúsculas/minúsculas
file_extension (string, opcional, padrão=""): Filtro de sufixo de arquivo
charset (string, opcional, padrão=utf-8): Codificação do arquivo

fs_search_in_files_by_content

Descrição: Correspondência de conteúdo em múltiplos arquivos, retorna resultados estruturados com linhas de contexto personalizáveis e limite de resultados.

Parâmetros:

dir_path (string, obrigatório): Diretório raiz de escaneamento
recursive (boolean, obrigatório): Habilita escaneamento recursivo
search_term (string, obrigatório): Palavra-chave/regex de pesquisa
limit (integer, obrigatório): Número máximo de resultados correspondentes
is_regex (boolean, opcional, padrão=false): Habilita regex
ignore_case (boolean, opcional, padrão=true): Ignorar maiúsculas/minúsculas
lines_before (integer, opcional, padrão=0): Linhas de contexto anteriores
lines_after (integer, opcional, padrão=0): Linhas de contexto posteriores
file_extension (string, opcional, padrão=""): Filtro de sufixo
charset (string, opcional, padrão=utf-8): Codificação do arquivo

Resposta de Sucesso:

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

Descrição: Busca precisa de conteúdo em arquivo único com pré-visualização de contexto por linha.

Parâmetros: Semelhante à busca em múltiplos arquivos, entrada de caminho de arquivo único

Resposta de Sucesso: Resultados estruturados de correspondência em arquivo único

fs_file_replace

Descrição: Substituição de texto no local em arquivo único, retorna o total de substituições realizadas.

Parâmetros:

file_path (string, obrigatório): Caminho do arquivo de destino
search_term (string, obrigatório): Texto a ser substituído
replacement (string, obrigatório): Novo texto de substituição
line_separator (string, opcional, padrão="\n"): Separador de quebra de linha

Resposta de Sucesso:

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

5. Ferramentas de Processamento de Imagem

fs_image_resize

Descrição: Redimensiona imagem com suporte a bloqueio de proporção, gera novo arquivo de imagem de saída.

Parâmetros:

source_path (string, obrigatório): Caminho da imagem de origem
dest_path (string, obrigatório): Caminho da imagem de saída
width (inteiro, obrigatório, >0): Largura alvo
height (inteiro, obrigatório, >0): Altura alvo
keep_aspect_ratio (booleano, opcional, padrão=true): Bloquear proporção original

Resposta de Sucesso: Objeto de informação vazio com sinalizador de sucesso

fs_image_crop

Descrição: Recorta região retangular especificada da imagem de origem e exporta novo arquivo.

Parâmetros:

source_path (string, obrigatório): Caminho da imagem de origem
dest_path (string, obrigatório): Caminho da imagem de saída
x (inteiro, obrigatório, ≥0): Coordenada X inicial do recorte
y (inteiro, obrigatório, ≥0): Coordenada Y inicial do recorte
width (inteiro, obrigatório, >0): Largura da região de recorte
height (inteiro, obrigatório, >0): Altura da região de recorte

Resposta de Sucesso: Objeto de informação vazio com sinalizador de sucesso

fs_image_rotate

Descrição: Rotaciona imagem no sentido horário por graus arbitrários, expande automaticamente a tela para preservar o conteúdo completo.

Parâmetros:

source_path (string, obrigatório): Caminho da imagem de origem
dest_path (string, obrigatório): Caminho da imagem de saída
degrees (número, obrigatório): Ângulo de rotação no sentido horário

Resposta de Sucesso: Objeto de informação vazio com sinalizador de sucesso

6. Ferramenta de OCR

fs_ocr_extract_text

Descrição: Extrai texto de imagens via Tesseract OCR, com suporte a runtime WASM (sem mecanismo local) e caminho binário local personalizado.

Parâmetros:

image_path (string, obrigatório): Caminho da imagem de destino
tesseract_bin_path (string, opcional, padrão=""): Caminho personalizado do executável Tesseract
tessdata_path (string, opcional, padrão=""): Caminho personalizado do recurso de idioma tessdata
lang (string, opcional, padrão eng): Prefixo do idioma de reconhecimento

Resposta de Sucesso:

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

Compilação e Desenvolvimento do Projeto

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

Dependências

Dependências Principais de Runtime

fastmcp: Framework oficial de runtime do servidor MCP
sharp: Mecanismo de processamento de imagem de alto desempenho
tesseract.js: Mecanismo de OCR multiplataforma baseado em WASM
winston: Sistema de registro padrão
zod: Validação estrita de esquema para parâmetros de ferramentas
chardet / iconv-lite: Detecção e conversão de múltiplas codificações
cors: Suporte a compartilhamento de recursos entre origens para transporte HTTP
minimist: Análise de parâmetros de linha de comando

Licença

Este projeto é de código aberto sob a Apache License 2.0. Consulte o arquivo LICENSE na raiz do projeto para obter os detalhes completos da licença.

Repositório e Problemas

GitHub: https://github.com/kurtzhi/fsext-mcp-server-typescript
Problemas: Relatar bugs ou solicitar recursos