Архитектура Toolhub: древовидная навигация инструментов для LLM и легковесный рантайм на Bun

Развитие экосистемы автономных ИИ-агентов выявило противоречие между возможностями языковых моделей и протоколами подключения утилит. Механизм вызова функций (Function Calling) и стандарт Model Context Protocol (MCP) стали базой для работы нейросетей с внешним окружением. Однако стандартная схема создает ощутимую контекстную перегрузку: чтобы предоставить модели доступ к скриптам, разработчик вынужден внедрять тяжелые JSON-схемы непосредственно в системный промпт.

В проекте с десятками инструментов передача их описаний сжигает от 15 до 30 тысяч токенов еще до первого вопроса пользователя. Это не только увеличивает расходы на вызовы API, но и рассеивает внимание нейросети. Возникает эффект «Lost in the Middle», при котором модель путается в параметрах и галлюцинирует схемами. Дополнительной проблемой становится инфраструктурная избыточность: типовые MCP-серверы оборачивают в Docker-контейнеры, расходуя сотни мегабайт памяти ради запуска элементарных консольных команд.

Ответом на эти вызовы стал открытый проект Toolhub — легковесный self-hosted движок на рантайме Bun. Проект заменяет плоские списки иерархическим деревом каталогов с прогрессивным раскрытием схем, использует временные воркспейсы вместо контейнеров и поддерживает пулы постоянных процессов.

Древовидная навигация вместо плоского списка схем

Вместо единовременной передачи документации всех инструментов Toolhub организует навыки в дерево каталогов:

/
├── system/
│   ├── fetch_logs
│   └── restart_service
├── database/
│   └── query_pg
└── git/
    └── diff_check

На старте диалога в системный промпт инжектируется только корневая карта дерева с краткими аннотациями назначений категорий (по одной строке на раздел). Модель видит структуру верхнего уровня, но не расходует контекст на детальные описания параметров.

Процесс взаимодействия состоит из простых шагов:

1. При необходимости решить прикладную задачу агент запрашивает ветку: listTools("/system").
2. Движок возвращает параметры только тех инструментов, которые лежат в запрошенном каталоге.
3. Модель выполняет целевой вызов: callTool("/system/fetch_logs", {"service": "nginx"}).

Для связи с моделью Toolhub использует Re-Act цикл на базе XML-тегов <hub>callTool(...)</hub>. Это позволяет подключать к движку любые модели, включая локальные нейросети без нативной поддержки вендорных форматов вызова функций.

Механика исполнения на Bun

Вместо запуска Docker-контейнеров Toolhub выполняет скрипты через рантайм Bun во временных каталогах операционной системы. Конвейер вызова включает следующие этапы:

1. Изолированный воркспейс: в системной временной папке создается каталог /tmp/hub_run_<timestamp>_<hash>.
2. Инъекция кода и данных: в каталог записываются исполняемый файл и input.json. Параметры вызова одновременно пробрасываются в переменные окружения $INPUT_<KEY_NAME>. Поддерживаются скрипты на Bash, Bun, Python, Go и PHP.
3. Установка зависимостей: при наличии команды installCmd модули подтягиваются за счет глобального кэша Bun или локальных wheel-кэшей Python за доли секунды.
4. Запуск: команда runCmd выполняется с жестким ограничением timeoutMs. Результат считывается из output.json или stdout.
5. Очистка: сразу после завершения процесса временная директория удаляется командой rm -rf.

Режимы MCP: Stateless и Stateful Pool

Поддержка Model Context Protocol в Toolhub реализована в двух вариантах:

• Stateless (Stdio): стандартный цикл запуска процесса под конкретный вызов с немедленным завершением. Оптимален для разовых утилит.
• Stateful Pool: удержание тяжелых процессов в оперативной памяти. Если инструменту требуется постоянное состояние (авторизованная сессия Puppeteer, SSH-туннель или пул соединений с базой данных), Toolhub держит процесс активным. Повторные вызовы отрабатывают за 10–30 миллисекунд. Простой регулируется через TTL (по умолчанию 5 минут), после чего процесс завершается. Функция MCP Promote в панели управления позволяет в один клик перенести схемы стороннего MCP-сервера в базу данных Toolhub.

Официальная процедура локального развертывания

Официальный README Toolhub описывает следующий алгоритм установки:

Предварительные требования

Требуются установленный рантайм Bun и Git. В качестве хранилища по умолчанию используется база данных SQLite на базе Prisma ORM.

Инструкция по запуску

1. Клонировать репозиторий: git clone https://github.com/Talos-Popcorn/toolhub.git
2. Перейти в каталог и установить зависимости: bun install
3. Применить схему базы данных: bun run db:push
4. Выполнить инициализацию учетных записей (seed): В интерактивном режиме запускается bun run db:seed. Для автоматической установки используется команда: bun run prisma/seed.ts --lang=en --admin-pass=admin --agent-pass=123(Предупреждение: эти пароли взяты из документации как пример; для реального использования задавайте стойкие секреты).
5. Запустить сервер разработки: bun run dev
6. Для производственной эксплуатации запустить сборку: bun run build && bun run start

Проверка работоспособности

Панель управления доступна по адресу http://localhost:5173/admin/, а документация Swagger/OpenAPI — на http://localhost:3000/docs (только в dev-режиме). Авторизация осуществляется по заголовкам x-admin-password и x-agent-password.

Федерация и версионирование

Toolhub поддерживает каскадное объединение узлов. Локальный сервер может обращаться к удаленному экземпляру через прозрачное проксирование HubSDK. Для агента путь выглядит единым: <hub>callTool("/office/server/reboot", {})</hub>. Циклические вызовы блокируются заголовками x-hub-nodes с ограничением maxHops.

Наборы навыков экспортируются в переносимые файлы .toolpack. Встроенный модуль ToolVersion ведет учет снимков кода и параметров, обеспечивая откат ревизий из интерфейса.

Исследовательские предостережения

При внедрении Toolhub важно учитывать технические ограничения:

• Зрелость проекта: по данным GitHub API, репозиторий создан 6 сентября 2026 года и на момент проверки имел 9 звезд и 0 issues. Это ранняя разработка, требующая тестирования.
• Бенчмарки: заявленные задержки навигации 0.8–1.4 мс и время запуска утилит 13.4 мс получены автором на мощном стенде (12 vCPU, 32 ГБ RAM) и не являются независимым аудитом.
• Безопасность: удаление папки /tmp не заменяет изоляцию уровня контейнеров или виртуальных машин. Скрипты выполняются с правами хоста. В документации нет инструкций по настройке TLS, ротации секретов и детальной ролевой модели (RBAC).
• Лицензия: код распространяется под лицензией AGPL-3.0, требующей открытия производных сетевых решений (предусмотрен вариант закрытой коммерческой лицензии).
• Границы применимости: дерево каталогов не дает преимуществ, если в проекте менее 10 инструментов или если агент регулярно обходит все категории за одну сессию.