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

English | 中文（默认）

ChatGPT 웹 버전이 로컬 프로젝트에 안전하게 연결할 수 있게 합니다: Git 사용 여부와 관계없이 파일을 보고, 검색하고, 수정하고, 화이트리스트 작업을 실행할 수 있습니다. Git 프로젝트는 diff 확인, 로컬 커밋 생성, 그리고 사용자의 명시적 승인 후 지정된 원격 저장소와 브랜치로 푸시도 가능합니다.

Codex를 설치할 필요가 없습니다. ChatGPT는 OpenAI Secure MCP Tunnel을 통해 사용자 컴퓨터에서 계속 실행 중인 MCP 서비스를 호출합니다. 프로젝트 디렉터리와 MCP 포트를 공개 네트워크에 노출할 필요가 없습니다.

먼저 사용 시나리오를 선택하세요

Related MCP server: Kastor

제공되는 기능

프로젝트는 임의 Shell, git add ., 강제 푸시, 히스토리 재작성, 프로덕션 배포 또는 임의 디스크 접근을 제공하지 않습니다.

최초 설치: 처음부터 ChatGPT 연결

아래 절차는 Windows PowerShell 기준입니다. 일반적으로 한 번만 완료하면 됩니다.

1단계: 사전 요구 사항 확인

필요한 것:

• Windows PowerShell;

• Git;

• Node.js 20 이상;

• ChatGPT 개발자 모드 사용 가능;

• OpenAI Platform에서 Tunnel에 필요한 권한.

로컬 명령 확인:

git --version
node --version
npm --version

ChatGPT가 Git commit을 생성하도록 할 예정이라면 먼저 Git 신원(identity)을 설정해야 합니다. 이미 설정했다면 건너뛸 수 있습니다:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

2단계: 프로젝트 다운로드

git clone https://github.com/dxawdc/secure-local-workspace-mcp.git
Set-Location .\secure-local-workspace-mcp

3단계: OpenAI 페이지에서 Tunnel 준비

OpenAI Secure MCP Tunnel 공식 문서에 따라 다음 작업을 완료하세요:

1. OpenAI Platform에서 Tunnel 생성;

2. Tunnel을 사용할 ChatGPT workspace에 연결;

3. tunnel-client용 Runtime API Key 생성;

4. 공식 최신 버전 tunnel-client 다운로드;

5. tunnel_id와 tunnel-client.exe의 로컬 경로 기록.

이 단계들은 계정 권한과 키가 관련되므로 반드시 사용자가 OpenAI 페이지에서 확인해야 하며, 프로젝트가 사용자를 대신해 계정 자격 증명을 생성하거나 읽지 않습니다.

4단계: Runtime Key를 저장소 외부에 저장

Key를 README, 프로젝트 설정, Git 또는 PowerShell 명령 히스토리에 작성하지 마세요. 먼저 저장소 외부 파일을 생성할 수 있습니다:

New-Item -ItemType Directory -Path "C:\Secrets" -Force
notepad "C:\Secrets\openai-tunnel-runtime-key.txt"

메모장에 Runtime Key를 붙여넣고 한 줄만 유지한 후 저장하고 닫습니다. 프로덕션 또는 팀 환경에서는 조직이 승인한 키 관리 방식을 사용하고 해당 파일의 접근 권한을 제한해야 합니다.

5단계: 원클릭 설정 실행

예시의 세 경로와 Tunnel ID를 자신의 값으로 바꾸세요:

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\my-app" `
  -DiscoveryRoot "D:\Projects" `
  -TunnelId "tunnel_REPLACEME" `
  -TunnelClient "C:\Tools\tunnel-client\tunnel-client.exe" `
  -ControlPlaneApiKeyRef "file:C:\Secrets\openai-tunnel-runtime-key.txt" `
  -RegisterStartup `
  -StartTunnel

매개변수 입력 방법:

• ProjectRoot: 이번에 ChatGPT가 작업할 프로젝트 디렉터리. Git 저장소가 아니어도 됨;

• DiscoveryRoot: ChatGPT가 프로젝트를 발견하도록 허용할 상위 디렉터리. 일반적으로 ProjectRoot의 상위 수준;

• TunnelId: OpenAI Platform에 표시된 실제 tunnel_id;

• TunnelClient: 다운로드 후 압축 해제한 tunnel-client.exe;

• ControlPlaneApiKeyRef: Runtime Key 파일 경로. 반드시 file: 접두사를 붙여야 함.

스크립트가 자동으로 완료하는 작업:

1. 잠금 파일을 사용해 Node.js 의존성 설치;

2. 단위 테스트 및 MCP 스모크 테스트 실행;

3. 프로젝트를 읽기/쓰기 가능으로 설정하고 로컬 commit 허용;

4. 프로젝트 발견 디렉터리 승인;

5. package.json의 test, lint, build, typecheck 자동 식별;

6. Tunnel profile 생성 및 확인;

7. 현재 사용자 로그인 자동 시작 작업 등록 및 Tunnel 즉시 시작.

기본적으로 push는 허용되지 않습니다. 비-Git 프로젝트는 파일 읽기/쓰기 기능을 자동으로 유지하면서 commit과 push를 강제로 비활성화하므로 -DisableCommit을 수동으로 추가할 필요가 없습니다.

로컬에서 OpenAI에 접근할 때 프록시를 거쳐야 한다면 명령 끝에 다음을 추가하세요:

-HttpProxy "http://127.0.0.1:7890"

6단계: ChatGPT에서 프라이빗 앱 생성

1. ChatGPT 설정에서 개발자 모드를 활성화합니다. Enterprise/Edu 사용자는 관리자 승인이 필요할 수 있습니다;

2. ChatGPT Plugins을 엽니다;

3. 더하기(+)를 클릭해 개발자 모드 앱을 생성합니다;

4. Connection에서 Tunnel을 선택합니다;

5. 방금 생성한 Tunnel을 선택하거나 실제 tunnel_id를 붙여넣습니다;

6. 앱을 생성하고 ChatGPT가 도구를 발견할 때까지 기다립니다.

공식 설명에 따르면 tunnel-client가 계속 실행 중이어야 합니다. 그렇지 않으면 ChatGPT가 도구를 발견하거나 호출할 수 없습니다.

7단계: 연결 확인

ChatGPT 새 대화에서 이 앱을 선택하거나 @로 호출한 후 다음을 보내세요:

调用 diagnostics 和 list_projects。
告诉我 Tunnel 后面的本地 MCP 是否正常，并列出已授权项目、读写权限、commit 权限和 push 权限。
不要修改任何文件。

정상적으로 프로젝트 목록이 표시되어야 하며 기본 allowPush는 false여야 합니다. 새 버전은 총 17개의 도구를 제공합니다. 여전히 이전 도구가 표시되면 Tunnel을 재시작한 후 ChatGPT에서 앱을 새로고침하거나 새 대화를 만드세요.

기존 Tunnel: 새 프로젝트 연결

Tunnel과 로그인 자동 시작 작업이 모두 이 프로젝트를 통해 구성된 경우, 저장소 디렉터리에서 다음을 실행하세요:

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\another-app" `
  -DiscoveryRoot "D:\Projects" `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

이 명령은 프로젝트 구성을 추가하거나 업데이트하며 다른 승인된 프로젝트를 덮어쓰지 않습니다.

이 프로젝트로 로그인 작업을 등록하지 않았다면 -RestartTunnel을 제거하고, 구성 완료 후 원래 방식으로 tunnel-client를 재시작하세요. 재시작 후 ChatGPT 앱 설정에서 도구를 새로고침하세요.

ChatGPT가 비-Git 프로젝트를 자동으로 연결하게 하기

일반적인 Node.js, Python, Java, Go, Rust, .NET, PHP, Ruby, Elixir, Swift, CMake 등의 프로젝트 디렉터리는 discover_projects가 자동으로 식별합니다. 디렉터리에 일반적인 프로젝트 식별 표시가 없어도 승인된 DiscoveryRoot 내에서 명시적 절대 경로를 통해 연결할 수 있습니다:

调用 discover_projects，列出已批准目录中的 Git 和非 Git 项目。
把 D:\Projects\notes-app 接入为可读写项目。
如果它不是 Git 仓库，必须自动关闭 commit 和 push。
接入后调用 list_projects，确认 projectType 和最终权限。

ChatGPT가 connect_project를 호출하면 구성이 즉시 영구 저장되고 현재 MCP 프로세스에 적용되므로 개별 프로젝트마다 Tunnel을 다시 재시작할 필요가 없습니다.

보기만 허용, 수정 불가

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\reference-project" `
  -DiscoveryRoot "D:\Projects" `
  -ReadOnly `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

수정 허용, commit 불가

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\my-app" `
  -DiscoveryRoot "D:\Projects" `
  -DisableCommit `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

발견 가능한 프로젝트 상위 디렉터리만 추가

.\scripts\quick-setup.ps1 `
  -DiscoveryRoot "E:\OtherProjects" `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

DiscoveryRoot를 디스크 루트, 전체 사용자 디렉터리 또는 개인 파일이 많은 디렉터리로 설정하지 마세요. 코드 저장소를 전용으로 보관하는 상위 디렉터리여야 합니다.

일상 사용 프롬프트

프로젝트 이름은 list_projects가 반환한 ID를 기준으로 합니다. 아래 프롬프트를 ChatGPT에 직접 복사한 후 프로젝트 이름과 요구 사항을 바꾸면 됩니다.

1. 보기 및 분석만

使用 Secure Local Workspace MCP 检查项目 my-app。
先调用 list_projects 确认项目，再查看与登录流程有关的代码。
解释实现和可能的问题，不要修改文件，不要提交。

2. 수정 및 테스트, 커밋은 하지 않음

检查项目 my-app 的重复提交问题并完成修复。
修改前重新读取目标文件并使用最新 SHA-256，只改与本次问题有关的文件。
运行项目允许的 test 或 lint 任务，最后展示 git_status 和 git_diff。
不要 commit，不要 push。

3. 수정, 테스트 및 로컬 커밋 생성

修复项目 my-app 的重复提交问题。
运行相关测试，然后展示完整 git_diff 和 git_status。
确认差异只包含本次修改后，使用最新 statusSha256，
只提交本次涉及的明确文件，提交信息为：fix: prevent duplicate submissions。
提交后报告本地 commit SHA。不要 push。

4. 이미 완료된 수정 사항만 커밋

检查项目 my-app 当前 git_status 和 git_diff，不要继续改代码。
如果存在与本任务无关或已经预暂存的文件，停止并告诉我。
否则使用最新 statusSha256，只提交这些明确文件：src/example.js、test/example.test.js。
提交信息为：fix: handle duplicate submissions。不要 push。

git_commit은 다음을 거부합니다:

• ., 디렉터리 또는 프로젝트 외부 경로;

• 검토 후 변경된 Git 상태;

• 기존 staged changes;

• .env, 개인 키, 인증서, 비밀번호 저장소 등 민감 경로;

• 신뢰도 높은 API Key, Token, 개인 키 또는 실제 Tunnel/조직 식별자;

• git diff --cached --check 실패;

• 로컬 구성에서 commit이 활성화되지 않음.

커밋 성공은 로컬에 커밋되었음을 의미할 뿐 push되었음을 의미하지 않습니다.

제한된 push 별도 활성화

Push는 외부 쓰기 작업이므로 반드시 로컬에서 프로젝트별로 명시적으로 활성화해야 합니다. 대상 브랜치도 함께 제한하는 것을 권장합니다:

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\my-app" `
  -AllowPush `
  -AllowedRemote "origin" `
  -AllowedBranch "main" `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

그런 다음 ChatGPT에서 명확히 요청하세요:

检查项目 my-app 当前分支、HEAD、git_status 和待推送 commit。
只有在工作区状态和 commit 都符合预期时，才把当前 HEAD 推送到允许的 origin/main。
禁止 force push。分别报告本地 commit SHA、远端分支和推送结果。

git_push는 commit을 자동으로 생성하지 않으며, 구성되지 않은 remote 또는 branch로 푸시하지 않습니다.

자동화와 수동 작업 경계

더 자세한 일괄 구성, 프록시, 자동 시작, 롤백 및 무인 참조는 Windows 자동화 구성 절차를 참조하세요.

구성 관리

기본 구성 파일은 저장소 외부에 있습니다:

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

새 버전 구성이 없으면 서비스가 이전 경로를 호환하여 읽습니다:

%USERPROFILE%\.local-project-workspace\config.json

현재 구성 확인:

npm run config -- list

PowerShell 자동화를 사용하지 않는 경우에도 크로스 플랫폼 구성 CLI를 호출할 수 있습니다:

npm run config -- add-discovery-root --root "D:\Projects"

npm run config -- add-project `
  --root "D:\Projects\my-app" `
  --writable `
  --allow-commit `
  --no-push

호환 스크립트 bootstrap-config.ps1도 개별 프로젝트를 멱등적으로 추가하거나 업데이트하며 전체 구성을 대체하지 않습니다.

프로젝트 업데이트

Set-Location .\secure-local-workspace-mcp
git pull --ff-only
npm ci
npm test
npm run smoke:mcp

코드 또는 도구 정의가 업데이트된 후에는 반드시 tunnel-client를 재시작하고 ChatGPT에서 앱을 새로고침하거나 새 대화를 만들어야 합니다.

프로젝트 접근 해제

ChatGPT에서 다음을 보내세요:

调用 disconnect_project 撤销项目 my-app 的 MCP 访问权限，然后重新列出项目。

이 작업은 로컬 승인 구성만 삭제하며 프로젝트 디렉터리, 파일 또는 Git 히스토리를 삭제하지 않습니다.

로그인 자동 시작 작업을 제거하려면:

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

이 작업은 Tunnel, Runtime Key, profile 또는 프로젝트 파일을 삭제하지 않습니다.

자주 묻는 질문

Git commit identity is missing

먼저 Git 사용자 이름과 이메일을 설정한 후 구성을 다시 실행하세요:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Scheduled task not found

-RestartTunnel을 사용했지만 Tunnel이 이 프로젝트를 통해 등록되지 않았습니다. 해당 매개변수를 제거하고 프로젝트 구성을 완료한 후 원래 방식으로 tunnel-client를 재시작하세요.

ChatGPT에서 Tunnel이 보이지 않음

순서대로 확인하세요:

1. Tunnel이 Platform organization뿐만 아니라 현재 ChatGPT workspace에 연결되어 있는지;

2. 현재 계정에 Tunnels Read + Use 권한이 있는지;

3. ChatGPT 개발자 모드가 활성화되어 있는지;

4. tunnel-client가 계속 실행 중이고 healthy/ready 상태인지.

ChatGPT가 17개 도구를 발견하지 못함

• Tunnel runtime 재시작;

• tunnel-client doctor --profile <profile> --explain 실행;

• ChatGPT 앱 설정에서 새로고침;

• 새 ChatGPT 대화를 만들어 이전 대화가 캐시된 도구 정의를 계속 사용하지 않도록 함.

프로젝트를 발견하거나 연결할 수 없음

• 프로젝트는 승인된 DiscoveryRoot 내에 있어야 함;

• Git 저장소와 일반적인 프로젝트 식별 표시가 있는 비-Git 디렉터리는 발견 결과에 자동으로 표시됨;

• 프로젝트 식별 표시가 없는 일반 디렉터리는 자동으로 나열되지 않지만, ChatGPT가 명시적 절대 경로로 connect_project를 호출하게 할 수 있음;

• 비-Git 프로젝트는 projectType: non-git으로 표시되며 commit과 push가 강제로 비활성화됨;

• npm run config -- list를 실행해 실제 구성을 확인;

• 필요 시 상위 디렉터리를 다시 추가하고 Tunnel을 재시작.

쓰기가 거부되거나 SHA 만료 안내

• 프로젝트가 쓰기를 허용해야 함;

• 기존 파일을 수정하거나 삭제하기 전에 ChatGPT가 read_file을 다시 호출해야 함;

• 파일이 다른 프로그램에 의해 수정되면 이전 SHA가 무효화되는 것은 정상적인 동시성 보호입니다.

기존 staged changes로 인해 Commit 거부

먼저 ChatGPT가 git_status를 호출해 확인하게 하세요. Unstage가 가능하다고 확인되면 git_unstage를 호출해 명시적 파일을 처리하세요. 이 작업은 워크스페이스 내용을 버리지 않습니다.

Tunnel은 로컬에서 정상인데 ChatGPT 호출이 타임아웃

• api.openai.com:443으로의 아웃바운드 연결 확인;

• 브라우저가 프록시를 사용할 수 있다고 해서 tunnel-client가 동일한 프록시를 자동으로 사용하는 것은 아님;

• 최초 구성 시 -HttpProxy로 프록시를 기록;

• 로컬 방화벽, 프록시 인증서, 조직 네트워크 정책 확인.

로컬 검증

npm ci
npm test
npm run smoke:mcp
npm audit --omit=dev

로컬 MCP 포그라운드 시작:

.\scripts\start-local.ps1

Tunnel 상태는 최소한 다음을 충족해야 합니다:

process_running = true
healthy = true
ready = true

보안 권장 사항

• Discovery Root는 전용 프로젝트 상위 디렉터리여야 하며 디스크 루트나 전체 사용자 디렉터리를 사용하지 마세요;

• 우선 commit만 활성화하고, 실제 필요 시에만 프로젝트, remote, branch별로 push를 활성화하세요;

• Runtime Key, Tunnel profile, 실제 구성 및 로그는 반드시 저장소 외부에 보관하세요;

• MCP commit은 프로젝트 Git hooks를 일시적으로 비활성화하므로 테스트와 포맷팅은 명시적 작업 화이트리스트로 실행해야 합니다;

• push 전에도 명확한 commit SHA, remote, branch를 확인해야 합니다;

• 키가 실수로 커밋되면 즉시 폐기하고 전체 Git 히스토리를 정리하세요.

보안 설계 및 취약점 보고는 SECURITY.md를 참조하세요.

공식 참고 자료

• OpenAI Secure MCP Tunnel

• OpenAI MCP and Connectors

License

MIT