safe-workspace-mcp

최소한의 보안 중심 MCP 서버로, 정확히 하나의 로컬 워크스페이스에 대한 구조화된 읽기/쓰기 액세스를 제공하며 내장된 로컬 Git 체크포인트와 롤백을 지원합니다.

채팅 모델(예: MCP를 지원하는 ChatGPT)이 하나의 프로젝트 폴더에서 안전하게 파일을 편집할 수 있도록 설계되었습니다. 그 외의 작업은 수행하지 않습니다.

Windows 휴대용 빠른 시작(Python, Git, Node 불필요)

1. Releases에서 Windows 릴리스 ZIP을 다운로드하고 압축을 풉니다.

2. 워크스페이스 디렉터리(서버가 접근할 수 있는 유일한 폴더)를 준비합니다.

3. OpenAI Secure MCP Tunnel ID(여기에서 생성) 및 Runtime API Key(여기에서 생성)를 받습니다.

4. 압축을 푼 폴더에서 다음을 실행합니다:

   .\Start-SafeWorkspaceMCP.ps1 -Workspace "D:\ChatGPT_Workspace\demo" -TunnelId "tunnel_..."

5. 프롬프트가 표시되면 Runtime API Key를 입력합니다(입력은 숨겨지며 저장되지 않습니다).

6. 터미널을 열어 둡니다. Ctrl+C를 누르면 모든 것이 중지됩니다.

7. ChatGPT Developer Mode에서 기존 터널을 연결합니다. 이 계정 측 단계는 직접 수행해야 합니다.

런처는 첫 실행 시 공식 OpenAI 터널 클라이언트(고정된 v0.0.11, SHA-256 검증)를 다운로드하여 %LOCALAPPDATA%\SafeWorkspaceMCP\에 캐시합니다. 관리자 권한이 필요 없으며 PATH/레지스트리 변경도 없습니다. 자세한 내용은 ZIP 안의 README-PORTABLE.md\를 참조하세요.

정확한 설명: Python/Git/Node 설치가 필요 없는 휴대용 로컬 배포; 런처가 테스트된 OpenAI 터널 클라이언트를 자동으로 부트스트랩합니다. "zero configuration"은 아닙니다. 워크스페이스, 터널 ID, 런타임 키, ChatGPT 계정 측 설정은 직접 준비해야 합니다.

Related MCP server: git-mcp-server

개요

• 하나의 프로세스 = 하나의 구성 = 하나의 고정된 워크스페이스(시작 시 선택, 런타임 중 불변)

• 구조화된 텍스트 파일 CRUD 및 원자적 다중 파일 트랜잭션

• 낙관적 동시성: 기존 파일을 수정하려면 항상 현재 sha256이 필요합니다.

• 관리되는 로컬 Git 히스토리(Dulwich 사용, git.exe 사용 안 함): 변경 전/후 체크포인트, diff, 히스토리, 복원

• stdio MCP 서버, 총 9개 도구

비목표(단호히 없음)

셸 없음, 터미널 없음, 서브프로세스 없음, 코드 실행 없음, 컴파일러/테스트 러너/패키지 매니저 없음, 임의의 HTTP 또는 네트워크 도구 없음, 원격 Git 없음, 워크스페이스 전환 없음, 바이너리/이미지 편집 없음, OS 샌드박스 주장 없음.

아래에 나열되지 않은 기능은 이 서버에 없습니다.

아키텍처

ChatGPT / any MCP client
        │
OpenAI Secure MCP Tunnel (account-side, outbound-only)
        │
tunnel-client.exe            <- external deployment layer (official OpenAI binary,
        │                       pinned + SHA-256 verified by the launcher)
        │ MCP over stdio (child process)
        ▼
Safe Workspace MCP           <- this project (9 tools, no network, no exec)
        │
   fixed single workspace
        │
   ┌────┴─────────────┐
   │                   │
structured file CRUD   managed local Git checkpoints

• 웹 검색/URL 가져오기는 채팅 호스트 자체가 수행합니다. 이 서버는 설계상 네트워크 기능이 없습니다.

• 터널 클라이언트는 이 서버의 일부가 아닌 외부 배포 구성 요소입니다. 서버 프로세스 자체는 소켓을 열지 않으며, 런처의 유일한 네트워크 활동은 고정되고 체크섬이 검증된 공식 터널 클라이언트를 다운로드하는 것입니다.

9가지 도구

apply_changes 작업은 모두 먼저 검증합니다(경로, 해시, 정책, 계획 충돌). 하나라도 실패하면 아무것도 적용되지 않습니다. 실행 중간에 실패하면 모든 것이 롤백됩니다.

설치

지원되는 두 가지 방법:

• 최종 사용자(Windows): 휴대용 릴리스 ZIP을 다운로드합니다. Python/Git/Node가 필요 없습니다(위 빠른 시작 참조).

• 개발자 / Linux: Python 3.12+ 소스 체크아웃:

git clone https://github.com/Xs-trek/safe-workspace-mcp.git
cd safe-workspace-mcp
py -3.12 -m venv .venv
.venv\Scripts\pip install -e .

런타임 종속성: mcp==2.0.0(공식 SDK), dulwich==1.2.6, Python 표준 라이브러리. 그 외에는 없습니다. 휴대용 릴리스의 최종 사용자 사전 요구 사항은 Windows 10/11, PowerShell, 터널용 인터넷, 워크스페이스 폴더, 터널 ID + Runtime API Key, 그리고 직접 수행하는 ChatGPT 계정 설정뿐입니다.

구성

TOML 파일은 시작 시 한 번 로드되며 그 후에는 불변입니다. 런타임에 구성, 워크스페이스 루트 또는 제한 사항을 변경할 수 있는 도구(및 코드 경로)는 없습니다.

[workspace]
root = "D:/ChatGPT_Workspace/demo"
max_file_bytes = 2097152        # largest file the server will write/track
max_read_bytes = 1048576        # largest read returned / searched per file
max_transaction_bytes = 10485760
max_search_results = 200
excluded = ["node_modules", "build", "dist", ".venv"]  # plus built-ins

[paths]
reject_reparse_points = true    # symlinks/junctions/mounts: always recommended
reject_hardlinks = true
require_same_filesystem = true

[write]
allow_create_file = true
allow_modify_file = true
allow_delete_file = true
allow_move = true
allow_create_directory = true
allow_delete_empty_directory = true
require_expected_hash = true

[git]
mode = "managed"                # only mode in v0.1.0
author_name = "Safe Workspace MCP"
author_email = "safe-workspace-mcp@local"

[search]
include_hidden = false

[server]
transport = "stdio"             # only transport in v0.1.0

examples/에서 최소 / 기존 소스 / 대형 소스 변형을 참조하세요.

관리되는 워크스페이스

빈 디렉터리 또는 일반 소스 디렉터리(.git 없음)로 처음 시작하면 서버는 다음을 수행합니다.

1. 디렉터리를 스캔합니다(일반 텍스트 파일만 추적).

2. <root>/.git에 관리되는 저장소를 초기화합니다.

3. initial snapshot 체크포인트를 생성합니다.

워크스페이스에 이미 .git이 있으면 시작이 EXISTING_GIT_REPOSITORY_NOT_SUPPORTED로 실패합니다. 기존 저장소, worktree, 서브모듈 및 리모트를 채택하는 것은 v0.1.0 범위를 벗어납니다.

편집 가능 ⇒ 복구 가능: MCP가 수정하거나 삭제할 수 있는 모든 일반 파일은 관리되는 저장소에서 추적되므로 항상 체크포인트에서 복원할 수 있습니다. 제외된 디렉터리(node_modules, 빌드 산출물, virtualenv 등)는 모든 도구에 보이지 않습니다 — 읽을 수 없고, 쓸 수 없고, 검색되지 않으며, 체크포인트에도 포함되지 않습니다.

실행

.venv\Scripts\safe-workspace-mcp path\to\config.toml

서버는 stdio에서 MCP를 사용하며 로그는 stderr로 출력합니다. 워크스페이스 루트가 존재하지 않거나 안전하지 않으면 시작을 거부합니다.

여러 프로젝트

하나의 프로세스는 정확히 하나의 워크스페이스를 제공합니다. 여러 구성으로 여러 프로세스를 실행하세요:

safe-workspace-mcp project-a.toml
safe-workspace-mcp project-b.toml

기존 소스 가져오기

workspace.root를 .git이 없는 기존 소스 디렉터리로 지정하세요. 초기 스냅샷이 현재 상태를 기준선으로 커밋하며, 그 이후로 디렉터리는 관리됩니다. 대량으로 생성된 디렉터리는 excluded에 추가해야 합니다.

휴대용 사용 시나리오(Windows)

• 새 PC에서 첫 실행: ZIP을 추출하고 워크스페이스를 만들거나 선택한 다음 런처를 실행하고 터널 자격 증명을 제공합니다. 런처가 고정된 터널 클라이언트를 자동으로 다운로드하고 검증합니다.

• 두 번째 실행: 동일한 런처를 사용하면 캐시된 터널 클라이언트가 재사용됩니다. 다시 다운로드하거나 재설치할 필요가 없습니다.

• 프로젝트 전환: 동일한 릴리스에 다른 -Workspace 경로를 사용합니다. 각 MCP 프로세스는 여전히 정확히 하나의 고정 워크스페이스를 제공합니다(런타임 전환 없음).

• 오프라인 설치(고급): 공식 tunnel-client-<version>-windows-<arch>.zip을 직접 사전 다운로드하고 공식 SHA256SUMS.txt와 대조 검증한 다음, 추출된 공식 tunnel-client.exe를 -TunnelClientPath로 지정합니다. 이는 고급 운영자 재정의입니다. 런처의 고정 SHA-256 보장을 건너뜁니다(존재 및 --version은 여전히 확인됨). 일반적인 사용에는 필요하지 않습니다.

MCP Inspector로 테스트

npx @modelcontextprotocol/inspector .venv\Scripts\safe-workspace-mcp -- args/config.toml

(또는 MCP SDK CLI의 mcp dev.) tools/list에 정확히 9개의 도구가 표시되는지, 읽기 전용 주석이 올바른지 확인하고, 임시 워크스페이스에서 read → search → apply_changes → git_diff/git_history/git_restore 흐름을 먼저 테스트하세요.

ChatGPT Desktop / ChatGPT Web 연결

ChatGPT는 OpenAI의 Secure MCP Tunnel(Developer Mode / 커넥터)을 통해 로컬 MCP 서버에 연결합니다. 이 프로젝트는 stdio 서버와 운영자가 실행하는 런처만 포함합니다. 터널 전송, OAuth, 자격 증명 저장소가 없으며 ChatGPT/Codex 구성을 읽거나 쓰지 않습니다.

권장 절차:

1. 임시 워크스페이스로 전체 로컬 테스트 스위트를 통과합니다(위 참조).

2. OpenAI Platform에서 Secure MCP Tunnel을 만들고 해당 터널 ID로 휴대용 런처(또는 직접 tunnel-client run)를 실행합니다.

3. ChatGPT에서 런처 터미널이 실행되는 동안 기존 터널을 개발자/앱 커넥터로 연결합니다.

4. 먼저 전용 테스트 워크스페이스를 사용한 다음 구성을 실제 프로젝트로 전환합니다.

ChatGPT는 항상 해당 UI에서 수동으로 구성하세요.

보안 개요

• 워크스페이스 격리 — 워크스페이스 상대 경로만 허용됩니다. 경로 순회, 절대/드라이브/UNC 경로, 예약된 장치 이름, ADS 콜론, 끝자리 점/공백 이름은 모두 거부됩니다. 포함 검사는 파일시스템을 인식하는(realpath 기반) 방식이며 절대 문자열 접두사 방식이 아닙니다.

• 링크 — 기존 경로의 모든 구성 요소에 있는 재분석 지점(심볼릭 링크, 정션, 마운트, 알 수 없는 태그)은 거부됩니다. 하드 링크된 일반 파일(st_nlink > 1)도 거부됩니다.

• 내부 격리 — .git은 모든 파일 도구로 접근할 수 없으며 관리되는 Git 저장소에서만 처리됩니다.

• 원자적 쓰기 — 임시 형제 파일 → fsync → 검증 → os.replace; 실패한 쓰기는 원본을 절대 잘라내지 않습니다.

• 낙관적 동시성 — 오래된 expected_sha256이면 HASH_MISMATCH가 발생하며 사용자의 최신 파일을 덮어쓰지 않습니다.

• 실행 없음 / 네트워크 없음 — 프로덕션 코드에는 서브프로세스/소켓 사용이 없습니다(테스트가 모든 모듈의 import와 호출을 스캔하여 AST로 강제). dulwich의 무조건적인 훅 실행 경로는 import 시에 무력화되며, 심어 놓은 훅 파일로 회귀 테스트됩니다. 관리되는 저장소에는 훅, 필터, 리모트가 절대 추가되지 않습니다.

• 리소스 제한 — 최대 파일/읽기/트랜잭션 바이트 및 검색 결과 수가 제한됩니다. 제한에 도달하면 안전하게 실패합니다.

• 프롬프트 인젝션 — 해결되지 않았고, 격리되어 있습니다. 속은 모델은 한 폴더 안에서 구조화되고 체크포인트된 파일 편집만 수행할 수 있으며, 언제든 롤백할 수 있습니다.

전체 분석 및 잔여 위험은 SECURITY.md와 THREAT_MODEL.md를 참조하세요.

알려진 제한 사항(v0.1.0)

• 텍스트(UTF-8) 파일만 지원하며 바이너리 파일은 거부됩니다.

• Windows가 기본 보안 대상이며 Linux는 지원되고 CI 테스트를 거칩니다.

• 해시 검사 외의 동시 다중 클라이언트 조정은 없습니다(작성자는 하나만 실행하세요).

• 체크포인트 히스토리가 무한정 늘어납니다(v0.1.0에는 gc가 없음).

• 복원은 파일 수준으로 수행되며 제외된 디렉터리는 복원에서 건드리지 않습니다.

보안 취약점 신고

공개 이슈 대신 비공개 보안 권고(GitHub "Report a vulnerability")를 열어 주세요.

라이선스

Apache-2.0 — LICENSE를 참조하세요.