Arun-kc/schemabrain
GitHub: Arun-kc/schemabrain
Schema Brain 是一个面向 AI 智能体的 SQL 边界安全层，通过 LLM 驱动的 schema 智能化帮助智能体准确理解复杂数据库结构，并计划在后续版本提供执行前验证和查询安全拦截能力。
Stars: 3 | Forks: 0
# Schema 概览
[](https://github.com/Arun-kc/schemabrain/actions/workflows/ci.yml)
[](https://www.python.org/)
[](LICENSE)
**状态：0.1.0a1（Alpha 预览版）。** 目前已支持 Postgres + SQLite。Snowflake / BigQuery / MySQL 已列入 v1 路线图。在 v1 版本之前，API 可能会发生变化——如需稳定性，请固定版本（`pip install schemabrain==0.1.0a1`）。
## 存在的问题
AI 智能体在查询真实的生成数据库时常常失败：
1. **Schema 无法完全放入上下文** —— 一个包含 300 张表的 schema，仅 `CREATE TABLE` 语句就需要 50k+ 个 token。
2. **列名晦涩难懂** —— 诸如 `acct_dim_v3`、`pmt_fct_h`、`cust_id_v2_legacy` 这样的命名。
3. **Join 关系不明显** —— 当存在三个外键（FK）时，哪一个是“正确”的那个？
4. **数据具有特定的形态** —— `status` 可能是 5 个枚举值、50 个枚举值，或者是一堆杂乱的自由文本。
Schema Brain 解决了以上所有四个问题，并通过稳定的 MCP 工具接口提供服务，供任何智能体（Claude Desktop、Anthropic SDK 或自定义智能体）调用。
**隐藏在这些背后更大的问题** —— 以具有凭证权限的角色运行的数据库 MCP、提示注入升级为 SQLi（根据 Datadog Security Labs 的报告，Anthropic Postgres MCP 发布的 NPM/Docker 产物在归档时携带了一个未修补的 SQL 注入漏洞；Supabase MCP 在其文档记录的条件下可能导致数据泄露）、在 SQL 边界缺乏针对 PII 的拒绝执行机制 —— 这正是 Schema Brain 在 v2 版本的 SQL 边界安全层中致力于解决的问题。今天发布的 schema 智能化是该层所需的基础底座。请参阅 [未来的发展方向](#where-this-is-going)。
## 它的功能
- 索引您的数据库 schema，对每一列进行剖析，并为每列生成一段 LLM 描述（默认使用 Claude Haiku 4.5；对于晦涩的缩写词使用 Sonnet 4.6）。
- 通过 `fastembed` 在本地使用 `BAAI/bge-small-en-v1.5` 对描述进行向量化嵌入 —— 无需引入第二个 API 供应商。
- 将所有数据存储在一个单独的 SQLite 文件中。不需要 Qdrant，不需要 Redis，零运维负担。
- 提供四个 MCP 工具：[`find_relevant_tables`、`describe_table`、`describe_column`、`suggest_joins`](docs/mcp-tools.md)。每次响应都包含 token 估算，以便智能体进行上下文预算。
## 未来的发展方向
Schema Brain 正在构建为**AI 智能体的 SQL 边界安全层** —— 该层会解析您的智能体即将向数据库发送的请求，并在执行前予以拒绝（或重写）。
该层需要一个位于其下方的语义底座。如果您不知道哪些列包含 PII，就无法拒绝“此查询涉及 PII”的请求。如果没有规范化的 join 定义，就无法重写“通过此关联表进行 join”。如果您不知道指标的粒度，就无法对其进行验证。
因此，工程化的顺序是 **schema 智能化 → 语义底座 → 安全原语：**
- **v0 —— schema 智能化（正在发布）：** schema 内省、经 LLM 充实的列描述、嵌入检索。查询日志挖掘 + 第 5 个 MCP 工具将在 v0.5 中推出。
- **v1 —— 语义底座：** 实体、指标和规范化 join 将作为一等持久化定义。从观测数据中通过 LLM 建议生成；由用户在 YAML 中确认。
- **v2 —— 安全楔子：** PII 标记拒绝、执行前 `validate_query`、带有行数/成本/超时上限的 `execute`、**带有恢复机制的子查询拒绝**（解析智能体的 SQL，仅拒绝不安全的片段并提供重写建议）。截至 2026 年中尚无竞争对手发布类似功能。
今天的产品是 schema 智能化。安全层是我们的发展轨迹，而非当前的声明。如果您现在就需要安全原语，该产品尚未准备好——请关注 v2 路线图。
## 与同类项目对比
开源领域在 2026 年变得稀薄：Vanna 的公开代码库随着项目商业化而被冻结，而参考的 Postgres MCP 服务器于 2025 年归档，且未指定官方继任者。当前的活跃版图如下：
| 项目 | 许可证 | 官方 MCP | 状态 |
|---|---|---|---|
| **Schema Brain** | MIT | ✅ | 活跃 — `0.1.0a1` alpha |
| [Vanna AI](https://github.com/vanna-ai/vanna) | MIT (代码库已冻结) | ❌ | OSS 于 2026-03 归档；项目已转为商业化 (Vanna 2.0 / Cloud / Enterprise) |
| [Reference Postgres MCP](https://github.com/modelcontextprotocol/servers-archived) | MIT | ✅ | 于 2025-05 归档；未指定官方继任者 |
| [Atlan](https://atlan.com) | 闭源 | ✅ | 仅限 SaaS，企业级定价 |
| [dbt-mcp](https://github.com/dbt-labs/dbt-mcp) | Apache-2.0 | ✅ | 活跃 — 需要一个 dbt 项目 |
| [WrenAI](https://github.com/canner/WrenAI) | Apache-2.0 | ❌ (在路线图中) | 活跃 — 使用 MDL 建模层 |
Schema Brain 所处的位置是上述任何项目都无法完全覆盖的：**OSS + MIT + 官方 MCP + 无需建模层 + 在单个 Python 进程中内省一个实时的 Postgres 数据库**。目前坦诚存在的差距是：查询日志感知 —— `pg_stat_statements` 解析已排期在 v0 的第 8 周进行。
长远定位是为智能体提供 SQL 边界安全层（参见 [未来的发展方向](#where-this-is-going)）。上述项目均未在“解析智能体 SQL 并依据策略进行评判”的层面运作；这正是 v2 的切入点。
## 实际应用展示
真实的 Claude Desktop 会话，于 2026-05-11 针对捆绑的电商测试数据（6 张表，24 列，索引成本 $0.0074）进行了验证：
这是资深工程师级别的输出。其中没有任何注意事项是硬编码的 —— M:N 双重计数、递归 CTE 意识、自由文本状态标记 —— 这些都得益于让 Claude 能够对索引后的描述进行推理而自然得出。要验证 Claude 生成的 SQL 在机制上是否正确（以及标记出的注意事项是否反映了实际的数据行为），请参阅 [验证 Claude 生成的 SQL](docs/setup.md#validating-sql-claude-generates)。
### 以及当答案不存在时
这个限定语 —— *"至少在 Schema Brain 已索引的任何内容中不存在"* —— 非常关键。大多数基于数据库的 LLM 工具会自信地凭空捏造一个 `payments` 表，或者将答案强行套入 `orders.total_cents`。但 Schema Brain 不会。
## 快速开始
从 `pip install` 到可用的 Claude Desktop 集成只需五分钟。以下是三个前置注意事项——这些都是真实用户踩过的坑：
| 注意事项 | 解决方法 |
|---|---|
| macOS 默认没有 `psql` | 我们改用 `docker exec -i sb-pg psql ...` —— 这会在 postgres 容器内运行 psql，无需在主机上安装 |
| `pip install schemabrain` 和首次运行 `schemabrain index` 时各有大约 30-60 秒的无反馈时间 | 不要强制终止它们。`pip` 需要解析约 75 个 wheels 包；首次索引运行会下载 ONNX 嵌入模型（约 67 MB）并执行 24 次 LLM 调用。进度条将在 v0 版本中加入。 |
| `ANTHROPIC_API_KEY` 环境变量传递 | 请在将要运行 `index` 的同一终端中执行 `export ANTHROPIC_API_KEY=sk-ant-...` |
### 1. 安装
```
pip install schemabrain
```
如果您想对其进行修改开发，也可以从源码安装：
```
git clone git@github.com:Arun-kc/schemabrain.git
cd schemabrain && uv sync --extra dev
```
### 2. 启动 Postgres 并应用捆绑的测试数据（或指向您自己的数据库）
```
docker run --rm -d -p 5432:5432 -e POSTGRES_PASSWORD=local --name sb-pg postgres:16-alpine
docker exec -i sb-pg psql -U postgres -d postgres \
< $(schemabrain fixture-path ecommerce.sql)
```
如果您使用自己的数据库，请跳过 docker，并使用您真实的 `postgresql+psycopg://` URL。
### 3. 建立索引
```
export ANTHROPIC_API_KEY=sk-ant-...
schemabrain index "postgresql+psycopg://postgres:local@localhost:5432/postgres" \
--store-path ./schemabrain.db
```
首次运行预计会有约 30-60 秒的无反馈时间，随后将显示：
```
Indexed 6 table(s): 6 changed, 0 unchanged, 0 removed.
Columns: +24/~0/-0. LLM: 24 descriptions ($0.0074). Embeddings: 24
```
### 4. 接入 Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
```
{
"mcpServers": {
"schemabrain": {
"command": "/ABSOLUTE/PATH/TO/.venv/bin/schemabrain",
"args": [
"serve",
"--source",
"postgresql+psycopg://postgres:local@localhost:5432/postgres",
"--store-path",
"/ABSOLUTE/PATH/TO/schemabrain.db"
]
}
}
}
```
这两个路径必须为绝对路径。完全退出 Claude Desktop（Cmd+Q）并重新启动。🔌 工具面板现在应显示包含 4 个工具的“schemabrain”。
**如果是 Cursor 用户：** 将相同的 `mcpServers` 配置块放入 `~/.cursor/mcp.json`（全局配置）或 `.cursor/mcp.json`（项目级配置）。配置模板见 [`examples/cursor_mcp_config.example.json`](examples/cursor_mcp_config.example.json)。配置完成后重启 Cursor。
有关无界面的 Anthropic-SDK 使用方式，请参阅 [`examples/anthropic_demo.py`](examples/anthropic_demo.py) 和 [`docs/setup.md`](docs/setup.md)。
## 路线图
**v0.5 —— 完善智能化：**
- 将智能体体验 (Agent-UX) 宪章 v1.0 改造应用于现有工具，并辅以 CI 强制执行
- 开发者体验 (Dev-UX) 基础：丰富的进度 UI、引导式错误提示、`--dry-run`
- 通过 `pg_stat_statements` 进行查询日志挖掘
- 第 5 个 MCP 工具：`get_example_queries` —— 从您的查询日志中返回与智能体意图匹配的真实 SQL
**v1 —— 语义底座：**
- 实体、指标和规范化 join 作为一等持久化定义
- 基于现有列描述 + FK 关系图，由 LLM 建议实体/指标定义（切入点：Cube/dbt 需要数周的手工编写；Schema Brain 将引导过程缩减至约 30 分钟）
- BIRD Mini-Dev 自动化评估套件
- Drift CLI：`schemabrain reindex --diff`
- 新增一个数据库引擎：Snowflake / BigQuery / MySQL
- 迁移至 Typer + rich CLI
**v2 —— SQL 边界安全楔子：**
- 超越模式遮蔽的 PII 打标（列级分类，在工具边界对智能体可见的拒绝机制）
- `validate_query` —— 智能体发出的 SQL 在执行前被解析并根据策略进行评判
- 带有硬性上限的 `execute` —— 在数据库层面强制执行只读 Postgres 角色（不仅仅是 SQL 字符串检查）、语句超时、行数上限、单次调用成本限制
- **带有恢复机制的子查询拒绝** —— 解析 SQL，识别不安全的片段，仅拒绝该片段并提供重写建议或替代的工具调用
- 仅追加的 `mcp_audit` 日志，以及每次工具调用的响应溯源
**v3 —— 多引擎 + 控制平面（商业化，取决于托管需求）：**
- 剩余引擎（广泛支持 BigQuery / Snowflake / Redshift）
- 基于遥测和查询重写模式的学习循环
- 具有全舰队对抗性特征聚合的托管控制平面（跨租户传播按部署的拒绝模式——Cloudflare-WAF 模型）
## 文档
- [`docs/architecture.md`](docs/architecture.md) —— 流水线、检索契约、缓存逻辑、成本模型、评估体系及已验证内容
- [`docs/mcp-tools.md`](docs/mcp-tools.md) —— 包含示例响应的 4 个 MCP 工具完整参考
- [`docs/setup.md`](docs/setup.md) —— Claude Desktop 接入 + Anthropic SDK 演示及故障排除
- [`CONTRIBUTING.md`](CONTRIBUTING.md) —— 开发环境设置、TDD 预期、约定式提交及架构不变量
- [`examples/`](examples/) —— 可直接复制粘贴的 Claude Desktop 配置 + 使用官方 `mcp` Python SDK 的无界面智能体循环
## 常见问题
**我的数据会离开我的机器吗？**
只有经 LLM 充实的列描述及其输入的脱敏样本值会离开。在样本离开 profiler 模块之前，会对每个样本运行三次正则表达式过滤（电子邮件、美国社会安全号码 SSN、信用卡格式的数字串）—— 请参阅 [`chemabrain/profiler/stats.py`](schemabrain/profiler/stats.py)。对 Anthropic API 的调用会发送列元数据 + 脱敏样本 + 同级列上下文 —— 不包含原始行数据，也不包含完整结果集。嵌入通过 `fastembed` 在本地生成（BAAI/bge-small-en-v1.5，ONNX，约 67 MB）。
**这像 Cube 或 dbt Semantic Layer 那样是一个语义层吗？**
今天不是 —— Schema Brain 是 schema 智能化（经 LLM 充实的描述 + 对物理 schema 的检索）。智能体看到的是 `schema.table.column`，而不是 `entity.metric`。
语义底座（将诸如 `customer` 的一等实体代替 `public.users`、带有粒度 + 单位的指标、作为版本化定义的规范化 join）将在 v1 中推出。但语义层是**底座**，而不是核心卖点 —— 它是让 v2 SQL 边界安全原语（按 PII 标签拒绝、执行前验证、子查询拒绝）成为可能的基础。如果您已经在使用 dbt 或 Cube，Schema Brain 将在安全层补充它们，而不是在语义层替代它们；如果您没有使用，v1 版本的底座将为您自动生成（由 LLM 建议，用户确认）。
**目前支持哪些数据库？**
Postgres 16+（主要目标）和 SQLite（用于开发和演示）。添加 Snowflake / BigQuery / MySQL 基本上只需要一个新的 `DataSource` 实现加上一个 profiler 调整 —— 已列入 v1 路线图。
**为什么选择 MCP 而不是 REST API？**
消费者是智能体，而不是服务。MCP 标准化了工具注册、schema 描述以及请求/响应传输。智能体（Claude Desktop、Anthropic SDK、自定义智能体）能够原生发现 Schema Brain 并获取四个工具 —— 无需 API 包装器，无需为每种语言维护 SDK。
**为什么使用本地嵌入而不是 OpenAI / Voyage？**
一个 LLM 供应商和一个本地向量模型，比两个 API 供应商更简单。嵌入很少发生变化，模型规模有限（每列一段简短描述），并且笔记本电脑上每次查询约 30 毫秒的嵌入速度已经足够快。本地优先也意味着您可以为私有 schema 建立索引，而无需将其暴露给第二个供应商。
## 贡献
欢迎提交 PR。我们的标准很高 —— 请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md) 以了解测试优先 / 99% 覆盖率 / 约定式提交 / 架构不变量检查清单。CI 会强制执行所有这些要求。
错误和功能请求请使用 `.github/ISSUE_TEMPLATE/` 中的结构化模板。缺少复现步骤（Bug）或未明确底层问题（功能需求）的 Issue 将被关闭，并要求在补充正确信息后重新开启。
## 许可证
[MIT](LICENSE)。
标签：AI代理, AI安全, Anthropic, BigQuery, Chat Copilot, CISA项目, CIS基准, Claude, CNCF毕业项目, CVE检测, DLL 劫持, DLP, MCP, PII, PostgreSQL, Python, RAG, Schema智能, Snowflake, SOC Prime, SQLite, SQL安全, SQL注入防护, 人工智能, 向量检索, 大语言模型, 开发工具, 数据库Schema, 数据库中间件, 数据脱敏, 数据防泄露, 文本嵌入, 无后门, 模型上下文协议, 测试用例, 用户模式Hook绕过, 请求拦截, 边界安全, 逆向工具