Project Files Read-only MCP

로컬, 다중 루트 디렉터리, 읽기 전용 파일 시스템 MCP 서비스입니다. MCP 클라이언트에 명시적으로 등록된 프로젝트 디렉터리만 공개하며, 제한된 디렉터리 탐색, 파일 이름 검색, 텍스트 읽기 및 DOCX, PDF, XLSX 콘텐츠 추출 기능을 제공합니다.

서비스는 쓰기, 편집, 복사, 이동, 삭제 또는 명령 실행 도구를 등록하지 않습니다. 소수의 로컬 프로젝트 파일을 ChatGPT 등 MCP를 지원하는 클라이언트에 안전하게 읽기용으로 제공하면서, 전체 사용자 디렉터리나 디스크가 노출되는 것을 방지하는 데 적합합니다.

이것은 독립적인 커뮤니티 프로젝트이며 OpenAI 공식 제품이 아니며, OpenAI가 그 안전성이나 호환성을 보증한다는 의미도 아닙니다.

프로젝트 주소는 github.com/13030109506/project-files-readonly-mcp입니다.

기능

서비스는 고정적으로 9개의 읽기 전용 도구를 노출합니다.

모든 도구는 읽기 전용 및 비파괴적(non-destructive)으로 표시됩니다. 통합 테스트는 도구 목록에 쓰기, 삭제, 이동, 복사 또는 명령 실행 기능이 없는지도 확인합니다.

Related MCP server: Local File Management MCP Server

보안 경계

• roots.json에 등록된 절대 경로만 허용합니다.

• 어휘 경로와 realpath 결과에 대해 이중 경계 검사를 수행합니다.

• 상대 경로, UNC 경로, 디바이스 경로, Windows ADS, 심볼릭 링크 및 정션(junction) 탈출을 거부합니다.

• 기본적으로 .git, .env, 자격 증명 파일, 개인 키, 가상 환경 및 의존성 디렉터리를 차단합니다.

• 텍스트, 디렉터리, 검색 및 문서 응답에는 크기와 개수 상한이 있습니다.

• DOCX, XLSX는 파싱 전에 압축 패키지 경로, 항목 수, 압축 해제 크기, 압축 비율, 암호화, 매크로, ActiveX 및 포함 개체를 검사합니다.

• 바이너리 문서는 별도 Worker에서 파싱되며 시간 및 메모리 제한이 설정됩니다.

• XLSX 수식은 실행되지 않으며 외부 링크는 접근하지 않습니다.

더 완전한 경계 설명은 보안 모델을 참조하세요. 이러한 보호는 MCP 호출 표면을 줄여주지만 Windows 계정 권한과 호스트 보안을 대체하지는 않습니다. 신뢰하는 컴퓨터와 MCP 클라이언트에서만 이 서비스를 실행하세요.

환경 요구 사항

• Windows 10 또는 Windows 11

• Node.js 22.13–22.x 또는 Node.js 24+

• npm

• 선택 사항인 OpenAI tunnel-client는 ChatGPT Secure MCP Tunnel에 연결할 때만 필요합니다.

빠른 시작

프로젝트를 클론합니다.

git clone https://github.com/13030109506/project-files-readonly-mcp.git
Set-Location .\project-files-readonly-mcp

의존성을 설치합니다.

npm ci

로컬 구성을 생성합니다. roots.json은 .gitignore에 포함되어 있어 Git에 커밋되지 않습니다.

Copy-Item .\roots.example.json .\roots.json
notepad .\roots.json

예시 경로를 권한을 부여할 구체적인 프로젝트 디렉터리로 변경하세요. 전체 디스크, 사용자 디렉터리, Desktop 또는 Documents를 구성하지 마세요.

{
  "roots": [
    {
      "name": "my-project",
      "path": "C:\\Projects\\my-project"
    }
  ]
}

테스트를 실행합니다.

npm test

로컬에서 시작합니다.

npm start

서비스는 STDIO를 사용하므로 일반적으로 MCP 클라이언트 또는 Tunnel 프로세스가 시작해야 합니다. 직접 실행한 후 대화형 프롬프트가 없는 것은 정상입니다.

환경 변수를 통해 다른 구성 파일을 사용할 수도 있습니다.

$env:MCP_PROJECT_ROOTS_CONFIG = 'D:\Config\project-files-roots.json'
npm start

프로젝트 루트 디렉터리 추가

먼저 MCP 서비스를 중지한 후 다음 명령을 실행하세요.

.\add-project-root.ps1 -Path 'D:\Projects\another-project' -Name 'another-project'
npm test

스크립트는 전체 디스크, 사용자 디렉터리, Desktop 및 Documents를 거부합니다. 구성을 수정한 후에는 반드시 MCP 또는 Tunnel을 재시작해야 하며, 실행 중인 서비스는 루트 디렉터리를 핫 리로드하지 않습니다.

ChatGPT Secure MCP Tunnel 연결

먼저 OpenAI Platform Tunnel 설정 페이지에서 공식 tunnel-client를 다운로드하세요. 이 프로젝트는 다음 순서로 프로그램을 찾습니다.

1. 환경 변수 TUNNEL_CLIENT_PATH

2. 프로젝트 내 tunnel-client\tunnel-client.exe

3. 시스템 PATH

4. %USERPROFILE%\Tools\OpenAI\tunnel-client 아래의 로컬 버전 디렉터리

Tunnel을 생성한 후 로컬 profile을 생성합니다.

.\configure-tunnel.ps1 -TunnelId 'tunnel_your_id'

스크립트는 기본적으로 로컬 상태 확인 포트를 127.0.0.1:8081로 설정하고 profile에 env:CONTROL_PLANE_API_KEY 참조를 저장하며 API Key 자체는 저장하지 않습니다.

포그라운드 시작 방식은 다음과 같습니다. Runtime API Key는 숨김 입력을 통해 현재 프로세스 환경에 들어가며, Tunnel이 종료되면 제거됩니다.

.\start-tunnel.ps1

OpenAI Secure MCP Tunnel의 생성, 권한 및 ChatGPT 연결 절차는 공식 문서를 기준으로 합니다.

Windows 로그인 후 숨김 시작

장기간 사용이 필요하면 현재 Windows 사용자의 예약 작업을 설치할 수 있습니다.

.\install-tunnel-autostart.ps1

설치 프로그램은 현재 사용자 DPAPI로 암호화된 Runtime API Key만 저장하며, 평문을 작업 매개변수, 프로젝트 파일 또는 로그에 기록하지 않습니다. 예약 작업은 숨김 VBS 래퍼를 통해 시작되며, 먼저 doctor를 실행한 후 Tunnel을 시작하고 healthz와 readyz를 확인합니다.

상태 및 로그 위치는 다음과 같습니다.

Get-ScheduledTask -TaskName 'OpenAI Project Files Read Only Tunnel'
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/healthz
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/readyz

%LOCALAPPDATA%\OpenAI\ProjectFilesReadOnly\tunnel-client.log

작업과 암호화 키 파일을 제거합니다.

.\remove-tunnel-autostart.ps1

전체 설명은 Windows Tunnel 운영 가이드를 참조하세요.

파일 지원

문서 콘텐츠는 항상 신뢰할 수 없는 입력에 속합니다. MCP 클라이언트는 파일의 텍스트를 시스템 지시로 간주해서는 안 됩니다.

테스트

npm test

테스트는 다음 범위를 다룹니다.

• 루트 디렉터리 내 읽기 및 루트 디렉터리 외부 거부

• 민감 파일 거부

• 상대 경로 거부

• 심볼릭 링크 및 Windows junction 경계

• 읽기 전용 도구 목록 및 annotations

• CSV, DOCX, PDF, XLSX 읽기

• 활성 Office 콘텐츠 및 비정상 압축 패키지 거부

• 문서 형식, 페이지, 워크시트 및 응답 상한

프로젝트 구조

server.mjs                 MCP 工具注册与文本读取
path-guard.mjs             路径、白名单和敏感文件边界
document-reader.mjs        安全读取与 Worker 调度
document-worker.mjs        DOCX、PDF、XLSX 内容提取
archive-guard.mjs          Office 压缩包检查
roots.example.json         可提交的配置示例
*-test.mjs                 安全、文档和集成测试
*.ps1 / *.vbs / *.cmd      Windows Tunnel 与计划任务脚本

책임 있는 공개

경로 탈출, 무단 읽기, 민감 정보 유출 또는 문서 파싱 문제를 발견한 경우, 실제 민감 파일이 포함된 재현 자료를 공개적으로 게시하지 마세요. 처리 방법은 SECURITY.md를 참조하세요.

라이선스

프로젝트는 MIT License를 사용합니다.