safe-workspace-mcp

Un servidor MCP mínimo y centrado en la seguridad que proporciona acceso de lectura/escritura estructurado a exactamente un espacio de trabajo local, con puntos de control Git locales integrados y reversión.

Diseñado para permitir que un modelo de chat (p. ej., ChatGPT con soporte MCP) edite archivos de forma segura en una carpeta de proyecto, y nada más.

Inicio rápido portable en Windows (sin Python, sin Git, sin Node)

1. Descarga el ZIP de la versión para Windows desde Releases y extráelo.

2. Prepara un directorio de espacio de trabajo (la única carpeta que el servidor puede tocar).

3. Obtén un ID de Secure MCP Tunnel de OpenAI (crearlo aquí) y una Runtime API Key (crearla aquí).

4. En la carpeta extraída, ejecuta:

   .\Start-SafeWorkspaceMCP.ps1 -Workspace "D:\ChatGPT_Workspace\demo" -TunnelId "tunnel_..."

5. Introduce la Runtime API Key cuando se solicite (entrada oculta, nunca se almacena).

6. Mantén la terminal abierta; Ctrl+C detiene todo.

7. Conecta el túnel existente desde el modo desarrollador de ChatGPT: es el paso que haces tú en la cuenta.

El lanzador descarga el cliente de túnel oficial de OpenAI (fijado en v0.0.11, verificado con SHA-256) en la primera ejecución y lo guarda en caché en %LOCALAPPDATA%\SafeWorkspaceMCP\. No requiere derechos de administrador ni cambios en PATH/registro. Consulta README-PORTABLE.md\ dentro del ZIP para más detalles.

Afirmación precisa: implementación local portable sin necesidad de instalar Python/Git/Node; el lanzador arranca automáticamente el cliente de túnel oficial de OpenAI probado. No es "configuración cero": tú aportas el espacio de trabajo, el ID de túnel, la Runtime API Key y la configuración de la cuenta de ChatGPT.

Related MCP server: git-mcp-server

Qué es

• Un proceso = una configuración = un espacio de trabajo fijo (elegido al iniciar, inmutable en tiempo de ejecución).

• CRUD estructurado de archivos de texto con transacciones atómicas de múltiples archivos.

• Concurrencia optimista: toda modificación de un archivo existente requiere su sha256 actual.

• Historial Git local gestionado (mediante Dulwich, nunca git.exe): puntos de control antes/después del cambio, diff, historial, restauración.

• Servidor MCP stdio, 9 herramientas en total.

No objetivos (estrictamente ausentes)

Sin shell, sin terminal, sin subprocesos, sin ejecución de código, sin compilador/ejector de pruebas/gestor de paquetes, sin herramientas HTTP o de red arbitrarias, sin Git remoto, sin cambio de espacio de trabajo, sin edición de binarios/imágenes, sin promesas de sandbox del sistema operativo.

Si una capacidad no aparece en la lista siguiente, este servidor no la tiene.

Arquitectura

ChatGPT / any MCP client
        │
OpenAI Secure MCP Tunnel (account-side, outbound-only)
        │
tunnel-client.exe            <- external deployment layer (official OpenAI binary,
        │                       pinned + SHA-256 verified by the launcher)
        │ MCP over stdio (child process)
        ▼
Safe Workspace MCP           <- this project (9 tools, no network, no exec)
        │
   fixed single workspace
        │
   ┌────┴─────────────┐
   │                   │
structured file CRUD   managed local Git checkpoints

• La búsqueda web / obtención de URL la realiza el propio anfitrión del chat; este servidor no tiene capacidad de red por diseño.

• El cliente de túnel es un componente de despliegue externo, no forma parte de este servidor: el proceso del servidor nunca abre sockets, y la única actividad de red del lanzador es descargar el cliente de túnel oficial fijado y verificado por checksum.

Las nueve herramientas

Las operaciones de apply_changes primero validan todo (rutas, hashes, política, conflictos de plan); si algo falla, no se aplica nada. Ante un fallo a mitad de ejecución, todo se revierte.

Instalación

Dos vías compatibles:

• Usuario final (Windows): descarga el ZIP de la versión portable: no requiere Python/Git/Node (ver inicio rápido arriba).

• Desarrollador / Linux: checkout del código fuente con Python 3.12+:

git clone https://github.com/Xs-trek/safe-workspace-mcp.git
cd safe-workspace-mcp
py -3.12 -m venv .venv
.venv\Scripts\pip install -e .

Dependencias en tiempo de ejecución: mcp==2.0.0 (SDK oficial), dulwich==1.2.6, librería estándar de Python. Nada más. Los prerrequisitos del usuario final para la versión portable son solo: Windows 10/11, PowerShell, internet para el túnel, una carpeta de espacio de trabajo, ID de túnel + Runtime API Key, y tu propia configuración de cuenta de ChatGPT.

Configuración

Archivo TOML, cargado una vez al inicio, inmutable después. No hay ninguna herramienta (ni ruta de código) que pueda cambiar la configuración, la raíz del espacio de trabajo o cualquier límite en tiempo de ejecución.

[workspace]
root = "D:/ChatGPT_Workspace/demo"
max_file_bytes = 2097152        # largest file the server will write/track
max_read_bytes = 1048576        # largest read returned / searched per file
max_transaction_bytes = 10485760
max_search_results = 200
excluded = ["node_modules", "build", "dist", ".venv"]  # plus built-ins

[paths]
reject_reparse_points = true    # symlinks/junctions/mounts: always recommended
reject_hardlinks = true
require_same_filesystem = true

[write]
allow_create_file = true
allow_modify_file = true
allow_delete_file = true
allow_move = true
allow_create_directory = true
allow_delete_empty_directory = true
require_expected_hash = true

[git]
mode = "managed"                # only mode in v0.1.0
author_name = "Safe Workspace MCP"
author_email = "safe-workspace-mcp@local"

[search]
include_hidden = false

[server]
transport = "stdio"             # only transport in v0.1.0

Consulta examples/ para las variantes mínima / fuente existente / fuente grande.

Espacio de trabajo gestionado

En el primer inicio con un directorio de origen vacío o simple (sin .git), el servidor:

1. escanea el directorio (solo se rastrean archivos de texto regulares),

2. inicializa un repositorio gestionado en <root>/.git,

3. crea el punto de control initial snapshot.

Si el espacio de trabajo ya contiene .git, el inicio falla con EXISTING_GIT_REPOSITORY_NOT_SUPPORTED. La adopción de repositorios existentes, árboles de trabajo, submódulos y remotos está fuera del alcance de v0.1.0.

Editable ⇒ Recuperable: todo archivo regular que el MCP pueda modificar o eliminar se rastrea en el repositorio gestionado, por lo que siempre se puede restaurar desde un punto de control. Los directorios excluidos (node_modules, artefactos de compilación, virtualenvs, …) son invisibles para todas las herramientas: no se pueden leer, escribir, buscar ni marcar como punto de control.

Ejecución

.venv\Scripts\safe-workspace-mcp path\to\config.toml

El servidor habla MCP por stdio y registra en stderr. Se niega a iniciar si la raíz del espacio de trabajo no existe o no es segura.

Múltiples proyectos

Un proceso sirve exactamente a un espacio de trabajo. Ejecuta varios procesos con varias configuraciones:

safe-workspace-mcp project-a.toml
safe-workspace-mcp project-b.toml

Importación de código fuente existente

Apunta workspace.root a un directorio de origen existente sin .git. La instantánea inicial confirma el estado actual como línea base; a partir de entonces el directorio está gestionado. Los directorios grandes generados deben añadirse a excluded.

Escenarios de uso portable (Windows)

• Primera ejecución en un PC nuevo: extrae el ZIP, crea/selecciona un espacio de trabajo, ejecuta el lanzador y proporciona las credenciales del túnel. El lanzador descarga y verifica automáticamente el cliente de túnel fijado.

• Segunda ejecución: mismo lanzador; el cliente de túnel en caché se reutiliza: sin descargas ni reinstalaciones.

• Cambio de proyectos: misma versión, distinta ruta -Workspace. Cada proceso MCP sigue sirviendo exactamente a un espacio de trabajo fijo (sin cambio en tiempo de ejecución).

• Instalación sin conexión (avanzado): descarga previamente el tunnel-client-<version>-windows-<arch>.zip oficial, verifícalo contra el SHA256SUMS.txt oficial y apunta -TunnelClientPath al oficial tunnel-client.exe extraído. Es una anulación avanzada para operadores: omite la garantía SHA-256 fijada por el lanzador (aunque la existencia y --version aún se comprueban). No es necesario para el uso normal.

Pruebas con MCP Inspector

npx @modelcontextprotocol/inspector .venv\Scripts\safe-workspace-mcp -- args/config.toml

(O mcp dev desde la CLI del SDK de MCP). Verifica que tools/list muestra exactamente nueve herramientas, que las anotaciones de solo lectura son correctas, y ejercita lectura → búsqueda → apply_changes → git_diff/git_history/git_restore contra un espacio de trabajo desechable primero.

Conexión con ChatGPT Desktop / ChatGPT Web

ChatGPT llega a un servidor MCP local a través del Secure MCP Tunnel de OpenAI (modo desarrollador / conectores). Este proyecto es solo el servidor stdio más un lanzador ejecutado por el operador: no contiene transporte de túnel, ni OAuth, ni almacenamiento de credenciales, y nunca lee ni escribe la configuración de ChatGPT/Codex.

Flujo recomendado:

1. Pasa la suite de pruebas local completa con un espacio de trabajo desechable (ver arriba).

2. Crea un Secure MCP Tunnel en la plataforma de OpenAI y ejecuta el lanzador portable (o tunnel-client run tú mismo) con ese ID de túnel.

3. En ChatGPT, conecta el túnel existente como conector de desarrollador/aplicación mientras la terminal del lanzador está en ejecución.

4. Usa primero un espacio de trabajo de prueba dedicado y luego cambia la configuración a tu proyecto real.

Configura siempre ChatGPT manualmente en su interfaz.

Resumen de seguridad

• Confinamiento del espacio de trabajo: solo rutas relativas al espacio de trabajo; se rechazan las travesías de directorio, las rutas absolutas/de unidad/UNC, los nombres de dispositivos reservados, los dos puntos de ADS y los nombres con punto/espacio final; la contención es consciente del sistema de archivos (basada en realpath), nunca en prefijos de cadena.

• Enlaces: cualquier punto de reanálisis (symlink, junction, mount, etiqueta desconocida) en cualquier componente de una ruta existente ⇒ denegar. Archivos regulares con enlaces duros (st_nlink > 1) ⇒ denegar.

• Aislamiento interno: .git es inaccesible a través de todas las herramientas de archivos; solo lo toca el almacén Git gestionado.

• Escrituras atómicas: archivo temporal hermano → fsync → validar → os.replace; una escritura fallida nunca trunca el original.

• Concurrencia optimista: expected_sha256 obsoleto ⇒ HASH_MISMATCH, el archivo más reciente del usuario nunca se sobrescribe.

• Sin ejecución / sin red: el código de producción no contiene uso de subprocesos/sockets (aplicado por AST mediante pruebas, escaneando cada módulo en busca de importaciones y llamadas); la ruta de ejecución incondicional de hooks de dulwich se neutraliza en el momento de la importación y se prueba con archivos de hook plantados; el repositorio gestionado nunca recibe hooks, filtros ni remotos.

• Límites de recursos: máximos de bytes para archivo/lectura/transacción y resultados de búsqueda; alcanzar un límite falla de forma segura (fail closed).

• Inyección de prompt: no resuelta, contenida: un modelo engañado solo puede realizar ediciones estructuradas y con puntos de control dentro de una carpeta, que siempre puedes revertir.

Consulta SECURITY.md y THREAT_MODEL.md para el análisis completo y los riesgos residuales.

Limitaciones conocidas (v0.1.0)

• Solo archivos de texto (UTF-8); los archivos binarios se rechazan.

• Windows es el objetivo de seguridad principal; Linux está soportado y probado en CI.

• No hay coordinación concurrente multicliente más allá de las comprobaciones de hash (ejecuta un solo escritor).

• El historial de puntos de control crece sin límite (sin gc en v0.1.0).

• Las restauraciones son a nivel de archivo; los directorios excluidos no se tocan al restaurar.

Reporte de seguridad

Por favor, abre un aviso de seguridad privado (GitHub "Report a vulnerability") en lugar de una incidencia pública.

Licencia

Apache-2.0 — consulta LICENSE.