WorkspaceGuard MCP

WorkspaceGuard MCP는 로컬, 크로스 플랫폼 MCP 서버로, ChatGPT 또는 MCP 클라이언트가 지정된 하나의 workspace에서 작업할 수 있게 해줍니다. 이 프로젝트는 FileMCP를 연구한 후 새로 구축되었으며, 유용한 보안 원칙을 유지하고 첫 버전에 아직 필요하지 않은 부분은 줄였습니다.

무엇에 사용하나요?

• 파일별 또는 줄 단위로 나열, 읽기, 이름 검색 및 내용 검색.

• 원자적(atomic) 방식으로 파일 쓰기, dry_run 및 expected_sha256 지원으로 최신 변경 사항 덮어쓰기 방지.

• .workspaceguard/trash로 이동하여 "삭제", 수동 복원 가능.

• 셸을 활성화하지 않고 Git status, log 및 diff 읽기.

• 선택적으로 program + args로 터미널 실행, 셸을 통한 문자열 연결 없이 allowlist의 실행 파일만 허용.

• stdio 또는 127.0.0.1의 토큰이 있는 MCP Streamable HTTP를 통해 사용.

• 파일 내용이나 전체 명령 매개변수를 저장하지 않는 audit JSONL 기록.

Related MCP server: Kastor

주요 개선 사항

이 앱은 workspace 선택, 모드 선택, command allowlist 선택, 서버 시작/중지, 앱 내 MCP 테스트 및 Secure MCP Tunnel 연결을 위한 Electron 데스크톱 인터페이스를 제공합니다. FileMCP 방식을 따라 앱은 세션마다 새로운 loopback 토큰을 생성하고, 서버를 127.0.0.1에 유지하며, tunnel-client 수명 주기를 관리하고, Runtime API 키를 OS 암호화 메커니즘(macOS에서 Keychain 사용 가능 시)으로 저장합니다. tunnel-client 바이너리는 여전히 사용자가 OpenAI에서 다운로드합니다. 프로젝트는 해당 바이너리를 패키징하지 않습니다. 로컬 런타임과 Tunnel은 Codex 또는 OpenAI 모델/API를 호출하지 않습니다. 개발자 모드 앱을 통해 ChatGPT Web과 함께 앱을 사용하므로 Codex 할당량을 사용하지 않습니다. 대화는 여전히 사용 중인 ChatGPT 요금제의 제한을 따릅니다.

요구 사항

• Node.js 20 이상 (Node.js 24로 테스트됨).

• git_* 도구 사용 시 Git.

• ChatGPT의 경우: custom MCP 앱을 지원하는 workspace, Secure MCP Tunnel 및 적절한 터널 권한이 있는 runtime API 키. OpenAI Secure MCP Tunnel 참조.

단계별 실행

1단계 — dependency 설치

cd "/Users/danhpham/Documents/ChatGPT/MCP"
npm install

API 키를 .env에 넣거나 Git에 커밋하지 마세요.

2단계 — 전체 프로젝트 테스트

npm run verify

이 명령은 typecheck, unit/integration test, production build 및 MCP stdio를 통한 semantic smoke test를 실행합니다.

3단계 — 데스크톱 인터페이스 실행 (가장 쉬운 방법)

npm run desktop

WorkspaceGuard 창에서:

1. 폴더 선택… 을 누르고 테스트용 workspace를 선택합니다.

2. 처음 사용 시 읽기 전용을 유지합니다.

3. MCP 시작을 누릅니다. 상태가 실행 중으로 바뀌면 HTTP 서버가 127.0.0.1:<포트>에서 준비된 것입니다.

4. 완료되면 중지를 누릅니다. 앱을 닫아도 서버와 Tunnel이 모두 중지됩니다.

인터페이스는 HTTP 토큰을 표시하거나 저장하지 않습니다. 토큰은 시작할 때마다 main process에서 새로 생성됩니다.

인터페이스에서 전체 MCP 테스트

서버가 실행 중을 표시한 후 MCP 테스트 실행을 누릅니다. 이는 Electron main process의 실제 MCP 클라이언트이며, 인터페이스를 통한 가짜 테스트가 아닙니다.

• 읽기 전용의 경우, 앱은 MCP HTTP handshake, 도구 검색, workspace_info 및 list_files를 테스트합니다.

• 읽기 및 쓰기의 경우, 앱은 write_file → read_file → trash_path를 추가로 테스트합니다. 임의 이름의 테스트 파일이 .workspaceguard/trash로 이동되므로 확인 체크를 해야 합니다.

• 명령 실행의 경우, allowlist에서 node 체크를 유지하여 앱이 node --version으로 run_command를 추가로 테스트합니다.

마지막 두 모드에는 별도의 테스트 폴더를 선택하세요. 각 단계의 결과는 인터페이스의 테스트 섹션에 즉시 표시됩니다.

4단계 — 터미널로 코어 빌드 (선택 사항)

npm run build

프로덕션 진입점은 다음과 같습니다:

/Users/danhpham/Documents/ChatGPT/MCP/dist/index.js

5단계 — 터미널로 workspace 및 모드 선택 (선택 사항)

작은 테스트 폴더로 시작하는 것이 좋습니다:

mkdir -p /tmp/workspaceguard-demo
printf 'Xin chào MCP\n' > /tmp/workspaceguard-demo/hello.txt

세 가지 모드:

• read-only: 파일 읽기 및 Git 읽기 도구만 있습니다. 기본값입니다.

• workspace-write: write_file 및 trash_path 추가.

• command: 쓰기 권한 및 run_command 추가.

참고: 서버는 세 모드 모두에서 내부 감사 기록을 .workspaceguard/audit.jsonl에 계속 씁니다. "읽기 전용"은 공개 도구를 설명하는 것이지 서버 프로세스 자체의 파일시스템 샌드박스가 아닙니다.

6A단계 — stdio로 실행 (권장)

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode read-only

터미널은 MCP 클라이언트가 stdin을 통해 요청을 보낼 때까지 대기합니다. 이는 올바른 동작이며, 멈춤이 아닙니다.

6B단계 — 쓰기 권한 활성화

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode workspace-write

trash_path는 기본적으로 dry_run=true입니다. 호출자가 dry_run=false를 보낼 때만 경로가 휴지통으로 이동됩니다.

6C단계 — 터미널 명령 자동 실행 허용

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode command \
  --allow-command git,node,npm,npx

도구 입력 예시:

{
  "program": "npm",
  "args": ["test"],
  "cwd": "",
  "timeout_seconds": 120
}

run_command는 셸을 사용하지 않지만, OS 샌드박스가 아닙니다. 허용된 node, npm, Python 또는 실행 파일은 여전히 workspace 외부에서 읽기/쓰기, 네트워크 사용 및 현재 계정 권한으로 다른 프로세스 실행이 가능합니다. 신뢰할 수 있는 workspace와 워크플로우에서만 command 모드를 사용하세요.

7단계 — Secure MCP Tunnel 인터페이스로 ChatGPT 연결

OpenAI Platform에서 Secure MCP Tunnel과 터널 사용 권한이 있는 runtime API 키를 생성하세요. OS에 맞는 tunnel-client를 다운로드하세요. Runtime API 키를 Codex에 보내지 말고 .env, 소스 또는 Git에 기록하지 마세요.

앱에서 MCP가 실행 중을 표시한 후:

1. tunnel_... 형식의 Tunnel ID를 붙여넣습니다.

2. Runtime API key를 붙여넣습니다. 다음에는 비워 두어 암호화되어 저장된 키를 사용할 수 있습니다.

3. 바이너리가 PATH에 있으면 tunnel-client를 입력하거나, 파일 선택… 을 눌러 다운로드한 바이너리를 선택합니다.

4. 기본 프로필을 유지하고 Tunnel 연결을 누른 후 "ChatGPT 사용 준비 완료" 알림을 기다립니다.

5. 녹색 줄 "ChatGPT 사용 준비 완료"가 로컬 부분이 연결되었음을 확인합니다. ChatGPT Web 열기를 누릅니다. 이 앱은 Codex를 열거나 호출하지 않습니다.

6. ChatGPT만 끊으려면 Tunnel 연결 끊기를 누르고, Tunnel과 MCP 서버를 모두 중지하려면 중지를 누릅니다.

앱은 tunnel-client init --sample sample_mcp_remote_no_auth → doctor --explain → run 시퀀스와 동일한 작업을 수행하며, MCP 엔드포인트는 http://127.0.0.1:<포트>/mcp, 로컬 health 엔드포인트, 토큰 헤더는 환경 변수로 전달됩니다. 터널 프로필은 workspace가 아닌 앱의 자체 데이터에 있습니다.

ChatGPT Web에서 workspace 정책에 따라 Developer Mode/custom MCP 앱을 활성화하고, 새 앱을 만들고, Tunnel 연결을 선택하고, 방금 만든 터널을 선택하고, Scan Tools를 실행한 후 쓰기 도구를 활성화하기 전에 workspace_info, list_files 및 read_file을 시도하세요. Tunnel 옵션이 보이지 않으면 workspace에 Tunnel 읽기 및 사용 권한이 부여되었는지 확인하세요.

8단계 — HTTP loopback (선택 사항)

export WORKSPACE_MCP_TOKEN="$(openssl rand -hex 32)"

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport http \
  --mode read-only \
  --port 7331

Health check:

curl --fail http://127.0.0.1:7331/healthz

MCP 요청은 다음 헤더를 보내야 합니다:

X-Workspace-MCP-Token: <WORKSPACE_MCP_TOKEN>

HTTP 서버는 127.0.0.1에만 바인딩하고, Host, Origin, 토큰, 기본 프레이밍 및 본문 크기 제한을 확인합니다. 특정 HTTP 요구 사항이 없으면 stdio를 사용하세요.

사용 가능한 도구

항상 사용 가능

• workspace_info

• list_files

• read_file

• read_file_range

• search_filenames

• search_content

• git_status

• git_log

• git_diff

workspace-write 또는 command 모드

• write_file

• trash_path

command 모드 전용

• run_command

휴지통 파일 복원

도구는 trashPath를 반환합니다. 로컬 명령으로 복원하세요. 예:

mv "/tmp/workspaceguard-demo/.workspaceguard/trash/<id>/remove-me.txt" \
  "/tmp/workspaceguard-demo/remove-me.txt"

WorkspaceGuard는 의도하지 않은 데이터 삭제를 방지하기 위해 이 버전에서 휴지통을 자동으로 정리하지 않습니다.

구조

src/
├── config.ts                 # CLI/env và mode
├── security/path-policy.ts   # containment + sensitive-path policy
├── services/files.ts         # file/search/write/trash
├── services/git.ts           # Git read-only
├── services/process.ts       # process limits + tree cleanup
├── tools.ts                  # MCP schemas, annotations, audit
├── server.ts                 # stdio + HTTP loopback
├── desktop/                  # Electron main/preload + renderer an toàn
└── index.ts                  # CLI entry
tests/                        # unit, integration, MCP semantic smoke
docs/                         # phân tích source và lộ trình

추가 문서

• 원본 FileMCP 프로젝트 분석

• 프로젝트 구축 단계 및 로드맵

• 보안 모델

라이선스 및 참고 출처

이 프로젝트는 Apache License 2.0을 사용합니다. FileMCP도 Apache-2.0을 사용합니다. 참고 설계 출처는 NOTICE를 참조하세요. tunnel-client 바이너리는 포함되지 않습니다. 운영자는 공식 OpenAI 소스에서 적절한 버전을 다운로드합니다.