Superbrain Schema-Context MCP — POC

1つの機能の概念実証: Superbrainのコーディングエージェントに、接続されたデータベースのスキーマへのライブ・オンデマンドアクセスを提供するMCPサーバー。スキーマ全体を最初にコンテキストにダンプする代わりに、必要なときに必要な分だけ取得します。UIはその周りの薄いシェルで、Superbrainの実際のインターフェースに合わせてスタイルされており、実際の製品に近い環境で機能を評価できるようになっています。

これが何であるか(そして何でないか)

• 本物で動作するもの: MCPサーバー(/api/mcp)、その5つのスキーマ取得ツール、その背後にあるPostgresイントロスペクション、そしてコーディングエージェントがビルド中に実際に何を取得するかを示すライブエージェントデモ。

• プレースホルダー: IDEクロームの残り(メニュー、その他のパネル)と、「データソースに接続」モーダルのPostgres以外のすべてのデータソース。これらは、この機能が実際の製品のどこに配置されるかを示すためのものであり、機能するためのものではありません。

• アプリ内ガイドツアーは、初回ロード時にこれを明示的に示しており、評価者がどの部分を真剣に受け取るべきかを推測する必要はありません。

Related MCP server: keystone-mcp

なぜこの機能か

Superbrain自身の売り文句は、コードインテリジェンスを圧縮・優先順位付けしてトークン使用量を60〜80%削減しながら、リポジトリ全体の認識を維持するコンテキストエンジンです。データベーススキーマは、その1層下にある同じ問題です: データアプリを構築するエージェントは、正しいコードを書くためにテーブル/カラム/リレーションシップのコンテキストを必要とします。そして、素朴なアプローチ — スキーマ全体を1つのブロブとして渡す — は、まさに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)  │
└─────────────────┘                                └──────────────────────┘

エージェント側はGroqのResponses API(openai/gpt-oss-120b)上で動作し、GroqのネイティブなリモートMCPサポートを使用します: GroqにMCPサーバーURLを渡すと、ツールの検出、呼び出し、結果のモデルへのフィードバックをサーバー側で1回のAPI呼び出しで処理します — クライアント側のオーケストレーションループを書く必要はありません。これは機能的にはAnthropicのMCPコネクタやOpenAIのリモートMCP APIと同じ形です。Groqの実装は、どちらかのドロップイン置換として明示的に構築されています。/api/agentの背後にあるモデル/プロバイダーは、MCPサーバー自体から意図的に切り離されています — LLMプロバイダーが変わっても/api/mcpは決して変更されません。これが、プロバイダー固有のツール呼び出しシムではなく、実際のMCPサーバーとして構築する要点です。

5つのMCPツール(lib/schema-context.ts、app/api/mcp/route.ts経由で公開):

各ツールの結果は推定トークン数をUIに返すため、コンテキストパネルは、エージェントが何を、どの順序で、どのコストで取得したかを正確に表示できます — そして、その累計を、同じデータベースに対する素朴な「スキーマ全体をDDLとしてダンプする」アプローチのコスト(lib/schema-context.tsのgetFullSchemaDump / getNaiveDumpTokenEstimate)と比較できます。

主要な設計上の決定

• このPOCでは、埋め込みよりも段階的開示。 search_schemaはキーワード/コメントマッチングを使用し、ベクトル検索ではありません。ツールの契約(クエリ入力、ランキング付きテーブル出力)が重要であり、本番バージョンが保持するものです。スコアリング関数を埋め込みに交換することは、インターフェースの変更ではなく、内部実装の変更です。キーワード検索は、1日ビルドに埋め込みパイプラインを追加することなくパターンを実証するのに十分でした。

• クライアント提供ではなく、サーバー側の接続文字列。 データソースモーダルは、透明性のためにデモPostgres認証情報を表示しますが、実際の接続はDEMO_DATABASE_URLを介してサーバー側で行われます。公開デモアプリが任意のクライアント提供の接続文字列を受け入れることは、実際のセキュリティ問題(内部ネットワークへのSSRF、認証情報の収集)です — デモであっても削る価値のあるコーナーではありません。

• 設計による1つのライブデータソース。省略によるものではありません。 Redshift/Snowflake/Synapse/BigQueryは、実際の製品のピッカーが表示するものだからピッカーに表示されますが、Postgresのみが配線されています。上記のツール契約はデータベースに依存しません(テーブル/カラム/FK/サンプル値の取得だけです)。2番目のソースを追加するということは、同じ5つのツールの背後に新しいイントロスペクションモジュールを書くことを意味し、機能の再設計ではありません。

• 独自APIではなくMCP。 カスタムのツール呼び出しシムの代わりに、実際のModel Context Protocol(Vercel上のmcp-handler、モデル側のGroqのネイティブリモートMCPサポート)を使用することで、Superbrain自身のエージェント — または他のMCPを話すエージェント/プロバイダー — が接続した場合、このサーバーは変更なしで動作します。LLMプロバイダーの交換(これはAnthropicとして始まり、現在はGroqで動作)は/api/agentにのみ触れました。/api/mcpはまったく変更されていません。その移植性が、エージェントが直接呼び出すAPIルートではなくMCPサーバーとして構築する実際のポイントです。

• Chat CompletionsではなくGroqのResponses API。 GroqはMCPワークフローにResponses APIを明示的に推奨しています — ツールの検出、推論、ツール呼び出しがoutput[]内の個別のラベル付きステップとして返され、それが追加の解析の手間なしにコンテキストパネルのトレースを可能にします。

• デモ用の単一の非ストリーミングエージェント呼び出し。 /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を開く → 「データソースに接続」→ PostgreSQL → 接続。

ローカルでのライブエージェント呼び出しのテストに関する注意: Groqのサーバーは、公開HTTPS URL経由でMCPサーバーに到達する必要があります — localhostは彼らの側から到達できません。エージェントデモ(何かを構築するよう依頼する)は、デプロイ後(またはngrok http 3000のようなトンネルをローカルサーバーに向け、オリジン検出をそれに合わせて調整した場合)にのみ機能します。MCPサーバー自体とDBイントロスペクションは、/api/db/connectとMCPプロトコルで/api/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. Vercelプロジェクトの環境変数としてDEMO_DATABASE_URL、NEXT_PUBLIC_DEMO_DB_HOST、NEXT_PUBLIC_DEMO_DB_NAME、NEXT_PUBLIC_DEMO_DB_USERを設定します。

4. デプロイします。MCPサーバーは自動的にhttps://<your-app>.vercel.app/api/mcpで到達可能です — /api/agentは受信リクエストからそのURLを導出するため、2つが互いを見つけるための追加設定は不要です。

製品戦略

A. この製品を構築しているとしたら、次に何を変更または追加しますか、そしてなぜですか?

(ここに自分の回答を記入してください — このPOCの構築からの正直な出発点をいくつか:)

• 完全な応答を待つのではなく、エージェントのツール呼び出しトレースをコンテキストパネルにライブでストリーミングし、「今何を取得しているか」の瞬間が事後的ではなくライブとして読まれるようにする — Superbrain自身の製品がおそらくコンテキストエンジンの動作を示す方法に近い。

• スキーマが十分に大きくなり、キーワードの重複が適切な関連性シグナルでなくなったら(数十以上のテーブル、曖昧な命名)、search_schemaのキーワードマッチングを埋め込みに交換する — ツール契約は変わらず、背後にあるものだけが変わる。

• キャッシュ/差分レイヤーを追加して、長いエージェントセッションが同じセッション内で以前に取得したスキーマに対して完全なトークンコストを再支払いしないようにし、デルタのみを支払うようにする。

• 同じ5ツール契約を他のリストされたデータソース(Redshift、Snowflake、Synapse、BigQuery)に拡張する — それぞれに独自のイントロスペクションモジュール(異なるシステムカタログ/information_schemaの癖)が必要だが、同じインターフェース。

B. どのような主要なUIの問題が嫌いですか、そしてそれらは現在のユーザーをどのように悩ませていると思いますか?

(Superbrainで実際に過ごした時間に基づいて、ここに自分の回答を記入してください。)

私が構築したものとなぜ

(記入してください — この特定の機能を構築する選択と、それが「Founding AI Engineer」のブリーフにどのように適合するかについて、自分の言葉で1〜2段落。)

意思決定ログ

(記入してください — 実際に行った決定とトレードオフの順序。上記の「主要な設計上の決定」セクションは出発点ですが、このセクションは課題の信頼性の要求に従って、自分の声で書く必要があります。)