MCP 服务器

Windows Scoped Remote MCP Server

Enables secure remote development on Windows by allowing LLM clients to manage files, run commands, and automate browsers within sandboxed workspaces, with multi-project switching and OAuth authentication.

README

🛡️ 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 호환 — 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를 통해 연결합니다.

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를 사용합니다.

MCP	Namespace 예시
Godot	`godot_*`
Blender	`blender_*`
Browser	`browser_*`
새로운 MCP	`<provider>_*`

예를 들어 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-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도 갱신합니다.

현재 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

주요 환경변수

변수	기본값	설명
`MCP_PORT`	`12000`	WSR HTTP 서버 포트
`MCP_WORKSPACE_ROOT`	현재 경로	활성 Workspace
`MCP_WORKSPACE_ROOTS`	`MCP_WORKSPACE_ROOT`	Multi-Workspace 목록
`MCP_AUTH_TOKEN`	없음	인증용 토큰
`MCP_PUBLIC_URL`	없음	공개 MCP URL
`CLOUDFLARE_TUNNEL_TOKEN`	없음	Cloudflare Tunnel 토큰
`MCP_BROWSER_HEADLESS`	`false`	Playwright Headless 여부
`MCP_PROVIDER_HEALTH_INTERVAL_MS`	`10000`	연결된 Provider 검사 주기(ms)
`MCP_PROVIDER_RETRY_INTERVAL_MS`	`5000`	연결되지 않은 Provider 재연결 주기(ms)
`MCP_GODOT_ENABLED`	`false`	Godot MCP Provider 활성화
`MCP_GODOT_URL`	`http://127.0.0.1:8000/mcp`	Godot MCP endpoint

민감한 토큰과 비밀번호는 .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은 개발 자동화를 위해 강력한 기능을 제공하므로 다음 원칙을 중요하게 취급합니다.

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

License

MIT License

PostgreSQL MCP (CrystalDBA)

WSR? Remote MCP Provider?? transport? ??? ? ????. ?? ??? ??? ??? ????.

Provider	Endpoint	Transport	Tools
Godot	`http://127.0.0.1:8000/mcp`	Streamable HTTP	45
PostgreSQL (CrystalDBA postgres-mcp)	`http://127.0.0.1:10021/sse`	legacy SSE	9

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? ?????.