local-code-agent

Servidor MCP local desarrollado con FastMCP: permite que la IA externa (ChatGPT, Claude, etc.) acceda de forma segura a través de Cloudflare Tunnel y controle remotamente el espacio de trabajo local — lectura/escritura/edición de archivos, búsqueda, comandos shell, operaciones Git — con autenticación Bearer Token, aislamiento en sandbox y registros de auditoría.

Este proyecto no contiene lógica de IA/LLM; solo incluye la capa de herramientas y la configuración del túnel.

Requisitos del entorno

• Python 3.10+ (requisito estricto de FastMCP)

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

Inicio rápido

# 1. 安装依赖
pip install -r requirements.txt
set MCP_AUTH_TOKEN=your_long_random_token
set MCP_WORKSPACE=D:\projects\my-project

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

# 3. 公网穿透（临时域名）
cloudflared tunnel --url http://127.0.0.1:8000

# 固定域名（绑定自有域名）
cloudflared tunnel --url http://127.0.0.1:8000 --hostname mcp.yourdomain.com

Comprobación de salud: GET http://127.0.0.1:8000/health (sin autenticación por defecto; el resto de endpoints deben incluir Bearer Token).

Interfaz gráfica (opcional)

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

python -m gui.app

Funciones de la consola:

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

• Token de autenticación: se genera automáticamente un token aleatorio al iniciar; puede pulsar «Regenerar» para cambiarlo. Este token es el que debe introducirse en el cliente de IA como Authorization: Bearer ....

• Puerto / modo de solo lectura: establece el puerto de escucha; si se marca solo lectura, se deshabilitan las herramientas de escritura/edición/comandos.

• Iniciar / detener servicio: ejecuta server.py como subproceso; detener finaliza el proceso.

• Barra de estado: consulta /health periódicamente y muestra la versión del servicio, el espacio de trabajo actual y el tiempo de ejecución; también permite copiar con un clic el comando del túnel cloudflared.

• Área de registros: muestra en tiempo real la salida del subproceso del servidor; si supera las 600 líneas, se recorta automáticamente.

La GUI es solo un lanzador de server.py; usa el mismo mecanismo de seguridad de autenticación, sandbox y auditoría; la conexión con la red pública es igual que en la línea de comandos.

Integración con clientes

ChatGPT Custom Connector: URL https://<tunnel-host>/mcp, añada la cabecera Authorization: Bearer your_long_random_token.

El claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "local-code-agent": {
      "url": "https://mcp.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer your_long_random_token" }
    }
  }
}

Lista de herramientas

Modelo de seguridad

• Sandbox: todas las rutas se resuelven con realpath y deben estar dentro del directorio raíz del espacio de trabajo (puede interceptar escapes por enlaces simbólicos). ../ y las rutas absolutas no pueden salirse de los límites.

• Autenticación: FastMCP DebugTokenVerifier valida el Bearer Token. El token solo se lee de MCP_AUTH_TOKEN (en desarrollo puede usar --token). Si falta, se rechaza el arranque.

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

• Lista blanca de comandos: en config.yaml, command_allow, command_deny, danger_commands (requieren x-confirm: true).

• Descargas: solo se permiten hosts http(s) incluidos en download_allow_domains; se prohíben las redirecciones; si supera los 50 MB, se aborta y se elimina el archivo parcial.

• Registro de auditoría: formato JSON Lines, rotación de 10 MB × 5; registra hora, nombre de la herramienta, parámetros enmascarados, resultado y duración.

• Modo de solo lectura: python server.py --readonly solo registra herramientas de lectura/búsqueda/consulta de Git.

Prioridad de configuración

Espacio de trabajo: --workspace > variable de entorno MCP_WORKSPACE > config.yaml (por defecto .). El resto de la configuración proviene de config.yaml (consulte los valores predeterminados en el archivo).

Estructura del proyecto

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
command_whitelist.py      # 命令白名单校验
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # 域名白名单下载
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
gui/                      # tkinter 启动器
start.py / start.spec     # GUI 入口 + PyInstaller onedir
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, puede verificarlos con python tests/test_core.py.

• Cloudflare Tunnel tiene un tiempo de espera de solicitud predeterminado de aproximadamente 100 segundos. run_command usa streaming SSE; el tiempo de espera total máximo es de 3600 segundos.

• Solo se admite un único espacio de trabajo. El cambio entre múltiples espacios de trabajo y el contexto a nivel de sesión aún no están implementados (YAGNI).

• Empaquetado: pip install -r requirements-build.txt && pyinstaller start.spec, el resultado es dist/start/start.exe. En la GUI, debe hacer clic manualmente en «Iniciar servicio».