Editor MCP
Un servidor para operaciones de archivos, que permite leer, editar y gestionar archivos de texto a través de una API estandarizada.
Documentación
Editor MCP
Un servidor de editor de texto basado en Python construido con FastMCP que proporciona potentes herramientas para operaciones con archivos. Este servidor permite leer, editar y gestionar archivos de texto a través de una API estandarizada con un enfoque único de múltiples pasos que mejora significativamente la precisión y fiabilidad de la edición de código para LLMs y asistentes de IA.
Características
- Selección de Archivos: Establece un archivo con el que trabajar usando rutas absolutas
- Operaciones de Lectura:
- Leer archivos completos con números de línea usando
skim - Leer rangos específicos de líneas con números de línea prefijados usando
read - Buscar texto específico dentro de archivos usando
find_line - Buscar y extraer definiciones de funciones en archivos Python y JavaScript/JSX usando
find_function
- Leer archivos completos con números de línea usando
- Operaciones de Edición:
- Proceso de edición en dos pasos con vista previa de diferencias
- Seleccionar y sobrescribir texto con verificación de ID
- Flujo de edición limpio con patrón seleccionar → sobrescribir → confirmar/cancelar
- Verificación de sintaxis para archivos Python (.py) y JavaScript/React (.js, .jsx)
- Crear nuevos archivos con contenido
- Gestión de Archivos:
- Crear nuevos archivos con inicialización adecuada
- Eliminar archivos del sistema de archivos
- Listar contenidos de directorios con
listdir
- Soporte de Pruebas:
- Ejecutar pruebas de Python con
run_tests - Establecer rutas de Python para una resolución adecuada de módulos
- Ejecutar pruebas de Python con
- Características de Seguridad:
- Verificación de ID de contenido para prevenir conflictos
- Límites de número de líneas para prevenir agotamiento de recursos
- Verificación de sintaxis para mantener la integridad del código
- Rutas protegidas para restringir el acceso a archivos sensibles
Riesgos de Seguridad
El editor-mcp incluye capacidades potentes que conllevan ciertas consideraciones de seguridad:
- Riesgo de Jailbreak: El editor-mcp puede potencialmente ser vulnerado al leer un archivo que tiene instrucciones dañinas incrustadas. El contenido malicioso en archivos que se están editando podría contener instrucciones que manipulen al asistente de IA.
- Ejecución Arbitraria de Código: Si la ejecución de pruebas está habilitada, existe un riesgo de ejecución arbitraria de código a través de archivos de prueba manipulados o código Python malicioso.
- Exposición de Datos: El acceso a operaciones del sistema de archivos podría potencialmente exponer información sensible si no se configuran protecciones de ruta adecuadas.
Para mitigar estos riesgos:
- Use la variable de entorno
PROTECTED_PATHSpara restringir el acceso a archivos y directorios sensibles. - Deshabilite las capacidades de ejecución de pruebas en entornos de producción a menos que sea absolutamente necesario.
- Revise cuidadosamente los archivos antes de abrirlos, especialmente si provienen de fuentes no confiables.
- Considere ejecutar el editor en un entorno sandbox con permisos limitados.
Ventajas Clave Para LLMs
El diseño único de este editor de texto resuelve problemas críticos que típicamente afectan la edición de código por LLMs:
-
Previene la Pérdida de Contexto - Los enfoques tradicionales a menudo llevan a que los LLMs pierdan la visión general del código base después de unas pocas ediciones. Esta implementación mantiene el contexto a través del proceso de múltiples pasos.
-
Evita Reescrituras Intensivas en Recursos - Los LLMs típicamente tienden a reemplazar archivos completos cuando están confundidos, lo cual es costoso, lento e ineficiente. Este editor impone ediciones selectivas.
-
Proporciona Retroalimentación Visual - El sistema de vista previa de diferencias permite al LLM ver y verificar realmente los cambios antes de confirmarlos, reduciendo drásticamente los errores.
-
Impone Verificación de Sintaxis - La validación automática para Python y JavaScript/React asegura que no se confirme código roto.
-
Mejora el Razonamiento de Edición - El enfoque de múltiples pasos le da al LLM tiempo para razonar entre pasos, reduciendo la producción de tokens al azar.
Gestión de Recursos
El editor implementa varias salvaguardas para asegurar la estabilidad del sistema y prevenir el agotamiento de recursos:
- Máximo de Líneas de Edición: Por defecto, el editor impone un límite de 50 líneas para cualquier operación de edición individual
Instalación
Este MCP fue desarrollado y probado con Claude Desktop. Puede descargar Claude Desktop en cualquier plataforma. Para Claude Desktop en Linux, puede usar un script de instalación no oficial (usa el archivo oficial), repositorio recomendado: https://github.com/emsi/claude-desktop/tree/main
Una vez que tenga Claude Desktop instalado, siga las instrucciones a continuación para instalar este MCP específico:
Instalación Fácil con UVX (Recomendado)
La forma más fácil de instalar el Editor MCP es usando el script de instalación proporcionado:
# 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:
- Verificará si UVX está instalado y lo instalará si es necesario
- Instalará el Editor MCP en modo de desarrollo
- Hará que el comando
editor-mcpesté disponible en su PATH
Instalación 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 desde el archivo de bloqueo:
uv pip install -r uv.lock
Generando un archivo de requirements bloqueado:
uv pip compile requirements.in -o uv.lock
Uso
Iniciando el Servidor
Después de la instalación, puede iniciar el servidor Editor MCP usando uno de estos métodos:
# Using the installed script
editor-mcp
# Or using the Python module
python -m text_editor.server
Configuración MCP
Puede agregar el Editor MCP a su archivo de configuración 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"
}
}
}
}
Configuración de Variables de Entorno
El Editor MCP admite varias variables de entorno para personalizar su comportamiento:
-
MAX_SELECT_LINES: "100" - Número máximo de líneas que se pueden editar en una sola operación (por defecto es 50)
-
ENABLE_JS_SYNTAX_CHECK: "0" - Habilitar/deshabilitar la verificación de sintaxis de JavaScript y JSX (por defecto es "1" - habilitado)
-
FAIL_ON_PYTHON_SYNTAX_ERROR: "1" - Cuando está habilitado, los errores de sintaxis de Python cancelarán automáticamente la operación de sobrescritura (por defecto está habilitado)
-
FAIL_ON_JS_SYNTAX_ERROR: "0" - Cuando está habilitado, los errores de sintaxis de JavaScript/JSX cancelarán automáticamente la operación de sobrescritura (por defecto está deshabilitado)
-
PROTECTED_PATHS: Lista separada por comas de patrones de archivos o rutas que no pueden ser accedidos, con soporte para comodines (por ejemplo, ".env,.env,/etc/passwd")
Ejemplo de Configuración MCP al Compilar desde el Código Fuente
{
"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"
}
}
}
}
Herramientas Disponibles
El Editor MCP proporciona 13 potentes herramientas para manipulación de archivos, edición y pruebas:
1. set_file
Establece el archivo actual con el que trabajar.
Parámetros:
filepath(str): Ruta absoluta al archivo
Retorna:
- Mensaje de confirmación con la ruta del archivo
2. skim
Lee el texto completo del archivo actual. Cada línea está prefijada con su número de línea.
Retorna:
- Diccionario que contiene las líneas con sus números de línea, el número total de líneas y la configuración de máximo de líneas de edición
Ejemplo de salida:
{
"lines": [
[1, "def hello():"],
[2, " print(\"Hello, world!\")"],
[3, ""],
[4, "hello()"]
],
"total_lines": 4,
"max_select_lines": 50
}
3. read
Lee texto del archivo actual desde la línea de inicio hasta la línea final.
Parámetros:
start(int): Número de línea de inicio (indexación basada en 1)end(int): Número de línea final (indexación basada en 1)
Retorna:
- Diccionario que contiene las líneas con sus números de línea como claves, junto con información de inicio y fin de línea
Ejemplo de salida:
{
"lines": [
[1, "def hello():"],
[2, " print(\"Hello, world!\")"],
[3, ""],
[4, "hello()"]
],
"start_line": 1,
"end_line": 4
}
4. select
Selecciona un rango de líneas del archivo actual para la operación de sobrescritura posterior.
Parámetros:
start(int): Número de línea de inicio (basado en 1)end(int): Número de línea final (basado en 1)
Retorna:
- Diccionario que contiene las líneas seleccionadas, el rango de líneas y el ID para verificación
Nota:
- Esta herramienta valida la selección contra max_select_lines
- Los detalles de la selección se almacenan para su uso en la herramienta de sobrescritura
- Debe usarse antes de llamar a la herramienta de sobrescritura
5. overwrite
Prepara la sobrescritura de un rango de líneas en el archivo actual con texto nuevo.
Parámetros:
new_lines(list): Lista de nuevas líneas para sobrescribir el rango seleccionado
Retorna:
- Vista previa de diferencias que muestra los cambios propuestos
Nota:
- Este es el primer paso en un proceso de dos pasos:
- Primero llame a overwrite() para generar una vista previa de diferencias
- Luego llame a confirm() para aplicar o cancel() para descartar los cambios pendientes
- Esta herramienta permite reemplazar las líneas previamente seleccionadas con contenido nuevo
- El número de líneas nuevas puede diferir de la selección original
- Para archivos Python (extensión .py), se realiza verificación de sintaxis antes de escribir
- Para archivos JavaScript/React (extensiones .js, .jsx), la verificación de sintaxis es opcional y puede deshabilitarse mediante la variable de entorno
ENABLE_JS_SYNTAX_CHECK
6. confirm
Aplica los cambios pendientes de la operación de sobrescritura.
Retorna:
- Resultado de la operación con estado y mensaje
Nota:
- Esta es una de las dos acciones posibles en el segundo paso del proceso de edición
- La selección se elimina al aplicar exitosamente los cambios
7. cancel
Descarta los cambios pendientes de la operación de sobrescritura.
Retorna:
- Resultado de la operación con estado y mensaje
Nota:
- Esta es una de las dos acciones posibles en el segundo paso del proceso de edición
- La selección permanece intacta cuando se cancelan los cambios
8. delete_file
Elimina el archivo actualmente establecido.
Retorna:
- Resultado de la operación con estado y mensaje
9. new_file
Crea un nuevo archivo y automáticamente lo establece como el archivo actual para operaciones posteriores.
Parámetros:
filepath(str): Ruta del nuevo archivo
Retorna:
- Resultado de la operación con estado, mensaje e información de selección
- La primera línea se selecciona automáticamente para edición
Comportamiento:
- Crea automáticamente directorios padre si no existen
- Establece el archivo recién creado como el archivo de trabajo actual
- La primera línea está preseleccionada, lista para edición inmediata
Nota sobre Archivos Protegidos:
- Los archivos que coinciden con ciertos patrones (como
*.env) pueden crearse normalmente - Sin embargo, una vez que se cambia a otro archivo, estos archivos protegidos no pueden reabrirse
- Esto permite un flujo de trabajo de "escribir-una-vez, proteger-después" para archivos de configuración sensibles
- Ejemplo: Puede crear
config.env, poblarlo con configuración de ejemplo, pero no puede reabrirlo más tarde
Nota:
- Esta herramienta fallará si el archivo actual existe y no está vacío
10. find_line
Encuentra líneas que coinciden con el texto proporcionado en el archivo actual.
Parámetros:
search_text(str): Texto a buscar en el archivo
Retorna:
- Diccionario que contiene las líneas coincidentes con sus números de línea y el total de coincidencias
Ejemplo de salida:
{
"status": "success",
"matches": [
[2, " print(\"Hello, world!\")"]
],
"total_matches": 1
}
Nota:
- Retorna un error si no se establece una ruta de archivo
- Busca coincidencias exactas de texto dentro de cada línea
- El id puede usarse para operaciones de edición posteriores
11. find_function
Encuentra una definición de función o método en el archivo Python o JavaScript/JSX actual.
Parámetros:
function_name(str): Nombre de la función o método a encontrar
Retorna:
- Diccionario que contiene las líneas de la función con sus números de línea, start_line y end_line
Ejemplo de salida:
{
"status": "success",
"lines": [
[10, "def hello():"],
[11, " print(\"Hello, world!\")"],
[12, " return True"]
],
"start_line": 10,
"end_line": 12
}
Nota:
- Para archivos Python, esta herramienta usa los módulos AST y tokenize de Python para identificar con precisión los límites de las funciones, incluyendo decoradores y docstrings
- Para archivos JavaScript/JSX, esta herramienta usa una combinación de enfoques:
- Método principal: Análisis AST de Babel cuando está disponible (requiere Node.js y paquetes Babel)
- Método alternativo: Coincidencia de patrones regex para declaraciones de funciones cuando Babel no está disponible
- Admite varios tipos de funciones JavaScript, incluyendo funciones estándar, funciones asíncronas, funciones flecha y hooks de React
- Retorna un error si no se establece una ruta de archivo o si la función no se encuentra
12. listdir
Lista los contenidos de un directorio.
Parámetros:
dirpath(str): Ruta al directorio a listar
Retorna:
- Diccionario que contiene la lista de nombres de archivos y la ruta consultada
13. run_tests and set_python_path
Herramientas para ejecutar pruebas de Python con pytest y configurar el entorno de Python.
- Establezca en "0", "false" o "no" para deshabilitar la verificación de sintaxis de JavaScript
- Útil si no tiene Babel y las dependencias relacionadas instaladas
FAIL_ON_PYTHON_SYNTAX_ERROR: Controla si los errores de sintaxis de Python cancelan automáticamente la operación de sobrescritura (predeterminado: 1)- Cuando está habilitado, los errores de sintaxis en archivos Python harán que la acción de sobrescritura se cancele automáticamente
- Las líneas permanecerán seleccionadas para que pueda corregir el error e intentarlo de nuevo
FAIL_ON_JS_SYNTAX_ERROR: Controla si los errores de sintaxis de JavaScript/JSX cancelan automáticamente la operación de sobrescritura (predeterminado: 0)- Cuando está habilitado, los errores de sintaxis en archivos JavaScript/JSX harán que la acción de sobrescritura se cancele automáticamente
- Las líneas permanecerán seleccionadas para que pueda corregir el error e intentarlo de nuevo
DUCKDB_USAGE_STATS: Controla si se recopilan estadísticas de uso en una base de datos DuckDB (predeterminado: 0)- Establezca en "1", "true" o "yes" para habilitar la recopilación de estadísticas de uso de herramientas
- Cuando está habilitado, registra información sobre cada llamada a herramienta, incluidos marcas de tiempo y argumentos
STATS_DB_PATH: Ruta donde se almacenará la base de datos DuckDB para estadísticas (predeterminado: "text_editor_stats.duckdb")- Solo se usa cuando
DUCKDB_USAGE_STATSestá habilitado
- Solo se usa cuando
PROTECTED_PATHS: Lista separada por comas de patrones de archivo o rutas absolutas a las que se denegará el acceso- Ejemplo:
*.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/credentials.txt - Admite tanto rutas de archivo exactas como patrones glob flexibles con comodines en cualquier posición:
*.env- coincide con archivos que terminan en .env, como.env,dev.env,prod.env.env*- coincide con archivos que comienzan con .env, como.env,.env.local,.env.production*secret*- coincide con cualquier archivo que contenga 'secret' en el nombre
- Proporciona protección contra la exposición accidental de archivos de configuración sensibles y credenciales
- Las líneas permanecerán seleccionadas para que pueda corregir el error e intentarlo de nuevo
- Ejemplo:
Desarrollo
Requisitos previos
El editor-mcp requiere:
- Python 3.7+
- paquete FastMCP
- black (para comprobaciones de formato de código Python)
- Babel (para comprobaciones de sintaxis de JavaScript/JSX si trabaja con esos archivos)
Instale las dependencias de desarrollo:
# Using pip
pip install pytest pytest-asyncio pytest-cov
# Using uv
uv pip install pytest pytest-asyncio pytest-cov
Para la validación de sintaxis de JavaScript/JSX, necesita Node.js y Babel. El editor de texto usa npx babel para verificar la sintaxis de JS/JSX al editar estos tipos de archivo:
# 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
El editor requiere:
@babel/corey@babel/cli- Paquetes principales de Babel para la verificación de sintaxis@babel/preset-env- Para archivos JavaScript (.js) estándar@babel/preset-react- Para archivos React JSX (.jsx)
Ejecución de Pruebas
# Run tests
pytest -v
# Run tests with coverage
pytest -v --cov=text_editor
Estructura de Pruebas
La suite de pruebas cubre:
-
herramienta set_file
- Configurar archivos válidos
- Configurar archivos inexistentes
-
herramienta read
- Validación del estado del archivo
- Lectura de archivos completos
- Lectura de rangos de líneas específicos
- Casos límite como archivos vacíos
- Manejo de rangos no válidos
-
herramienta select
- Validación del rango de líneas
- Validación de selección contra max_select_lines
- Almacenamiento de selección para operaciones posteriores
-
herramienta overwrite
- Verificación del contenido seleccionado mediante ID
- Validación del reemplazo de contenido
- Verificación de sintaxis para archivos Python y JavaScript/React
- Generación de vista previa de diff para los cambios
-
herramientas confirm y cancel
- Aplicar o cancelar cambios pendientes
- Proceso de verificación en dos pasos
-
herramienta delete_file
- Validación de eliminación de archivos
-
herramienta new_file
- Validación de creación de archivos
- Manejo de archivos existentes
-
herramienta find_line
- Encontrar coincidencias de texto en archivos
- Manejo de términos de búsqueda específicos
- Manejo de errores para archivos inexistentes
- Manejo de casos sin coincidencias
- Manejo de archivos existentes
Cómo Funciona
El Enfoque de Edición en Múltiples Pasos
A diferencia de los enfoques tradicionales de edición de código donde los LLM simplemente buscan líneas para editar y hacen reemplazos (a menudo causando confusión después de múltiples ediciones), este editor implementa un flujo de trabajo estructurado de múltiples pasos que mejora drásticamente la precisión de la edición:
- set_file - Primero, el LLM establece qué archivo desea editar
- skim - El LLM lee el archivo completo para obtener una visión general completa
- read - El LLM examina secciones específicas relevantes para la tarea, con líneas mostradas junto a números para un mejor contexto
- select - Cuando está listo para editar, el LLM selecciona líneas específicas (limitado a un número configurable, predeterminado 50)
- overwrite - El LLM propone contenido de reemplazo, resultando en una vista previa estilo git diff que muestra exactamente qué cambiará
- confirm/cancel - Después de revisar la vista previa, el LLM puede aplicar o descartar los cambios
Este flujo de trabajo estructurado obliga al LLM a razonar cuidadosamente sobre cada edición y previene errores comunes como sobrescribir accidentalmente archivos completos. Al ver vistas previas de los cambios antes de confirmarlos, el LLM puede verificar que sus ediciones sean correctas.
Sistema de Verificación de ID
El servidor usa FastMCP para exponer capacidades de edición de texto a través de una API bien definida. El sistema de verificación de ID garantiza la integridad de los datos al verificar que el contenido no haya cambiado entre las operaciones de lectura y modificación.
El mecanismo de ID usa SHA-256 para generar un identificador único del contenido del archivo o de los rangos de líneas seleccionados. Para operaciones específicas de líneas, el ID incluye un prefijo que indica el rango de líneas (por ejemplo, "L10-15-[hash]"). Esto ayuda a garantizar que las ediciones se apliquen al contenido esperado.
Detalles de Implementación
La clase principal TextEditorServer:
- Se inicializa con una instancia de FastMCP llamada "text-editor"
- Establece un límite configurable
max_select_lines(predeterminado: 50) a partir de variables de entorno - Mantiene la ruta del archivo actual como estado
- Registra trece herramientas principales a través de FastMCP:
set_file: Valida y establece la ruta del archivo actualskim: Lee el contenido completo de un archivo, devolviendo un diccionario de números de línea a texto de línearead: Lee líneas de un rango de líneas especificado, devolviendo un diccionario estructurado del contenido de las líneasselect: Selecciona líneas para la operación de sobrescritura posterioroverwrite: Toma una lista de nuevas líneas y prepara una vista previa de diff para cambiar el contenidoconfirm: Aplica los cambios pendientes de la operación de sobrescrituracancel: Descarta los cambios pendientes de la operación de sobrescrituradelete_file: Elimina el archivo actualnew_file: Crea un nuevo archivofind_line: Encuentra líneas que contienen texto específicofind_function: Encuentra definiciones de funciones o métodos en archivos Python y JavaScript/JSXlistdir: Lista el contenido de un directoriorun_testsyset_python_path: Herramientas para ejecutar pruebas de Python
El servidor se ejecuta usando el transporte stdio de FastMCP por defecto, lo que facilita la integración con varios clientes.
Prompt del Sistema para Mejores Resultados
Para obtener resultados óptimos con asistentes de IA, se recomienda usar el prompt del sistema (ver system_prompt.md) que ayuda a guiar a la IA para realizar ediciones manejables y seguras.
Este prompt del sistema ayuda al asistente de IA:
- Hacer cambios incrementales - Dividir las ediciones en partes más pequeñas
- Mantener la integridad del código - Realizar cambios que mantengan el código funcional
- Trabajar dentro de los límites de recursos - Evitar operaciones que puedan abrumar al sistema
- Seguir un flujo de trabajo de verificación - Realizar comprobaciones finales de errores después de las ediciones
Al incorporar este prompt del sistema al trabajar con asistentes de IA, obtendrá un comportamiento de edición más confiable y evitará errores comunes en la edición automatizada de código.

Estadísticas de Uso
El editor de texto MCP puede recopilar estadísticas de uso cuando está habilitado, proporcionando información sobre cómo se están utilizando las herramientas de edición:
- Recopilación de datos: Las estadísticas se recopilan en una base de datos DuckDB cuando
DUCKDB_USAGE_STATSestá habilitado - Información rastreada: Registra nombre de la herramienta, argumentos, marca de tiempo, ruta del archivo actual, respuesta de la herramienta e IDs de solicitud/cliente
- Ubicación de almacenamiento: Los datos se almacenan en un archivo DuckDB especificado por
STATS_DB_PATH - Privacidad: Todo se almacena localmente en su máquina
Las estadísticas recopiladas pueden ayudar a comprender los patrones de uso, identificar flujos de trabajo comunes y optimizar el editor para las operaciones más frecuentes.
Puede consultar la base de datos usando SQL estándar a través de cualquier cliente DuckDB para analizar los patrones de uso.
Solución de Problemas
Si encuentra problemas:
- Verifique los permisos de archivo
- Verifique que las rutas de archivo sean absolutas
- Asegúrese de que el entorno use Python 3.7+
Inspiración
Inspirado en un proyecto similar: https://github.com/tumf/mcp-text-editor, que al principio bifurqué, sin embargo decidí reescribir todo el código desde cero, por lo que solo la idea general permaneció igual.