Project Files Read-only MCP

Локальный, многокорневой, доступный только для чтения MCP-сервис файловой системы. Он открывает MCP-клиентам только явно зарегистрированные каталоги проектов и предоставляет ограниченные возможности просмотра каталогов, поиска по именам файлов, чтения текста, а также извлечения содержимого DOCX, PDF и XLSX.

Сервис не регистрирует инструменты записи, редактирования, копирования, перемещения, удаления или выполнения команд. Он подходит для безопасной передачи небольшого количества локальных файлов проекта таким MCP-клиентам, как ChatGPT, для чтения, не exposing при этом весь пользовательский каталог или диск.

Это независимый общественный проект, не являющийся официальным продуктом OpenAI, и OpenAI не даёт никаких гарантий его безопасности или совместимости.

Адрес проекта: github.com/13030109506/project-files-readonly-mcp.

Возможности

Сервис фиксированно предоставляет 9 инструментов только для чтения.

Все инструменты помечены как доступные только для чтения и неразрушающие. Интеграционные тесты также проверяют, что в списке инструментов нет возможностей записи, удаления, перемещения, копирования или выполнения команд.

Related MCP server: Local File Management MCP Server

Границы безопасности

• Принимаются только абсолютные пути, зарегистрированные в roots.json.

• Двойная проверка границ по лексическому пути и результату realpath.

• Отклоняются относительные пути, UNC-пути, пути устройств, Windows ADS, побеги через символические ссылки и точки соединения.

• По умолчанию блокируются .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

Сначала скачайте официальный tunnel-client со страницы настроек OpenAI Platform Tunnel. Этот проект ищет программу в следующем порядке.

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

Установщик сохраняет только Runtime API Key, зашифрованный DPAPI текущего пользователя, и не записывает открытый ключ в параметры задачи, файлы проекта или журналы. Запланированное задание запускается через скрытую 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.