local-code-agent

Servidor MCP local desarrollado sobre FastMCP: permite que IAs externas (ChatGPT, Claude, etc.) controlen de forma remota un área de trabajo local a través de HTTP — lectura/escritura/edición de archivos, búsqueda, comandos shell, operaciones Git —, proporcionando aislamiento en entorno aislado (sandbox), protección de archivos sensibles y registro de auditoría.

Este proyecto no incluye lógica de IA/LLM, solo contiene la capa de herramientas y controles de seguridad.

Requisitos del entorno

• Python 3.10+ (requisito estricto de FastMCP)

• pip install -r requirements.txt (fastmcp, pyyaml)

Related MCP server: OpenAI Secure MCP Tunnel

Inicio rápido

Método 1: Interfaz gráfica (recomendado)

python start.py

Pasos en la ventana de la consola:

1. Carpeta de trabajo: Haz clic en «Seleccionar…» para elegir una carpeta. Todas las operaciones de la IA se limitan a esa carpeta (sandbox); cambiar de carpeta equivale a cambiar la raíz del sandbox.

2. Prompt de conexión: En el centro de la ventana hay una tarjeta «Prompt de conexión». Copia el texto que contiene y envíalo a la IA en la página web; la IA se vinculará a este servidor MCP según la configuración (sin necesidad de token).

3. Puerto: Por defecto 8000; se puede cambiar si está ocupado.

4. Modo solo lectura: Al activarlo, se rechazan todas las herramientas de escritura/edición/comandos. El cambio es efectivo de inmediato mientras se ejecuta.

5. Haz clic en «Iniciar servicio» → La barra de estado muestra la versión, el estado de solo lectura, el área de trabajo y el tiempo de ejecución; el área de registro muestra el log del servicio en tiempo real.

6. Para detenerlo: haz clic en «Detener servicio» o cierra la ventana directamente (se preguntará antes).

Método 2: Línea de comandos

# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动服务（默认监听 127.0.0.1:8000，MCP 路径 /mcp，无需 Token）
python server.py

Parámetros opcionales: --workspace D:\projects\my-project (directorio raíz del sandbox), --host 0.0.0.0 (permite acceso desde la red local), --port 9000. Para detenerlo, usa Ctrl+C.

Verificación y comprobación de estado

Una vez iniciado el servicio, accede a: GET http://127.0.0.1:8000/health (sin autenticación). Devuelve:

{ "status": "ok", "service": "local-code-agent", "version": "0.1.0",
  "workspace": "D:\\projects\\my-project", "readonly": false,
  "uptime_seconds": 3 }

Los demás endpoints (incluyendo /mcp) son accesibles directamente, sin autenticación.

Acceso desde la red local

Por defecto solo escucha en 127.0.0.1, solo accesible desde la máquina local. Para que otros dispositivos en la misma red local accedan:

python server.py --host 0.0.0.0

Dirección de conexión del cliente: http://<IP local de la máquina>:8000/mcp (la IP local se obtiene con ipconfig). Exponerlo a la red local significa que cualquier dispositivo en la misma subred puede acceder sin autenticación, por lo que se debe actuar con precaución.

No se recomienda exponerlo directamente a Internet público. Si se necesita acceso desde Internet, utiliza una solución de proxy inverso (Nginx + TLS, frp u otras herramientas de túnel) y fuerza HTTPS y autenticación en la capa de proxy.

Interfaz gráfica (opcional)

Se puede usar sin escribir comandos. tkinter es parte de la biblioteca estándar de Python, no requiere instalación adicional.

python start.py

Funcionalidades de la consola:

• Carpeta de trabajo: Haz clic en «Seleccionar…» para abrir el selector de carpetas. Solo se puede seleccionar una carpeta a la vez; todas las operaciones de la IA se limitan a esa carpeta (sandbox). Cambiar de carpeta sustituye la selección actual.

• Prompt de conexión: Contiene un texto de prompt editable. Haz clic en «Copiar prompt» para copiarlo de una vez y enviarlo a la IA en la página web para completar el enlace MCP. No se necesita token.

• Puerto / Modo solo lectura: Configura el puerto de escucha; al marcar solo lectura se deshabilitan las herramientas de escritura/edición/comandos.

• Iniciar / Detener servicio: Inicia FastMCP dentro del proceso de la GUI (hilo en segundo plano + uvicorn), usando un manejador de logs independiente. Al detenerlo, espera a que el hilo del servicio termine.

• Cambio en caliente: Cambiar el área de trabajo o marcar/desmarcar solo lectura tiene efecto inmediato, sin necesidad de reiniciar. El cambio de puerto requiere reiniciar el servicio.

• Barra de estado: Consulta periódicamente /health, mostrando la versión, el estado de solo lectura, el área de trabajo actual y el tiempo de ejecución.

• Área de registro: Muestra la salida del servicio en tiempo real, limpia automáticamente los códigos de escape ANSI, se puede copiar con clic derecho, y se trunca automáticamente si supera las 600 líneas.

La GUI y la línea de comandos comparten el mismo mecanismo de sandbox y auditoría; la forma de conexión es la misma.

Conexión del cliente

Clientes locales: rellenar la URL con http://127.0.0.1:8000/mcp; clientes en la red local usar http://<IP local de la máquina>:8000/mcp (el servidor debe iniciarse con --host 0.0.0.0). No requiere autenticación.

claude_desktop_config.json para Claude Desktop:

{
  "mcpServers": {
    "local-code-agent": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Lista de herramientas

Modelo de seguridad

• Sandbox: Todas las rutas se resuelven con realpath y deben estar dentro del directorio raíz del área de trabajo (puede interceptar escapes mediante enlaces simbólicos). ../ y rutas absolutas no pueden salirse.

• Autenticación: Sin autenticación por token. El servicio solo escucha en 127.0.0.1 por defecto; si se necesita acceso externo, se debe agregar autenticación en la capa de proxy inverso.

• Confirmación de operaciones peligrosas: Los commits de Git requieren la cabecera x-confirm: true para ejecutarse.

• Archivos sensibles: .env, .env.*, *.pem, *.key, id_rsa, .ssh/, .aws/, credentials son bloqueados en cualquier nivel de ruta. Se devuelve un mensaje unificado «access denied», sin revelar si el archivo existe.

• Descargas: Soporta cualquier host HTTP(S); redirecciones prohibidas; si supera los 50MB se aborta y se elimina el archivo parcial.

• Registro de auditoría: Formato JSON por línea, rotación de 10MB × 5, registra hora, nombre de la herramienta, parámetros ofuscados, resultado y tiempo de ejecución.

• Modo solo lectura: python server.py --readonly o marcar en la GUI. Las herramientas de escritura/comandos siguen siendo visibles, pero al invocarlas devuelven read-only mode. Se puede cambiar durante la ejecución.

Prioridad de configuración

Área de trabajo: --workspace > variable de entorno MCP_WORKSPACE > config.yaml (por defecto .). El resto de la configuración proviene de config.yaml (ver valores por defecto en el archivo).

Estructura del proyecto

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # HTTP(S) 下载（无域名白名单）
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
runtime.py                # 运行时只读标志
gui/                      # tkinter 控制台（进程内服务）
start.py                  # GUI 入口
tests/                    # test_core.py + test_extra.py

Limitaciones conocidas

• Python 3.8 no puede ejecutar este servicio (fastmcp requiere 3.10+); los módulos de lógica son compatibles con 3.8, se puede usar python tests/test_core.py para autocomprobación.

• run_command tiene salida en streaming SSE, con un tiempo de espera máximo total de 3600 segundos.

• Solo admite un área de trabajo. El cambio entre múltiples áreas de trabajo y el contexto a nivel de sesión aún no se han implementado (YAGNI).