🛡️ 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를 전환할 수 있으며, ChatGPT/MCP 세션별로 활성 Workspace 상태가 독립됩니다.
• 파일/코드 관리 — 조회, 생성, 수정, 이동, 복사, 삭제, patch 적용 등을 지원합니다.
• PowerShell / CMD / 프로세스 관리 — 개발 명령 실행과 백그라운드 프로세스를 관리합니다.
• Playwright 브라우저 자동화 — 실제 브라우저를 열고 탐색, 입력, 클릭, 스크린샷 등을 수행합니다.
• Remote MCP Provider — Godot, Blender 등 원하는 MCP를 Gateway에 추가할 수 있습니다.
• Provider 장애 격리 — 하나의 MCP가 꺼져 있어도 WSR Core와 다른 Provider는 계속 사용할 수 있습니다.
• Provider Scheduler — MCP의 연결 상태와 tools/list를 주기적으로 확인하고 자동 재연결 및 Tool Registry 갱신을 수행합니다.
• Provider Tool 변경 알림 — Remote MCP의 Tool 목록이 바뀌면 지원하는 modern MCP 클라이언트에 tools/list_changed 알림을 전달합니다.
• Project Handoff / Resume — workspace_context와 workspace_resume으로 Git, AGENTS, Roadmap, Session 문서를 기반으로 다른 AI/세션에서 작업 상태를 이어받을 수 있습니다.
• WSR 운영 진단 — wsr_status 하나로 WSR, Workspace, Provider, Browser, cloudflared 및 인증 설정 상태를 비밀값 없이 확인할 수 있습니다.
• OAuth 2.1 / Cloudflare Tunnel 지원 — 원격 MCP 클라이언트와 안전하게 연결할 수 있는 구성을 제공합니다.
• MCP 2026-07-28 + legacy 호환 — server/discover 기반 최신 stateless 요청과 2025 initialize 흐름을 같은 /mcp endpoint에서 지원합니다.

---

아키텍처

                         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를 통해 연결합니다. Provider transport는 Streamable HTTP, legacy SSE, local stdio를 지원합니다.

HTTP MCP 계층은 공식 TypeScript SDK v2의 createMcpHandler를 사용합니다. 2026-07-28 클라이언트에는 server/discover와 요청별 _meta envelope를 제공하고, 기존 클라이언트에는 같은 tool 정의로 2025-era stateless 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를 추가해줘.
AGENTS.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-specific 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 health check: 10초
• 연결되지 않은 Provider retry: 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도 갱신합니다.

Remote MCP의 Tool 정의가 바뀌면 Registry snapshot을 갱신한 뒤, 지원하는 modern MCP 클라이언트에는 표준 tools/list_changed 알림을 fan-out합니다. 알림을 지원하지 않는 legacy 클라이언트도 다음 tools/list 요청에서 최신 Registry를 받습니다. Provider의 실행/종료나 Tool 목록 변경 때문에 WSR 자체를 다시 시작할 필요는 없습니다.

---

프로젝트 작업 인계와 재개

WSR은 Codex, ChatGPT/WSR 등 서로 다른 AI 작업 환경 사이에서 대화 기록이 아니라 저장소 자체를 공통 기준으로 사용합니다.

공통 기준은 Git 상태, AGENTS.md, Roadmap, TODO, Session/Handoff 문서입니다.

workspace_context는 등록된 Workspace를 전환하지 않고 다음 정보를 read-only로 수집합니다.

• 현재 Git branch / HEAD / dirty 상태 / 최근 commit
• AGENTS.md 또는 AGENT.md
• Roadmap
• 최근 Session/Handoff 문서
• TODO 문서

workspace_resume는 이 정보를 다시 해석해 작업 재개에 필요한 힌트를 구조화합니다.

workspace_context(workspace="ec")
workspace_resume(workspace="ec")

→ branch/session 불일치 경고
→ dirty 변경 영역 요약
→ Roadmap의 다음 작업
→ 최신 handoff 기준 resume summary

두 Tool 모두 대상 Workspace를 전환하거나 수정하지 않습니다. 따라서 ChatGPT에서 다른 프로젝트의 상태를 확인하면서 현재 활성 Workspace를 그대로 유지할 수 있습니다.

자세한 동작은 docs/workspace-context.md와 docs/workspace-resume.md를 참고하세요.

---

WSR 운영 상태 진단

wsr_status는 여러 개의 진단 Tool을 따로 호출하지 않고 WSR의 핵심 운영 상태를 한 번에 확인하는 read-only Tool입니다.

주요 정보:

• WSR version / Git commit / uptime / Node version
• active Workspace와 등록 Workspace 수
• Provider 연결 상태와 Tool 개수
• Browser manager 초기화/페이지 상태
• cloudflared 설치 및 버전
• public endpoint, OAuth, static auth, Tunnel token의 설정 여부
• 운영상 주의가 필요한 warning

응답에는 실제 token/password/cookie/session 값이나 Provider raw error를 포함하지 않습니다. WSR 시작 로그와 Tunnel 연결 로그 역시 Bearer token 원문을 출력하지 않습니다.

자세한 내용은 docs/wsr-status.md를 참고하세요.

---

Multi-Workspace

여러 프로젝트를 하나의 WSR에서 관리할 수 있습니다.

MCP_WORKSPACE_FILE=workspaces.local.json

workspaces.example.json을 workspaces.local.json으로 복사한 뒤 Workspace를 한 항목씩 등록합니다. 파일에 등록된 첫 번째 Workspace가 자동으로 활성 Workspace가 됩니다. 별도의 MCP_WORKSPACE_ROOT 설정은 필요하지 않습니다. 기존 MCP_WORKSPACE_ROOTS 한 줄 형식은 호환성을 위해 계속 지원됩니다.

활성 Workspace 상태는 MCP 세션별로 독립됩니다. 따라서 서로 다른 ChatGPT 채팅에서 각각 game, tools처럼 다른 Workspace를 선택해도 switch_workspace 상태가 다른 채팅으로 전파되지 않습니다. MCP 2025-era는 Mcp-Session-Id, ChatGPT의 MCP 2026-07-28 연결은 x-openai-session을 기준으로 세션을 구분합니다.

Workspace 경계를 벗어난 파일 및 명령 접근은 SandboxGuard가 차단합니다. 세부 구현은 docs/session-scoped-workspaces.md를 참고하세요.

---

Playwright

Playwright가 통합되어 실제 브라우저를 MCP를 통해 조작할 수 있습니다.

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

지원 예:

• URL 이동
• 요소 클릭
• 입력/폼 작성
• 키보드 입력
• 페이지 내용 조회
• JavaScript 평가
• 스크린샷
• 브라우저 세션 관리

---

설치

git clone 
cd windows-scoped-remote-mcp-server
npm install
copy .env.example .env
copy workspaces.example.json workspaces.local.json
npm run build
npm test

Windows에서는 CMD/PowerShell용 start.bat와 Git Bash용 start.sh를 모두 지원합니다.

start.bat

./start.sh
# 또는
bash start.sh

두 시작 스크립트는 uvx가 없으면 Astral 공식 설치 스크립트로 uv/uvx 설치를 시도하고, 현재 프로세스 PATH에 %USERPROFILE%\.local\bin을 반영합니다. 또한 bin\cloudflared.exe가 없으면 최신 Windows 64-bit 바이너리를 내려받습니다. 바이너리가 준비된 뒤에는 현재 버전을 표시하고 cloudflared update로 공식 업데이트 서버를 확인합니다. 업데이트 확인이 실패해도 기존 바이너리로 WSR 시작을 계속합니다.

WSR의 Windows 기본 셸은 자동으로 선택됩니다. Git Bash가 설치되어 있으면 PATH 등록 여부와 관계없이 일반적인 Git for Windows 설치 경로까지 탐색해 Git Bash를 우선 사용합니다. Git Bash를 찾지 못하면 PowerShell 7(pwsh)을 사용하며, PowerShell 7도 없으면 winget으로 설치를 시도합니다.

---

ChatGPT에 WSR 연결

최근 ChatGPT에서는 WSR 같은 Remote MCP 서버를 먼저 Custom MCP app으로 등록합니다. 필요하다면 이 MCP app을 별도의 Plugin 구성에 포함할 수 있지만, WSR 자체 연결 절차는 MCP app 생성 흐름을 기준으로 설명합니다.

먼저 WSR과 Cloudflare Tunnel을 실행한 상태에서 실제 MCP endpoint를 확인합니다.

MCP_PUBLIC_URL=https://mcp.example.com
MCP_ENDPOINT=/mcp

ChatGPT에 입력할 MCP endpoint:
https://mcp.example.com/mcp

중요: MCP_PUBLIC_URL은 기본 공개 URL이며 기본 MCP 경로 /mcp를 포함하지 않습니다. ChatGPT에 등록할 때는 MCP_PUBLIC_URL + MCP_ENDPOINT를 사용합니다. MCP_ENDPOINT를 따로 바꾸지 않았다면 기본값은 /mcp입니다.

ChatGPT 쪽 등록 절차는 다음과 같습니다.

1. ChatGPT의 Settings → Apps → Create로 이동합니다. 관리형 Workspace에서는 Workspace Settings → Apps → Create 경로를 사용할 수 있습니다.
2. 계정/Workspace 정책상 필요한 경우 Developer mode를 활성화합니다. 메뉴 위치는 플랜과 Workspace 권한에 따라 Settings → Apps → Advanced Settings 또는 Workspace 설정에 있을 수 있습니다.
3. 새 Custom MCP app을 만들고 이름(예: wsr)과 MCP endpoint를 입력합니다.
4. 인증 방식은 OAuth를 선택합니다.
5. Scan Tools를 실행합니다. WSR OAuth 승인 화면이 열리면 .env의 MCP_AUTH_TOKEN 값을 입력하고 승인합니다.
6. Tool scan이 끝나면 app 생성을 완료합니다.

예시:

Name: wsr
MCP endpoint: https://mcp.example.com/mcp
Authentication: OAuth

Godot, Blender 등 Provider를 새로 활성화하거나 Provider 버전 변경으로 Tool 목록이 바뀌면 ChatGPT의 WSR app 설정에서 Refresh / Scan Tools를 다시 실행해야 합니다. ChatGPT는 승인된 MCP Tool 구성을 자동으로 즉시 갱신하지 않을 수 있습니다.

연결 후에는 새 채팅에서 WSR app을 선택한 뒤 다음처럼 확인할 수 있습니다.

"WSR 상태 확인해줘"              → wsr_status
"워크스페이스 목록 확인해줘"     → list_workspaces
"Provider 연결 상태 확인해줘"    → mcp_provider_status

---

주요 환경변수

Needle 3 Fast Tool Router

Needle은 선택 기능이며 기본적으로 비활성화됩니다. 활성화하려면 먼저 로컬 Python에 cactus-needle을 설치하고 다음처럼 설정합니다.

python -m pip install cactus-needle

MCP_NEEDLE_ENABLED=true
MCP_NEEDLE_PYTHON=python
MCP_NEEDLE_CONFIDENCE_THRESHOLD=0.70

needle_route는 Tool을 실행하지 않고 추천만 반환합니다. AI 클라이언트는 사용자의 언어와 관계없이 요청을 짧은 영어 canonical command로 정규화해서 query에 넣고, 원문은 필요하면 originalQuery로 함께 전달합니다. Workspace alias, 경로, URL, branch, object/schema/table 이름 같은 literal 값은 번역하지 않습니다.

Provider가 명확한 요청은 scope="providers"와 providerId로 좁히고, Core 요청은 scope="core"를 사용합니다. confidence가 threshold 미만이거나 escalate=true면 일반 LLM reasoning으로 fallback합니다.

민감한 토큰과 비밀번호는 .env에만 저장하고 Git에 커밋하지 마세요.

---

개발

npm run typecheck
npm test
npm run build

MCP SDK는 v2 split package 구조를 사용합니다.

• 서버 및 createMcpHandler: @modelcontextprotocol/server
• Node/Express adapter: @modelcontextprotocol/node
• Streamable HTTP Provider client: @modelcontextprotocol/client
• legacy SSE / stdio Provider compatibility client: @modelcontextprotocol/sdk
• 기존 내장 OAuth Authorization Server 호환 계층: @modelcontextprotocol/server-legacy/auth

마지막 항목은 공식 v1→v2 마이그레이션 브리지이며 deprecated 상태입니다. discovery 복구와 기존 OAuth 동작 보존을 위해 유지하되, 장기적으로는 전용 OAuth/IdP 라이브러리로 분리해야 합니다.

새 MCP Provider를 추가할 때는 다음 문서를 먼저 읽는 것을 권장합니다.

• AGENTS.md — 프로젝트 작업 규칙
• docs/mcp-gateway-architecture.md — Gateway / Provider 구조
• docs/workspace-context.md — Workspace 작업 상태 수집
• docs/workspace-resume.md — 작업 재개 힌트
• docs/provider-tool-change-notifications.md — Provider Tool 변경 알림
• docs/wsr-status.md — WSR 운영 진단
• 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은 개발 자동화를 위해 강력한 기능을 제공하므로 다음 원칙을 중요하게 취급합니다.

• Workspace 외부 접근을 SandboxGuard로 제한합니다.
• 다른 Workspace를 수정하지 않도록 교차 Workspace 권한을 분리합니다.
• 인증 토큰과 Cloudflare Tunnel 토큰을 소스 코드에 저장하지 않으며, 운영 로그에도 Bearer token 원문을 출력하지 않습니다.
• 보안 기능을 절대적인 안전 보장으로 표현하지 않고 설정된 경계와 권한 모델을 기준으로 설명합니다.
• 원격 MCP Provider 하나의 장애가 전체 Gateway 장애로 이어지지 않도록 격리합니다.

---

License

MIT License

Blender Lab 공식 MCP

WSR은 Blender Lab 공식 MCP 서버를 로컬 stdio Provider로 실행합니다. Blender의 Preferences → Get Extensions에서 Blender Lab 저장소의 MCP 확장 기능을 설치하고 활성화합니다. Blender 확장 기능의 9876 소켓은 MCP HTTP 엔드포인트가 아닙니다. WSR은 공식 Python MCP 서버를 stdio로 실행하여 이 소켓에 연결합니다.

Blender 확장 기능 Preferences에서 Server is running을 확인하고, uvx 및 Python 3.12를 준비한 뒤 루트 .env를 설정합니다.

MCP_BLENDER_ENABLED=true
MCP_BLENDER_COMMAND=uvx
MCP_BLENDER_VERSION=1.0.3
MCP_BLENDER_HOST=127.0.0.1
MCP_BLENDER_PORT=9876

공식 MCP 서버는 https://projects.blender.org/lab/blender_mcp의 v1.0.3 소스를 uvx --python 3.12로 실행합니다. 소켓 통신 환경변수는 BLENDER_MCP_HOST, BLENDER_MCP_PORT입니다. 연결된 도구는 blender_* namespace로 노출됩니다. 자세한 내용은 docs/blender-mcp-provider.md를 참고하세요.

---

Windows Computer Use MCP

WSR은 CursorTouch/Windows-MCP를 local stdio Provider로 실행할 수 있습니다. 별도 소스를 mcp-servers/에 복사하지 않고 uvx windows-mcp serve를 사용하므로, 첫 WSR 시작 시 uv가 패키지와 의존성을 내려받아 캐시하고 이후 WSR 수명과 함께 실행/종료합니다.

기본 allowlist는 Windows 화면 관찰과 UI 입력에 필요한 도구만 유지합니다. App, PowerShell, FileSystem, Process, Notification, Registry, Scrape는 WSR 기존 기능과 겹치거나 권한 범위가 넓거나 현재 목적에 불필요해 기본적으로 노출하지 않습니다.

MCP_WINDOWS_ENABLED=true
MCP_WINDOWS_COMMAND=uvx
MCP_WINDOWS_TOOLS=DisplayInventory,Snapshot,Screenshot,Click,Type,Scroll,Move,Shortcut,Wait,WaitFor,MultiSelect,MultiEdit,Clipboard

Provider 실행 환경에서는 Python UTF-8 모드를 강제하고 Windows-MCP 익명 telemetry를 끄며 screenshot flash overlay도 비활성화합니다. 연결된 도구는 windows_* namespace로 노출됩니다. 자세한 내용은 docs/windows-computer-use-provider.md를 참고하세요.

---

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를 참고하세요.

Game Assets Studio MCP

GAS Desktop이 실행 중이면 WSR은 고정 localhost endpoint를 Streamable HTTP Provider로 연결할 수 있습니다.

MCP_GAS_ENABLED=true
MCP_GAS_URL=http://127.0.0.1:52214/mcp

GAS 자체 MCP는 별도 Bearer 인증 없이 127.0.0.1에만 바인딩됩니다. WSR에서는 Provider id/namespace 모두 gas를 사용하며 원격 job_list 같은 Tool은 gas_job_list 형태로 노출됩니다. GAS Desktop이 꺼져 있어도 WSR Core와 다른 Provider는 계속 동작하고 Scheduler가 주기적으로 재연결을 시도합니다.