safe-workspace-mcp

Минимальный, ориентированный на безопасность MCP сервер, который обеспечивает структурированный доступ на чтение/запись ровно к одной локальной рабочей области, со встроенными локальными контрольными точками Git и откатом.

Предназначен для того, чтобы чат-модель (например, ChatGPT с поддержкой MCP) могла безопасно редактировать файлы в одной папке проекта — и только в ней.

Переносимый быстрый старт в Windows (без Python, Git и Node)

1. Скачайте ZIP-архив релиза для Windows со страницы Releases и распакуйте его.

2. Подготовьте рабочую директорию (единственную папку, к которой сервер может обращаться).

3. Получите Secure MCP Tunnel ID от OpenAI (создайте здесь) и Runtime API Key (создайте здесь).

4. В распакованной папке выполните:

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

5. Введите Runtime API Key по запросу (скрытый ввод, никогда не сохраняется).

6. Держите терминал открытым; Ctrl+C останавливает всё.

7. Подключите существующий туннель из режима разработчика ChatGPT — этот шаг на стороне аккаунта вы выполняете самостоятельно.

Лаунчер при первом запуске загружает официальный клиент туннеля OpenAI (закреплённая версия v0.0.11, проверенная SHA-256) и кэширует его в %LOCALAPPDATA%\SafeWorkspaceMCP\. Права администратора не требуются, PATH и реестр не изменяются. Подробности см. в README-PORTABLE.md\ внутри ZIP-архива.

Точное утверждение: переносимое локальное развёртывание без необходимости установки Python/Git/Node; лаунчер автоматически загружает проверенный клиент туннеля OpenAI. Это не «нулевая настройка» — вы предоставляете рабочую область, ID туннеля, runtime-ключ и настройку на стороне аккаунта ChatGPT.

Related MCP server: git-mcp-server

Что это

• Один процесс = одна конфигурация = одна фиксированная рабочая область (выбирается при запуске, неизменна во время выполнения)

• Структурированный CRUD для текстовых файлов с атомарными транзакциями для нескольких файлов

• Оптимистичная конкурентность: каждое изменение существующего файла требует его текущий sha256

• Управляемая локальная история Git (через Dulwich, никогда через git.exe): контрольные точки до/после изменений, diff, история, восстановление

• stdio MCP-сервер, всего 9 инструментов

Нецели (жёстко отсутствуют)

Никакой оболочки, никакого терминала, никаких подпроцессов, никакого выполнения кода, никакого компилятора/тест-раннера/менеджера пакетов, никаких произвольных HTTP- или сетевых инструментов, никакого удалённого Git, никакого переключения рабочих областей, никакого редактирования двоичных файлов/изображений, никаких заявлений о песочнице ОС.

Если возможность не указана ниже, этот сервер её не имеет.

Архитектура

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 выполняется самим хостом чата; этот сервер по замыслу не имеет сетевых возможностей.

• Клиент туннеля — это внешний компонент развёртывания, не входящий в состав сервера: сам процесс сервера никогда не открывает сокеты, а единственная сетевая активность лаунчера — загрузка закреплённого официального клиента туннеля с проверкой контрольной суммы.

Девять инструментов

Все операции 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. Принятие существующих репозиториев, рабочих деревьев, подмодулей и удалённых репозиториев выходит за рамки v0.1.0.

Редактируемое ⇒ Восстанавливаемое: каждый обычный файл, который MCP может изменить или удалить, отслеживается в управляемом репозитории, поэтому его всегда можно восстановить из контрольной точки. Исключённые директории (node_modules, артефакты сборки, virtualenvs, …) невидимы для всех инструментов — их нельзя прочитать, записать, найти или сохранить в контрольной точке.

Запуск

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

Сервер работает по MCP через stdio и пишет журнал в stderr. Он отказывается запускаться, если корень рабочей области не существует или небезопасен.

Несколько проектов

Один процесс обслуживает ровно одну рабочую область. Запустите несколько процессов с несколькими конфигурациями:

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

Импорт существующего исходного кода

Укажите workspace.root на существующую исходную директорию без .git. Начальный снимок фиксирует текущее состояние как базовое; с этого момента директория управляется. Большие генерируемые директории следует добавить в excluded.

Сценарии переносимого использования (Windows)

• Первый запуск на новом ПК: распакуйте ZIP, создайте/выберите рабочую область, запустите лаунчер, укажите учётные данные туннеля. Лаунчер автоматически загружает и проверяет закреплённый клиент туннеля.

• Повторный запуск: тот же лаунчер; кэшированный клиент туннеля используется повторно — без повторной загрузки и переустановки.

• Переключение проектов: тот же релиз, другой путь -Workspace. Каждый процесс MCP по-прежнему обслуживает ровно одну фиксированную рабочую область (без переключения во время выполнения).

• Автономная установка (для опытных): заранее скачайте официальный tunnel-client-<version>-windows-<arch>.zip, проверьте его по официальному SHA256SUMS.txt и укажите -TunnelClientPath на распакованный официальный tunnel-client.exe. Это расширенное переопределение для оператора: оно пропускает гарантию лаунчера о закреплённой SHA-256 (существование и --version по-прежнему проверяются). Для обычного использования не требуется.

Тестирование с MCP Inspector

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

(Или mcp dev из CLI MCP SDK.) Убедитесь, что tools/list показывает ровно девять инструментов, аннотации «только чтение» корректны, и сначала опробуйте read → search → apply_changes → git_diff/git_history/git_restore на одноразовой рабочей области.

Подключение ChatGPT Desktop / ChatGPT Web

ChatGPT подключается к локальному MCP-серверу через Secure MCP Tunnel от OpenAI (режим разработчика / коннекторы). Этот проект — только stdio-сервер плюс лаунчер, запускаемый оператором — в нём нет туннельного транспорта, OAuth, хранения учётных данных, и он никогда не читает и не записывает конфигурацию ChatGPT/Codex.

Рекомендуемый порядок действий:

1. Пройдите полный локальный набор тестов с одноразовой рабочей областью (см. выше).

2. Создайте Secure MCP Tunnel в OpenAI Platform и запустите переносимый лаунчер (или tunnel-client run самостоятельно) с этим ID туннеля.

3. В ChatGPT подключите существующий туннель как коннектор разработчика/приложения, пока запущен терминал лаунчера.

4. Сначала используйте отдельную тестовую рабочую область, затем переключите конфигурацию на ваш реальный проект.

Всегда настраивайте ChatGPT вручную в его интерфейсе.

Обзор безопасности

• Ограничение рабочей области — только пути относительно рабочей области; выход за пределы, абсолютные/дисковые/UNC-пути, зарезервированные имена устройств, двоеточия ADS, имена с точкой/пробелом в конце — всё отклоняется; изоляция учитывает файловую систему (на основе realpath), а не только строковый префикс.

• Ссылки — любая точка повторной обработки (символьная ссылка, junction, точка монтирования, неизвестный тег) в любом компоненте существующего пути ⇒ запрет. Обычные файлы с жёсткими ссылками (st_nlink > 1) ⇒ запрет.

• Внутренняя изоляция — .git недоступен через все файловые инструменты; к нему обращается только управляемое хранилище Git.

• Атомарные записи — временный файл рядом → fsync → проверка → os.replace; неудачная запись никогда не усекает оригинал.

• Оптимистичная конкурентность — устаревший expected_sha256 ⇒ HASH_MISMATCH, более новый файл пользователя никогда не перезаписывается.

• Нет выполнения / нет сети — производственный код не использует подпроцессы/сокеты (это обеспечивается тестами через AST, сканирующими каждый модуль на импорты и вызовы); безусловный путь выполнения хуков в dulwich нейтрализуется при импорте и регрессионно тестируется с подложенными файлами хуков; управляемый репозиторий никогда не получает хуки, фильтры или удалённые репозитории.

• Лимиты ресурсов — максимальный размер файла/чтения/транзакции в байтах и результаты поиска; при достижении лимита происходит безопасный отказ.

• Инъекция в промпт — не решена, но ограничена: введённая в заблуждение модель может выполнять только структурированные изменения файлов с контрольными точками внутри одной папки, которые вы всегда можете откатить.

Полный анализ и остаточные риски см. в SECURITY.md и THREAT_MODEL.md.

Известные ограничения (v0.1.0)

• Только текстовые файлы (UTF-8); двоичные файлы отклоняются.

• Windows — основная цель безопасности; Linux поддерживается и тестируется в CI.

• Нет координации нескольких одновременных клиентов, кроме проверок хэшей (запускайте один пишущий процесс).

• История контрольных точек растёт неограниченно (no gc в v0.1.0).

• Восстановление происходит на уровне файлов; исключённые директории не затрагиваются восстановлением.

Сообщение о проблемах безопасности

Пожалуйста, откройте частное уведомление о безопасности (в GitHub «Report a vulnerability»), а не публичный issue.

Лицензия

Apache-2.0 — см. LICENSE.