Superbrain Schema-Context MCP — 概念验证

这是一个针对单一功能的验证性原型：一个 MCP 服务器，让 Superbrain 的编码代理能够按需实时访问所连接数据库的 schema，而不是一开始就把整个 schema 全部塞进上下文。UI 只是围绕它的一层薄壳，样式与 Superbrain 的真实界面保持一致，以便在接近真实使用环境的情况下评估该功能。

这是什么（以及不是什么）

• 真实且可运行： MCP 服务器（/api/mcp）、它的 5 个 schema 检索工具、背后的 Postgres 内省逻辑，以及展示编码代理在构建过程中实际获取内容的实时代理演示。

• 占位性质： 其余 IDE 界面元素（菜单、其他面板）以及"连接数据源"弹窗中除 Postgres 之外的所有数据源。这些元素的存在是为了展示该功能在真实产品中的位置，而非真正可用。

• 应用内的引导式巡览在首次加载时会明确说明这一点，这样评估者就不必猜测哪些部分值得认真对待。

Related MCP server: keystone-mcp

为什么做这个功能

Superbrain 自身的卖点是它是一个上下文引擎，能够压缩和优先处理代码智能，在保持完整仓库感知的同时将 token 用量削减 60-80%。数据库 schema 是同一类问题在下一层的体现：构建数据应用的代理需要表/列/关系上下文才能写出正确的代码，而最朴素的做法——把完整 schema 作为一个整体块交给它——恰恰是 Superbrain 架构旨在为代码避免的那种无差别上下文膨胀。这个 POC 将同样的思路应用到 schema 上：按需渐进式检索，范围限定在当前步骤实际需要的内容，而不是一次性全部倾倒。

架构

┌─────────────────┐     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：你把 MCP 服务器 URL 交给 Groq，它会在服务端处理工具发现、调用以及把结果回传给模型，全部在一次 API 调用内完成——无需编写客户端编排循环。这在功能形态上与 Anthropic 的 MCP 连接器或 OpenAI 的远程 MCP API 相同；Groq 的实现明确设计为可直接替换上述两者。/api/agent 背后使用哪个模型/提供商与 MCP 服务器本身有意解耦——/api/mcp 在 LLM 提供商更换时完全不需要改动，这正是把它构建为真正的 MCP 服务器而非提供商特定的工具调用适配层的意义所在。

五个 MCP 工具（lib/schema-context.ts，通过 app/api/mcp/route.ts 暴露）：

每个工具结果都会携带估算的 token 数返回给 UI，这样上下文面板就能精确显示代理获取了什么、按什么顺序、花费多少成本——并将该累计值与同一数据库下朴素"将整个 schema 作为 DDL 倾倒"方案的成本进行对比（lib/schema-context.ts 中的 getFullSchemaDump / getNaiveDumpTokenEstimate）。

关键设计决策

• 本 POC 采用渐进式披露而非嵌入向量。 search_schema 使用关键词/注释匹配，而非向量搜索。工具契约（查询进、排序后的表出）才是关键，也是生产版本会保留的部分；将评分函数替换为嵌入向量是内部实现变更，而非接口变更。关键词搜索足以演示这一模式，无需在一天构建中加入嵌入向量管道。

• 连接字符串在服务端，而非客户端提供。 数据源弹窗展示演示用 Postgres 凭据以保证透明度，但实际连接通过 DEMO_DATABASE_URL 在服务端完成。让一个公开演示应用接受任意客户端提供的连接字符串是真实的安全问题（SSRF 进入内网、凭据窃取）——即使在演示中也不值得为此妥协。

• 只有一个真实数据源，这是有意为之，而非遗漏。 Redshift/Snowflake/Synapse/BigQuery 出现在选择器中，因为真实产品的选择器会显示这些选项，但只有 Postgres 真正接入。上述工具契约与数据库无关（它只是表/列/外键/示例值检索）；添加第二个数据源意味着在同样的五个工具背后编写一个新的内省模块，而不是重新设计功能。

• 使用 MCP 而非定制 API。 使用实际的 Model Context Protocol（在 Vercel 上通过 mcp-handler，模型侧通过 Groq 的原生远程 MCP 支持）而非自定义工具调用封装器，意味着如果 Superbrain 自己的代理——或任何其他支持 MCP 的代理/提供商——连接上来，这个服务器可以不做任何修改直接工作。更换 LLM 提供商（最初是 Anthropic，现在运行在 Groq 上）只涉及 /api/agent；/api/mcp 完全没变。这种可移植性才是把它构建为 MCP 服务器而非代理直接调用的 API 路由的真正意义。

• 使用 Groq 的 Responses API，而非 Chat Completions。 Groq 明确推荐将 Responses API 用于 MCP 工作流——工具发现、推理和工具调用会作为独立、带标签的步骤返回在 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 服务器本身和数据库内省可以通过 /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，因此两者之间无需额外配置即可互相找到。

产品策略

A. 如果你在构建这个产品，你接下来会改变或添加什么，为什么？

（在此填写你自己的答案——构建这个 POC 时的一些诚实的出发点：）

• 将代理的工具调用追踪实时流式输出到上下文面板，而不是等待完整响应，让"它现在正在获取什么"的瞬间读起来是实时的，而非回顾性的——更接近 Superbrain 自身产品展示其上下文引擎工作方式的样子。

• 当 schema 足够大、关键词重叠不再是好的相关性信号时（几十张以上的表、命名模糊），将 search_schema 的关键词匹配替换为嵌入向量——工具契约不变，只变背后的实现。

• 增加缓存/差异层，让长代理会话不会为同一会话中先前已检索过的 schema 重复支付完整 token 成本，只支付增量部分。

• 将同样的 5 工具契约扩展到其他列出的数据源（Redshift、Snowflake、Synapse、BigQuery）——每个都需要自己的内省模块（不同的系统目录/information_schema 特性），但接口相同。

B. 你讨厌哪些主要的 UI 问题，你认为它们如何困扰现有用户？

（根据你在 Superbrain 中的实际使用时间，在此填写你自己的答案。）

我构建了什么以及为什么

（填写——用你自己的话写一两段，说明为什么选择构建这个特定功能，以及它如何契合"创始 AI 工程师"的定位。）

决策日志

（填写——你做出的一系列真实决策和权衡；上面的"关键设计决策"部分是一个起点，但本节应该按照作业对真实性的要求，用你自己的语气来写。）