Secure Local Workspace MCP（안전한 로컬 워크스페이스 MCP）

English | 한국어（기본）

ChatGPT와 Codex를 위한 안전한 로컬 워크스페이스 게이트웨이입니다. MCP를 통해 명시적으로 권한이 부여된 프로젝트 디렉터리만 노출하며, 제한된 파일 읽기, 검색, 패치 수정, Git 조회, 화이트리스트 작업 기능을 제공합니다. 모델에게 임의 Shell, 삭제, 커밋, 푸시, 배포 권한은 부여하지 않습니다.

활용 시나리오

• ChatGPT 웹 버전에서 로컬 프로젝트 코드를 읽고, 분석하고, 수정합니다.

• Codex가 통합된 MCP 도구를 통해 사용자가 명시적으로 권한을 승인한 여러 프로젝트에 접근할 수 있습니다.

• 쓰기 연산에 디렉터리 경계, 파일 크기, SHA-256 동시성 보호를 적용합니다.

• 테스트, 빌드와 같은 실행 작업을 로컬 구성의 작업 화이트리스트로 제한합니다.

기능 및 보안 경계

서버는 실제 경로를 검증하고 .., 절대 경로, 심볼릭 링크를 통한 경로 이탈을 차단합니다. 프로젝트는 기본적으로 읽기 전용이며, 프로젝트가 writable: true로 설정된 경우에만 쓰기 도구가 동작합니다.

이 프로젝트는 의도적으로 다음 기능을 제공하지 않습니다:

• 임의 Shell 또는 임의 명령 실행;

• 파일 삭제 또는 덮어쓰기 방식의 새 파일 생성;

• Git commit, push, 브랜치 재작성;

• 프로덕션 배포 및 원격 서버 조작.

디렉터리와 개인 데이터

저장소에는 소스, 예시 구성, 자동화 스크립트만 담깁니다. 실제 인증 구성, API Key, 터널 구성과 로그는 반드시 저장소 밖에 두어야 합니다.

Windows 권장 디렉터리:

项目源码              <clone-directory>
授权配置              %USERPROFILE%\.secure-local-workspace-mcp\config.json
隧道 profile          %USERPROFILE%\.secure-local-workspace-mcp\tunnel-profiles\
运行时 API Key        用户自选的受保护文件或环境变量
tunnel-client         用户自选的本机工具目录

구버전 경로인 %USERPROFILE%\.local-project-workspace\config.json은 새 경로가 없을 때 자동으로 읽히므로 무중단 업그레이드가 가능합니다.

환경 요구사항

• Windows, macOS 또는 Linux. 자동화 스크립트는 Windows PowerShell을 기준으로 작성되어 있습니다.

• Node.js 20 이상.

• Git.

• ChatGPT 웹 버전을 연동하려면 OpenAI Platform에서 Tunnel를 만들 수 있고, ChatGPT에서 개발자 모드를 사용할 수 있어야 합니다.

단계별 수동 설치 절차

1. 소스 코드 내려받기 및 의존성 설치

git clone https://github.com/dxawdc/secure-local-workspace-mcp.git
Set-Location .\secure-local-workspace-mcp
npm ci
npm test
npm run smoke:mcp

2. 로컬 인증 구성 만들기

첫 프로젝트 구성은 자동화 스크립트로 만드는 것을 권장합니다.

.\scripts\bootstrap-config.ps1 `
  -ProjectId "my-app" `
  -ProjectLabel "我的应用" `
  -ProjectRoot "D:\Projects\my-app"

스크립트는 기본적으로 읽기 전용 프로젝트를 생성합니다. 쓰기 위험을 확인한 후에만 명시적으로 -Writable을 추가하세요.

.\scripts\bootstrap-config.ps1 `
  -ProjectId "my-app" `
  -ProjectLabel "我的应用" `
  -ProjectRoot "D:\Projects\my-app" `
  -Writable `
  -Force

config.example.json을 복사해 config.json으로 저장할 수도 있습니다.

%USERPROFILE%\.secure-local-workspace-mcp\config.json

작업 화이트리스트 예시:

{
  "tasks": {
    "test": {
      "command": "npm",
      "args": ["test"],
      "timeoutSeconds": 300
    }
  }
}

ChatGPT 또는 Codex는 작업 이름 test만 제출할 수 있으며, 명령이나 인자는 변경할 수 없습니다.

3. 로컬에서 MCP를 시작하고 검증하기

.\scripts\start-local.ps1

또는:

npm start

프로세스는 실제의 설정 파일 경로가 아닌, 실제 개수 정보를 포함한 인증 프로젝트 개수를 각각 출력합니다. MCP는 stdio를 사용하므로 포그라운드로 실행한 동안 HTTP 페이지는 존재하지 않습니다.

4. Codex에 연결

저장소에는 .codex-plugin/plugin.json, .mcp.json, 그리고 함께 사용되는 skill이 포함되어 있습니다. 기존 설치가 해제되지 않도록 개인 플러그인의 호환 ID는 local-project-workspace를 그대로 유지하며, 표시 이름은 Secure Local Workspace MCP로 변경되었습니다.

저장소를 %USERPROFILE%\plugins\local-project-workspace에 넣거나 클론된 디렉터리를 가리키는 Junction을 만든 다음, 개인 마켓플레이스에서 플러그인을 설치하거나 새로고침합니다. 업데이트 후에는 새 Codex 대화를 만들어야 MCP와 skill이 다시 로드됩니다.

5. OpenAI Secure MCP Tunnel 만들기

1. OpenAI Platform의 Tunnel 관리 페이지에서 Tunnel을 만들고 대상 ChatGPT 워크스페이스에 바인딩합니다.

2. 별도 Runtime을 위한 API를 발급합니다. 장기 실행 프로세스에는 반드시 Runtime Key를 사용하고 Admin Key는 사용하지 마세요.

3. OpenAI 공식 tunnel-client를 다운로드한 뒤 릴리스 페이지에 제공된 SHA-256을 확인하고 해제합니다.

4. Runtime API Key가 포함된 보호 파일은 저장소 외부에 두거나, 조직이 승인한 시크릿 관리 도구를 이용하여 환경변수로 주입합니다. 명령 기록, 사례 설정, 커밋에 절대로 넣지 마세요.

5. 스크립트를 이용해 프로파일을 만들고 추가 확인하세요.

ACL 보호 파일 참조 방식을 권장합니다. 다음 명령은 파일 경로만 전달하며 키 내용을 읽거나 출력하지 않습니다.

.\scripts\setup-tunnel.ps1 `
  -TunnelId "tunnel_REPLACE_ME" `
  -TunnelClient "C:\Tools\tunnel-client\tunnel-client.exe" `
  -ControlPlaneApiKeyRef "file:C:\Secrets\openai-tunnel-runtime-key.txt" `
  -ProfileDir "$env:USERPROFILE\.secure-local-workspace-mcp\tunnel-profiles"

이 컴퓨터가 로컬 프록시로 OpenAI에 접근 필요하면:

.\scripts\setup-tunnel.ps1 `
  -TunnelId "tunnel_REPLACE_ME" `
  -TunnelClient "C:\Tools\tunnel-client\tunnel-client.exe" `
  -ControlPlaneApiKeyRef "file:C:\Secrets\openai-tunnel-runtime-key.txt" `
  -ProfileDir "$env:USERPROFILE\.secure-local-workspace-mcp\tunnel-profiles" `
  -HttpProxy "http://127.0.0.1:7890"

스크립트는 tunnel-client init과 doctor --explain을 실행합니다. 확인이 통과된 뒤, 전경에서 실행합니다:

& "C:\Tools\tunnel-client\tunnel-client.exe" run `
  --profile secure-local-workspace-mcp `
  --profile-dir "$env:USERPROFILE\.secure-local-workspace-mcp\tunnel-profiles"

6. ChatGPT 웹에서 개인 플러그인 생성

1. ChatGPT 설정을 열어 개발자 모드를 활성화합니다.

2. 플러그인 페이지로 이동해'앱 만들기'를 선택합니다.

3. 연결 방식을 Tunnel로 정하고, 방금 만든 Tunnel을 선택하거나 Tunnel ID를 입력합니다.

4. 본 서비스는 물리적인 별도의 인증이 필요하지 않으므로 인증이 없는 방법("인증 비사용")을 선택합니다. Tunnel Runtime은 로컬 클라이언트와 OpenAI 제어반 사이에만 사용됩니다.

5. 위험 안내를 읽고 확인한 뒤 만들고 연결합니다.

6. 10개의 도구가 지원되는지 확인하고, 읽기 전용 검증을 한 번 실행합니다.

검증 프롬프트:

@Secure Local Workspace MCP 调用 list_projects，只返回项目名称和是否可写。

변경 프롬프트:

@Secure Local Workspace MCP 读取 my-app 的 README.md，先说明修改计划，再用哈希保护补丁修改并展示 git_diff。

자동화 구성 절차

저장소에는 다음의 Windows PowerShell 스크립트 세 개가 제공됩니다.

1. bootstrap-config.ps1: 사용자 트랜잭션 인증 프로젝트 구성 생성, 어떤 키도 처리하지 않음

2. setup-tunnel.ps1: Tunnel profile을 만들고 doctor를 실행

3. register-tunnel-startup.ps1: 검증 된 profile을 현재 사용자의 로그온 작업으로 등록

전체 자동화 시나리오, 인자 설명, 실행, 관리(CI/Operation) 견해는 자동화 구성 참조를 참조하세요.

일상 사용

로컬 구성 진단 확인

ChatGPT/Codex에서 diagnostics와 list_projects를 호출하세요. 모델이 프로젝트 ID를 추측하게 두지 마세요.

프로젝트 갱신

git pull --ff-only
npm ci
npm test
npm run smoke:mcp

MCP 도구 정의가 바뀌었을 때는 tunnel-client를 다시 시작해야 하며, ChatGPT 내 플러그인 구성에서 도구를 새로고침해야 합니다. Codex에 대해서는 새로운 대화를 시작합니다.

로그온 자동 시작 중지

Stop-ScheduledTask -TaskName "Secure Local Workspace MCP Tunnel"

로그온 자동 시작 삭제

Unregister-ScheduledTask -TaskName "Secure Local Workspace MCP Tunnel" -Confirm:$false

이 명령은 작업만 삭제할 뿐이며, Tunnel, API Key, profile 또는 프로젝트 구성을 삭제하지 않습니다.

자주 묻는 질문

Tunnel 상태 정상인데 ChatGPT 호출이 시간 초과

• api.openai.com:443에 프록시가 필요한지 확인하세요.

• 시스템 프록시를 사용하는 브라우저들도 Go로 작성된 tunnel-client를 같이 사용하는 것은 아닙니다.

• 프로필에 http_proxy를 설정하거나, 구동 프로세스에 HTTPS_PROXY를 설정하세요.

• tunnel-client runtimes status <alias> --json을 실행하여 process_running, healthy, ready, 그리고 원격 쿼리 오류를 구별하세요.

ChatGPT에서 도구 수술이 안 보여요

• tunnel-client가 실행 중인지 확인합니다.

• doctor --explain을 실행합니다.

• Tunnel이 현재 ChatGPT 워크스페이스에 바인딩되어 있는지 확인합니다.

• 플러그인 설정에서 '새로고침'을 누릅니다.

• 서비스 시작 로그의 구성 파일 위치와 인증된 프로젝트 수를 확인합니다.

스텝: 프로젝트 목록이 비어 있어요

• 실제로 읽은 구성 파일 경로가 신규인지 기존인지 확인하시기 바랍니다.

• LOCAL_PROJECT_WORKSPACE_CONFIG를 설정하면 특정 설정 파일을 직접 가리킬 수 있습니다.

• JSON 포맷, 프로젝트 ID와 프로젝트 폴더 위치가 정확한지 살펴보세요.

쓰기가 거부되는 경우

• 프로젝트를 writable: true로 입력합니다.

• 기존 파일을 변경하기 전에는 read_file을 다시 호출한 이후 최신 SHA-256을 사용하세요.

• 파일이 바뀌면 기존 해시가 유효하지 않습니다. 이것은 의도적인 충돌 보호 기능입니다.

배포 전 개인정보 점검

오픈(fork) 또는 커밋 전에 최소한 다음을 확인합니다.

• API 키, GitHub Token, SSH 프라이빗 키와 인증서;

• Tunnel ID, 조직 ID, 지갑 ID;

• 실제로 사용한 config.json, 로그, 다운로드 폴더, 실행 프로필;

• 개인 사용자 이름, 절대 경로, 비공개 리포지토리 URL;

• node_modules, 빌드 산출물, 임시 파일.

저장소의 .gitignore는 흔히 사용하는 민감한 경로를 포함하지만, 커밋 트리의 스캔과 키 무효화 절차를 대체할 수 없습니다.

라이센스

MIT