# 🛡️ 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로 후원하기](https://github.com/sponsors/moosin76)**

후원은 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에서 지원합니다.

---

## 아키텍처

```text
                         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을 제공합니다.

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

---

## Remote MCP Provider

사용자마다 필요한 MCP가 다르므로 WSR은 특정 MCP 하나에 종속되지 않습니다.

예를 들어:

```text
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에게 다음처럼 요청할 수 있습니다.

```text
이 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는 선택적 의존성입니다.

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

Provider 연결 실패 때문에 WSR 전체가 종료되지 않습니다.

Provider-specific tool을 호출했을 때 연결되어 있지 않으면 명확한 오류를 반환합니다.

```text
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의 상태를 지속적으로 관리합니다.

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

기본값:

- 연결된 Provider health check: **10초**
- 연결되지 않은 Provider retry: **5초**

환경변수로 변경할 수 있습니다.

```env
MCP_PROVIDER_HEALTH_INTERVAL_MS=10000
MCP_PROVIDER_RETRY_INTERVAL_MS=5000
```

### MCP를 켰다 꺼도 자동으로 따라갑니다

```text
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`는 이 정보를 다시 해석해 작업 재개에 필요한 힌트를 구조화합니다.

```text
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에서 관리할 수 있습니다.

```env
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를 통해 조작할 수 있습니다.

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

지원 예:

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

---

## 설치

```cmd
git clone <repository-url>
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`를 모두 지원합니다.

```cmd
start.bat
```

```bash
./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를 확인합니다.

```text
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 생성을 완료합니다.

예시:

```text
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을 선택한 뒤 다음처럼 확인할 수 있습니다.

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

---

## 주요 환경변수

| 변수                              | 기본값                      | 설명                                   |
| :-------------------------------- | :-------------------------- | :------------------------------------- |
| `MCP_PORT`                        | `12000`                     | WSR HTTP 서버 포트                     |
| `MCP_WORKSPACE_FILE`              | 없음                        | Workspace JSON 파일. 첫 항목이 활성 Workspace |
| `MCP_WORKSPACE_ROOTS`             | 현재 경로                   | 레거시 한 줄 Multi-Workspace 형식             |
| `MCP_AUTH_TOKEN`                  | 없음                        | 인증용 토큰                            |
| `MCP_PUBLIC_URL`                  | 없음                        | 공개 기본 URL (`/mcp` 제외)          |
| `MCP_ENDPOINT`                    | `/mcp`                      | ChatGPT가 연결할 MCP 경로             |
| `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_NEEDLE_ENABLED`              | `false`                     | Needle 3 Fast Tool Router 활성화       |
| `MCP_NEEDLE_PYTHON`               | `python`                    | Needle sidecar Python 실행 명령        |
| `MCP_NEEDLE_CONFIDENCE_THRESHOLD` | `0.70`                      | 추천으로 인정할 최소 confidence       |
| `MCP_NEEDLE_TOOL_INDEX_PATH`      | `.cache/needle/wsr-tools.idx` | Needle Tool index 기준 경로          |
| `MCP_NEEDLE_REQUEST_TIMEOUT_MS`   | `60000`                     | Needle 요청 timeout(ms)                |
| `MCP_NEEDLE_MAX_CATALOG_TOOLS`    | `24`                        | Needle에 전달할 전체 Tool 상한         |
| `MCP_GODOT_ENABLED`               | `false`                     | Godot AI MCP Provider 활성화           |
| `MCP_GODOT_COMMAND`               | `uvx`                       | Godot AI attach 실행용 uvx 명령        |
| `MCP_GODOT_VERSION`               | `4.3.0`                     | Godot AI Python package 버전           |
| `MCP_GODOT_HTTP_PORT`             | `8001`                      | Godot AI HTTP 포트                     |
| `MCP_GODOT_WS_PORT`               | `8002`                      | Godot AI WebSocket 포트                |
| `MCP_BLENDER_ENABLED`             | `false`                     | Blender MCP Provider 활성화            |
| `MCP_BLENDER_COMMAND`             | `uvx`                       | Blender MCP stdio 실행 명령            |
| `MCP_BLENDER_VERSION`             | `1.0.3`                     | Blender Lab 공식 MCP 서버 버전         |
| `MCP_BLENDER_HOST`                | `127.0.0.1`                 | Blender add-on socket host             |
| `MCP_BLENDER_PORT`                | `9876`                      | Blender add-on socket port             |
| `MCP_WINDOWS_ENABLED`             | `false`                     | Windows Computer Use Provider 활성화   |
| `MCP_WINDOWS_COMMAND`             | `uvx`                       | Windows-MCP stdio 실행 명령            |
| `MCP_WINDOWS_TOOLS`               | UI allowlist                | WSR에 노출할 Windows-MCP 도구 목록     |
| `MCP_GAS_ENABLED`                 | `false`                     | Game Assets Studio MCP Provider 활성화 |
| `MCP_GAS_URL`                     | `http://127.0.0.1:52214/mcp` | GAS Desktop MCP endpoint               |

### Needle 3 Fast Tool Router

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

```bash
python -m pip install cactus-needle
```

```env
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에 커밋하지 마세요.

---

## 개발

```cmd
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와 실제 연결하여 다음 작업을 검증했습니다.

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

테스트 Scene:

```text
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`를 설정합니다.

```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 기존 기능과 겹치거나 권한 범위가 넓거나 현재 목적에 불필요해 기본적으로 노출하지 않습니다.

```env
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를 선택할 수 있습니다. 현재 검증된 구성은 다음과 같습니다.

| Provider | Endpoint | Transport | Tools |
| --- | --- | --- | ---: |
| Godot | `http://127.0.0.1:8000/mcp` | Streamable HTTP | 45 |
| Blender Lab 공식 MCP 1.0.3 | `uvx --python 3.12` → 공식 소켓 `127.0.0.1:9876` | stdio | 26 |
| Windows (CursorTouch/Windows-MCP) | `uvx windows-mcp serve` | stdio | 13 (기본 allowlist) |
| PostgreSQL (CrystalDBA postgres-mcp) | `http://127.0.0.1:10021/sse` | legacy SSE | 9 |
| Game Assets Studio (GAS) | `http://127.0.0.1:52214/mcp` | Streamable HTTP | 16 |

PostgreSQL Provider를 활성화하려면 루트 `.env`에 다음 값을 설정합니다.

```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로 연결할 수 있습니다.

```env
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가 주기적으로 재연결을 시도합니다.