HostGate MCP

Ориентированный на Windows локальный плоскость контроля возможностей для MCP-клиентов.

HostGate MCP предоставляет MCP-клиенту явно авторизованный доступ к выбранным локальным файлам и доверенным программам командной строки, с настольным Центром управления для политик, аудита, отката, диагностики и управления жизненным циклом службы.

Модель выполнения намеренно уже, чем у универсального терминала: верхнеуровневые cmd.exe, Windows PowerShell и pwsh не предоставляются как доверенные инструменты выполнения. Разрешённые исполняемые файлы разрешаются до фиксированных путей и запускаются напрямую.

Почему существует HostGate

Чтение локальных файлов через MCP — просто. Безопасно предоставлять запись и возможности выполнения процессов удалённому ИИ-клиенту — сложнее.

HostGate фокусируется на этой плоскости контроля:

• явные корни чтения / записи / запрета;

• транзакционные изменения политик с просмотром diff и откатом;

• горячая перезагрузка разрешений без перезапуска службы MCP;

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

• аудируемое прямое выполнение процессов без универсальной оболочки;

• изоляция дерева процессов Windows Job Object;

• локальная история аудита, редакции конфигурации, симуляция политик и диагностика;

• двуязычный Центр управления Windows (zh-CN / en-US);

• управление жизненным циклом запланированных задач;

• локальные режимы stdio и защищённого OAuth потокового HTTP;

• сборки Центра управления PyInstaller onedir и портативный onefile.

Related MCP server: MCP Local Filesystem Server

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

MCP client
    |
    | OAuth / stdio
    v
HostGate MCP
    |
    +-- Filesystem policy
    |     read roots
    |     write roots
    |     deny paths
    |
    +-- Direct execution policy
    |     trusted executable allowlist
    |     exact path resolution
    |     no general-purpose shell
    |     stdin disabled / bounded output
    |     Windows Job Object lifetime
    |
    +-- Control plane
          GUI / audit / revisions
          diagnostics / rollback

Важная граница

HostGate MCP — не песочница файловой системы операционной системы.

Политика файловой системы контролирует собственные файловые инструменты HostGate и рабочую директорию, принимаемую exec_command. Как только авторизованный исполняемый файл запускается, эта программа и её дочерние процессы работают с привилегиями ОС учётной записи службы MCP и могут получать доступ к ресурсам, доступным этой учётной записи.

Список разрешённых исполняемых файлов ограничивает верхнеуровневый процесс. Он не изолирует дочерние процессы, порождённые авторизованной программой.

Прочитайте SECURITY.md и docs/THREAT_MODEL.md перед тем, как открывать службу за пределами localhost.

Центр управления

Центр управления Windows предоставляет шесть страниц:

• Service — статус, PID, запуск/остановка/перезапуск запланированной задачи.

• Permissions — просмотр и управление корнями чтения/записи/запрета.

• Execution — управление доверенными программами CLI.

• Policy — симуляция действующих разрешений и восстановление редакций конфигурации.

• Diagnostics — проверка состояния службы/конфигурации/аудита/редакций и экспорт отредактированного отчёта.

• Audit — просмотр недавних событий изменения файлов и выполнения процессов.

Изменения политик используют транзакционный поток, а не прямое редактирование TOML:

candidate
  -> validate
  -> review diff
  -> stale SHA256 check
  -> save previous revision
  -> atomic replace
  -> hot reload or controlled restart
  -> health check / rollback

Безопасные публичные значения по умолчанию

Репозиторий стартует в режиме fail-closed:

• нет корней чтения;

• нет корней записи;

• нет пользовательских путей запрета (пути плоскости управления запрещаются автоматически);

• изначально доверена только утилита Windows where.exe;

• URL-адреса OAuth указывают на 127.0.0.1:8000;

• нет реального хэша пароля, базы токенов, данных аудита или пользовательской политики.

Предоставляйте только те директории и исполняемые файлы, которые вам действительно нужны, через Центр управления.

Установка

Требования:

• Windows 10/11;

• Python 3.10+;

• рекомендуется uv.

Установка основного сервера + GUI:

cd C:\path\to\hostgate-mcp
uv sync --no-dev
Copy-Item config\secrets.example.toml config\secrets.toml

Стандартная установка включает инструменты файловой системы/текста/CSV/мутации/выполнения, поддержку OAuth HTTP и Центр управления. Специфичные для форматов чтения инструменты опциональны:

uv sync --extra excel      # Excel tools
uv sync --extra pdf        # PDF tools
uv sync --extra image      # image tools
uv sync --extra pytorch    # PyTorch checkpoint tools
uv sync --extra all        # all optional tool families

Для разработки и полного набора тестов:

uv sync --all-extras
.venv\Scripts\python.exe -m pytest -q

Установите реальный хэш пароля владельца Argon2id в config\secrets.toml, затем настройте корни и доверенные исполняемые файлы перед открытием HTTP-службы.

Запустите Центр управления:

scripts\start_control_center.ps1

Установите запланированную задачу Windows, когда будете готовы запускать HostGate при входе в систему:

scripts\install_server_task.ps1

Сборки Центра управления Windows

Рекомендуемая сборка onedir:

scripts\build_control_center.ps1

Портативная сборка onefile:

scripts\build_control_center.ps1 -OneFile

Артефакты сборки намеренно исключены из системы контроля версий.

Опциональные семейства инструментов

С каждым установленным опциональным расширением HostGate предоставляет полный набор читателей, разработанных для частной линейки 1.4, включая инструменты проверки Excel, PDF, изображений и PyTorch. Без расширения это семейство инструментов просто не регистрируется; остальная часть MCP-сервера остаётся работоспособной.

Это сохраняет стандартную установку сфокусированной на варианте использования RWX/плоскости управления, вместо того чтобы заставлять каждого пользователя устанавливать большие научные зависимости, такие как PyTorch.

Статус проекта

Текущая версия публичной подготовки: 1.4.0rc1.

Публичный репозиторий создан из чистого экспорта проверенной частной линии разработки без истории. Частная история Git, производственные политики, состояние OAuth, журналы, секреты и результаты сборки намеренно исключены.

Не-цели

HostGate не пытается стать:

• полноценным эмулятором терминала;

• фреймворком оркестрации оболочки;

• маркетплейсом или маршрутизатором MCP;

• кроссплатформенной заменой агента кодирования;

• полной песочницей ОС.

Новые возможности следует добавлять только тогда, когда они решают продемонстрированную операционную проблему или проблему безопасности.

Документация

• SECURITY.md — границы безопасности и отчётность об уязвимостях.

• docs/THREAT_MODEL.md — допущения, защищаемые активы и гарантии вне области действия.

• docs/control_center.md — архитектура Центра управления и транзакции политик.

• docs/architecture.md — архитектура сервера.

• docs/tools.md — справочник по инструментам MCP.

• CHANGELOG.md — история релизов.

Лицензия

Лицензировано по Apache License 2.0. См. NOTICE для информации об авторстве.