Superbrain Schema-Context MCP — prueba de concepto

Una prueba de concepto para una función: un servidor MCP que le da al agente de codificación de Superbrain acceso en vivo y bajo demanda al esquema de una base de datos conectada, en lugar de volcar todo el esquema en el contexto de antemano. La interfaz es una capa fina alrededor de él, diseñada para imitar la interfaz real de Superbrain, de modo que la función pueda evaluarse en algo cercano a su hogar real.

Qué es esto (y qué no es)

• Real y funcional: el servidor MCP (/api/mcp), sus 5 herramientas de recuperación de esquema, la introspección de Postgres que las respalda y la demo de agente en vivo que muestra lo que el agente de codificación obtiene realmente mientras construye.

• Marcador de posición: el resto del marco de la IDE (menús, otros paneles) y todas las fuentes de datos excepto Postgres en el modal "Conectar una fuente de datos". Existen para mostrar dónde se ubicaría esta función dentro del producto real, no para ser funcionales.

• El recorrido guiado dentro de la aplicación lo dice explícitamente en la primera carga, para que quien evalúe no tenga que adivinar qué partes tomarse en serio.

Related MCP server: keystone-mcp

Por qué esta función

La propuesta de Superbrain es un motor de contexto que comprime y prioriza la inteligencia del código para reducir el uso de tokens entre un 60 y un 80 % mientras mantiene pleno conocimiento del repositorio. El esquema de base de datos es el mismo problema un nivel más abajo: un agente que construye una aplicación de datos necesita el contexto de tablas, columnas y relaciones para escribir código correcto, y el enfoque ingenuo —entregarle el esquema completo como un solo bloque— es exactamente el tipo de inflado de contexto indiferenciado que la arquitectura de Superbrain está diseñada para evitar en el código. Esta prueba de concepto aplica la misma idea al esquema: recuperar de forma progresiva, limitado a lo que el paso actual realmente necesita, en lugar de volcarlo todo de antemano.

Arquitectura

┌─────────────────┐     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)  │
└─────────────────┘                                └──────────────────────┘

El lado del agente se ejecuta en la API de Responses de Groq (openai/gpt-oss-120b), usando el soporte nativo de MCP remoto de Groq: le pasas a Groq la URL de un servidor MCP y él se encarga del descubrimiento de herramientas, las llamadas y la devolución de resultados al modelo en el lado del servidor, en una sola llamada a la API — sin necesidad de escribir un bucle de orquestación en el cliente. Esto es funcionalmente igual que el conector MCP de Anthropic o la API de MCP remoto de OpenAI; la implementación de Groq está construida explícitamente para ser un reemplazo directo de cualquiera de los dos. Qué modelo/proveedor se encuentra detrás de /api/agent está intencionalmente desacoplado del propio servidor MCP — /api/mcp nunca cambia cuando cambia el proveedor de LLM, que es el sentido de construir esto como un servidor MCP real en lugar de un adaptador de llamadas a herramientas específico de un proveedor.

Las cinco herramientas MCP (lib/schema-context.ts, expuestas a través de app/api/mcp/route.ts):

Cada resultado de herramienta lleva un recuento estimado de tokens de vuelta a la interfaz, de modo que el Panel de contexto puede mostrar exactamente qué obtuvo el agente, en qué orden y a qué costo — y comparar ese total acumulado con lo que habría costado un enfoque ingenuo de "volcar todo el esquema como DDL" para la misma base de datos (getFullSchemaDump / getNaiveDumpTokenEstimate en lib/schema-context.ts).

Decisiones de diseño clave

• Divulgación progresiva en lugar de embeddings, para esta prueba de concepto. search_schema usa coincidencia por palabras clave/comentarios, no búsqueda vectorial. El contrato de la herramienta (consulta de entrada, tablas clasificadas de salida) es lo que importa y lo que una versión de producción conservaría; cambiar la función de puntuación por embeddings es un cambio de implementación interna, no de interfaz. La búsqueda por palabras clave fue suficiente para demostrar el patrón sin añadir un pipeline de embeddings a una construcción de un día.

• Cadena de conexión en el servidor, no proporcionada por el cliente. El modal de fuente de datos muestra las credenciales de Postgres de demostración por transparencia, pero la conexión real se realiza en el servidor a través de DEMO_DATABASE_URL. Permitir que una aplicación de demostración pública acepte cadenas de conexión arbitrarias proporcionadas por el cliente es un problema de seguridad real (SSRF hacia redes internas, recolección de credenciales) — no es un atajo que valga la pena tomar ni siquiera en una demo.

• Una sola fuente de datos en vivo, por diseño, no por omisión. Redshift/Snowflake/Synapse/BigQuery aparecen en el selector porque eso es lo que mostraría el selector del producto real, pero solo Postgres está conectado. El contrato de herramientas anterior es agnóstico respecto a la base de datos (es solo recuperación de tablas/columnas/FK/valores de muestra); añadir una segunda fuente significa escribir un nuevo módulo de introspección detrás de las mismas cinco herramientas, no rediseñar la función.

• MCP en lugar de una API a medida. Usar el Protocolo de Contexto de Modelos real (a través de mcp-handler en Vercel, y el soporte nativo de MCP remoto de Groq en el lado del modelo) en lugar de un adaptador personalizado de llamadas a herramientas significa que este servidor funcionaría sin modificaciones si el propio agente de Superbrain — o cualquier otro agente/proveedor que hable MCP — se conectara a él. Cambiar el proveedor de LLM (esto empezó con Anthropic, ahora se ejecuta en Groq) solo tocó /api/agent; /api/mcp no cambió en absoluto. Esa portabilidad es el verdadero sentido de construirlo como un servidor MCP en lugar de una ruta de API a la que el agente llama directamente.

• La API de Responses de Groq, no Chat Completions. Groq recomienda explícitamente la API de Responses para flujos de trabajo MCP — el descubrimiento de herramientas, el razonamiento y las llamadas a herramientas vuelven como pasos distintos y etiquetados en output[], que es lo que hace posible el rastro del Panel de contexto sin malabares adicionales de análisis.

• Una única llamada de agente sin streaming para la demo. /api/agent espera la respuesta completa de Claude (incluidos todos los viajes de ida y vuelta de las herramientas MCP) antes de devolverla, en lugar de transmitir en streaming. Más sencillo de construir y depurar correctamente en el tiempo disponible; transmitir el rastro de llamadas a herramientas en vivo es lo primero que añadiría a continuación (ver más abajo).

• La clave de API permanece en el cliente, solo en memoria. Quien evalúa pega su propia clave de Groq en la aplicación; se envía directamente a la ruta /api/agent de esta aplicación en cada solicitud y nunca se escribe en almacenamiento ni en registros. Una aplicación de demostración no debería incluir una clave de producción real en un repositorio público.

Cómo ejecutarlo

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

Abre http://localhost:3000 → "Conectar una fuente de datos" → PostgreSQL → Conectar.

Nota sobre probar la llamada de agente en vivo localmente: los servidores de Groq necesitan alcanzar tu servidor MCP a través de una URL HTTPS pública — localhost no es accesible desde su lado. La demo del agente (pedirle que construya algo) solo funciona una vez desplegada (o a través de un túnel como ngrok http 3000 apuntando a tu servidor local, con la detección de origen ajustada en consecuencia). El propio servidor MCP y la introspección de la base de datos se pueden probar completamente en local a través de /api/db/connect y llamando a /api/mcp directamente con el protocolo MCP — ambos están cubiertos arriba y no necesitan Groq en absoluto.

Base de datos de demostración

Cualquier Postgres sirve. Opciones gratuitas: Neon o Supabase. Crea un rol de solo lectura para la cadena de conexión utilizada en la aplicación:

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;

Despliegue

1. Sube este repositorio a GitHub.

2. Impórtalo en Vercel.

3. Establece DEMO_DATABASE_URL, NEXT_PUBLIC_DEMO_DB_HOST, NEXT_PUBLIC_DEMO_DB_NAME, NEXT_PUBLIC_DEMO_DB_USER como variables de entorno en el proyecto de Vercel.

4. Despliega. El servidor MCP es accesible en https://<your-app>.vercel.app/api/mcp automáticamente — /api/agent deriva esa URL de la solicitud entrante, por lo que no se necesita configuración adicional para que ambos se encuentren.

Estrategia de producto

A. Si estuvieras construyendo este producto, ¿qué cambiarías o añadirías a continuación, y por qué?

(Escribe aquí tu propia respuesta — algunos puntos de partida honestos de construir esta prueba de concepto:)

• Transmitir en streaming el rastro de llamadas a herramientas del agente en vivo al Panel de contexto en lugar de esperar la respuesta completa, para que el momento de "¿qué está obteniendo ahora mismo?" se lea como en vivo, no retrospectivo — más cerca de cómo el propio producto de Superbrain presumiblemente muestra su motor de contexto funcionando.

• Cambiar la coincidencia por palabras clave de search_schema por embeddings una vez que un esquema es lo suficientemente grande como para que la superposición de palabras clave deje de ser una buena señal de relevancia (decenas o más de tablas, nombres ambiguos) — el contrato de la herramienta no cambia, solo lo que hay detrás.

• Una capa de caché/diferencias para que una sesión larga de agente no vuelva a pagar el costo completo de tokens por el esquema que ya recuperó antes en la misma sesión, solo el delta.

• Extender el mismo contrato de 5 herramientas a las otras fuentes de datos enumeradas (Redshift, Snowflake, Synapse, BigQuery) — cada una necesita su propio módulo de introspección (diferentes catálogos de sistema/particularidades de information_schema) pero la misma interfaz.

B. ¿Qué problemas importantes de interfaz te desagradan, y cómo crees que molestan a los usuarios actuales?

(Escribe aquí tu propia respuesta basada en el tiempo real que pasaste en Superbrain.)

Qué construí y por qué

(Completa — un párrafo o dos con tus propias palabras sobre la elección de construir esta función específica y por qué encaja con el encargo de "Founding AI Engineer".)

Registro de decisiones

(Completa — la secuencia de decisiones reales y compensaciones tal como las tomaste; la sección "Decisiones de diseño clave" de arriba es un punto de partida, pero esta sección debe estar en tu propia voz según la solicitud de autenticidad del encargo.)