Superbrain Schema-Context MCP — POC

Ein Proof of Concept für eine Funktion: ein MCP-Server, der dem Coding-Agenten von Superbrain live und bei Bedarf Zugriff auf das Schema einer verbundenen Datenbank gibt, statt das gesamte Schema im Voraus in den Kontext zu laden. Die UI ist eine schlanke Hülle darum, gestaltet passend zur echten Oberfläche von Superbrain, sodass die Funktion in einer Umgebung bewertet werden kann, die ihrem echten Zuhause nahekommt.

Was das ist (und was nicht)

• Real und funktionsfähig: der MCP-Server (/api/mcp), seine 5 Schemaabruf-Tools, die dahinterliegende Postgres-Introspection und die Live-Agent-Demo, die zeigt, was der Coding-Agent während des Entwickelns tatsächlich abruft.

• Platzhalter: die restliche IDE-Oberfläche (Menüs, andere Panels) und jede Datenquelle außer Postgres im Modal „Connect a data source“. Diese dienen nur dazu zu zeigen, wo diese Funktion im echten Produkt leben würde, und sind nicht funktional.

• Der integrierte geführte Rundgang sagt dies beim ersten Laden ausdrücklich, damit ein Evaluator nicht rät, welche Teile ernst zu nehmen sind.

Related MCP server: keystone-mcp

Warum diese Funktion

Superbrains eigener Pitch ist eine Context Engine, die Code-Intelligenz komprimiert und priorisiert, um den Token-Verbrauch um 60–80 % zu senken und dabei das volle Repo-Bewusstsein zu behalten. Das Datenbankschema ist dasselbe Problem eine Ebene tiefer: Ein Agent, der eine Datenanwendung baut, braucht Tabellen-/Spalten-/Beziehungskontext, um korrekten Code zu schreiben, und der naive Ansatz – das gesamte Schema als einen einzigen Brocken zu übergeben – ist genau die Art von undifferenzierter Kontextblähung, die Superbrains Architektur für Code vermeiden soll. Dieser POC wendet dieselbe Idee auf Schemas an: schrittweise abrufen, begrenzt auf das, was der aktuelle Schritt tatsächlich benötigt, statt alles im Voraus zu laden.

Architektur

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

Die Agentenseite läuft auf der Responses API von Groq (openai/gpt-oss-120b) und nutzt die native Remote-MCP-Unterstützung von Groq: Du übergibst Groq eine MCP-Server-URL, und Groq übernimmt Tool-Erkennung, Aufruf und das Zurückspielen der Ergebnisse an das Modell serverseitig in einem einzigen API-Aufruf — ohne dass du eine clientseitige Orchestrierungsschleife schreiben müsstest. Das ist funktional dieselbe Form wie der MCP-Connector von Anthropic oder die Remote-MCP-API von OpenAI; die Implementierung von Groq ist ausdrücklich als Drop-in-Ersatz für beide gebaut. Welches Modell bzw. welcher Provider hinter /api/agent sitzt, ist bewusst vom MCP-Server selbst entkoppelt — /api/mcp ändert sich nie, wenn der LLM-Provider wechselt, und genau darum geht es, dies als echten MCP-Server zu bauen statt als providerspezifischen Tool-Calling-Shim.

Die fünf MCP-Tools (lib/schema-context.ts, bereitgestellt über app/api/mcp/route.ts):

Jedes Tool-Ergebnis bringt eine geschätzte Token-Anzahl zurück in die UI, sodass das Context Panel genau zeigen kann, was der Agent abgerufen hat, in welcher Reihenfolge und zu welchen Kosten — und diese laufende Summe mit den Kosten vergleichen kann, die ein naiver Ansatz – „das gesamte Schema als DDL auszugeben“ – für dieselbe Datenbank verursacht hätte (getFullSchemaDump / getNaiveDumpTokenEstimate in lib/schema-context.ts).

Zentrale Designentscheidungen

• Progressive Disclosure statt Embeddings, für diesen POC. search_schema nutzt Stichwort-/Kommentarabgleich, keine Vektorsuche. Der Tool-Vertrag (Anfrage rein, bewertete Tabellen raus) ist das, worauf es ankommt, und das würde eine Produktionsversion beibehalten; die Scoring-Funktion gegen Embeddings auszutauschen ist eine interne Implementierungsänderung, keine Schnittstellenänderung. Die Stichwortsuche reichte aus, um das Muster zu demonstrieren, ohne eine Embeddings-Pipeline in einen Ein-Tages-Build einzubauen.

• Serverseitige Verbindungszeichenfolge, nicht vom Client bereitgestellt. Das Datenquellen-Modal zeigt die Demo-Postgres-Zugangsdaten aus Transparenzgründen an, aber die tatsächliche Verbindung wird serverseitig über DEMO_DATABASE_URL hergestellt. Einer öffentlichen Demo-App zu erlauben, beliebige vom Client bereitgestellte Verbindungszeichenfolgen anzunehmen, ist ein echtes Sicherheitsproblem (SSRF in interne Netzwerke, Abgreifen von Zugangsdaten) — keine Ecke, an der man sparen sollte, selbst in einer Demo.

• Eine Live-Datenquelle, mit Absicht und nicht aus Versehen. Redshift/Snowflake/Synapse/BigQuery erscheinen im Auswahlmenü, weil das Auswahlmenü des echten Produkts sie zeigen würde, aber nur Postgres ist angebunden. Der Tool-Vertrag oben ist datenbankagnostisch (es geht nur um den Abruf von Tabellen-/Spalten-/FK-/Beispielwerten); eine zweite Quelle hinzuzufügen bedeutet, ein neues Introspectionsmodul hinter denselben fünf Tools zu schreiben, nicht die Funktion neu zu entwerfen.

• MCP statt einer maßgeschneiderten API. Die Verwendung des tatsächlichen Model Context Protocol (über mcp-handler auf Vercel und die native Remote-MCP-Unterstützung von Groq auf der Modellseite) anstelle eines benutzerdefinierten Tool-Calling-Shims bedeutet, dass dieser Server unverändert funktionieren würde, wenn sich der eigene Agent von Superbrain — oder ein anderer MCP-sprechender Agent/Provider — mit ihm verbinden würde. Den LLM-Provider zu wechseln (das begann mit Anthropic, läuft jetzt auf Groq) berührte nur /api/agent; /api/mcp änderte sich überhaupt nicht. Diese Portabilität ist der eigentliche Grund, es als MCP-Server zu bauen statt als API-Route, die der Agent direkt aufruft.

• Die Responses API von Groq, nicht Chat Completions. Groq empfiehlt die Responses API ausdrücklich für MCP-Workflows — Tool-Erkennung, Reasoning und Tool-Aufrufe kommen als separate, beschriftete Schritte in output[] zurück, und genau das ermöglicht den Trace des Context Panels ohne zusätzliche Parsing-Akrobatik.

• Ein einzelner nicht-streamender Agent-Aufruf für die Demo. /api/agent wartet auf die vollständige Claude-Antwort (einschließlich aller MCP-Tool-Round-Trips), bevor es zurückkehrt, anstatt zu streamen. In der verfügbaren Zeit einfacher korrekt zu bauen und zu debuggen; das Live-Streamen des Tool-Call-Traces ist das Erste, was ich als Nächstes hinzufügen würde (siehe unten).

• Der API-Schlüssel bleibt clientseitig, nur im Speicher. Der Evaluator fügt seinen eigenen Groq-Schlüssel in die App ein; er wird pro Anfrage direkt an die /api/agent-Route dieser App gesendet und nie in Speicher oder Logs geschrieben. Eine Demo-App sollte keinen echten Produktionsschlüssel in einem öffentlichen Repo ausliefern.

Ausführen

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

Öffne http://localhost:3000 → „Connect a Data Source“ → PostgreSQL → Connect.

Hinweis zum lokalen Testen des Live-Agent-Aufrufs: Die Server von Groq müssen deinen MCP-Server über eine öffentliche HTTPS-URL erreichen können — localhost ist von deren Seite aus nicht erreichbar. Die Agent-Demo (die es auffordert, etwas zu bauen) funktioniert erst nach dem Deployment (oder über einen Tunnel wie ngrok http 3000, der auf deinen lokalen Server zeigt, wobei die Origin-Erkennung entsprechend angepasst werden muss). Der MCP-Server selbst und die DB-Introspection können vollständig lokal getestet werden — über /api/db/connect und durch direkten Aufruf von /api/mcp mit dem MCP-Protokoll. Beides ist oben beschrieben und benötigt überhaupt kein Groq.

Demo-Datenbank

Jede Postgres-Datenbank funktioniert. Kostenlose Optionen: Neon oder Supabase. Erstelle eine Nur-Lese-Rolle für die in der App verwendete Verbindungszeichenfolge:

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;

Deployment

1. Übertrage dieses Repo auf GitHub.

2. Importiere es in Vercel.

3. Setze DEMO_DATABASE_URL, NEXT_PUBLIC_DEMO_DB_HOST, NEXT_PUBLIC_DEMO_DB_NAME, NEXT_PUBLIC_DEMO_DB_USER als Umgebungsvariablen im Vercel-Projekt.

4. Führe das Deployment durch. Der MCP-Server ist automatisch unter https://<your-app>.vercel.app/api/mcp erreichbar — /api/agent leitet diese URL aus der eingehenden Anfrage ab, sodass keine zusätzliche Konfiguration nötig ist, damit die beiden zueinander finden.

Produktstrategie

A. Wenn du dieses Produkt bauen würdest, was würdest du als Nächstes ändern oder hinzufügen, und warum?

(Trage hier deine eigene Antwort ein — ein paar ehrliche Ausgangspunkte aus dem Bau dieses POC:)

• Den Tool-Call-Trace des Agents live in das Context Panel streamen, statt auf die vollständige Antwort zu warten, damit der Moment „Was ruft es gerade ab?“ als live wirkt und nicht als nachträglich — näher daran, wie das eigene Produkt von Superbrain vermutlich seine Context Engine zeigt.

• Die Stichwortsuche von search_schema durch Embeddings zu ersetzen, sobald ein Schema groß genug ist, dass Stichwortüberschneidungen kein gutes Relevanzsignal mehr sind (Dutzende+ Tabellen, mehrdeutige Benennung) — der Tool-Vertrag ändert sich nicht, nur das, was dahintersteckt.

• Eine Caching-/Diffing-Schicht, damit eine lange Agent-Sitzung nicht die vollen Token-Kosten für Schema erneut zahlt, das sie bereits früher in derselben Sitzung abgerufen hat, sondern nur das Delta.

• Denselben 5-Tool-Vertrag auf die anderen aufgeführten Datenquellen auszuweiten (Redshift, Snowflake, Synapse, BigQuery) — jede braucht ihr eigenes Introspectionsmodul (unterschiedliche Systemkataloge/information_schema-Eigenheiten), aber dieselbe Schnittstelle.

B. Welche größeren UI-Probleme gefallen dir nicht, und wie denkst du, dass sie aktuelle Nutzer stören?

(Trage hier deine eigene Antwort ein, basierend auf deiner tatsächlichen Zeit in Superbrain.)

Was ich gebaut habe und warum

(Fülle aus — ein oder zwei Absätze in deinen eigenen Worten über die Entscheidung, genau diese Funktion zu bauen, und warum sie zum „Founding AI Engineer“-Brief passt.)

Entscheidungsprotokoll

(Fülle aus — die Abfolge der tatsächlichen Entscheidungen und Abwägungen, wie du sie getroffen hast; der Abschnitt „Zentrale Designentscheidungen“ oben ist ein Ausgangspunkt, aber dieser Abschnitt sollte gemäß der Bitte des Auftrags um Authentizität in deiner eigenen Stimme verfasst sein.)