PC FileBridge

PC FileBridge는 ChatGPT, Codex 및 기타 MCP 클라이언트에 운영자가 선택한 폴더에 대한 제한된 접근을 제공하는 로컬 Model Context Protocol(MCP) 서버입니다. UTF-8 텍스트를 읽고 새 파일이나 디렉터리를 만들 수 있지만, 덮어쓰기, 추가, 이름 변경, 이동, 링크, 삭제는 할 수 없습니다.

생성 전용 보장은 서버에 의해 강제됩니다. 새 파일은 운영 체제의 배타적 생성 모드(wx)를 사용하므로, 기존 대상이 있으면 TARGET_EXISTS를 반환하고 변경되지 않은 상태로 유지됩니다.

보안 속성

• 모든 작업은 구성된 root_id와 상대 경로를 사용합니다.

• 절대 경로, UNC 경로, 경로 탐색(traversal), 대체 데이터 스트림, 예약된 Windows 이름, 심볼릭 링크, 정션(junction), reparse-point 탈출이 차단됩니다.

• 민감한 폴더와 자격 증명 파일 이름은 숨겨지고 거부됩니다. 여기에는 .ssh, .aws, .azure, .codex, .git, AppData, .env*, 개인 키 형식, PuTTY .ppk, Java 키스토어, SSH id_* 개인 키 이름이 포함됩니다.

• 텍스트 읽기는 UTF-8 전용이며 바이트 크기가 제한되고 일반적인 자격 증명 패턴을 편집(redact)합니다.

• 디렉터리 목록과 파일 이름 검색은 결과가 제한됩니다.

• 서버에는 네트워크 클라이언트가 없으며 셸 명령을 실행하지 않습니다.

• 전체 드라이브 루트를 노출하려면 정확하고 명시적인 위험 옵트인(opt-in)이 필요합니다.

이러한 통제는 위험을 줄여 주지만 모든 일반 문서가 비공개인지 판단할 수는 없습니다. 가장 좁은 유용한 루트를 구성하고 반환된 파일 콘텐츠를 신뢰할 수 없는 데이터로 취급하십시오.

Related MCP server: Kastor

MCP 도구

삭제, 덮어쓰기, 추가, 패치, 이름 변경, 이동, 제거, 연결 해제(unlink) 도구는 없습니다.

요구 사항

• Node.js 22 이상

• 제공되는 Secure MCP Tunnel 및 작업 스케줄러 도우미에는 Windows 필요

• MCP 호환 클라이언트

핵심 서버와 정책 테스트는 Linux 및 macOS에서도 실행됩니다.

설치 및 구성

git clone https://github.com/gexiro-global/pc-filebridge.git
Set-Location pc-filebridge
npm ci --ignore-scripts
Copy-Item .\config\roots.example.json .\config\roots.local.json

config\roots.local.json을 편집하고 예제 경로를 사용자가 제어하는 하나 이상의 폴더로 바꾸십시오. 이 로컬 파일은 Git에서 무시됩니다.

빌드 및 검증:

npm run verify

stdio로 실행:

$env:FILEBRIDGE_CONFIG = (Resolve-Path .\config\roots.local.json).Path
node .\mcp\server.mjs

저장소에는 .mcp.json과 Codex 플러그인 매니페스트가 포함되어 있습니다. 생성된 MCP 프로세스에서 FILEBRIDGE_CONFIG를 사용할 수 있는지 확인하십시오. 구성이 없으면 시작 시 CONFIG_UNAVAILABLE과 함께 안전하게 실패(fail closed)합니다.

ChatGPT Secure MCP Tunnel

ChatGPT의 경우 전용 Secure MCP Tunnel과 전용 런타임 API 키를 만드십시오. 키는 저장소 외부에 보관하십시오. 도우미 스크립트는 터널 클라이언트가 %LOCALAPPDATA%\PCFileBridge\bin\tunnel-client.exe에 있기를 기대하며, 키는 제한된 ACL로 %LOCALAPPDATA%\PCFileBridge\private\.env.local에 저장합니다.

.\scripts\Initialize-PCFileBridgeRuntimeKey.ps1
.\scripts\Connect-PCFileBridgeTunnel.ps1 -TunnelId 'tunnel_...'
.\scripts\Get-PCFileBridgeTunnelStatus.ps1

터널 런타임은 구성된 폴더를 소유한 컴퓨터에서 실행되어야 합니다. 별도로 보안된 개인 채널이 해당 PC의 런타임에 도달하지 않는 한 원격 VPS는 PC 디스크에 접근할 수 없습니다.

도우미는 기본적으로 구성된 좁은 루트를 사용합니다. 전체 드라이브 모드는 기본적으로 절대 활성화되지 않습니다.

선택적 자동 시작

수동 연결이 성공한 후:

.\scripts\Install-PCFileBridgeAutostart.ps1 -TunnelId 'tunnel_...'

설치 프로그램은 새 사용자별 예약 작업을 만들며 기존 작업을 대체하지 않습니다.

전체 드라이브 모드

전체 드라이브를 노출하면 정보 공개 위험이 크게 증가합니다. 서버는 전체 드라이브 구성과 다음의 정확한 프로세스 변수가 모두 제공되지 않는 한 파일 시스템 루트를 거부합니다:

$env:FILEBRIDGE_CONFIG = (Resolve-Path .\config\roots.full-drive.example.json).Path
$env:FILEBRIDGE_ALLOW_DRIVE_ROOT = 'I_ACCEPT_FULL_DRIVE_ACCESS_RISK'
node .\mcp\server.mjs

Windows 터널 도우미는 -EnableFullDrive $true로 명시적으로 호출된 경우에만 동일한 옵트인을 수행합니다.

개발

npm ci --ignore-scripts
npm run check
npm pack --dry-run --ignore-scripts

npm run check는 추적 파일 비밀 검사, 타입 검사, 정책 테스트, 프로덕션 빌드, 그리고 정확히 7개의 도구와 금지된 변경(mutation) 도구 0개를 요구하는 실제 MCP stdio 스모크 테스트를 수행합니다. 풀 리퀘스트는 Linux와 Windows에서 동일한 보안 게이트를 실행합니다. Windows 작업은 실제 정션을 만들고 거부해야 하며 해당 검사를 조용히 건너뛸 수 없습니다.

릴리스 검증

공식 릴리스에는 다음 네 개의 다운로드 파일이 포함됩니다:

• pc-filebridge-vX.Y.Z-runtime-npm.tgz

• pc-filebridge-vX.Y.Z-source.tar.gz

• pc-filebridge-vX.Y.Z-sbom.cdx.json

• SHA256SUMS

설치 전에 모든 파일을 하나의 빈 디렉터리에 다운로드하고 해시를 검증하십시오. Windows에서:

Get-Content .\SHA256SUMS | ForEach-Object {
  $hash, $name = $_ -split '  ', 2
  if ((Get-FileHash -Algorithm SHA256 -LiteralPath $name).Hash.ToLowerInvariant() -ne $hash) {
    throw "Checksum mismatch: $name"
  }
}

GitHub 릴리스에는 빌드 출처 증명(build-provenance attestations)도 포함되어 있습니다. 릴리스 검증 및 릴리스 프로세스를 참조하십시오.

개인 정보 보호 및 보안

PC FileBridge는 자체 호스팅되며 원격 측정(telemetry)을 포함하지 않습니다. MCP를 통해 요청된 데이터는 연결된 클라이언트로 전송되며, 이후 해당 클라이언트의 공급자 및 작업 공간 정책의 적용을 받습니다. 민감한 폴더를 노출하기 전에 ARCHITECTURE.md, PRIVACY.md, SECURITY.md, SUPPORT.md, THREAT_MODEL.md를 읽으십시오.

라이선스

Apache-2.0. Copyright 2026 Gexiro Global Enterprises Ltd.