WorkspaceGuard MCP

WorkspaceGuard MCP es un servidor MCP local y multiplataforma que permite a ChatGPT o a un cliente MCP operar sobre un workspace designado. El proyecto se ha construido desde cero tras investigar FileMCP, conservando los principios de seguridad útiles y reduciendo las partes que aún no son necesarias para la primera versión.

¿Para qué sirve?

• Listar, leer por archivo o por líneas, buscar por nombre y buscar por contenido.

• Escribir archivos de forma atómica, con soporte de dry_run y expected_sha256 para evitar sobrescribir cambios más recientes.

• "Eliminar" moviendo a .workspaceguard/trash, con posibilidad de restauración manual.

• Leer el estado de Git, el log y el diff sin activar shell.

• Ejecutar terminal opcionalmente mediante program + args, sin concatenar cadenas a través del shell y permitiendo solo ejecutables en la allowlist.

• Usar mediante stdio o MCP Streamable HTTP en 127.0.0.1 con token.

• Registrar auditoría JSONL sin guardar el contenido de los archivos ni los parámetros completos de los comandos.

Related MCP server: Kastor

Principales mejoras

La aplicación tiene una interfaz de escritorio Electron para elegir workspace, elegir modo, elegir la allowlist de comandos, iniciar/detener el servidor, probar MCP dentro de la propia app y conectar Secure MCP Tunnel. Siguiendo el enfoque de FileMCP, la app genera un nuevo token loopback por sesión, mantiene el servidor en 127.0.0.1, gestiona el ciclo de vida de tunnel-client y guarda la Runtime API key mediante el mecanismo de cifrado del sistema operativo (Keychain en macOS cuando está disponible). El binario tunnel-client lo descarga el usuario de OpenAI; el proyecto no incluye ese binario. El runtime local y el Tunnel no llaman a Codex ni a modelos/API de OpenAI: se usa la app con ChatGPT Web mediante la app en modo desarrollador, por lo que no se consume cuota de Codex. La conversación sigue sujeto a los límites del plan de ChatGPT en uso.

Requisitos

• Node.js 20 o superior (probado con Node.js 24).

• Git si se usan las herramientas git_*.

• Para ChatGPT: un workspace que admita apps MCP personalizadas, un Secure MCP Tunnel y una runtime API key con permisos de túnel adecuados. Consulta OpenAI Secure MCP Tunnel.

Ejecución paso a paso

Paso 1 — instalar dependencias

cd "/Users/danhpham/Documents/ChatGPT/MCP"
npm install

No pongas la API key en .env ni la subas a Git.

Paso 2 — comprobar todo el proyecto

npm run verify

Este comando ejecuta typecheck, pruebas unitarias/de integración, build de producción y smoke test semántico mediante MCP stdio.

Paso 3 — ejecutar la interfaz de escritorio (la forma más fácil)

npm run desktop

En la ventana de WorkspaceGuard:

1. Pulsa Elegir carpeta… y selecciona un workspace de prueba.

2. Mantén Solo lectura la primera vez.

3. Pulsa Iniciar MCP. Cuando el estado cambie a En ejecución, el servidor HTTP estará listo en 127.0.0.1:<puerto>.

4. Pulsa Detener al terminar. Cerrar la aplicación también detiene tanto el servidor como el Tunnel.

La interfaz no muestra ni guarda el token HTTP; el token se genera de nuevo en el proceso principal en cada inicio.

Probar todo el MCP dentro de la interfaz

Después de que el servidor indique En ejecución, pulsa Ejecutar prueba MCP. Se trata de un cliente MCP real en el proceso principal de Electron, no una prueba simulada a través de la interfaz.

• Con Solo lectura, la app comprueba el handshake HTTP de MCP, el descubrimiento de herramientas, workspace_info y list_files.

• Con Leer y escribir, la app comprueba además write_file → read_file → trash_path. Debes marcar la confirmación porque el archivo de prueba con nombre aleatorio se moverá a .workspaceguard/trash.

• Con Ejecutar comando, mantén marcado node en la allowlist para que la app compruebe además run_command con node --version.

Elige una carpeta de prueba independiente para los dos últimos modos. El resultado de cada paso aparece al instante en la sección de pruebas de la interfaz.

Paso 4 — compilar el núcleo con terminal (opcional)

npm run build

El punto de entrada de producción es:

/Users/danhpham/Documents/ChatGPT/MCP/dist/index.js

Paso 5 — elegir workspace y modo con terminal (opcional)

Conviene empezar con una carpeta de prueba pequeña:

mkdir -p /tmp/workspaceguard-demo
printf 'Xin chào MCP\n' > /tmp/workspaceguard-demo/hello.txt

Tres modos:

• read-only: solo herramientas de lectura de archivos y lectura de Git. Es el valor por defecto.

• workspace-write: añade write_file y trash_path.

• command: añade permisos de escritura y run_command.

Nota: el servidor sigue registrando auditoría interna en .workspaceguard/audit.jsonl en los tres modos. "Read-only" describe las herramientas públicas, no el sandbox de filesystem del propio proceso del servidor.

Paso 6A — ejecutar mediante stdio (recomendado)

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode read-only

La terminal esperará a que el cliente MCP envíe solicitudes por stdin. Este es el comportamiento correcto, no es un cuelgue.

Paso 6B — activar permisos de escritura

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode workspace-write

trash_path tiene dry_run=true por defecto. Solo cuando el llamador envía dry_run=false la ruta se mueve a la papelera.

Paso 6C — permitir ejecutar comandos de terminal

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode command \
  --allow-command git,node,npm,npx

Ejemplo de entrada de herramienta:

{
  "program": "npm",
  "args": ["test"],
  "cwd": "",
  "timeout_seconds": 120
}

run_command no usa shell, pero no es un sandbox de SO. node, npm, Python o cualquier ejecutable permitido pueden leer/escribir fuera del workspace, usar la red y lanzar otros procesos con los permisos de la cuenta actual. Usa el modo command solo con workspaces y flujos de trabajo de confianza.

Paso 7 — conectar ChatGPT con la interfaz Secure MCP Tunnel

En OpenAI Platform, crea un Secure MCP Tunnel y una runtime API key con permiso para usar el túnel. Descarga el tunnel-client adecuado para tu sistema operativo. No envíes la Runtime API key a Codex ni la escribas en .env, en el código fuente o en Git.

En la app, después de que MCP indique En ejecución:

1. Pega el Tunnel ID con el formato tunnel_....

2. Pega la Runtime API key. La próxima vez puedes dejarla vacía para usar la clave guardada cifrada.

3. Introduce tunnel-client si el binario ya está en PATH, o pulsa Elegir archivo… para seleccionar el binario descargado.

4. Mantén el perfil por defecto, pulsa Conectar Tunnel y espera el aviso "listo para ChatGPT".

5. La línea verde "listo para ChatGPT" confirma que la parte local está conectada. Pulsa Abrir ChatGPT Web; esta app no abre ni llama a Codex.

6. Pulsa Desconectar Tunnel si solo quieres desconectar ChatGPT; pulsa Detener para detener tanto el Tunnel como el servidor MCP.

La app realiza el equivalente a la secuencia tunnel-client init --sample sample_mcp_remote_no_auth → doctor --explain → run, con el endpoint MCP http://127.0.0.1:<puerto>/mcp, endpoint de salud local y el header de token pasado mediante variable de entorno. Los perfiles de túnel están en los datos propios de la app, no en el workspace.

En ChatGPT Web, activa Developer Mode/app MCP personalizada según la política del workspace, crea una app nueva, elige la conexión Tunnel, selecciona el túnel recién creado, ejecuta Scan Tools y luego prueba workspace_info, list_files y read_file antes de activar las herramientas de escritura. Si no ves la opción Tunnel, comprueba que el workspace tenga permiso de lectura y uso de Tunnel.

Paso 8 — HTTP loopback (opcional)

export WORKSPACE_MCP_TOKEN="$(openssl rand -hex 32)"

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport http \
  --mode read-only \
  --port 7331

Comprobación de salud:

curl --fail http://127.0.0.1:7331/healthz

La solicitud MCP debe enviar el header:

X-Workspace-MCP-Token: <WORKSPACE_MCP_TOKEN>

El servidor HTTP solo se vincula a 127.0.0.1, comprueba Host, Origin, token, framing básico y límite de cuerpo. Usa stdio si no necesitas HTTP específicamente.

Herramientas disponibles

Siempre disponibles

• workspace_info

• list_files

• read_file

• read_file_range

• search_filenames

• search_content

• git_status

• git_log

• git_diff

Modo workspace-write o command

• write_file

• trash_path

Solo modo command

• run_command

Restaurar archivos movidos a la papelera

La herramienta devuelve trashPath. Restaura con un comando local, por ejemplo:

mv "/tmp/workspaceguard-demo/.workspaceguard/trash/<id>/remove-me.txt" \
  "/tmp/workspaceguard-demo/remove-me.txt"

WorkspaceGuard no vacía la papelera automáticamente en esta versión para evitar borrados accidentales de datos.

Estructura

src/
├── config.ts                 # CLI/env và mode
├── security/path-policy.ts   # containment + sensitive-path policy
├── services/files.ts         # file/search/write/trash
├── services/git.ts           # Git read-only
├── services/process.ts       # process limits + tree cleanup
├── tools.ts                  # MCP schemas, annotations, audit
├── server.ts                 # stdio + HTTP loopback
├── desktop/                  # Electron main/preload + renderer an toàn
└── index.ts                  # CLI entry
tests/                        # unit, integration, MCP semantic smoke
docs/                         # phân tích source và lộ trình

Documentación adicional

• Análisis del proyecto FileMCP original

• Pasos de construcción del proyecto y hoja de ruta

• Modelo de seguridad

Licencia y fuentes de referencia

El proyecto usa Apache License 2.0. FileMCP también usa Apache-2.0; consulta NOTICE para conocer las fuentes de diseño de referencia. No se incluye el binario tunnel-client; el operador descarga la versión adecuada desde la fuente oficial de OpenAI.