FolderBridge MCP

简体中文 | English

[!TIP] FolderBridge 자체는 단일 파일 Windows 앱입니다: FolderBridge.exe 직접 다운로드 후 더블 클릭하세요. Python이나 Node.js 설치가 필요 없습니다. 바이너리는 GitHub Releases → latest release → Assets에 있습니다. 저장소의 소스 파일 목록에는 나타나지 않습니다. 웹용 ChatGPT의 경우 FolderBridge는 여전히 OpenAI가 별도로 배포하는 공식 tunnel-client.exe를 사용합니다. 런처가 선택 과정을 안내합니다. EXE 및 선택적 SHA-256 체크섬 파일은 전체 릴리스 페이지에서도 열 수 있습니다.

AI 클라이언트와 사용자가 명시적으로 선택한 소수의 폴더 사이의 더 안전하고 로컬 우선 브리지입니다.

FolderBridge MCP는 제로 의존성 Python MCP 서버와 데스크톱 런처입니다. 웹의 ChatGPT 또는 로컬 stdio MCP를 지원하는 모든 클라이언트가 제한된 로컬 작업 영역을 검사하고 신중하게 편집할 수 있게 해줍니다. 공개 HTTP 서버, 임의 셸 액세스, 원격 측정, 조용한 백그라운드 서비스를 의도적으로 피합니다.

[!IMPORTANT] 이 프로젝트는 초기 공개 베타 단계입니다. 공격 표면을 줄여 주지만 운영 체제 샌드박스는 아닙니다. 신뢰하는 폴더와 저장소만 노출하세요.

0.5.1 하이라이트

• 브라우저 인증 GitHub 게시: 새로 번들된 git-publisher 확장은 Git Credential Manager를 통해 GitHub 인증을 열고, OAuth 자격 증명을 Windows 자격 증명 관리자에 보관하며, 명시적 파일 허용 목록만 커밋하고, 현재 브랜치만 기존 GitHub HTTPS 원격으로 푸시할 수 있습니다. 모델에 토큰/PAT/비밀번호 필드가 노출되지 않습니다.

• Git 게시는 계속 제한됩니다: Publisher는 기존 스테이징 변경 사항, 자격 증명/키 유사 파일, 콘텐츠를 변환하는 Git 속성 및 안전하지 않은 저장소 로컬 Git 설정을 거부합니다. git add .를 실행하지 않으며, 임의의 remote/ref를 허용하지 않고, 제한된 커밋에 대해 훅/서명을 비활성화하며, 강제 푸시를 하지 않습니다.

• 네이티브 Microsoft Office 시각적 파이프라인: 번들된 office 확장은 로컬에 설치된 Microsoft Office로 .pptx, .docx, .xlsx를 렌더링할 수 있습니다. PowerPoint는 슬라이드를 PNG로 직접 내보내고, Word/Excel은 네이티브 고정 형식 레이아웃 엔진과 Windows PDF 렌더러를 사용하여 페이지 PNG를 생성합니다.

• Word를 실행하지 않고 Word 구조 읽기: inspect_docx는 OOXML에서 단락, 스타일/번호 매기기, 표, 섹션/페이지 설정, 머리글/바닥글, 미디어, 하이퍼링크, 각주/미주 및 주석을 노출합니다.

• Excel을 실행하지 않고 Excel 구조/수식 읽기: inspect_xlsx는 시트, 제한된 셀 범위, 수식 및 캐시된 값, 병합된 범위, 숨겨진 행/열, 정의된 이름, 계산 설정 및 외부 링크 부분을 노출합니다.

• 감사 준비 출력: 네이티브 렌더링은 결정적 PNG 디렉터리와 함께 같은 위치의 ZIP을 작성하고 Office 소스 및 생성된 출력 모두에 대해 SHA-256/크기 메타데이터를 반환합니다. 기존 image_open 도구는 각 페이지 또는 ZIP 구성원을 시각적으로 검사할 수 있습니다.

• Office 자동화는 제한됩니다: 작업 영역 기준의 비링크 경로만 허용됩니다. 매크로 사용 형식은 제외됩니다. Office 자동화 매크로는 강제로 비활성화됩니다. 파일은 읽기 전용으로 열립니다. Excel 링크 업데이트는 비활성화됩니다. 번들된 PowerShell 스크립트는 고정되어 있으며 임의의 명령을 허용하지 않습니다.

• 기존 0.4.x 안전성/UI 개선 사항 유지: 고DPI 스크롤, ComfyUI 관리 서비스 진단, 안정적인 확장 게이트웨이, 제한된 전역 기능, 단일 파일 Windows 배포는 변경되지 않았습니다.

전체 릴리스 기록은 CHANGELOG.md를, 관리 서비스 및 플러그인 경계는 Extension ABI v1을 참조하세요.

Related MCP server: mcp-readonly-code-server

FolderBridge를 사용하는 이유

• 독립적인 폴더 경계: 하나의 연결에는 최대 8개의 정식 작업 영역이 포함될 수 있습니다. 모든 다중 작업 영역 도구 호출은 루트를 병합하는 대신 workspace_id를 선택합니다.

• 기본적으로 읽기 전용: 런처에서 명시적으로 읽기/쓰기로 전환합니다.

• 충돌 방지 편집: 기존 파일은 마지막 읽기에서 반환된 SHA-256이 필요합니다. 오래된 편집은 최신 작업을 덮어쓰는 대신 실패합니다.

• 임의 셸 없음: 선택적 작업은 이름이 지정되고, 로컬에서 검토되며, 정확한 구성 해시로 승인됩니다.

• 공개 리스너 없음: MCP 서버는 stdio만 사용합니다.

• 원격 측정 없음: FolderBridge 자체는 네트워크 요청을 하지 않습니다.

• 비밀 인식 런처: OpenAI Runtime API 키는 메모리에 유지되며 로컬 MCP 프로세스가 사용할 수 있기 전에 제거됩니다.

• 초보자 친화적 데스크톱 UI: 폴더 추가/제거 목록, 전역 액세스 모드, Tunnel 설정, 진단, 시작/중지, 프로세스 모니터링, 마스킹된 로그가 하나의 창에 있습니다.

• Windows 배율 지원: 글꼴과 창 크기는 현재 디스플레이 DPI를 따르며 배율이 다른 모니터 간에 이동할 때 새로 고쳐집니다.

빠른 시작

요구 사항은 FolderBridge 사용 방법에 따라 다릅니다.

• 독립 실행형 Windows EXE: 별도의 Python 또는 Node.js 설치가 필요 없습니다. Windows는 테스트된 더블 클릭 런처 환경입니다.

• 소스에서 실행/개발: Python 3.11 이상이 필요합니다. Python 3.11 x64가 권장 Windows 빌드 기준입니다.

• 프로젝트 기능: 작업 영역 자체에 필요한 도구 체인만 설치합니다(예: Node/npm 프로젝트의 테스트/빌드 스크립트용 Node.js LTS). 기능을 활성화해도 해당 도구 체인은 설치되지 않습니다.

• Git은 선택 사항입니다. 제한된 status/diff 보기는 Git을 사용할 수 있을 때 사용합니다. Git Publisher 확장은 브라우저 인증 GitHub 커밋/푸시를 위해 Git Credential Manager가 포함된 Git for Windows를 추가로 요구합니다.

Windows 실행 파일 — 권장

단일 FolderBridge.exe를 최신 GitHub 릴리스 Assets에서 다운로드하거나 EXE를 직접 다운로드하세요. 바이너리는 저장소의 소스 파일 목록에 나타나지 않습니다. FolderBridge.exe는 완전한 FolderBridge 애플리케이션이며 이미 Python 런타임을 포함하고 있으므로 일반 EXE 사용자는 Python이나 Node.js를 설치하지 않습니다. 인접한 FolderBridge.exe.sha256 파일은 선택 사항이며 무결성 검증을 위해서만 존재합니다.

단일 파일 실행 파일은 의도적으로 OpenAI가 독립적으로 배포한 tunnel-client를 다시 번들하지 않습니다. 공식 클라이언트를 OpenAI 릴리스에서 별도로 다운로드하고 웹에서 ChatGPT를 사용할 때만 런처에서 tunnel-client.exe를 선택하세요.

[!NOTE] 현재 커뮤니티 빌드는 코드 서명되지 않았으므로 Windows에서 게시자를 알 수 없음으로 식별합니다. 서명되지 않은 바이너리를 신뢰할 수 없다면 감사된 소스에서 직접 빌드하세요.

소스에서 실행

저장소를 클론하고 GUI를 시작하세요:

git clone https://github.com/MoonTzai/folderbridge-mcp.git
cd folderbridge-mcp
python .\folderbridge_launcher.py gui

필요한 작업 영역을 추가하고, 첫 실행에서는 Read only를 선택한 상태로 유지한 후 상태 패널을 사용하여 설정을 완료하세요. 런처 기본 설정은 저장소 외부에 저장되며 Runtime API 키는 절대 저장되지 않습니다. 레거시 단일 작업 영역 설정은 자동으로 첫 번째 목록 항목으로 마이그레이션됩니다.

folderbridge_gui.pyw는 .pyw 연결이 Tkinter가 있는 인터프리터를 가리키는 Python 설치를 위한 소스 전용 편의 파일로 유지됩니다. 독립 실행형 FolderBridge.exe가 지원되는 더블 클릭 진입점입니다.

선택적 개발 및 프로젝트 도구 체인

이들은 일반적인 FolderBridge.exe 사용을 위한 전제 조건이 아닙니다:

• 소스 개발 또는 Windows EXE 재빌드를 위해 공식 Python Windows 다운로드에서 Python 3.11 x64를 설치하고 python --version을 확인하세요. 패키징 흐름은 격리된 .build-venv와 requirements-build.txt를 사용합니다.

• 대상 Node/npm 작업 영역이 자체 테스트 또는 빌드 명령에 node/npm이 필요할 때만 공식 Node.js 다운로드에서 Node.js LTS를 설치하고 node --version 및 npm --version으로 확인하세요.

• 다른 프로젝트는 자체 런타임 또는 컴파일러가 필요할 수 있습니다. FolderBridge 기능은 인증과 제한된 검색/실행을 제공하며 종속성 설치는 제공하지 않습니다.

웹에서 ChatGPT 연결

ChatGPT는 로컬 stdio 프로세스에 직접 연결할 수 없습니다. FolderBridge는 이 경로에 OpenAI의 공식 Secure MCP Tunnel을 사용합니다. 필요한 것:

[!IMPORTANT] Secure MCP Tunnel은 이 컴퓨터에서 **아웃바운드 HTTPS(기본적으로 포트 443)**만 필요하며 인터넷에 노출되는 인바운드 포트가 필요 없습니다. FolderBridge를 위해 Windows 원격 데스크톱, 라우터 포트 포워딩, DMZ, UPnP 매핑 또는 포트 3389를 절대 활성화하지 마세요. 이들 중 어느 것도 Tunnel 설정의 일부가 아닙니다. 방화벽이 인바운드 액세스에 대해 묻는 경우 Tunnel을 작동시키기 위해 광범위한 공용 인바운드 규칙을 만들지 마세요.

• OpenAI Platform Tunnel 설정에서 tunnel_id;

• 같은 조직의 Runtime API Keys에서 tunnel-client용 키;

• 공식 tunnel-client;

• 계정 또는 작업 영역에 적합한 ChatGPT 개발자 모드 액세스.

런처 오른쪽 위의 连接设置向导 (연결 설정 가이드)를 클릭하면 아래의 동일한 단계와 바로 가기(선택적 Python/Node 부록 포함)를 볼 수 있습니다.

1. 공식 Windows x64 클라이언트 다운로드

[!WARNING] 완전한 tunnel-client-v<version>-windows-amd64.zip 아카이브만 다운로드하세요. tunnel-client-runtime-* 파일은 절대 다운로드하거나 선택하지 마세요. 런타임 파일은 내부 구성 요소이며 설정에 필요한 init 명령을 구현하지 않습니다. 이름이 비슷해도 “configuration failed”가 발생할 수 있습니다. 완전한 아카이브를 추출한 후 정확히 tunnel-client.exe라는 이름의 기본 프로그램만 선택하세요.

1. 최신 openai/tunnel-client 릴리스를 열고 Assets를 펼치세요.

2. tunnel-client-v<version>-windows-amd64.zip이라는 이름의 완전한 아카이브를 다운로드하세요. 릴리스 파일 이름에서 amd64는 Windows x64를 의미하며 대부분의 Intel/AMD PC에 적합합니다.

3. 선택적으로 SHA256SUMS.txt를 다운로드하여 검증하세요. tunnel-client-runtime-*, windows-arm64, all.zip, 소스 코드 아카이브 또는 라이선스 파일을 선택하지 마세요. Runtime 아카이브는 완전한 클라이언트를 대체할 수 없습니다.

4. 전체 ZIP을 안정적인 폴더에 추출하세요. 설치 프로그램이 없으며 아카이브 내부에서 실행해서는 안 됩니다. 가이드는 권장 위치로 %LOCALAPPDATA%\FolderBridge\bin을 만들고 열 수 있습니다.

5. FolderBridge로 돌아가 选择已解压的 EXE를 클릭하고 정확히 tunnel-client.exe라는 이름의 파일만 선택하세요.

2. Platform Tunnel 만들기

OpenAI Platform Tunnel 설정을 열고 Create tunnel을 클릭한 후 다음 현재 선택 사항을 사용하세요:

생성 후 tunnel_로 시작하는 Tunnel ID를 복사하세요. 실행 및 선택에는 Tunnels Read + Use 권한이 필요하며, 생성 또는 편집에도 Manage 권한이 필요합니다. 이 로컬 작업 공간에 액세스해야 하는 조직과 ChatGPT 작업 공간만 연결하세요.

같은 Platform 조직의 Runtime API Keys에서 tunnel-client용 키를 생성하세요. 키 생성자에게는 Tunnels Read + Use 권한이 필요합니다. 이 키는 FolderBridge에만 붙여넣고, 프로세스 메모리에만 유지됩니다. Admin API 키는 사용하지 마세요. Runtime 키를 ChatGPT 앱의 Authentication 필드에 넣지 마세요.

3. FolderBridge 시작

1. 명시적 작업 공간 폴더를 하나 이상(최대 8개) 추가하고 첫 실행에서는 읽기 전용(권장) 을 유지하세요. 전역 액세스 모드는 나열된 모든 폴더에 적용됩니다.

2. 전체 아카이브에서 tunnel-client.exe를 선택하세요. tunnel-client-runtime-* 구성 요소는 절대 선택하지 마세요. 기본 folderbridge 프로필로 충분합니다.

3. 동일한 Tunnel ID와 Runtime API 키를 입력하세요. 원하는 전역 기능을 한 번만 활성화할 수 있습니다. 사용자 지정 명령이 필요하지 않으면 작업 공간별 고급 명명 작업은 비활성화된 상태로 두세요.

4. 연결 시작을 클릭하세요. 런처는 공식 init, doctor, run 흐름을 실행합니다. 상단 상태가 运行中(실행 중)으로 표시된 후에만 계속 진행하세요. 나중에 폴더나 액세스 모드를 변경할 때는 应用配置(구성 적용)을 다시 클릭하세요. 런처는 관리하는 동일한 프로파일을 업데이트합니다.

4. ChatGPT 개발자 모드 앱 만들기

ChatGPT Plugins을 열고 **+**를 클릭한 후 다음 중요한 선택을 하세요:

[!WARNING] 양식을 기본 OAuth 선택으로 두지 마세요. Server URL에 https://tunnel-service... 주소를 붙여넣지 마세요. FolderBridge는 사용자 OAuth를 구현하지 않으므로 해당 구성은 does not implement OAuth 오류를 생성합니다.

ChatGPT 대화에서 앱 호출

1. FolderBridge 상태를 运行中(실행 중)으로 유지한 후 새 ChatGPT 대화를 시작하세요.

2. 작성기 옆의 **+**를 선택하고 More를 연 다음 방금 만든 FolderBridge 앱을 선택하세요.

3. 다음과 같은 작업을 보내세요: "먼저 FolderBridge server_info를 사용하여 사용 가능한 작업 공간을 나열한 다음, 제가 지정한 작업 공간의 루트를 읽으세요." 승인 전에 도구 확인에서 workspace_id와 대상 파일을 검토하세요.

이 진입점은 OpenAI 공식 연결 및 테스트 가이드를 따릅니다. 런처의 연결 가이드에는 동일한 단계와 원클릭 복사 가능한 예제 프롬프트가 포함되어 있습니다.

ChatGPT가 작업 공간을 사용하는 동안 런처를 계속 실행하세요. 런처를 닫으면 Tunnel 프로세스가 중지됩니다. 계정 수준의 개발자 모드 및 앱 설치 확인은 ChatGPT에 남아 있습니다. FolderBridge는 브라우저 세션이나 보안 설정을 자동화하지 않습니다.

브라우저 확장 프로그램은 필요하지 않습니다. FolderBridge는 의도적으로 네트워크에서 전달된 바이너리를 자동으로 다운로드하거나 실행하지 않습니다.

다른 로컬 MCP 클라이언트 연결

예. FolderBridge의 호환성 접합부는 표준 MCP stdio 서버입니다. ChatGPT Tunnel은 로컬 프로세스를 시작할 수 없는 웹 클라이언트를 위한 브리지일 뿐입니다. MCP stdio 전송은 클라이언트가 서버 하위 프로세스를 시작하고 표준 입력/출력으로 JSON-RPC를 교환하도록 지정합니다. MCP stdio 사양

클라이언트 요구 사항

• 로컬 명령 + 인수 쌍을 구성하고 하위 프로세스를 계속 실행할 수 있어야 합니다.

• stdio를 통한 MCP를 지원하며 프로토콜 메시지용으로 stdout을 예약해야 합니다.

• MCP 도구(initialize, tools/list, tools/call 또는 최신 2026-07-28 검색 흐름)를 검색하고 호출할 수 있어야 합니다.

• 세션이 종료되면 stdin을 닫거나 하위 프로세스를 종료해야 합니다.

• 도구 승인 UX가 있는 클라이언트를 선호하지만, 해당 확인 대화 상자를 유일한 보안 경계로 취급하지 마세요.

FolderBridge는 현재 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25, 2026-07-28 프로토콜 경로를 처리합니다. 표준 도구 스키마, 텍스트 콘텐츠 및 structuredContent를 반환합니다. 확인 프롬프트가 표시되는지 여부는 클라이언트에 따라 다릅니다. MCP 도구 사양

가장 간단한 로컬 설정

1. FolderBridge에서 작업 공간을 하나 이상 추가하고 읽기 전용(권장) 을 유지하세요.

2. 连接设置向导의 5페이지를 열고 JSON, TOML 또는 전체 stdio 명령을 복사하세요.

3. 클라이언트의 MCP 서버 설정에 붙여넣고 해당 클라이언트의 정확한 필드 이름에 대한 문서를 따르세요.

4. 클라이언트를 다시 시작하거나 새로 고치고 server_info 및 workspace가 나타나는지 확인하세요.

직접 stdio 연결에는 tunnel-client, Tunnel ID, Runtime API 키 또는 실행 중인 FolderBridge GUI가 필요 없습니다. 클라이언트는 필요할 때 이 명령을 시작합니다:

FolderBridge.exe serve --workspace C:\path\to\repo --read-only

각 루트를 독립적으로 유지하면서 폴더를 추가하려면 --workspace를 반복하세요:

FolderBridge.exe serve --workspace C:\work\frontend --workspace C:\work\backend --read-only

소스에서 붙여넣기 준비된 구성을 생성하세요:

python .\folderbridge_launcher.py client-config --workspace C:\path\to\repo --format json --read-only
python .\folderbridge_launcher.py client-config --workspace C:\path\to\repo --format toml --read-only
python .\folderbridge_launcher.py client-config --workspace C:\path\to\repo --format tunnel --read-only

JSON 출력은 많은 데스크톱 클라이언트에서 사용하는 일반적인 mcpServers 규칙을 따릅니다:

{
  "mcpServers": {
    "folderbridge": {
      "command": "C:\\Tools\\FolderBridge.exe",
      "args": ["serve", "--workspace", "C:\\work\\frontend", "--workspace", "C:\\work\\backend", "--read-only"]
    }
  }
}

[!IMPORTANT] JSON/TOML 최상위 키는 일반적인 규칙이지 보편적인 클라이언트 요구 사항이 아닙니다. 호환성은 궁극적으로 클라이언트가 명령/인자를 변경하지 않고 MCP stdio 하위 프로세스로 시작한다는 것을 의미합니다. 클라이언트가 URL만 허용하는 경우 이 릴리스에는 기본 제공 HTTP/SSE 리스너가 없습니다. 임시 로컬 포트를 공개 인터넷에 직접 노출하지 마세요.

프로토콜 버전, 프로세스 수명 주기, cwd/env, 승인 경계 및 원격 브리징 세부 정보는 클라이언트 호환성 연구를 참조하세요.

도구 및 편집 워크플로우

내장 서버 도구는 작업 공간별 작업 구성에 의존하지 않습니다:

• server_info: 각 사용 가능한 작업 공간 이름, 안정적인 workspace_id, 내장/전역 기능 및 안전 경계를 보고합니다.

• workspace: 선택한 workspace_id 내에서 파일을 나열, 읽기, 검색하고 제한된 Git 상태/diff 출력을 표시합니다.

• file_info: 바이너리 파일에 대한 제한된 메타데이터와 SHA-256을 반환합니다.

• pptx_inspect: Office 콘텐츠를 실행하지 않고 PPTX 텍스트, OOXML 다이어그램 관계 및 SmartArt 데이터를 검사합니다.

• image_open: ZIP 파일 내의 정확한 이미지 멤버를 포함하여 제한된 PNG/JPEG/GIF/WebP 이미지 콘텐츠를 MCP 클라이언트에 반환합니다.

• extension: 핫로드 확장을 위한 안정적인 list / info / run 게이트웨이입니다. 플러그인을 더 설치해도 MCP 도구 이름이 추가되지 않습니다.

• edit_file: 읽기/쓰기 모드에서 선택한 작업 공간 내부에 UTF-8 파일을 생성하거나 정확히 편집합니다.

작업 공간이 하나인 경우 기존 클라이언트는 workspace_id를 계속 생략할 수 있습니다. 작업 공간이 여러 개인 경우 작업 공간 범위 도구에는 server_info가 반환한 workspace_id가 필요합니다. 누락되거나 알 수 없는 ID는 거부됩니다. 중복 루트, 부모/자식 겹침 및 8개 이상의 목록은 시작 전에 거부됩니다.

안전한 편집 루프는 다음과 같습니다:

1. 파일을 나열하거나 검색합니다.

2. 파일을 읽고 반환된 SHA-256을 유지합니다.

3. 해당 해시로 정확한 대체 파일을 제출합니다.

4. Git diff를 검사합니다.

서버는 파일을 삭제하거나 이동할 수 없습니다. 절대 경로, .., 심볼릭 링크, 정션/리파스 포인트, VCS 내부, 일반적인 종속성/빌드 폴더 및 자격 증명과 유사한 이름은 거부됩니다.

전역 사전 승인 기능

런처는 현재 및 미래의 모든 작업 공간에 대해 test, build, package-windows, package-android, git-push와 같은 일반적인 기능을 한 번에 승인할 수 있습니다. 이러한 권한은 .folderbridge.json이 아닌 런처 설정에 저장되므로 작업 공간이 추가된 지 몇 달 후에 지원되는 빌드 스크립트를 얻을 수 있으며 FolderBridge는 호출 시점에 이를 감지합니다. 런처는 이 그룹에 대한 Select all 및 Clear 컨트롤도 제공합니다.

git-push는 GitHub HTTPS origin, 현재 브랜치, 강제 푸시 없음, 저장소 로컬 자격 증명 도우미/푸시 대상 재작성 구성 없음으로 제한된 저수준 푸시 전용 기능입니다. 브라우저 인증과 명시적 파일 커밋 + 푸시를 위해서는 번들된 Git Publisher 확장을 대신 사용하세요. 빌드/패키지 기능은 로컬 프로젝트 코드를 실행할 수 있으므로 원하는 전역 기능만 활성화하세요.

직접 stdio 클라이언트의 경우 serve 또는 client-config 명령에서 --capability <name>을 반복하세요. Windows 런처는 동일한 선택을 영구 체크박스로 표시합니다.

확장

FolderBridge Extension ABI v1은 ComfyUI, FFmpeg, Blender, Ollama, ADB 또는 기타 로컬 도구와 같은 향후 전역 통합을 MCP 도구 카탈로그를 변경하지 않고 추가하는 기본 방법입니다. Windows 런처에는 기본적으로 축소된 Extensions 사이드바가 있으며, 사용자 확장 디렉터리를 핫 스캔하고 설치/승인/로드 상태를 표시하며 Tunnel이 연결된 상태에서 플러그인을 승인하거나 비활성화할 수 있습니다.

각 확장은 최소한 folderbridge-extension.json과 plugin.py를 포함하는 디렉터리입니다. 외부 플러그인은 전체 플러그인 디렉터리의 정확한 SHA-256과 선언된 권한 목록에 대해 승인됩니다. 파일이나 권한을 변경하면 승인이 만료됩니다. 확장은 정리된 환경, 제한된 프로토콜 I/O 및 선언된 시간 제한이 있는 별도의 하위 프로세스에서 실행됩니다. 이는 충돌과 프로토콜 오염을 격리하지만 OS 보안 샌드박스는 아닙니다: 신뢰할 수 없는 플러그인 코드에는 VM/컨테이너를 사용하세요.

Workspace별 적응은 workspace_adapter.mode=dynamic과 detect.any_of / detect.all_of를 사용해야 합니다. FolderBridge는 호출 시점에 해당 패턴을 재평가하므로, 확장 프로그램은 설치 시 .folderbridge.json 작업을 주입할 필요가 없으며, 이후 프로젝트가 변경되면 적용 가능해질 수 있습니다. 영구 플러그인 상태는 제공된 프로필 상태 디렉터리를 사용해야 하며, 저장소를 오염시켜서는 안 됩니다.

ComfyUI는 첫 번째 번들 확장 프로그램입니다. 해당 상태 작업은 고정 루프백 엔드포인트 127.0.0.1:8188을 확인합니다. 워크플로 실행에는 Extensions 사이드바에서 일회성 승인이 필요합니다. FolderBridge 0.4.1에서 Windows 런처는 로컬 ComfyUI 프로세스 자체도 관리할 수 있습니다. 지원되는 Portable 루트(python_embeded\\python.exe + ComfyUI\\main.py) 또는 소스 루트(main.py + .venv\\Scripts\\python.exe / venv\\Scripts\\python.exe)를 한 번 선택하면, 런처가 명시적인 Python/main.py 인수, shell=False, 고정 127.0.0.1:8188 바인딩으로 자동 시작할 수 있습니다. FolderBridge가 시작하기 전에 해당 엔드포인트가 이미 온라인 상태라면, 해당 서비스는 외부 서비스로 표시되고 중복 생성 대신 재사용됩니다.

관리 서비스 소유권은 의도적으로 Extension 권한보다 엄격합니다. FolderBridge는 install_root와 auto_start만 저장하며, PID나 임의 명령은 절대 저장하지 않습니다. 현재 런처 실행에서 생성된 메모리 내 Popen 핸들만 소유 및 중지 가능한 것으로 간주됩니다. FolderBridge는 ComfyUI용으로 사용자가 선택한 BAT/CMD를 절대 실행하지 않으며, 단지 포트 8188을 점유하고 있다는 이유만으로 알 수 없는 프로세스를 조회하거나 종료하지 않습니다. 종료 시 Tunnel/MCP 이전에 소유한 관리 서비스를 중지하며, 외부 ComfyUI는 계속 실행됩니다.

Windows에서 런처는 Per-Monitor DPI V2 인식을 요청하고, 가벼운 폴백으로 현재 창 DPI도 폴링합니다. 고정 GUI 메트릭은 DPI가 실제로 변경될 때만 원래 논리적 크기(dpi / 96)에서 재계산되므로, 96 → 144 → 96 DPI로 이동해도 배율 드리프트가 누적되지 않습니다.

ABI v1 플러그인은 단일 파일 EXE 내부에서 임의의 pip 의존성을 가정하기보다 FolderBridge 패키지 모듈과 Python 표준 라이브러리를 사용해야 합니다. 추가 소프트웨어는 일반적으로 정밀한 루프백 API 또는 선언된 process.execute:<basename> 의존성을 통해 접근해야 합니다. FolderBridge.exe extensions --json을 실행하여 패키징된 실행 파일이 무엇을 발견할 수 있는지 확인하세요. 연결 가이드 부록에는 전체 형식과 원클릭 LLM 플러그인 개발 프롬프트가 포함되어 있으며, 이 프롬프트는 모델이 추측하는 대신 누락된 API 문서, 스크립트, 워크플로, 샘플 파일 또는 프로젝트 구조를 요청/업로드하도록 지시합니다. Extension ABI v1을 참조하세요.

선택적 workspace별 명명된 작업

임의의 명령 텍스트는 MCP를 통해 절대 허용되지 않습니다. 전역 기능으로 처리되지 않는 특이한 저장소별 명령의 경우, 로컬 작업 정책을 생성하고 검토하세요:

python .\folderbridge_launcher.py init --workspace C:\path\to\repo
# Review C:\path\to\repo\.folderbridge.json
python .\folderbridge_launcher.py approve --workspace C:\path\to\repo

그런 다음 런처에서 승인된 작업을 활성화하거나 생성된 서버 명령에 --allow-tasks를 추가하세요. 이 스위치를 활성화한다고 해서 구성된 모든 workspace에 .folderbridge.json이 포함되어야 하는 것은 아닙니다. 구성이 없는 workspace, 승인된 작업이 있는 workspace, 확장 전용 workspace, 아직 승인되지 않은 구성을 가진 workspace는 하나의 연결에서 공존할 수 있습니다. 승인은 해당 workspace의 명명된 작업이 실제로 호출될 때 확인됩니다. 모델은 작업 이름만 선택할 수 있으며, 명령, 인수, 환경 변수 또는 작업 디렉터리를 제공할 수 없습니다.

[!WARNING] 테스트, 빌드 도구 및 패키지 스크립트는 현재 OS 사용자 권한으로 저장소 코드를 실행합니다. 신뢰할 수 없는 저장소에는 일회용 VM이나 컨테이너를 사용하거나, 작업 실행을 비활성화된 상태로 두세요.

보안 모델

FolderBridge는 MCP 요청, 저장소 텍스트 및 도구 출력을 신뢰할 수 없는 데이터로 취급합니다. 강제는 MCP 주석만이 아니라 도구 구현에 있습니다. 주요 통제 수단은 다음과 같습니다:

• workspace별 정규 경로 제한 및 링크 거부, 중복 루트 거부;

• 제한된 UTF-8 읽기, 검색, Git 출력, 하위 프로세스 출력 및 프로토콜 메시지;

• 현재 콘텐츠 해시 사전 조건이 있는 원자적 쓰기;

• 보호된 로컬 정책 파일;

• shell=False, 고정 인수 배열, 깨끗한 작업 환경 및 타임아웃;

• 확장 매니페스트는 알 수 없거나 과도하게 광범위한 권한 이름을 거부하고, 확장 승인은 정확한 코드 해시와 권한에 바인딩되며, 플러그인 실행은 MCP 프로세스 밖으로 이동됨;

• 인바운드 네트워크 리스너 없음 및 FolderBridge 텔레메트리 없음.

전체 보안 모델과 업스트림 설계 연구를 읽어보세요. 취약점을 신고하려면 SECURITY.md를 따르세요.

개발

타사 런타임 의존성이 없습니다.

python -m unittest discover -s tests -v

풀 리퀘스트를 열기 전에 CONTRIBUTING.md를 참조하세요.

Windows 실행 파일 빌드

빌드는 고정된 빌드 전용 PyInstaller 의존성을 사용합니다. 릴리스된 EXE는 hide-console=hide-early와 함께 콘솔 부트로더를 사용합니다. 더블 클릭하면 GUI만 열리며, 동일한 실행 파일은 Tunnel이 serve 하위 명령을 시작할 때 stdio를 유지합니다.

python -m venv .build-venv
.\.build-venv\Scripts\python.exe -m pip install -r requirements-build.txt
.\scripts\build_windows.ps1 -Python .\.build-venv\Scripts\python.exe

아티팩트와 SHA-256 파일은 release\windows-x64에 기록됩니다.

라이선스

Apache License 2.0에 따라 라이선스가 부여됩니다.

FolderBridge MCP는 독립적인 오픈 소스 프로젝트입니다. OpenAI와 제휴, 보증 또는 후원 관계가 아닙니다. ChatGPT, OpenAI, MCP 및 기타 제품 이름은 해당 소유자의 자산입니다.