MCP ToolHub

MCP ToolHub — это локальный сервер Model Context Protocol, работающий только через stdio, который предоставляет ограниченные операции с файловой системой рабочего пространства, инспекцию Git только для чтения, структурированное выполнение команд и журнал аудита. Изменяющие файловую систему операции и все выбранные агентом внешние shell-команды используют существующую модель внеполосного утверждения человеком.

ToolHub не предоставляет HTTP-, SSE- или иного сетевого прослушивателя.

Возможности

• Чтение файлов, список каталогов, запись и патчи, ограниченные рабочим пространством

• Операции Git status и diff только для чтения

• Структурированные shell-команды с классификацией риска «запрещено по умолчанию»

• Атомарные, истекающие, одноразовые запросы на утверждение

• Отдельный доверенный CLI администратора; нет инструмента самоутверждения в MCP

• Ограниченные события аудита JSON Lines с маскированием данных

• Поддержка Windows и POSIX

Related MCP server: enterprise-agent-lab

Требования

• Python 3.12 или новее (CI в настоящее время проверяет 3.12 и 3.13)

• MCP-клиент, поддерживающий stdio-серверы

• git для инструментов Git и запросов Git shell, требующих утверждения

Установка

Установка из каталога исходного кода с помощью uv:

uv tool install .

Или соберите и установите wheel:

uv build
uv tool install dist/mcp_toolhub-0.1.0-py3-none-any.whl

Установка предоставляет два исполняемых файла:

• mcp-toolhub — stdio-сервер MCP

• mcp-toolhub-admin — доверенный CLI утверждения человеком

Конфигурация времени выполнения

Корень рабочего пространства

TOOLHUB_WORKSPACE_ROOT обязателен для mcp-toolhub serve и для CLI администратора. Он должен содержать абсолютный путь к существующему каталогу. ToolHub один раз канонизирует путь и фиксирует его на всё время жизни процесса.

ToolHub намеренно не использует по умолчанию текущий каталог, каталог исходного кода или каталог установки.

Доверенный корень состояния

TOOLHUB_STATE_ROOT опционально выбирает каталог, содержащий workspace-binding.json, approvals.json и audit.jsonl. При указании он должен быть абсолютным. При первом допустимом использовании каталог навсегда привязывается ровно к одному каноническому рабочему пространству; повторное использование его для другого рабочего пространства завершается отказом в закрытом состоянии.

Если TOOLHUB_STATE_ROOT не задан, ToolHub использует подходящую для платформы пользовательскую директорию состояния из platformdirs как базу. Каждое каноническое рабочее пространство получает независимое пространство имён в каталоге workspaces/, именованное с помощью детерминированного идентификатора SHA-256, полученного из нормализованного для платформы канонического пути рабочего пространства. Идентификатор позволяет не помещать путь рабочего пространства в имена каталогов, но это разделение пространств имён, а не секрет аутентификации. Перемещение или переименование рабочего пространства обычно создаёт новое пространство имён по умолчанию.

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

Пример для POSIX

export TOOLHUB_WORKSPACE_ROOT=/home/alice/projects/example
export TOOLHUB_STATE_ROOT=/home/alice/.local/state/mcp-toolhub
mcp-toolhub serve

Пример для Windows PowerShell

$env:TOOLHUB_WORKSPACE_ROOT = "D:\work\example"
$env:TOOLHUB_STATE_ROOT = "$env:LOCALAPPDATA\mcp-toolhub"
mcp-toolhub serve

Сервер не выводит баннер и человекочитаемый текст журнала в stdout. Stdout зарезервирован исключительно для сообщений протокола MCP. Ожидаемые ошибки конфигурации кратко выводятся в stderr, и процесс завершается с ненулевым кодом.

Команды

mcp-toolhub --version
mcp-toolhub serve
python -m mcp_toolhub serve

mcp-toolhub-admin --help
mcp-toolhub-admin list
mcp-toolhub-admin approve REQUEST_ID
mcp-toolhub-admin reject REQUEST_ID

Команда администратора предназначена для человека и может выводить обычные данные в stdout. Это не процесс транспорта MCP.

Конфигурация MCP-клиента

Точный внешний ключ конфигурации зависит от клиента. Типичная запись stdio для POSIX выглядит так:

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "/home/alice/projects/example",
        "TOOLHUB_STATE_ROOT": "/home/alice/.local/state/mcp-toolhub"
      }
    }
  }
}

Пути Windows требуют экранирования JSON:

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "D:\\work\\example",
        "TOOLHUB_STATE_ROOT": "C:\\Users\\alice\\AppData\\Local\\mcp-toolhub"
      }
    }
  }
}

Используйте абсолютный путь к исполняемому файлу, если MCP-клиент не наследует PATH оболочки.

Список инструментов

Производственный сервер предоставляет ровно эти 12 инструментов MCP:

• toolhub.ping

• toolhub.audit_recent

• filesystem.list_directory

• filesystem.read_file

• filesystem.write_file

• filesystem.write_file_approved

• filesystem.apply_patch

• filesystem.apply_patch_approved

• git.status

• git.diff

• shell.run

• shell.run_approved

Не существует инструментов MCP для администрирования, утверждения или отклонения.

Процедура утверждения человеком

1. Запрос мутации MCP или внешней shell-команды возвращает идентификатор ожидающего запроса.

2. Администратор запускает mcp-toolhub-admin list с тем же рабочим пространством и окружением состояния, что и сервер.

3. Для утверждения администратор запускает mcp-toolhub-admin approve REQUEST_ID.

4. CLI отображает защищённый запрос и требует, чтобы оператор ввёл APPROVE точно.

5. Вызывающая сторона MCP вызывает соответствующий инструмент _approved с идентификатором запроса. Успешное использование атомарно и одноразово.

Для shell-запросов отображаемое при утверждении включает исходную программу, канонический разрешённый исполняемый файл, SHA-256, размер в байтах, cwd и отдельно JSON-экранированные значения аргументов. Аргументы не представляются в виде неоднозначной строки shell-команды.

Модель безопасности и ограничения

Структурированные shell-команды

shell.run использует политику команд «запрещено по умолчанию». Уровень LOW ограничен точными внутренними операциями ToolHub — в настоящее время запросом версии работающего Python. LOW никогда не выполняет поиск в PATH и никогда не создаёт внешний подпроцесс. Произвольный Git, интерпретаторы shell, пакетные сценарии Windows, лаунчер py и неизвестные программы никогда не имеют уровень LOW.

Каждая внешняя shell-команда имеет уровень MEDIUM или HIGH и требует внеполосного утверждения администратором. При утверждении фиксируются неизменяемые снимки программы, аргументов, cwd, тайм-аута, рабочего пространства и основного исполняемого файла. Утверждённый shell-запрос атомарно потребляется до проверки снимков; любой последующий сбой окончательно потребляет его, поэтому для повтора требуется новое утверждение.

Непосредственно перед запуском subprocess ToolHub проверяет канонический путь, размер и SHA-256 основного исполняемого файла. Выполнение использует этот абсолютный путь с shell=False. Это проверенная идентичность основного исполняемого файла непосредственно перед запуском, а не криптографическая гарантия точных байтов, которые в конечном счёте отобразит операционная система.

ToolHub гарантирует:

• Уровень LOW никогда не создаёт внешний подпроцесс.

• Каждое внешнее выполнение shell-команды требует утверждения MEDIUM или HIGH.

• Агент не может заменить утверждённые программу, аргументы, cwd или тайм-аут.

• Утверждения атомарны, истекают и одноразовы.

• Снимки рабочего пространства и основного исполняемого файла обязательны и завершаются отказом в закрытом состоянии.

• Каноническая идентичность и хэш основного исполняемого файла повторно проверяются непосредственно перед запуском.

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

• Пути мутации отклоняют обход символьных ссылок и применяют проверки параллелизма expected_hash там, где это применимо.

ToolHub не гарантирует:

• Точную байтовую идентичность против конкурентного локального противника в файловой системе в узком окне гонки между финальной проверкой и запуском.

• Идентичность DLL, интерпретаторов, вспомогательных программ, плагинов, конфигурационных файлов, зависимостей, выбранных окружением, или дочерних процессов.

• Что байты утверждённого исполняемого файла безвредны, подписаны или получены от авторитетного издателя.

Отображение утверждения для администратора показывает защищённый канонический путь, хэш, размер, cwd и точные границы JSON-экранированных аргументов. События аудита, читаемые агентом, опускают каталоги внешних исполняемых файлов, сохраняя базовое имя, хэш, размер, область действия и корреляцию с идентификатором запроса.

Поведение аудита

События аудита добавляются в audit.jsonl в доверенном корне состояния. Они содержат ограниченные метаданные, маскируют распознаваемые секретные аргументы и сохраняют только количество символов stdout/stderr, а не необработанный вывод процесса. Сбои записи аудита не являются фатальными для выполнения инструментов.

Разработка

Установите все зафиксированные зависимости времени выполнения и разработки:

uv sync --all-groups

Запустите требуемые проверки:

uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q src/mcp_toolhub
uv run pytest -q
uv build
git diff --check

Чтобы намеренно применить форматирование:

uv run ruff format .

Smoke-тест артефакта

После uv build запустите кросс-платформенный smoke-драйвер с виртуальным окружением вне каталога исходного кода.

POSIX:

uv run python scripts/artifact_smoke.py --dist-dir dist --venv /tmp/mcp-toolhub-wheel-env --repository .

Windows PowerShell:

uv run python scripts/artifact_smoke.py --dist-dir dist --venv "$env:TEMP\mcp-toolhub-wheel-env" --repository .

Драйвер проверяет содержимое wheel, устанавливает только wheel в изолированное окружение, проверяет поведение консоли/версии и запускает извне репозитория тесты initialize, list_tools, ping, доступа к настроенному рабочему пространству, недопустимой конфигурации и общего состояния сервера/администратора.

Устранение неполадок

• TOOLHUB_WORKSPACE_ROOT is required: добавьте абсолютный путь к существующему рабочему пространству в окружение MCP-клиента.

• Рабочее пространство не является каталогом: создайте каталог или исправьте путь.

• Корень состояния должен находиться вне рабочего пространства: переместите TOOLHUB_STATE_ROOT в доверенный каталог, к которому инструменты файловой системы MCP не могут обратиться.

• Пространство имён состояния принадлежит другому рабочему пространству: выберите другой явный TOOLHUB_STATE_ROOT; привязки никогда не переназначаются молча.

• Клиент сообщает о недопустимом JSON в stdio: убедитесь, что обёртки и стартовые сценарии не выводят баннеры или журналы в stdout.

• Администратор не видит запрос: подтвердите, что сервер и администратор работают от имени одного пользователя с одинаковыми настройками рабочего пространства и корня состояния.

• Исполняемый файл изменился после утверждения: запросите новое утверждение; потреблённые или аннулированные утверждения никогда не воспроизводятся повторно.

Производственный ToolHub намеренно не предоставляет поверхности HTTP, SSE, публичной сети, сервера аутентификации, оркестрации контейнеров или облачного хостинга.