🛡️ Windows Scoped Remote MCP Server

在 Windows 环境中运行的安全隔离型远程开发 MCP（Model Context Protocol）服务器。
可与 ChatGPT、Claude 等最新 LLM 客户端联动，仅通过对话即可在指定的本地工作空间内自主执行文件创建/修改、PowerShell 命令执行、项目构建及调试等操作。

📌 主要特点

• Windows 优化沙箱（SandboxGuard）：

  • 100% 从源头阻断对指定 MCP_WORKSPACE_ROOT 目录之外的文件/文件夹访问及命令执行。

• ChatGPT 标准 OAuth 2.1 联动（RFC 8414 / RFC 9728 / DCR / PKCE）：

  • 提供动态客户端注册（DCR）及交互式安全授权页面（/authorize），仅允许知晓密码令牌（MCP_AUTH_TOKEN）的授权用户安全连接。

• 内置 19 种全栈 MCP 开发工具及 OpenAPI 3.0 规范：

  • 完整支持文件及目录 CRUD、补丁应用（apply_patch）、异步进程及 PowerShell/CMD 执行、状态监控。

• 基于 Cloudflare Tunnel 的 Zero Trust 通信：

  • 无需复杂的端口转发或开放防火墙，即可通过 Cloudflare Tunnel 提供安全的 HTTPS 端点。

• 支持项目无缝切换：

  • 只需在 .env 中更改 MCP_WORKSPACE_ROOT，即可在保持现有 ChatGPT 认证会话的情况下立即切换工作文件夹。

🏗️ 系统架构

┌────────────────────────────────────────────────────────┐
│                   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         │
└────────────────────────────────────────────────────────┘

🛠️ 提供的工具列表（共 30 个工具）

🌐 1. 浏览器自动化及 Web 测试工具（Playwright 8 个工具）

📂 2. 多工作空间管理工具（3 个工具）

📁 3. 文件及代码操作工具（11 个工具）

⚡ 4. 终端命令及脚本执行工具（8 个工具）

⚙️ 1. 环境配置指南（.env）

复制项目根目录下的 .env.example 文件，创建 .env 文件后进行配置：

copy .env.example .env

📋 主要配置项详细说明

# [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. Cloudflare Tunnel 及域名联动

本服务器通过 Cloudflare Zero Trust 隧道，将 .env 中指定的本地端口（MCP_PORT，默认值：12000）安全地暴露为您所拥有域名的子域名（https://mcp.yourdomain.com）。

🔌 Cloudflare 控制台设置

1. 进入 Cloudflare Zero Trust Dashboard ➔ Networks ➔ Tunnels 菜单。

2. 点击 [Create a tunnel] 创建 Cloudflared 隧道。

3. 添加 Public Hostname：

   • Subdomain：mcp（或您想要的子域名）

   • Domain：yourdomain.com（选择您拥有的域名）

   • Service Type：HTTP

   • URL：localhost:<MCP_PORT>（例如：localhost:12000）

4. 将颁发的**隧道令牌（Token）**复制并粘贴到 .env 的 CLOUDFLARE_TUNNEL_TOKEN 项中。

📦 3. Cloudflare 二进制文件（bin/cloudflared.exe）说明

本项目使用 cloudflared.exe 二进制文件来自动启动隧道。

• 支持自动下载（推荐）：

  • 首次运行 start.bat 或 start.ps1 时，如果 bin/cloudflared.exe 不存在，将自动从 Cloudflare 官方 GitHub Release 下载最新二进制文件并放置到位。

  • 用户无需单独下载，只需运行 start.bat 即可。

• 手动下载（离线 / 防火墙环境）：

  • 如果自动下载受限，请从 Cloudflare 官方发布页面下载 cloudflared-windows-amd64.exe 文件，然后重命名并放入项目内的 bin/cloudflared.exe 路径即可。

🚀 4. 服务器运行方法

方法 A. 一键自动运行（start.bat / 推荐）

双击 start.bat 或在控制台中运行：

start.bat

（自动完成 npm 包安装 ➔ 检查 .env ➔ 检查 cloudflared 二进制文件 ➔ TypeScript 构建并同时运行服务器 + 隧道）

方法 B. 手动终端运行

# 1. 의존성 설치
npm install

# 2. TypeScript 컴파일
npm run build

# 3. 테스트 실행
npm test

# 4. 서버 시작
npm start

🤖 5. ChatGPT 应用 / 插件连接指南（分步）

第 1 步. 注册 ChatGPT 应用

1. 访问 ChatGPT 网页，进入 [设置] ➔ [插件 / 开发者模式]。

2. 点击 [+ 新建插件 / 创建应用]。

3. 按如下方式输入设置值：

   • 名称：my-remote（或您想要的名称）

   • 连接（Connection）：服务器 URL ➔ https://mcp.yourdomain.com/mcp（您的域名）

   • 认证（Authentication）：选择 OAuth

4. 点击 [创建]。

第 2 步. 安全登录授权

1. 在已注册应用的详情页面中，点击 [连接 ➔] 按钮。

2. 浏览器弹出 [Windows Scoped Remote MCP 授权] 网页。

3. 在密码输入框中输入 .env 中设置的 MCP_AUTH_TOKEN 值，然后点击 [授权并返回 ChatGPT]。

第 3 步. 权限设置（"允许所有操作"）

• 将应用详情页面的**权限（Permissions）**选项设置为 允许所有操作。

• （这样每次调用工具时不会弹出确认窗口，ChatGPT 可以自主进行开发）

💬 6. 实战对话式开发提示词示例

在新聊天窗口（或 @ 插件 聊天窗口）中，可以按如下方式指示：

# 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. 多项目管理及实时切换方法

本服务器支持多工作空间（Multi-Workspace），可以同时注册多个项目，并在对话过程中实时切换。

方法 A. 通过 ChatGPT 对话实时切换（无需重启服务器 ⭐）

1. 确认当前工作空间：

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

2. 查看所有已注册项目列表：

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

3. 立即切换工作空间：

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

   （ChatGPT 调用 switch_workspace(name: "ether") 工具，无需重启服务器即可立即切换到该项目）

方法 B. 添加注册新项目（.env）

1. 在 .env 文件的 MCP_WORKSPACE_ROOTS 中添加新的项目别名和路径：

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

2. 在终端中重新运行 start.bat，即可立即访问和切换新增的项目。（OAuth 认证令牌会话将永久保留）

🔒 8. 安全及故障排除

• 问：是否存在外部人员未经授权访问我电脑的风险？

  • 通过三重安全结构得到完美保护：

    1. 密码认证：只有知道 MCP_AUTH_TOKEN 密码的您本人的 ChatGPT 账户才能访问。

    2. 沙箱隔离：文件和命令仅在指定的 MCP_WORKSPACE_ROOT 内运行，访问上级路径时立即阻断。

    3. Cloudflare Zero Trust：可以在 Cloudflare 控制台中添加仅允许您自己的 IP 访问的防火墙规则。

• 问：隧道无法连接或出现 502 错误时：

  • 请在 start.bat 窗口中确认本地服务器（port: .env 中的 MCP_PORT）是否正常启动，并在浏览器中访问 https://mcp.yourdomain.com/health，确认是否返回 { status: "ok" } 响应。

📄 许可证

MIT License