🛡️ Windows Scoped Remote MCP Server

Servidor MCP (Model Context Protocol) de desarrollo remoto aislado y seguro que funciona en entornos Windows.
Se integra con clientes LLM modernos como ChatGPT, Claude, etc., y permite realizar de forma autónoma creación/modificación de archivos, ejecución de comandos de PowerShell, compilación y depuración de proyectos dentro de un espacio de trabajo local designado, solo mediante conversación.

📌 Características principales

• Sandbox optimizado para Windows (SandboxGuard):

  • Bloquea al 100% el acceso a archivos/carpetas y la ejecución de comandos fuera del directorio MCP_WORKSPACE_ROOT especificado.

• Integración OAuth 2.1 estándar de ChatGPT (RFC 8414 / RFC 9728 / DCR / PKCE):

  • Proporciona registro dinámico de clientes (DCR) y una página de aprobación de seguridad interactiva (/authorize), de modo que solo los usuarios autorizados que conozcan el token de contraseña (MCP_AUTH_TOKEN) puedan conectarse de forma segura.

• 19 herramientas de desarrollo MCP full-stack y especificación OpenAPI 3.0:

  • Soporte completo para CRUD de archivos y directorios, aplicación de parches (apply_patch), ejecución de procesos asíncronos y PowerShell/CMD, y monitoreo de estado.

• Comunicación Zero Trust basada en Cloudflare Tunnel:

  • Proporciona un endpoint HTTPS seguro a través de Cloudflare Tunnel sin necesidad de reenvío de puertos complejo ni apertura de firewall.

• Soporte de cambio de proyecto sin interrupciones:

  • Al cambiar solo MCP_WORKSPACE_ROOT en .env, puede cambiar inmediatamente la carpeta de trabajo manteniendo la sesión de autenticación de ChatGPT existente.

🏗️ Arquitectura del sistema

┌────────────────────────────────────────────────────────┐
│                   ChatGPT (Web / App)                  │
└───────────────────────────┬────────────────────────────┘
                            │ HTTPS (Streamable HTTP / OAuth 2.1)
                            ▼
┌────────────────────────────────────────────────────────┐
│        Cloudflare Zero Trust Tunnel (mcp.yourdomain)   │
└───────────────────────────┬────────────────────────────┘
                            │ Local Proxy (HTTP localhost:<MCP_PORT>)
                            ▼
┌────────────────────────────────────────────────────────┐
│            Windows Scoped Remote MCP Server            │
│  ┌──────────────────────────────────────────────────┐  │
│  │ Express Router (/mcp, /authorize, /openapi.json) │  │
│  └────────────────────────┬─────────────────────────┘  │
│                           │                            │
│  ┌────────────────────────▼─────────────────────────┐  │
│  │   SandboxGuard & ProcessManager & FileService    │  │
│  └────────────────────────┬─────────────────────────┘  │
└───────────────────────────┼────────────────────────────┘
                            │ 격리된 파일 & 명령어 실행
                            ▼
┌────────────────────────────────────────────────────────┐
│       내 로컬 작업 공간 (MCP_WORKSPACE_ROOT)            │
│      예: D:\Godot\mcp-test 또는 D:\Godot\MyGame         │
└────────────────────────────────────────────────────────┘

🛠️ Lista de herramientas proporcionadas (30 herramientas en total)

🌐 1. Herramientas de automatización de navegador y pruebas web (8 herramientas de Playwright)

📂 2. Herramientas de gestión de múltiples espacios de trabajo (3 herramientas)

📁 3. Herramientas de manipulación de archivos y código (11 herramientas)

⚡ 4. Herramientas de ejecución de comandos de terminal y scripts (8 herramientas)

⚙️ 1. Guía de configuración del entorno (.env)

Copie el archivo .env.example en la raíz del proyecto para crear el archivo .env y configúrelo:

copy .env.example .env

📋 Descripción detallada de los elementos de configuración principales

# [Server Port]
MCP_PORT=12000

# [Multi-Root Security & Directory Sandbox]
MCP_WORKSPACE_ROOTS=test:C:\path\to\mcp-test, ether:C:\path\to\ether-chronicle, server:C:\path\to\localRemoteMcp

# [Authentication - ChatGPT OAuth 2.1]
MCP_AUTH_TOKEN=your_secure_password_here

# [Public Domain & Cloudflare Tunnel]
MCP_PUBLIC_URL=https://mcp.yourdomain.com
CLOUDFLARE_TUNNEL_TOKEN=your_cloudflare_tunnel_token_here

# [Shell Configuration]
MCP_DEFAULT_SHELL=powershell

# [Limits - Safety Guardrails]
MCP_MAX_FILE_CHUNK_BYTES=1048576
MCP_MAX_EDIT_FILE_BYTES=67108864
MCP_MAX_OUTPUT_BYTES=1048576

🌐 2. Integración de Cloudflare Tunnel y dominio

Este servidor expone de forma segura el puerto local (MCP_PORT, predeterminado: 12000) especificado en .env a través de un túnel de Cloudflare Zero Trust en el subdominio de su dominio (https://mcp.yourdomain.com).

🔌 Configuración en el panel de Cloudflare

1. Vaya al menú Cloudflare Zero Trust Dashboard ➔ Networks ➔ Tunnels.

2. Haga clic en [Create a tunnel] para crear un túnel de Cloudflared.

3. Agregue un Public Hostname:

   • Subdomain: mcp (o el subdominio que desee)

   • Domain: yourdomain.com (seleccione su dominio)

   • Service Type: HTTP

   • URL: localhost:<MCP_PORT> (por ejemplo, localhost:12000)

4. Copie el token del túnel (Token) emitido y péguelo en el campo CLOUDFLARE_TUNNEL_TOKEN de .env.

📦 3. Binario de Cloudflare (bin/cloudflared.exe)

Este proyecto utiliza el binario cloudflared.exe para iniciar el túnel automáticamente.

• Soporte de descarga automática (recomendado):

  • Al ejecutar start.bat o start.ps1 por primera vez, si bin/cloudflared.exe no existe, descarga automáticamente el binario más reciente desde la versión oficial de Cloudflare GitHub Release y lo coloca en su lugar.

  • No es necesario que el usuario descargue nada; solo ejecute start.bat.

• Descarga manual (entornos sin conexión / con firewall):

  • Si el entorno restringe la descarga automática, descargue el archivo cloudflared-windows-amd64.exe desde la página de versiones oficiales de Cloudflare y colóquelo en la ruta bin/cloudflared.exe dentro del proyecto, renombrándolo si es necesario.

🚀 4. Métodos de ejecución del servidor

Método A. Ejecución automática con un clic (start.bat / recomendado)

Haga doble clic en start.bat o ejecútelo desde la consola:

start.bat

(Instala automáticamente los paquetes npm ➔ verifica .env ➔ verifica el binario de cloudflared ➔ compila TypeScript y ejecuta el servidor + túnel a la vez)

Método B. Ejecución manual desde terminal

# 1. 의존성 설치
npm install

# 2. TypeScript 컴파일
npm run build

# 3. 테스트 실행
npm test

# 4. 서버 시작
npm start

🤖 5. Guía de conexión de la aplicación / complemento de ChatGPT (paso a paso)

Paso 1. Registro de la aplicación de ChatGPT

1. Acceda a ChatGPT web y vaya a [Configuración] ➔ [Complementos / Modo desarrollador].

2. Haga clic en [+ Crear nuevo complemento / aplicación].

3. Ingrese los valores de configuración de la siguiente manera:

   • Nombre: my-remote (o el nombre que desee)

   • Conexión (Connection): URL del servidor ➔ https://mcp.yourdomain.com/mcp (su dominio)

   • Autenticación (Authentication): seleccione OAuth

4. Haga clic en [Crear].

Paso 2. Aprobación de inicio de sesión seguro

1. En la pantalla de detalles de la aplicación registrada, presione el botón [Conectar ➔].

2. Aparecerá una ventana emergente del navegador con la página web [Aprobación de Windows Scoped Remote MCP].

3. Ingrese el valor de MCP_AUTH_TOKEN configurado en .env en el campo de contraseña y haga clic en [Aprobar y volver a ChatGPT].

Paso 3. Configuración de permisos ("Permitir todas las acciones")

• Configure la opción de Permisos (Permissions) en la pantalla de detalles de la aplicación como Permitir todas las acciones.

• (De esta manera, ChatGPT no mostrará una ventana emergente de confirmación cada vez que se llame a una herramienta y podrá realizar el desarrollo de forma autónoma)

💬 6. Ejemplos de indicaciones de desarrollo conversacional en la práctica

En una nueva ventana de chat (o en la ventana de chat de @ complemento), puede indicar lo siguiente:

# 1. 프로젝트 파일 목록 및 구조 파악
@my-remote 현재 작업 공간의 파일과 폴더 목록을 정리해서 보여줘

# 2. 웹 게임 / 프론트엔드 프로젝트 개발
@my-remote HTML5 Canvas로 브라우저에서 실행 가능한 레트로풍 벽돌깨기 게임(breakout.html)을 세련되게 만들어줘

# 3. Godot 4 게임 스크립트 작성
@my-remote Godot 4 기준으로 2D 캐릭터 이동, 대시, 점프 및 물리 충돌을 처리하는 Player.gd를 작성해줘

# 4. 패키지 설치 및 테스트 실행
@my-remote npm install 명령어로 필요한 라이브러리를 설치하고 npm test를 돌려 결과를 확인해줘

# 5. 웹 브라우저 자동화 & 화면 캡처 (Playwright)
@my-remote 네이버(naver.com)로 이동해서 검색창에 'Godot Engine 4' 검색하고 결과 페이지 스크린샷 찍어서 search.png로 저장해줘

# 6. 내가 만든 로컬 웹페이지 실시간 검증
@my-remote 로컬 웹서버를 실행하고 브라우저로 접속해서 [게임 시작] 버튼을 누른 다음 화면이 잘 나오는지 스크린샷으로 확인해줘

📂 7. Gestión de múltiples proyectos y método de cambio en tiempo real

Este servidor admite múltiples espacios de trabajo (Multi-Workspace), por lo que puede registrar varios proyectos simultáneamente y cambiar entre ellos en tiempo real durante la conversación.

Método A. Cambio en tiempo real mediante conversación con ChatGPT (sin reiniciar el servidor ⭐)

1. Verificar el espacio de trabajo actual:

   @my-remote 현재 작업 공간이 어디로 설정되어 있는지 확인해줘

2. Ver la lista completa de proyectos registrados:

   @my-remote 등록된 모든 워크스페이스 목록을 보여줘

3. Cambiar inmediatamente de espacio de trabajo:

   @my-remote ether 프로젝트로 작업 공간을 전환해줘

   (ChatGPT llama a la herramienta switch_workspace(name: "ether") para cambiar inmediatamente a ese proyecto sin reiniciar el servidor)

Método B. Agregar un nuevo proyecto (.env)

1. Agregue un nuevo alias y ruta de proyecto a MCP_WORKSPACE_ROOTS en el archivo .env:

   MCP_WORKSPACE_ROOTS=test:C:\path\to\mcp-test, ether:C:\path\to\ether-chronicle, mygame:C:\path\to\mygame

2. Vuelva a ejecutar start.bat en la terminal y los proyectos agregados estarán disponibles de inmediato para acceso y cambio. (La sesión de token de autenticación OAuth se conserva permanentemente)

🔒 8. Seguridad y solución de problemas

• P. ¿No hay riesgo de que personas externas accedan sin autorización a mi computadora?

  • Está completamente protegido por una estructura de seguridad de 3 capas:

    1. Autenticación por contraseña: Solo su cuenta de ChatGPT, que conoce la contraseña MCP_AUTH_TOKEN, puede acceder.

    2. Aislamiento de sandbox: Los archivos y comandos solo funcionan dentro del MCP_WORKSPACE_ROOT especificado; cualquier acceso a rutas superiores se bloquea inmediatamente.

    3. Cloudflare Zero Trust: Puede agregar reglas de firewall en el panel de Cloudflare para permitir solo su IP.

• P. ¿Qué hago si el túnel no se conecta o aparece un error 502?

  • Verifique en la ventana de start.bat que el servidor local (port: MCP_PORT de .env) esté funcionando correctamente y acceda a https://mcp.yourdomain.com/health en el navegador para confirmar que responde { status: "ok" }.

📄 Licencia

Licencia MIT