WorkspaceGuard MCP

WorkspaceGuard MCP — это локальный кроссплатформенный MCP-сервер, который позволяет ChatGPT или MCP-клиенту работать с указанным workspace. Проект создан заново после изучения FileMCP, сохраняет полезные принципы безопасности и убирает то, что не нужно для первой версии.

Для чего это нужно?

• Перечисление, чтение по файлам или по строкам, поиск по именам и по содержимому.

• Запись файлов атомарным способом с поддержкой dry_run и expected_sha256 для предотвращения перезаписи более новых изменений.

• «Удаление» путём перемещения в .workspaceguard/trash с возможностью ручного восстановления.

• Чтение Git status, log и diff без включения shell.

• Опциональный запуск терминала через program + args, без склейки строк через shell, с разрешением только executable из allowlist.

• Работа через stdio или MCP Streamable HTTP на 127.0.0.1 с токеном.

• Запись audit JSONL без сохранения содержимого файлов или полных параметров команд.

Related MCP server: Kastor

Основные улучшения

Приложение имеет настольный интерфейс Electron для выбора workspace, выбора режима, выбора command allowlist, запуска/остановки сервера, проверки MCP прямо в приложении и подключения Secure MCP Tunnel. Следуя подходу FileMCP, приложение создаёт новый loopback-токен для каждой сессии, держит сервер на 127.0.0.1, управляет жизненным циклом tunnel-client и хранит Runtime API key с помощью механизма шифрования ОС (Keychain на macOS, если доступен). Бинарный файл tunnel-client пользователь скачивает сам из OpenAI; проект не включает этот бинарный файл. Локальный runtime и Tunnel не вызывают Codex или модели/API OpenAI: приложение используется с ChatGPT Web через developer-mode app, поэтому квота Codex не расходуется. Разговор по-прежнему ограничен лимитами используемого тарифа ChatGPT.

Требования

• Node.js 20 или новее (проверено на Node.js 24).

• Git, если используются инструменты git_*.

• Для ChatGPT: workspace с поддержкой custom MCP app, Secure MCP Tunnel и runtime API key с соответствующими правами на tunnel. См. OpenAI Secure MCP Tunnel.

Пошаговый запуск

Шаг 1 — установка зависимостей

cd "/Users/danhpham/Documents/ChatGPT/MCP"
npm install

Не помещайте API key в .env и не коммитьте его в Git.

Шаг 2 — проверка всего проекта

npm run verify

Эта команда запускает typecheck, unit/integration тесты, production-сборку и семантический smoke-тест через MCP stdio.

Шаг 3 — запуск настольного интерфейса (самый простой способ)

npm run desktop

В окне WorkspaceGuard:

1. Нажмите Выбрать папку… и выберите тестовый workspace.

2. Оставьте Только чтение при первом использовании.

3. Нажмите Запустить MCP. Когда статус изменится на Работает, HTTP-сервер готов на 127.0.0.1:<порт>.

4. Нажмите Остановить по завершении. Закрытие приложения также останавливает и сервер, и Tunnel.

Интерфейс не отображает и не сохраняет HTTP-токен; токен создаётся заново в main process при каждом запуске.

Полная проверка MCP прямо в интерфейсе

После того как сервер сообщит Работает, нажмите Запустить проверку MCP. Это настоящий MCP-клиент в Electron main process, а не имитация проверки через интерфейс.

• В режиме Только чтение приложение проверяет HTTP MCP handshake, обнаружение инструментов, workspace_info и list_files.

• В режиме Чтение и запись приложение дополнительно проверяет write_file → read_file → trash_path. Вы должны отметить галочкой подтверждение, так как тестовый файл со случайным именем будет перемещён в .workspaceguard/trash.

• В режиме Запуск команд оставьте галочку node в allowlist, чтобы приложение дополнительно проверило run_command с помощью node --version.

Для двух последних режимов выберите отдельную тестовую папку. Результаты каждого шага отображаются сразу в разделе проверки интерфейса.

Шаг 4 — сборка ядра через терминал (опционально)

npm run build

Production entry point:

/Users/danhpham/Documents/ChatGPT/MCP/dist/index.js

Шаг 5 — выбор workspace и режима через терминал (опционально)

Рекомендуется начать с небольшой тестовой папки:

mkdir -p /tmp/workspaceguard-demo
printf 'Xin chào MCP\n' > /tmp/workspaceguard-demo/hello.txt

Три режима:

• read-only: только инструменты чтения файлов и чтения Git. Это значение по умолчанию.

• workspace-write: добавляет write_file и trash_path.

• command: добавляет права записи и run_command.

Примечание: сервер по-прежнему записывает внутренний audit в .workspaceguard/audit.jsonl во всех трёх режимах. «Read-only» описывает публичные инструменты, а не filesystem sandbox самого процесса сервера.

Шаг 6A — запуск через stdio (рекомендуется)

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode read-only

Терминал будет ждать запросы от MCP-клиента через stdin. Это правильное поведение, а не зависание.

Шаг 6B — включение прав записи

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode workspace-write

trash_path по умолчанию имеет dry_run=true. Только когда вызывающая сторона отправляет dry_run=false, путь перемещается в корзину.

Шаг 6C — разрешение самостоятельного запуска терминальных команд

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode command \
  --allow-command git,node,npm,npx

Пример входных данных инструмента:

{
  "program": "npm",
  "args": ["test"],
  "cwd": "",
  "timeout_seconds": 120
}

run_command не использует shell, но это не OS sandbox. node, npm, Python или любой разрешённый executable всё равно могут читать/писать за пределами workspace, использовать сеть и запускать другие процессы с правами текущей учётной записи. Используйте command mode только с доверенными workspace и рабочими процессами.

Шаг 7 — подключение ChatGPT через интерфейс Secure MCP Tunnel

На OpenAI Platform создайте Secure MCP Tunnel и runtime API key с правом использования tunnel. Скачайте tunnel-client, подходящий для вашей ОС. Не передавайте Runtime API key в Codex и не записывайте его в .env, исходный код или Git.

В приложении, после того как MCP сообщит Работает:

1. Вставьте Tunnel ID вида tunnel_....

2. Вставьте Runtime API key. В следующий раз можно оставить поле пустым, чтобы использовать сохранённый зашифрованный ключ.

3. Введите tunnel-client, если бинарный файл уже в PATH, или нажмите Выбрать файл…, чтобы выбрать скачанный бинарный файл.

4. Оставьте профиль по умолчанию, нажмите Подключить Tunnel, дождитесь сообщения «готов к ChatGPT».

5. Зелёная строка «готов к ChatGPT» подтверждает, что локальная часть подключена. Нажмите Открыть ChatGPT Web; это приложение не открывает и не вызывает Codex.

6. Нажмите Отключить Tunnel, если нужно отключить только ChatGPT; нажмите Остановить, чтобы остановить и Tunnel, и MCP-сервер.

Приложение выполняет эквивалент последовательности tunnel-client init --sample sample_mcp_remote_no_auth → doctor --explain → run с MCP endpoint http://127.0.0.1:<порт>/mcp, локальным health endpoint и передачей заголовка токена через переменную окружения. Профили tunnel хранятся в данных приложения, а не в workspace.

В ChatGPT Web включите Developer Mode/custom MCP app согласно политике workspace, создайте новое приложение, выберите подключение Tunnel, выберите созданный tunnel, запустите Scan Tools, затем попробуйте workspace_info, list_files и read_file перед включением инструментов записи. Если вариант Tunnel не отображается, проверьте, что workspace имеет права на чтение и использование Tunnel.

Шаг 8 — HTTP loopback (опционально)

export WORKSPACE_MCP_TOKEN="$(openssl rand -hex 32)"

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport http \
  --mode read-only \
  --port 7331

Health check:

curl --fail http://127.0.0.1:7331/healthz

MCP-запрос должен отправлять заголовок:

X-Workspace-MCP-Token: <WORKSPACE_MCP_TOKEN>

HTTP-сервер привязывается только к 127.0.0.1, проверяет Host, Origin, токен, базовый framing и ограничение размера тела. Используйте stdio, если нет особых потребностей в HTTP.

Доступные инструменты

Всегда доступны

• workspace_info

• list_files

• read_file

• read_file_range

• search_filenames

• search_content

• git_status

• git_log

• git_diff

Режим workspace-write или command

• write_file

• trash_path

Только режим command

• run_command

Восстановление перемещённых в корзину файлов

Инструмент возвращает trashPath. Восстановление выполняется локальной командой, например:

mv "/tmp/workspaceguard-demo/.workspaceguard/trash/<id>/remove-me.txt" \
  "/tmp/workspaceguard-demo/remove-me.txt"

WorkspaceGuard не очищает корзину автоматически в этой версии, чтобы избежать непреднамеренного удаления данных.

Структура

src/
├── config.ts                 # CLI/env và mode
├── security/path-policy.ts   # containment + sensitive-path policy
├── services/files.ts         # file/search/write/trash
├── services/git.ts           # Git read-only
├── services/process.ts       # process limits + tree cleanup
├── tools.ts                  # MCP schemas, annotations, audit
├── server.ts                 # stdio + HTTP loopback
├── desktop/                  # Electron main/preload + renderer an toàn
└── index.ts                  # CLI entry
tests/                        # unit, integration, MCP semantic smoke
docs/                         # phân tích source và lộ trình

Дополнительная документация

• Анализ оригинального проекта FileMCP

• Этапы создания проекта и дорожная карта

• Модель безопасности

Лицензия и источники

Проект использует Apache License 2.0. FileMCP также использует Apache-2.0; см. NOTICE для информации об источниках дизайна. Бинарный файл tunnel-client не включён; оператор скачивает подходящую версию из официального источника OpenAI.