Editor MCP
Um servidor para operações de arquivos, permitindo ler, editar e gerenciar arquivos de texto através de uma API padronizada.
Documentação
Editor MCP
Um servidor de editor de texto baseado em Python, construído com FastMCP, que fornece ferramentas poderosas para operações de arquivos. Este servidor permite ler, editar e gerenciar arquivos de texto por meio de uma API padronizada, com uma abordagem exclusiva de múltiplas etapas que melhora significativamente a precisão e a confiabilidade da edição de código para LLMs e assistentes de IA.
Recursos
- Seleção de Arquivo: Defina um arquivo para trabalhar usando caminhos absolutos
- Operações de Leitura:
- Leia arquivos inteiros com números de linha usando
skim - Leia intervalos específicos de linhas com números de linha prefixados usando
read - Encontre texto específico dentro de arquivos usando
find_line - Encontre e extraia definições de funções em arquivos Python e JavaScript/JSX usando
find_function
- Leia arquivos inteiros com números de linha usando
- Operações de Edição:
- Processo de edição em duas etapas com pré-visualização de diff
- Selecione e sobrescreva texto com verificação de ID
- Fluxo de edição limpo com padrão selecionar → sobrescrever → confirmar/cancelar
- Verificação de sintaxe para arquivos Python (.py) e JavaScript/React (.js, .jsx)
- Crie novos arquivos com conteúdo
- Gerenciamento de Arquivos:
- Crie novos arquivos com inicialização adequada
- Exclua arquivos do sistema de arquivos
- Liste o conteúdo de diretórios com
listdir
- Suporte a Testes:
- Execute testes Python com
run_tests - Defina caminhos Python para resolução adequada de módulos
- Execute testes Python com
- Recursos de Segurança:
- Verificação de ID de conteúdo para evitar conflitos
- Limites de contagem de linhas para evitar esgotamento de recursos
- Verificação de sintaxe para manter a integridade do código
- Caminhos protegidos para restringir o acesso a arquivos sensíveis
Riscos de Segurança
O editor-mcp inclui capacidades poderosas que vêm com certas considerações de segurança:
- Risco de Jailbreak: O editor-mcp pode potencialmente ser "jailbroken" ao ler um arquivo que contém instruções prejudiciais embutidas. Conteúdo malicioso em arquivos sendo editados pode conter instruções que manipulam o assistente de IA.
- Execução Arbitrária de Código: Se a execução de testes estiver habilitada, há risco de execução arbitrária de código por meio de arquivos de teste manipulados ou código Python malicioso.
- Exposição de Dados: O acesso a operações do sistema de arquivos pode potencialmente expor informações sensíveis se proteções de caminho adequadas não forem configuradas.
Para mitigar esses riscos:
- Use a variável de ambiente
PROTECTED_PATHSpara restringir o acesso a arquivos e diretórios sensíveis. - Desative os recursos de execução de testes em ambientes de produção, a menos que seja absolutamente necessário.
- Revise cuidadosamente os arquivos antes de abri-los, especialmente se vierem de fontes não confiáveis.
- Considere executar o editor em um ambiente isolado (sandbox) com permissões limitadas.
Principais Vantagens para LLMs
O design exclusivo deste editor de texto resolve problemas críticos que normalmente afetam a edição de código por LLMs:
-
Evita Perda de Contexto - Abordagens tradicionais frequentemente levam os LLMs a perder a visão geral do código após algumas edições. Esta implementação mantém o contexto por meio do processo de múltiplas etapas.
-
Evita Reescritas que Consomem Recursos - LLMs normalmente tendem a substituir arquivos inteiros quando confusos, o que é caro, lento e ineficiente. Este editor impõe edições seletivas.
-
Fornece Feedback Visual - O sistema de pré-visualização de diff permite que o LLM realmente veja e verifique as alterações antes de confirmá-las, reduzindo drasticamente os erros.
-
Impõe Verificação de Sintaxe - A validação automática para Python e JavaScript/React garante que código quebrado não seja confirmado.
-
Melhora o Raciocínio de Edição - A abordagem de múltiplas etapas dá ao LLM tempo para raciocinar entre as etapas, reduzindo a produção de tokens aleatórios.
Gerenciamento de Recursos
O editor implementa várias salvaguardas para garantir a estabilidade do sistema e evitar o esgotamento de recursos:
- Máximo de Linhas de Edição: Por padrão, o editor impõe um limite de 50 linhas para qualquer operação de edição única
Instalação
Este MCP foi desenvolvido e testado com Claude Desktop. Você pode baixar o Claude Desktop em qualquer plataforma. Para Claude Desktop no Linux, você pode usar um script de instalação não oficial (usa o arquivo oficial), repositório recomendado: https://github.com/emsi/claude-desktop/tree/main
Depois de ter o Claude Desktop instalado, siga as instruções abaixo para instalar este MCP específico:
Instalação Fácil com UVX (Recomendado)
A maneira mais fácil de instalar o Editor MCP é usando o script de instalação fornecido:
# Clone the repository
git clone https://github.com/danielpodrazka/editor-mcp.git
cd editor-mcp
# Run the installation script
chmod +x install.sh
./install.sh
Este script irá:
- Verificar se o UVX está instalado e instalá-lo se necessário
- Instalar o Editor MCP em modo de desenvolvimento
- Tornar o comando
editor-mcpdisponível no seu PATH
Instalação Manual
Usando UVX
# Install directly from GitHub
uvx install git+https://github.com/danielpodrazka/mcp-text-editor.git
# Or install from a local clone
git clone https://github.com/danielpodrazka/mcp-text-editor.git
cd mcp-text-editor
uvx install -e .
Usando pip Tradicional
pip install git+https://github.com/danielpodrazka/mcp-text-editor.git
# Or from a local clone
git clone https://github.com/danielpodrazka/mcp-text-editor.git
cd mcp-text-editor
pip install -e .
Usando Requirements (Legado)
Instale a partir do arquivo de bloqueio:
uv pip install -r uv.lock
Gerando um arquivo de requirements bloqueado:
uv pip compile requirements.in -o uv.lock
Uso
Iniciando o Servidor
Após a instalação, você pode iniciar o servidor Editor MCP usando um destes métodos:
# Using the installed script
editor-mcp
# Or using the Python module
python -m text_editor.server
Configuração do MCP
Você pode adicionar o Editor MCP ao seu arquivo de configuração do MCP:
{
"mcpServers": {
"text-editor": {
"command": "editor-mcp",
"env": {
"MAX_SELECT_LINES": "100",
"ENABLE_JS_SYNTAX_CHECK": "0",
"FAIL_ON_PYTHON_SYNTAX_ERROR": "1",
"FAIL_ON_JS_SYNTAX_ERROR": "0",
"PROTECTED_PATHS": "*.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/.ssh/id_rsa"
}
}
}
}
Configuração de Variáveis de Ambiente
O Editor MCP suporta várias variáveis de ambiente para personalizar seu comportamento:
-
MAX_SELECT_LINES: "100" - Número máximo de linhas que podem ser editadas em uma única operação (padrão é 50)
-
ENABLE_JS_SYNTAX_CHECK: "0" - Ativar/desativar a verificação de sintaxe JavaScript e JSX (padrão é "1" - ativado)
-
FAIL_ON_PYTHON_SYNTAX_ERROR: "1" - Quando ativado, erros de sintaxe Python cancelarão automaticamente a operação de sobrescrita (padrão é ativado)
-
FAIL_ON_JS_SYNTAX_ERROR: "0" - Quando ativado, erros de sintaxe JavaScript/JSX cancelarão automaticamente a operação de sobrescrita (padrão é desativado)
-
PROTECTED_PATHS: Lista separada por vírgulas de padrões de arquivo ou caminhos que não podem ser acessados, com suporte a curingas (ex.: ".env,.env,/etc/passwd")
Exemplo de Configuração do MCP ao Compilar a Partir do Código Fonte
{
"mcpServers": {
"text-editor": {
"command": "/home/daniel/pp/venvs/editor-mcp/bin/python",
"args": ["/home/daniel/pp/editor-mcp/src/text_editor/server.py"],
"env": {
"MAX_SELECT_LINES": "100",
"ENABLE_JS_SYNTAX_CHECK": "0",
"FAIL_ON_PYTHON_SYNTAX_ERROR": "1",
"FAIL_ON_JS_SYNTAX_ERROR": "0",
"PROTECTED_PATHS": "*.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/.ssh/id_rsa"
}
}
}
}
Ferramentas Disponíveis
O Editor MCP fornece 13 ferramentas poderosas para manipulação de arquivos, edição e testes:
1. set_file
Define o arquivo atual para trabalhar.
Parâmetros:
filepath(str): Caminho absoluto para o arquivo
Retorna:
- Mensagem de confirmação com o caminho do arquivo
2. skim
Lê o texto completo do arquivo atual. Cada linha é prefixada com seu número de linha.
Retorna:
- Dicionário contendo linhas com seus números de linha, número total de linhas e a configuração de máximo de linhas de edição
Exemplo de saída:
{
"lines": [
[1, "def hello():"],
[2, " print(\"Hello, world!\")"],
[3, ""],
[4, "hello()"]
],
"total_lines": 4,
"max_select_lines": 50
}
3. read
Lê o texto do arquivo atual da linha inicial até a linha final.
Parâmetros:
start(int): Número da linha inicial (indexação baseada em 1)end(int): Número da linha final (indexação baseada em 1)
Retorna:
- Dicionário contendo linhas com seus números de linha como chaves, juntamente com informações de início e fim de linha
Exemplo de saída:
{
"lines": [
[1, "def hello():"],
[2, " print(\"Hello, world!\")"],
[3, ""],
[4, "hello()"]
],
"start_line": 1,
"end_line": 4
}
4. select
Selecione um intervalo de linhas do arquivo atual para a operação de sobrescrita subsequente.
Parâmetros:
start(int): Número da linha inicial (baseado em 1)end(int): Número da linha final (baseado em 1)
Retorna:
- Dicionário contendo as linhas selecionadas, o intervalo de linhas e o ID para verificação
Nota:
- Esta ferramenta valida a seleção em relação a max_select_lines
- Os detalhes da seleção são armazenados para uso na ferramenta de sobrescrita
- Deve ser usada antes de chamar a ferramenta de sobrescrita
5. overwrite
Prepara a sobrescrita de um intervalo de linhas no arquivo atual com novo texto.
Parâmetros:
new_lines(list): Lista de novas linhas para sobrescrever o intervalo selecionado
Retorna:
- Pré-visualização de diff mostrando as alterações propostas
Nota:
- Este é o primeiro passo em um processo de duas etapas:
- Primeiro chame overwrite() para gerar uma pré-visualização de diff
- Depois chame confirm() para aplicar ou cancel() para descartar as alterações pendentes
- Esta ferramenta permite substituir as linhas previamente selecionadas por novo conteúdo
- O número de novas linhas pode diferir da seleção original
- Para arquivos Python (extensão .py), a verificação de sintaxe é realizada antes da escrita
- Para arquivos JavaScript/React (extensões .js, .jsx), a verificação de sintaxe é opcional e pode ser desativada via variável de ambiente
ENABLE_JS_SYNTAX_CHECK
6. confirm
Aplica as alterações pendentes da operação de sobrescrita.
Retorna:
- Resultado da operação com status e mensagem
Nota:
- Esta é uma das duas ações possíveis na segunda etapa do processo de edição
- A seleção é removida após a aplicação bem-sucedida das alterações
7. cancel
Descarta as alterações pendentes da operação de sobrescrita.
Retorna:
- Resultado da operação com status e mensagem
Nota:
- Esta é uma das duas ações possíveis na segunda etapa do processo de edição
- A seleção permanece intacta quando as alterações são canceladas
8. delete_file
Exclui o arquivo atualmente definido.
Retorna:
- Resultado da operação com status e mensagem
9. new_file
Cria um novo arquivo e o define automaticamente como o arquivo atual para operações subsequentes.
Parâmetros:
filepath(str): Caminho do novo arquivo
Retorna:
- Resultado da operação com status, mensagem e informações de seleção
- A primeira linha é automaticamente selecionada para edição
Comportamento:
- Cria automaticamente diretórios pai se não existirem
- Define o arquivo recém-criado como o arquivo de trabalho atual
- A primeira linha é pré-selecionada, pronta para edição imediata
Nota sobre Arquivos Protegidos:
- Arquivos que correspondem a certos padrões (como
*.env) podem ser criados normalmente - No entanto, depois que você mudar para outro arquivo, esses arquivos protegidos não podem ser reabertos
- Isso permite um fluxo de trabalho "escrever uma vez, proteger depois" para arquivos de configuração sensíveis
- Exemplo: Você pode criar
config.env, preenchê-lo com configuração de exemplo, mas não pode reabri-lo depois
Nota:
- Esta ferramenta falhará se o arquivo atual existir e não estiver vazio
10. find_line
Encontra linhas que correspondem ao texto fornecido no arquivo atual.
Parâmetros:
search_text(str): Texto a ser pesquisado no arquivo
Retorna:
- Dicionário contendo linhas correspondentes com seus números de linha e total de correspondências
Exemplo de saída:
{
"status": "success",
"matches": [
[2, " print(\"Hello, world!\")"]
],
"total_matches": 1
}
Nota:
- Retorna um erro se nenhum caminho de arquivo estiver definido
- Pesquisa correspondências exatas de texto dentro de cada linha
- O id pode ser usado para operações de edição subsequentes
11. find_function
Encontra uma definição de função ou método no arquivo Python ou JavaScript/JSX atual.
Parâmetros:
function_name(str): Nome da função ou método a ser encontrado
Retorna:
- Dicionário contendo as linhas da função com seus números de linha, start_line e end_line
Exemplo de saída:
{
"status": "success",
"lines": [
[10, "def hello():"],
[11, " print(\"Hello, world!\")"],
[12, " return True"]
],
"start_line": 10,
"end_line": 12
}
Nota:
- Para arquivos Python, esta ferramenta usa os módulos AST e tokenize do Python para identificar com precisão os limites das funções, incluindo decoradores e docstrings
- Para arquivos JavaScript/JSX, esta ferramenta usa uma combinação de abordagens:
- Método principal: Análise AST do Babel quando disponível (requer Node.js e pacotes Babel)
- Método alternativo: Correspondência de padrões regex para declarações de função quando o Babel não está disponível
- Suporta vários tipos de funções JavaScript, incluindo funções padrão, funções assíncronas, arrow functions e hooks do React
- Retorna um erro se nenhum caminho de arquivo estiver definido ou se a função não for encontrada
12. listdir
Lista o conteúdo de um diretório.
Parâmetros:
dirpath(str): Caminho para o diretório a ser listado
Retorna:
- Dicionário contendo a lista de nomes de arquivos e o caminho consultado
13. run_tests e set_python_path
Ferramentas para executar testes Python com pytest e configurar o ambiente Python.
- Defina como "0", "false" ou "no" para desabilitar a verificação de sintaxe JavaScript
- Útil se você não tiver Babel e dependências relacionadas instaladas
FAIL_ON_PYTHON_SYNTAX_ERROR: Controla se erros de sintaxe Python cancelam automaticamente a operação de sobrescrita (padrão: 1)- Quando habilitado, erros de sintaxe em arquivos Python farão com que a ação de sobrescrita seja cancelada automaticamente
- As linhas permanecerão selecionadas para que você possa corrigir o erro e tentar novamente
FAIL_ON_JS_SYNTAX_ERROR: Controla se erros de sintaxe JavaScript/JSX cancelam automaticamente a operação de sobrescrita (padrão: 0)- Quando habilitado, erros de sintaxe em arquivos JavaScript/JSX farão com que a ação de sobrescrita seja cancelada automaticamente
- As linhas permanecerão selecionadas para que você possa corrigir o erro e tentar novamente
DUCKDB_USAGE_STATS: Controla se estatísticas de uso são coletadas em um banco de dados DuckDB (padrão: 0)- Defina como "1", "true" ou "yes" para habilitar a coleta de estatísticas de uso das ferramentas
- Quando habilitado, registra informações sobre cada chamada de ferramenta, incluindo carimbos de data/hora e argumentos
STATS_DB_PATH: Caminho onde o banco de dados DuckDB para estatísticas será armazenado (padrão: "text_editor_stats.duckdb")- Usado apenas quando
DUCKDB_USAGE_STATSestá habilitado
- Usado apenas quando
PROTECTED_PATHS: Lista separada por vírgulas de padrões de arquivo ou caminhos absolutos que terão acesso negado- Exemplo:
*.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/credentials.txt - Suporta tanto caminhos de arquivo exatos quanto padrões glob flexíveis com curingas em qualquer posição:
*.env- corresponde a arquivos que terminam com .env, como.env,dev.env,prod.env.env*- corresponde a arquivos que começam com .env, como.env,.env.local,.env.production*secret*- corresponde a qualquer arquivo que contenha 'secret' no nome
- Fornece proteção contra a exposição acidental de arquivos de configuração sensíveis e credenciais
- As linhas permanecerão selecionadas para que você possa corrigir o erro e tentar novamente
- Exemplo:
Desenvolvimento
Pré-requisitos
O editor-mcp requer:
- Python 3.7+
- Pacote FastMCP
- black (para verificações de formatação de código Python)
- Babel (para verificações de sintaxe JavaScript/JSX se você trabalhar com esses arquivos)
Instale as dependências de desenvolvimento:
# Using pip
pip install pytest pytest-asyncio pytest-cov
# Using uv
uv pip install pytest pytest-asyncio pytest-cov
Para validação de sintaxe JavaScript/JSX, você precisa de Node.js e Babel. O editor de texto usa npx babel para verificar a sintaxe JS/JSX ao editar esses tipos de arquivo:
# Required for JavaScript/JSX syntax checking
npm install --save-dev @babel/core @babel/cli @babel/preset-env @babel/preset-react
# You can also install these globally if you prefer
# npm install -g @babel/core @babel/cli @babel/preset-env @babel/preset-react
O editor requer:
@babel/coree@babel/cli- Pacotes Babel principais para verificação de sintaxe@babel/preset-env- Para arquivos JavaScript (.js) padrão@babel/preset-react- Para arquivos React JSX (.jsx)
Executando Testes
# Run tests
pytest -v
# Run tests with coverage
pytest -v --cov=text_editor
Estrutura de Testes
A suíte de testes cobre:
-
Ferramenta set_file
- Definir arquivos válidos
- Definir arquivos inexistentes
-
Ferramenta read
- Validação do estado do arquivo
- Leitura de arquivos inteiros
- Leitura de intervalos específicos de linhas
- Casos extremos como arquivos vazios
- Tratamento de intervalos inválidos
-
Ferramenta select
- Validação de intervalo de linhas
- Validação da seleção em relação a max_select_lines
- Armazenamento da seleção para operações subsequentes
-
Ferramenta overwrite
- Verificação do conteúdo selecionado usando ID
- Validação da substituição de conteúdo
- Verificação de sintaxe para arquivos Python e JavaScript/React
- Geração de pré-visualização de diff para alterações
-
Ferramentas confirm e cancel
- Aplicar ou cancelar alterações pendentes
- Processo de verificação em duas etapas
-
Ferramenta delete_file
- Validação de exclusão de arquivo
-
Ferramenta new_file
- Validação de criação de arquivo
- Tratamento de arquivos existentes
-
Ferramenta find_line
- Encontrar correspondências de texto em arquivos
- Tratamento de termos de pesquisa específicos
- Tratamento de erros para arquivos inexistentes
- Tratamento de casos sem correspondências
- Tratamento de arquivos existentes
Como Funciona
A Abordagem de Edição em Múltiplas Etapas
Diferente das abordagens tradicionais de edição de código, onde LLMs simplesmente procuram linhas para editar e fazem substituições (muitas vezes levando a confusão após múltiplas edições), este editor implementa um fluxo de trabalho estruturado em múltiplas etapas que melhora drasticamente a precisão da edição:
- set_file - Primeiro, o LLM define qual arquivo deseja editar
- skim - O LLM lê o arquivo inteiro para obter uma visão geral completa
- read - O LLM examina seções específicas relevantes para a tarefa, com linhas exibidas junto com números para melhor contexto
- select - Quando pronto para editar, o LLM seleciona linhas específicas (limitadas a um número configurável, padrão 50)
- overwrite - O LLM propõe conteúdo de substituição, resultando em uma pré-visualização no estilo git diff que mostra exatamente o que mudará
- confirm/cancel - Após revisar a pré-visualização, o LLM pode aplicar ou descartar as alterações
Este fluxo de trabalho estruturado força o LLM a raciocinar cuidadosamente sobre cada edição e previne erros comuns como sobrescrever arquivos inteiros acidentalmente. Ao ver pré-visualizações das alterações antes de confirmá-las, o LLM pode verificar se suas edições estão corretas.
Sistema de Verificação de ID
O servidor usa FastMCP para expor capacidades de edição de texto através de uma API bem definida. O sistema de verificação de ID garante a integridade dos dados verificando se o conteúdo não mudou entre as operações de leitura e modificação.
O mecanismo de ID usa SHA-256 para gerar um identificador único do conteúdo do arquivo ou dos intervalos de linhas selecionados. Para operações específicas de linha, o ID inclui um prefixo indicando o intervalo de linhas (por exemplo, "L10-15-[hash]"). Isso ajuda a garantir que as edições estejam sendo aplicadas ao conteúdo esperado.
Detalhes de Implementação
A classe principal TextEditorServer:
- Inicializa com uma instância FastMCP chamada "text-editor"
- Define um limite configurável de
max_select_lines(padrão: 50) a partir de variáveis de ambiente - Mantém o caminho do arquivo atual como estado
- Registra treze ferramentas principais através do FastMCP:
set_file: Valida e define o caminho do arquivo atualskim: Lê o conteúdo inteiro de um arquivo, retornando um dicionário de números de linha para texto da linharead: Lê linhas de um intervalo especificado, retornando um dicionário estruturado do conteúdo das linhasselect: Seleciona linhas para a operação de sobrescrita subsequenteoverwrite: Recebe uma lista de novas linhas e prepara a pré-visualização de diff para alterar o conteúdoconfirm: Aplica alterações pendentes da operação de sobrescritacancel: Descarta alterações pendentes da operação de sobrescritadelete_file: Exclui o arquivo atualnew_file: Cria um novo arquivofind_line: Encontra linhas contendo texto específicofind_function: Encontra definições de funções ou métodos em arquivos Python e JavaScript/JSXlistdir: Lista o conteúdo de um diretóriorun_testseset_python_path: Ferramentas para executar testes Python
O servidor executa usando o transporte stdio do FastMCP por padrão, facilitando a integração com vários clientes.
Prompt de Sistema para Melhores Resultados
Para obter resultados ideais com assistentes de IA, é recomendado usar o prompt de sistema (veja system_prompt.md) que ajuda a guiar a IA a fazer edições gerenciáveis e seguras.
Este prompt de sistema ajuda o assistente de IA a:
- Fazer alterações incrementais - Dividindo edições em partes menores
- Manter a integridade do código - Fazendo alterações que mantêm o código funcional
- Trabalhar dentro dos limites de recursos - Evitando operações que possam sobrecarregar o sistema
- Seguir um fluxo de trabalho de verificação - Fazendo verificações finais de erros após as edições
Ao incorporar este prompt de sistema ao trabalhar com assistentes de IA, você obterá um comportamento de edição mais confiável e evitará armadilhas comuns na edição automatizada de código.

Estatísticas de Uso
O editor de texto MCP pode coletar estatísticas de uso quando habilitado, fornecendo insights sobre como as ferramentas de edição estão sendo usadas:
- Coleta de Dados: As estatísticas são coletadas em um banco de dados DuckDB quando
DUCKDB_USAGE_STATSestá habilitado - Informações Rastreadas: Registra nome da ferramenta, argumentos, carimbo de data/hora, caminho do arquivo atual, resposta da ferramenta e IDs de solicitação/cliente
- Local de Armazenamento: Os dados são armazenados em um arquivo DuckDB especificado por
STATS_DB_PATH - Privacidade: Tudo é armazenado localmente na sua máquina
As estatísticas coletadas podem ajudar a entender padrões de uso, identificar fluxos de trabalho comuns e otimizar o editor para as operações mais frequentes.
Você pode consultar o banco de dados usando SQL padrão através de qualquer cliente DuckDB para analisar padrões de uso.
Solução de Problemas
Se você encontrar problemas:
- Verifique as permissões de arquivo
- Confirme que os caminhos de arquivo são absolutos
- Garanta que o ambiente esteja usando Python 3.7+
Inspiração
Inspirado por um projeto semelhante: https://github.com/tumf/mcp-text-editor, que inicialmente eu fiz fork, porém decidi reescrever todo o código do zero, então apenas a ideia geral permaneceu a mesma.