Arun-kc/schemabrain

Give them SchemaBrain instead — a read-only trust and intelligence layer where the agent never writes SQL, PII is refused before the query runs, and every call lands in a tamper-evident audit log.
Works with Claude Desktop · Claude Code · Cursor · Windsurf · any MCP host
SchemaBrain compiles every query from definitions you control — no path from a prompt to raw SQL at your database.
Three guarantees that close the trust gap between AI agents and your database:
- **Read-only by architecture** — twelve MCP tools, none of which can write. No execute() tool, no query() tool, no path from agent prompt to a write at your database.
- **PII-aware refusal at retrieval** — PII tags propagate from the physical schema through joins and metrics. If a query touches a blocked category, SchemaBrain refuses before the database is queried.
- **Cryptographic audit chain** — every call, refusal, and recovery is recorded in a SHA256-hashed append-only log (best-effort: a disk-full or no-writer configuration logs a warning and continues rather than failing the query). audit verify exits non-zero if any past row was rewritten.
**See it in action** — ask for something the schema can't answer, and it refuses instead of fabricating a join:
> **You:** *compute usage volume by plan tier*
>
> **SchemaBrain → agent:** { "kind": "unreachable_entity", "recovery": { "suggested_tool": "resolve_join" } } — there's no plan_id on usage events, so it won't invent one.
>
> **Claude:** I can't fake that join — here's **contracted revenue by plan tier** instead, which actually resolves. ✓
→ Full session, with the SQL and results
**Watch it run** — a live Postgres schema becomes a governed knowledge graph, the firewall computes the safe metric and refuses the leaks, and every call lands in a tamper-evident audit log. No agent, no API key:
---
**Cost:** **$0** to run the bundled demo (pre-curated pack, no API key) · ~$0.03 to LLM-index a fresh 84-column schema · **$0** to re-index unchanged schemas. Detail in Sample session.
**Status: 0.6.0 (beta).** Postgres supported today (the local store itself is SQLite). SQLite / Snowflake / BigQuery / MySQL source connectors on the roadmap.
---
Contents
**Read next based on what you need:**
| Goal | Where to go |
|---|---|
| Try it on the bundled fixture | Quickstart |
| Understand the safety guarantees | Safety guarantees |
| Wire up your MCP client | Claude Desktop · Claude Code · Cursor · Windsurf · Cline · ChatGPT (roadmap) |
| Plug into your own agent loop | docs/setup/manual.md |
| Build a semantic layer | docs/semantic-layer.md |
| Run in production (audit, drift, Docker) | docs/operations.md |
| Observe the agent (tail, audit log, OTel) | docs/observability.md |
| Compare with Querybear / Anthropic reference Postgres MCP | vs Querybear · vs Anthropic reference |
| Compare with Vanna / Atlan / dbt-mcp / WrenAI | docs/landscape.md |
---
Quickstart
> **Just want to see what it does?** uvx schemabrain demo — one command, zero prompts. Builds the sample SaaS layer, then lets you open the dashboard or run a terminal firewall showcase. **No API key, and no Docker** for the dashboard / showcase paths. The steps below are for wiring SchemaBrain into your own agent against your own database.
Three steps from uvx schemabrain init to a working Claude Desktop integration. If you paste your own Postgres URL — no Docker needed, ~30s. Press Enter for the bundled demo and init invokes Docker + downloads a ~67 MB embedding model first time; ~45s once cached.
1. Install
Source install (git clone + uv sync --extra dev) is documented in docs/setup.md.
2. Run the activation wizard
init is a seven-stage wizard that takes you from "I have a Postgres database" to "Claude Desktop can answer questions about it" in one command. On first run it prompts for what it needs:
- **A Postgres URL** — paste your own connection string, or press **Enter** to spin up a local demo Postgres container with the bundled SaaS fixture (Docker is invoked automatically; idempotent on re-runs).
- **An ANTHROPIC_API_KEY** — optional. Skip and the wizard still wires Claude Desktop. On the **demo path**, entities + metrics + joins are pre-curated from a bundled YAML pack — the semantic layer works zero-config. On **your own database**, entity curation can run later via schemabrain entities suggest --apply once you have a key.
Full wizard reference (stages explained, flags, dbt auto-detection, --print-only for non-Claude-Desktop hosts, --no-entities / --no-metrics / --no-joins opt-outs, cost-cap pauses): docs/setup.md.