Давайте будем честны: текущее состояние вызова функций (Function Calling) у LLM и экосистемы MCP (Model Context Protocol) вызывает изжогу в лучшем случае. Чтобы дать агенту возможность сделать curl или дернуть локальный скрипт, современному разработчику предлагают:

1. Описать килобайты монструозных JSON-схем прямо в системном промпте (и спалить 15-30k токенов контекста еще до первого вопроса пользователя).

2. Написать полноценный сетевой MCP-сервер со своим бойлерплейтом, SDK и зависимостями.

3. Завернуть всё это в жирный Docker-контейнер, выделив 200 Мб ОЗУ ради выполнения элементарного скрипта на три строки.

И один bash-tool вместо десяти нормальных инструментов задачу не решает, сессии превращаются в нечто вроде (псевдокод):

bash("systemctl is-active my-app.service")
bash("journalctl -u my-app.service -n 50 --no-pager")
bash("ss -tunlp | grep 3000")
bash("kill -9 $(lsof -t -i:3000)")
bash("systemctl restart my-app.service")

Что повторяется три раза только за эту сессию, и это - совсем не DRY (Don’t Repeat Yourself). Интуитивно у инженера в этом моменте слегка подскакивает пульс и давление, и он хочет абстрагировать это в call_tool("check_journals_and_stats", {...})

А когда в проекте накапливается больше 30 таких абстракций - модель неизбежно ловит Lost in the Middle и начинает галлюцинировать схемами, а разработчик оплачивает тонны входящих токенов за документацию API, которую агент даже не собирался вызывать в текущей сессии.

Отдельное спасибо здесь стоит сказать маркетингу Anthropic - работает он отлично. Термины вроде MCP, agent, harness, tooling теперь на слуху у людей, которые до этого к тулингу LLM никакого отношения не имели, причём многие оперируют ими скорее на уровне потребления хайпа, чем реального понимания. Модели у Anthropic отличные, тут вопросов нет. Но стоит помнить, что всё вокруг их флагманского продукта (включая сам MCP как протокол) в первую очередь продвигает этот продукт, а развитие области вокруг него - уже вторичная задача.

Короче, я устал от натягивания совы на глобус именованием MCP как стандартизированного протокола для всего тулинга самой популярной области последних лет и сделал ?️ toolhub - self-hosted движок, который превращает любой консольный скрипт (Bun, Python, Bash, Go, PHP, etc) в инструмент для LLM на лету, с иерархической навигацией по дереву папок и околонулевыми требованиями к зависимостям.

Файловая система навыков вместо плоского списка

Почему контекст модели забивается? Потому что типичные MCP-прокси дают модели плоский массив из 100 тулов.

У меня подход иной - древовидная навигация:

/
├── system/
│   ├── fetch_logs
│   └── restart_service
├── database/
│   └── query_pg
└── sublime/
    └── replace-literal

Скажите мне, серьёзные разработчики, ML-щики, архитекторы, системные аналитики - не это ли было самым адекватным путём с самого начала? Хотя бы с момента, когда стало ясно, что без кеширования контекста направление продолжит быть убыточным.

Модель не знает схемы сотен инструментов заранее. На старте через hub.getSmartPrompt() в системный промпт инжектится только корневая карта дерева с краткими аннотациями назначений категорий (1–2 строки на папку). Модель стартует с базовым контрактом:

1. listTools("/system") - посмотреть, что валяется в конкретной ветке, и подтянуть точные описания только нужных инструментов.

2. callTool("/system/fetch_logs", { "service": "nginx" }) - вызвать конкретный инструмент с конкретными параметрами.

Результат: окно контекста чистое, модель лезет в папку только тогда, когда ей действительно нужен инструмент из этой категории. Когда она понимает, что к текущему запросу папка с ЭТИМ названием может иметь непосредственное отношение.

Важное уточнение - toolhub сознательно не работает ни с одним из стандартных интерфейсов tool calling каких-то конкретных провайдеров. Весь Re-Act loop построен на классических XML-like командах:

<hub>listTools("/")</hub>

<hub>callTool("/sublime/list-project-files", {})</hub>

Так с минимальным оверхедом на вызов мы даём возможность пользоваться тулами абсолютно любым моделям, даже если у них не встроена поддержка тулинга, или она сделана как-то странно/криво. По сути XML-обвязка (<hub>...</hub>) сопоставима или легче, чем JSON-разметка нативного tool_call у большинства провайдеров. Единственный таким образом порог входа для модели - понимание, что такое xml, json, js и древовидная навигация.

Как это работает

Поднимать Docker-контейнер на каждый чих - это дорого по ресурсам (особенно если вы крутите агентов на скромной VPS или Raspberry Pi). toolhub использует только Bun и его возможности. Глобальная зависимость всего одна, так что я даже не стал собирать для вас бойлерплейтные Dockerfile || docker-compose.yml - нужны они будут не всем, собрать самому - 3 минуты.

Механика исполнения под капотом простая как топор:

Workspace (/tmp) ➔ Инъекция (код + input.json) ➔ Установка deps ➔ runCmd с таймаутом ➔ rm -rf

1. Создание изолята: На лету генерируется временная папка /tmp/hub_run_<timestamp>_<hash>.

2. Инъекция кода и аргументов: В папку кладется код и input.json, а все параметры вызова автоматически пробрасываются в ENV-переменные вида $INPUT_<KEY_NAME>. Хочешь - парси JSON в коде, хочешь - пиши bash-однострочник, который сразу читает $INPUT_HOST. Никаких обвязок.

3. Зависимости: Если прописан installCmd, он отрабатывает в контексте папки. Bun и современные пакетные менеджеры за счет глобального кэша хоста подтягивают модули за миллисекунды; для Python-скриптов аналогично используются локальные wheel-кэши либо глобальное окружение хоста.

4. Запуск процесса: Выполняется runCmd с жестким ограничением timeoutMs. Результат считывается из output.json или stdout.

5. Очистка: Папка воркспейса сразу же аннигилируется через rm -rf.

Если скрипт выполняется в консоли - он автоматически становится навыком ИИ. Без написания оберток на протоколе MCP.

А что с MCP?

Я не против MCP как идеи, я против его кривых реализаций. В toolhub нативная поддержка MCP реализована в двух режимах:

1. Stateless (Stdio): Классика. Спавнится процесс -> отправляется запрос -> профит -> процесс убивается. Подходит для разовых утилит, т.е. для 90% того что есть на рынке. Так же для удалённых MCP в том числе.

2. Stateful Pool (Persistent PID): Самое вкусное. Если ваш MCP-сервер держит тяжелый контекст (Puppeteer с авторизованной сессией браузера, SSH-соединение, пул подключений к БД) - toolhub держит процесс в памяти. Повторные вызовы отрабатывают за 10–30 мс без затрат на холодный старт. Простой регулируется через TTL (по дефолту 5 минут), после чего память освобождается. Повторное использование агентом до истечения TTL - продлевает его жизнедеятельность.

Если MCP-инструмент из внешнего сервера вам понравился, но вам хочется затюнить его описание под свою модель, навесить строгую output-schema или прописать few-shots примеры (что классический MCP напрямую не поддерживает) - кнопка MCP Promote в админке в 1 клик переносит его метаданные и схемы вызова напрямую в базу toolhub, позволяя докручивать промпт и валидацию инструмента прямо из UI.

«А если я сижу в Claude Code / Cursor и хочу дергать тулы оттуда?»

Сам я не фанат завязки на конкретные закрытые проприетарные CLI, но если вы плотно сидите на Claude Code, Cursor или Cline - концептуально вам ничего не мешает использовать toolhub как единый бэкенд навыков.

Для этого достаточно написать микроскопический Stdio-мост на 40 строк (toolhub-mcp-bridge), который будет транслировать агентские вызовы Клода в REST API вашего локального toolhub. Прописали один сервер в конфиг - и Клодоподобные на лету видят всю вашу древовидную экосистему скриптов.

Перчатка брошена: кто первый напишет и оформит красивый toolhub-mcp-bridge в виде отдельного пакета/PR - с удовольствием добавлю в официальный README и закреплю авторство!

Бесконечная Федеративность

Узлы toolhub умеют каскадироваться.

Вы можете поднять локальный toolhub на рабочем ноутбуке, подключить к нему Remote-узлом toolhub вашего домашнего сервера, к которому подключен toolhub инфраструктуры дева.

Для агента это выглядит как единый путь: <hub>callTool("/office/home/server/reboot", {})</hub>

HubSDK берет на себя рекурсивную нормализацию путей, проксирование авторизации и прозрачное туннелирование запросов. А для защиты от дурака и циклических ссылок (когда Сервер А случайно ссылается на Сервер Б, ссылающийся на А) каждый запрос маркируется цепочкой заголовков x-hub-nodes с отслеживанием node_id каждого узла и жестким лимитом глубины (maxHops, по умолчанию задан разумный предел).

Шеринг навыков и встроенный Time-Machine

Любой инструмент или целую ветку дерева со всеми подпапками, раннерами и схемами можно экспортировать в один переносимый JSON-манифест .toolpack. Написал крутую связку для деплоя или работы с базой - выгрузил в 1 клик, закинул коллеге, он нажал «Import», и навыки сразу появились в его агенте. Так же с отдельными тулами.

А чтобы не бояться экспериментировать с промптами и кодом инструментов прямо в админке, toolhub ведет автоматический журнал ревизий (ToolVersion). Каждое сохранение создает неизменяемый снимок кода, схем и описания с возможностью отката к любой предыдущей версии в один клик.

Бенчмарки и производительность: а не медленно ли?

Главная претензия теоретиков к древовидной навигации: «Это же лишний RTT! Зачем делать listTools, если можно отправить всё сразу?»

Воспроизводимый бенчмарк-сьют - код лежит прямо в репозитории в папке basic-toolpacks/benchmark/. Замеры проводились на локальном тестовом стенде (VM в Proxmox, 12 vCPU Intel i5-14500 cpu_type: host, 32 GB RAM, Debian 12, NVMe SSD).

Методология: 100 последовательных итераций на каждый сценарий с расчетом p50, p90, p99 перцентилей + стресс-тест на параллельный спавн воркспейсов:

Важно про железо: замеры выше сделаны на мощной VM (12 vCPU/32GB) - это потолок производительности runtime’а, а не то, что вы получите на Raspberry Pi или бюджетной VPS. На слабом железе (1 vCPU/512MB) абсолютные цифры будут выше в разы, но относительная разница между навигацией по дереву (~1 мс) и полноценным спавном процесса (10-60+ мс) сохранится - узкое место всегда сам раннер, а не Navigation Engine.

Параллельный стресс-тест на изоляцию воркспейсов:

15 одновременных вызовов тулов отработали параллельно суммарно за 138 мс (Ошибок: 0, 100% изоляция ФС во временных директориях).

Что значат эти цифры?

1. Задержка навигации по дереву каталогов составляет 1.0–1.5 мс. Замеры отражают чистый overhead самого toolhub Runtime. На фоне сетевого latency и генерации токенов LLM (500–2000 мс) оверхед toolhub - это абсолютная погрешность.

2. Полный жизненный цикл одноразового bash-инструмента (генерация воркспейса /tmp/hub_run_*, запись input.json, спавн процесса, чтение output.json и атомарный rm -rf) занимает всего 13 миллисекунд.

Про базу данных: По умолчанию из коробки используется легковесная встроенная SQLite - чтобы проект поднимался без поднятия отдельных сервисов СУБД. Но благодаря тому, что весь бэкенд построен на Prisma ORM, при желании вынести ToolHub в высоконагруженный корпоративный кластер переезд на PostgreSQL, MySQL или CockroachDB сводится грубо говоря к изменению одной строчки провайдера в schema.prisma.

Когда дерево НЕ даёт выигрыша (или даже мешает) - честный список:

Итого: чем шире набор тулов и чем уже реальное использование за сессию - тем сильнее дерево выигрывает. toolhub целится ровно в этот кейс.

Быстрый запуск

# 1. Клонируем
git clone https://github.com/Talos-Popcorn/toolhub.git
cd toolhub

# 2. Установка зависимостей
bun install

# 3. Синхронизация схемы БД Prisma
bun run db:push

# 4. Интерактивный seed+install
# (Выбор языка системного промпта EN/RU/ZH, настройка паролей админки и агента)
bun run db:seed

# Или в тихом режиме для CI/Docker:
# bun run prisma/seed.ts --lang=ru --admin-pass=admin --agent-pass=123

# 5. Запуск в дев режиме
bun run dev

Панель управления доступна по адресу http://localhost:5173/admin/ (или порт 3000 в прод-сборке). Swagger/OpenAPI документация: http://localhost:3000/docs (в дев-режиме). Дальше - импортируем какие-нибудь тулпаки из папки basic-toolpacks и пробуем запускать их в Playground.

Интеграция в любой JS/TS код занимает пару строк:

import { HubSDK } from './SDK/JS/sdk';

const hub = new HubSDK('http://localhost:3000', '123');

async function runAgentLoop(userQuery: string) {
  const systemPrompt = await hub.getSmartPrompt();
  
  const messages = [
    { role: 'system', content: systemPrompt },
    { role: 'user', content: userQuery }
  ];

  while (true) {
    const aiResponse = await llm.generate(messages);
    const action = await hub.processAgentResponse(aiResponse);

    if (!action.called) {
      console.log('Ответ агента:', aiResponse);
      break;
    }

    messages.push({ role: 'assistant', content: aiResponse });
    messages.push({ 
      role: 'user', 
      content: `HUB_RESULT: ${JSON.stringify(action.result)}` 
    });
  }
}

Кстати, для тех, кто пробовал мой прошлый проект ?lab (статья, репо) (serverless-клиент для LLM без бэкенда) - поддержка ?️ toolhub уже встроена и прекрасно работает. Теперь можно цеплять локальные тулы прямо из браузерного интерфейса. Смотрим, как работает:

Лицензия и Open Source

Проект полностью открыт, распространяется под AGPL-3.0. Первичная задача - выкинуть из стека лишний оверхед и дать нормальный инструмент для быстрой автоматизации без переплат за токены.

• GitHub Repo: github.com/Talos-popcorn/toolhub

Буду рад конструктивной критике, issue и пулл-реквестам.