Superbrain Schema-Context MCP — POC

Прототип одной функции: MCP-сервер, который даёт кодинг-агенту Superbrain живой, по требованию, доступ к схеме подключённой базы данных — вместо того чтобы сбрасывать всю схему в контекст заранее. Интерфейс — тонкая оболочка вокруг него, стилизованная под реальный интерфейс Superbrain, чтобы функцию можно было оценить в условиях, близких к её реальному месту.

Что это такое (а что — нет)

• Реальное и рабочее: MCP-сервер (/api/mcp), его 5 инструментов получения схемы, интроспекция Postgres за ними и живое демо агента, показывающее, что кодинг-агент реально запрашивает во время работы.

• Заглушки: остальная часть IDE-оболочки (меню, другие панели) и все источники данных, кроме Postgres, в модальном окне «Connect a data source». Они нужны, чтобы показать, где эта функция жила бы внутри реального продукта, а не для работы.

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

Related MCP server: keystone-mcp

Зачем эта функция

Собственное позиционирование Superbrain — контекстный движок, который сжимает и приоритизирует интеллект кода, сокращая расход токенов на 60–80% при сохранении полной осведомлённости о репозитории. Схема базы данных — та же проблема на один уровень ниже: агенту, создающему приложение для работы с данными, нужен контекст таблиц/колонок/связей, чтобы писать корректный код, а наивный подход — отдать всю схему одним куском — это ровно тот вид недифференцированного раздувания контекста, которого архитектура Superbrain и призвана избегать для кода. Этот POC применяет ту же идею к схеме: получать данные прогрессивно, ограничиваясь тем, что реально нужно текущему шагу, вместо того чтобы выгружать всё заранее.

Архитектура

┌─────────────────┐     MCP (Streamable HTTP)     ┌──────────────────────┐
│  Groq              │ ─────────────────────────────▶│  /api/mcp             │
│  (Responses API,    │◀─────────────────────────────│  (mcp-handler)        │
│  remote MCP tool)    │        tool calls/results     │  5 schema tools       │
└─────────────────┘                                └──────────┬───────────┘
        ▲                                                      │
        │ prompt + trace                                       │ SQL (pg)
        │                                                       ▼
┌─────────────────┐                                ┌──────────────────────┐
│  Next.js UI       │──POST /api/agent─────────────▶│  Demo Postgres         │
│  (IDE-shell)      │                                │  (e-commerce schema)  │
└─────────────────┘                                └──────────────────────┘

Агентная сторона работает на Responses API от Groq (openai/gpt-oss-120b), используя нативную поддержку удалённого MCP от Groq: вы передаёте Groq URL MCP-сервера, и он сам обрабатывает обнаружение инструментов, вызовы и возврат результатов модели на серверной стороне — одним API-вызовом, без необходимости писать клиентский цикл оркестрации. Функционально это та же форма, что коннектор MCP от Anthropic или удалённый MCP API от OpenAI; реализация Groq явно построена как взаимозаменяемая замена для любого из них. Какая модель/провайдер стоит за /api/agent, намеренно развязано с самим MCP-сервером — /api/mcp не меняется при смене LLM-провайдера, а это и есть весь смысл создания настоящего MCP-сервера вместо провайдер-специфичной обёртки для вызова инструментов.

Пять MCP-инструментов (lib/schema-context.ts, доступны через app/api/mcp/route.ts):

Каждый результат инструмента несёт обратно в интерфейс оценку количества токенов, чтобы Context Panel мог показать точно, что агент запросил, в каком порядке и по какой цене — и сравнить этот нарастающий итог с тем, сколько стоила бы наивная «выгрузка всей схемы как DDL» для той же базы данных (getFullSchemaDump / getNaiveDumpTokenEstimate в lib/schema-context.ts).

Ключевые проектные решения

• Прогрессивное раскрытие вместо эмбеддингов — для этого POC. search_schema использует сопоставление по ключевым словам/комментариям, а не векторный поиск. Важен контракт инструмента (запрос на входе, ранжированные таблицы на выходе) — именно его сохранила бы продакшн-версия; замена функции скоринга на эмбеддинги — это внутреннее изменение реализации, а не изменение интерфейса. Ключевого поиска было достаточно, чтобы продемонстрировать паттерн без добавления пайплайна эмбеддингов в однодневную сборку.

• Строка подключения на серверной стороне, а не от клиента. Модальное окно источника данных показывает демо-учётные данные Postgres для прозрачности, но фактическое подключение выполняется на сервере через DEMO_DATABASE_URL. Позволять публичному демо-приложению принимать произвольные строки подключения от клиента — это реальная проблема безопасности (SSRF во внутренние сети, сбор учётных данных) — не тот угол, которым стоит пренебречь даже в демо.

• Один живой источник данных — осознанно, а не по упущению. Redshift/Snowflake/ Synapse/BigQuery появляются в выборе, потому что так выглядел бы выбор в реальном продукте, но подключён только Postgres. Контракт инструментов выше не зависит от БД (это просто получение таблиц/колонок/внешних ключей/примеров значений); добавление второго источника означает написание нового модуля интроспекции за теми же пятью инструментами, а не перепроектирование функции.

• MCP вместо самодельного API. Использование реального Model Context Protocol (через mcp-handler на Vercel и нативную поддержку удалённого MCP от Groq на стороне модели) вместо кастомной обёртки для вызова инструментов означает, что этот сервер работал бы без изменений, если бы к нему подключился собственный агент Superbrain — или любой другой агент/провайдер, говорящий на MCP. Смена LLM-провайдера (началось с Anthropic, теперь работает на Groq) затронула только /api/agent; /api/mcp не изменился вообще. Эта переносимость и есть фактический смысл создания MCP-сервера вместо API-маршрута, который агент вызывал бы напрямую.

• Responses API от Groq, а не Chat Completions. Groq явно рекомендует Responses API для MCP-сценариев — обнаружение инструментов, рассуждения и вызовы инструментов возвращаются как отдельные, помеченные шаги в output[], что и делает трассировку Context Panel возможной без лишних ухищрений с парсингом.

• Один нестриминговый вызов агента для демо. /api/agent ждёт полного ответа Claude (включая все раунды MCP-инструментов) перед возвратом, а не стримит. Проще построить и отладить корректно за доступное время; стриминг трассировки вызовов инструментов в реальном времени — первое, что я бы добавил дальше (см. ниже).

• API-ключ остаётся на клиентской стороне, только в памяти. Оценивающий вставляет свой собственный ключ Groq в приложение; он отправляется напрямую на собственный маршрут /api/agent этого приложения при каждом запросе и никогда не записывается в хранилище или логи. Демо-приложение не должно поставлять настоящий продакшн-ключ в публичном репозитории.

Запуск

npm install
cp .env.example .env.local   # fill in DEMO_DATABASE_URL
npm run seed                  # seeds the demo e-commerce schema (12 tables)
npm run dev

Откройте http://localhost:3000 → «Connect a Data Source» → PostgreSQL → Connect.

Примечание о тестировании живого вызова агента локально: серверам Groq нужно добраться до вашего MCP-сервера по публичному HTTPS-URL — localhost с их стороны недоступен. Демо агента (просьба что-то построить) работает только после деплоя (или через туннель вроде ngrok http 3000, направленный на ваш локальный сервер, с соответствующей настройкой определения origin). Сам MCP-сервер и интроспекцию БД можно полностью протестировать локально через /api/db/connect и прямыми вызовами /api/mcp по протоколу MCP — оба варианта описаны выше и не требуют Groq вообще.

Демо-база данных

Подойдёт любой Postgres. Бесплатные варианты: Neon или Supabase. Создайте роль только для чтения для строки подключения, используемой в приложении:

create role demo_reader with login password 'your_password';
grant connect on database superbrain_demo to demo_reader;
grant usage on schema public to demo_reader;
grant select on all tables in schema public to demo_reader;

Деплой

1. Запушьте этот репозиторий на GitHub.

2. Импортируйте его в Vercel.

3. Задайте DEMO_DATABASE_URL, NEXT_PUBLIC_DEMO_DB_HOST, NEXT_PUBLIC_DEMO_DB_NAME, NEXT_PUBLIC_DEMO_DB_USER как переменные окружения в проекте Vercel.

4. Задеплойте. MCP-сервер автоматически доступен по адресу https://<your-app>.vercel.app/api/mcp — /api/agent выводит этот URL из входящего запроса, так что дополнительная настройка для их взаимного поиска не нужна.

Продуктовая стратегия

A. Если бы вы строили этот продукт, что бы вы изменили или добавили следующим, и почему?

(Впишите свой собственный ответ здесь — несколько честных отправных точек из опыта создания этого POC:)

• Стриминг трассировки вызовов инструментов агента в Context Panel в реальном времени вместо ожидания полного ответа, чтобы момент «что он сейчас запрашивает» читался как живой, а не ретроспективный — ближе к тому, как собственный продукт Superbrain, вероятно, показывает работу своего контекстного движка.

• Замена ключевого сопоставления в search_schema на эмбеддинги, когда схема станет достаточно большой, чтобы пересечение ключевых слов перестало быть хорошим сигналом релевантности (десятки+ таблиц, неоднозначные имена) — контракт инструмента не меняется, меняется только то, что за ним стоит.

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

• Расширение того же контракта из 5 инструментов на остальные перечисленные источники данных (Redshift, Snowflake, Synapse, BigQuery) — каждому нужен свой модуль интроспекции (разные особенности системных каталогов/information_schema), но тот же интерфейс.

B. Какие крупные проблемы интерфейса вам не нравятся и как, по-вашему, они раздражают текущих пользователей?

(Впишите свой собственный ответ здесь, исходя из реального времени, проведённого в Superbrain.)

Что я построил и почему

(Впишите — абзац-другой своими словами о выборе построить именно эту функцию и почему она подходит под бриф «Founding AI Engineer».)

Журнал принятия решений

(Впишите — последовательность реальных решений и компромиссов по мере их принятия; раздел «Ключевые проектные решения» выше — отправная точка, но этот раздел должен быть написан вашим голосом, как того требует задание для аутентичности.)