🛡️ Windows Scoped Remote MCP Server

在 Windows 环境中运行的安全隔离型远程开发 MCP（Model Context Protocol）服务器。

可与 ChatGPT、Claude 等支持 MCP 的 LLM 客户端连接，以交互方式处理实际 Windows 开发环境中的文件、终端、进程、浏览器及多个 Workspace。

此外，还可以将 Godot、Blender 等独立的 Remote MCP 作为 Provider 连接，从而在一个 Gateway 中同时使用多种开发工具。

❤️ 项目赞助

如果 WSR 对您有帮助，可以通过 GitHub Sponsors 赞助本项目。

💖 前往 GitHub Sponsors 赞助

赞助将用于 WSR 的维护以及新 MCP Provider 和功能的开发。

主要特性

• Windows SandboxGuard — 在设定的 Workspace 边界内限制文件和命令执行。

• Multi-Workspace — 可注册多个项目并切换活动 Workspace。

• 文件/代码管理 — 支持查看、创建、修改、移动、复制、删除、应用 patch 等操作。

• PowerShell / CMD / 进程管理 — 管理开发命令执行和后台进程。

• Playwright 浏览器自动化 — 打开真实浏览器，执行导航、输入、点击、截图等操作。

• Remote MCP Provider — 可将 Godot、Blender 等所需的 MCP 添加到 Gateway。

• Provider 故障隔离 — 即使某个 MCP 关闭，WSR Core 和其他 Provider 仍可继续使用。

• Provider Scheduler — 定期检查 MCP 的连接状态和 tools/list，自动执行重连及 Tool Registry 更新。

• OAuth 2.1 / Cloudflare Tunnel 支持 — 提供可与远程 MCP 客户端安全连接的配置。

• MCP 2026-07-28 + legacy 兼容 — 在同一个 /mcp endpoint 上支持基于 server/discover 的最新无状态请求和 2025 initialize 流程。

Related MCP server: local-mcp

架构

                         ChatGPT / Claude
                                │
                         MCP / HTTPS
                                │
                       Cloudflare Tunnel
                                │
                                ▼
                 Windows Scoped Remote MCP Server
                                │
              ┌─────────────────┼─────────────────┐
              │                 │                 │
           Workspace        Playwright          Providers
              │                 │                 │
       Files / Process      Browser tools    ┌────┼─────┐
                                             │    │     │
                                           Godot Blender ...
                                             │    │
                                         godot_* blender_*

WSR 本身充当 Gateway 角色，外部 MCP 通过 RemoteMcpProvider 连接。

HTTP MCP 层使用官方 TypeScript SDK v2 的 createMcpHandler。对于 2026-07-28 客户端，提供 server/discover 和按请求的 _meta envelope；对于现有客户端，则使用相同的 tool 定义提供 2025-era 无状态 initialize fallback。

POST /mcp
  ├─ MCP 2026-07-28 → server/discover / per-request envelope
  └─ MCP 2025-era  → initialize / notifications/initialized

Remote MCP Provider

由于每个用户所需的 MCP 不同，WSR 不依赖于某一个特定的 MCP。

例如：

WSR
├── Godot MCP
├── Blender MCP
├── Playwright
└── 사용자가 추가한 MCP

每个 Provider 都使用 namespace。

例如，Blender MCP 的 get_scene 在 WSR 中以 blender_get_scene 形式暴露。

添加 MCP 的最简单方法

获取项目后，可以向 ChatGPT 提出如下请求。

이 windows-scoped-remote-mcp-server 프로젝트에 Blender MCP를 추가해줘.
AGENT.md와 skills/add-remote-mcp-provider/SKILL.md를 먼저 읽고
기존 RemoteMcpProvider / ProviderRegistry 구조를 따라 작업해줘.
Blender MCP의 연결 방법과 필요한 설정을 확인하고
blender_* namespace를 사용해줘.
테스트와 문서도 업데이트하고 typecheck와 전체 테스트까지 실행해줘.

详细步骤请参考 skills/add-remote-mcp-provider/SKILL.md。

即使 Provider 关闭，WSR 仍会继续运行

Remote MCP 是可选依赖。

Godot MCP OFF
     │
     ▼
Godot Provider = unavailable
     │
     ├── WSR Core       → 계속 사용 가능
     ├── Playwright     → 계속 사용 가능
     └── 다른 Provider  → 계속 사용 가능

Provider 连接失败不会导致整个 WSR 终止。

当调用 Provider 专属 tool 但未连接时，会返回明确的错误。

MCP provider 'godot' (godot) is not connected.
Start the godot MCP server/editor and try again.

当前状态可通过 mcp_provider_status tool 查看。

Provider Scheduler

WSR 在后台运行 ProviderScheduler，持续管理 Remote MCP 的状态。

                    ProviderScheduler
                           │
             ┌─────────────┴─────────────┐
             ▼                           ▼
        CONNECTED                    UNAVAILABLE
             │                           │
        tools/list                    reconnect
             │                           │
       변경 여부 확인                tools/list
             │                           │
             └─────────────┬─────────────┘
                           ▼
                    Tool Registry 갱신

默认值：

• 已连接 Provider 健康检查：10 秒

• 未连接 Provider 重试：5 秒

可通过环境变量修改。

MCP_PROVIDER_HEALTH_INTERVAL_MS=10000
MCP_PROVIDER_RETRY_INTERVAL_MS=5000

即使 MCP 开启或关闭，也会自动跟随

WSR 실행
   ↓
Godot OFF
   ↓
Provider unavailable
   ↓
Godot 실행
   ↓
Scheduler가 자동 발견
   ↓
tools/list
   ↓
godot_* Tool Registry 갱신

因此，无需为了开启或重新运行 Provider 而重启 WSR 本身。

当 Remote MCP 的 Tool 定义发生变化时，会比较 tools/list 结果并更新 Registry snapshot。

当前 HTTP 层采用每次 MCP 请求都构建 Server 的结构，因此下一次 tools/list 请求会反映最新的 Tool Registry。在长期会话中向客户端 UI 即时发送通知的 tools/list_changed notification 可在未来与会话管理结构一起扩展。

Multi-Workspace

可以在一个 WSR 中管理多个项目。

MCP_WORKSPACE_ROOTS=game:D:\Godot\MyGame,tools:D:\project\tools,reference:D:\project\reference
MCP_WORKSPACE_ROOT=D:\Godot\MyGame

当前活动 Workspace 用作默认工作目标，其他已注册 Workspace 可通过跨 Workspace 功能以读取/搜索/分析/复制为主使用。

超出 Workspace 边界的文件和命令访问将由 SandboxGuard 阻止。

Playwright

已集成 Playwright，可通过 MCP 操作真实浏览器。

ChatGPT
   ↓
"브라우저에서 페이지를 열고 버튼을 눌러줘"
   ↓
WSR
   ↓
Playwright
   ↓
실제 브라우저

支持示例：

• URL 跳转

• 元素点击

• 输入/表单填写

• 键盘输入

• 页面内容查看

• JavaScript 求值

• 截图

• 浏览器会话管理

安装

git clone <repository-url>
cd windows-scoped-remote-mcp-server
npm install
copy .env.example .env
npm run build
npm test

在 Windows 上还支持使用 start.bat 的方式。

start.bat

主要环境变量

敏感令牌和密码请仅保存在 .env 中，不要提交到 Git。

开发

npm run typecheck
npm test
npm run build

MCP SDK 使用 v2 split package 结构。

• 服务器及 createMcpHandler：@modelcontextprotocol/server

• Node/Express adapter：@modelcontextprotocol/node

• Remote Provider client：@modelcontextprotocol/client

• 现有内置 OAuth Authorization Server 兼容层：@modelcontextprotocol/server-legacy/auth

最后一项是官方 v1→v2 迁移桥接，处于 deprecated 状态。为保留 discovery 恢复和现有 OAuth 行为而保留，但长期应拆分为专用的 OAuth/IdP 库。

添加新 MCP Provider 时，建议先阅读以下文档。

• AGENT.md — 项目工作规则

• docs/mcp-gateway-architecture.md — Gateway / Provider 结构

• skills/add-remote-mcp-provider/SKILL.md — MCP 添加步骤

• skills/test-mcp-provider/SKILL.md — Provider 测试

• skills/debug-mcp-gateway/SKILL.md — MCP 问题排查

实际验证案例

目前 WSR 已与 Godot MCP 实际连接，验证了以下操作。

ChatGPT
  ↓
WSR
  ↓
Godot MCP
  ↓
Godot Editor
  ↓
Scene 생성 / 수정 / 저장

测试 Scene：

res://mcp_test.tscn

McpTest (Node3D)
├── TestCube (MeshInstance3D)
├── Camera3D
└── DirectionalLight3D

该流程是证明 WSR 不仅是简单的文件 MCP，而是连接实际开发工具的 Gateway 的代表性测试案例。

安全原则

WSR 为开发自动化提供了强大功能，因此重视以下原则。

• 通过 SandboxGuard 限制 Workspace 外部访问。

• 分离跨 Workspace 权限，避免修改其他 Workspace。

• 不将认证令牌和 Cloudflare Tunnel 令牌存储在源代码中。

• 不将安全功能表述为绝对的安全保障，而是基于设定的边界和权限模型进行说明。

• 隔离远程 MCP Provider 的单个故障，避免其导致整个 Gateway 故障。

License

MIT License

PostgreSQL MCP (CrystalDBA)

WSR 可以为每个 Remote MCP Provider 选择 transport。当前已验证的配置如下。

要启用 PostgreSQL Provider，请在根目录 .env 中设置以下值。

MCP_POSTGRESQL_ENABLED=true
MCP_POSTGRESQL_URL=http://127.0.0.1:10021/sse

Docker 运行环境位于 mcp-servers/postgres-mcp/ 中，实际的 DATABASE_URI 仅存放在该目录的 .env 中。DB 密码或实际连接字符串不会提交到 Git。

PostgreSQL MCP 提供的 9 个工具在应用 WSR namespace 后以 postgresql_* 形式暴露。实际连接中确认了 list_schemas、list_objects、get_object_details、explain_query、analyze_workload_indexes、analyze_query_indexes、analyze_db_health、get_top_queries、execute_sql。

详细的安装/操作方法请参考 docs/postgresql-mcp-provider.md 和 mcp-servers/postgres-mcp/README.md。