schemabrain

Deja de dar a los agentes de IA cadenas de conexión de base de datos en bruto.

Dales SchemaBrain en su lugar: una capa de confianza e inteligencia de solo lectura donde el agente nunca escribe SQL, la PII se rechaza antes de que se ejecute la consulta, y cada llamada queda registrada en un registro de auditoría a prueba de manipulaciones.

Funciona con Claude Desktop · Claude Code · Cursor · Windsurf · cualquier host MCP

SchemaBrain compila cada consulta a partir de definiciones que tú controlas: no hay camino desde un prompt hasta SQL en bruto en tu base de datos.

Tres garantías que cierran la brecha de confianza entre los agentes de IA y tu base de datos:

• Solo lectura por arquitectura — doce herramientas MCP, ninguna de las cuales puede escribir. Sin herramienta execute(), sin herramienta query(), sin camino desde el prompt del agente hasta una escritura en tu base de datos.
• Rechazo consciente de PII en la recuperación — las etiquetas de PII se propagan desde el esquema físico a través de joins y métricas. Si una consulta toca una categoría bloqueada, SchemaBrain la rechaza antes de que se consulte la base de datos.
• Cadena de auditoría criptográfica — cada llamada, rechazo y recuperación se registra en un log de solo añadidura con hash SHA256 (best-effort: una configuración de disco lleno o sin escritor registra una advertencia y continúa en lugar de fallar la consulta). audit verify sale con código distinto de cero si se reescribió alguna fila pasada.

Vélo en acción — pide algo que el esquema no pueda responder, y lo rechaza en lugar de inventar un join:

Tú: calcula el volumen de uso por nivel de plan

SchemaBrain → agente: { "kind": "unreachable_entity", "recovery": { "suggested_tool": "resolve_join" } } — no hay plan_id en los eventos de uso, así que no lo inventará.

Claude: No puedo falsificar ese join — aquí tienes ingresos contratados por nivel de plan en su lugar, que sí se resuelve. ✓

→ Sesión completa, con el SQL y los resultados

Míralo funcionar — un esquema Postgres en vivo se convierte en un grafo de conocimiento gobernado, el firewall calcula la métrica segura y rechaza las fugas, y cada llamada queda en un registro de auditoría a prueba de manipulaciones. Sin agente, sin clave API:

---

uvx schemabrain init
# then: Cmd+Q Claude Desktop, relaunch, and ask: "list the entities SchemaBrain knows about"
# prefer a persistent install? pipx install schemabrain (or) pip install schemabrain

Coste: $0 para ejecutar la demo incluida (paquete pre-curado, sin clave API) · ~$0,03 para indexar con LLM un esquema nuevo de 84 columnas · $0 para reindexar esquemas sin cambios. Detalle en Sesión de ejemplo.

Estado: 0.6.0 (beta). Postgres compatible hoy (el almacén local en sí es SQLite). Conectores de origen SQLite / Snowflake / BigQuery / MySQL en la hoja de ruta.

---

Contenido

Lee a continuación según lo que necesites:

Objetivo	Dónde ir
Pruébalo con el fixture incluido	Inicio rápido
Comprende las garantías de seguridad	Garantías de seguridad
Conecta tu cliente MCP	Claude Desktop · Claude Code · Cursor · Windsurf · Cline · ChatGPT (hoja de ruta)
Conéctalo a tu propio bucle de agente	docs/setup/manual.md
Construye una capa semántica	docs/semantic-layer.md
Ejecútalo en producción (auditoría, drift, Docker)	docs/operations.md
Observa el agente (tail, registro de auditoría, OTel)	docs/observability.md
Compáralo con Querybear / Postgres MCP de referencia de Anthropic	vs Querybear · vs referencia de Anthropic
Compáralo con Vanna / Atlan / dbt-mcp / WrenAI	docs/landscape.md

---

Inicio rápido

¿Solo quieres ver qué hace? uvx schemabrain demo — un comando, cero prompts. Construye la capa SaaS de ejemplo y luego te permite abrir el dashboard o ejecutar una demostración del firewall en terminal. Sin clave API y sin Docker para las rutas de dashboard / demostración. Los pasos siguientes son para conectar SchemaBrain a tu propio agente contra tu propia base de datos.

Tres pasos desde uvx schemabrain init hasta una integración funcional con Claude Desktop. Si pegas tu propia URL de Postgres — sin Docker, ~30s. Pulsa Enter para la demo incluida y init invoca Docker + descarga un modelo de embeddings de ~67 MB la primera vez; ~45s una vez en caché.

1. Instalación

uvx schemabrain init        # zero-install: runs the wizard in one shot
# or install persistently first:
pipx install schemabrain    # (or) pip install schemabrain
schemabrain --version

La instalación desde fuente (git clone + uv sync --extra dev) está documentada en docs/setup.md.

2. Ejecuta el asistente de activación

schemabrain init

init es un asistente de siete etapas que te lleva de «Tengo una base de datos Postgres» a «Claude Desktop puede responder preguntas sobre ella» en un solo comando. En la primera ejecución te pide lo que necesita:

• Una URL de Postgres — pega tu propia cadena de conexión, o pulsa Enter para levantar un contenedor Postgres de demo local con el fixture SaaS incluido (Docker se invoca automáticamente; idempotente en re-ejecuciones).
• Un ANTHROPIC_API_KEY — opcional. Omítelo y el asistente igualmente conecta Claude Desktop. En la ruta de demo, entidades + métricas + joins están pre-curados desde un paquete YAML incluido — la capa semántica funciona con configuración cero. En tu propia base de datos, la curación de entidades puede ejecutarse más tarde mediante schemabrain entities suggest --apply una vez que tengas una clave.

SchemaBrain init — activation wizard

  [1/7] Source check       ✓ source reachable + read-only
  [2/7] Index schema       ✓ 12 tables, 84 columns indexed
  [3/7] Curate entities    ✓ 12 entities applied (bundled demo pack)
  [4/7] Curate metrics     ✓ 5 metrics applied (bundled demo pack)
  [5/7] Curate joins       ✓ 11 canonical joins applied (bundled demo pack)
  [6/7] Wire host          ✓ wrote schemabrain entry to claude_desktop_config.json
                           (default; switch with --host claude-code|cursor|windsurf|manual)
  [7/7] Next               ✓ restart your MCP host, then ask: "list the entities SchemaBrain knows about"

Referencia completa del asistente (etapas explicadas, flags, auto-detección de dbt, --print-only para hosts que no son Claude Desktop, exclusiones de --no-entities / --no-metrics / --no-joins, pausas por límite de coste): docs/setup.md.

3. Reinicia Claude Desktop y pregunta

1. Sal de Claude Desktop por completo — Cmd+Q, no solo cierres la ventana. La configuración MCP solo se lee en el arranque en frío.

2. Vuelve a abrirlo.

3. Nueva conversación:

   lista las entidades que SchemaBrain conoce

Si Claude llama a list_entities e informa de user, order, etc., has terminado. Si no, consulta Solución de problemas.

Después del asistente, schemabrain inspect muestra lo que tiene el agente y schemabrain tail transmite cada llamada de herramienta en vivo — consulta docs/operations.md.

Tus archivos de proyecto

init escribe solo ./schemabrain.db (el almacén local — añádelo a gitignore) más la configuración de tu host. Para ajustar la política de PII y la capa semántica como YAML editable, vuelve a ejecutar con --emit-yaml-dir:

schemabrain init --url-env DATABASE_URL --emit-yaml-dir ./schemabrain
# → ./schemabrain/pii_policy.yaml + entities/ + metrics/ + joins/

Edita un archivo, schemabrain apply ./schemabrain, schemabrain check para validar, reinicia serve. No hay schemabrain.yaml — la configuración son flags de CLI + variables de entorno SCHEMABRAIN_* (auto-cargadas desde .env) + ese árbol YAML. Mapa completo: Tu proyecto.

---

Garantías de seguridad

Seis propiedades que SchemaBrain aplica hoy en el límite SQL:

1. Solo lectura por arquitectura, no por configuración

La superficie MCP expone doce herramientas — ninguna de las cuales puede escribir. Sin execute(), sin query(), sin camino desde el prompt del agente hasta una escritura en tu base de datos, independientemente del estado de la sesión — la garantía es estructural, no un flag que el agente pueda cambiar. schemabrain serve también fija default_transaction_read_only=on como cinturón y tirantes. Solo lectura por arquitectura →

2. Rechazo consciente de PII en el límite de la herramienta get_metric

Cualquier get_metric que toque una categoría de PII bloqueada devuelve un sobre refused — el SQL compilado nunca se ejecuta y el rechazo queda en mcp_audit. describe_entity aplica lo mismo a nivel de columna (las columnas bloqueadas envían redacted=True). init bloquea el conjunto de fugas catastróficas por defecto (credential,payment_card,government_id); --pii-block reemplaza el conjunto, así que amplíalo listando el objetivo completo. La detección es coincidencia de patrones en nombres de columna en doce categorías GDPR / CCPA / HIPAA / PCI; la clasificación consciente del contenido está en la hoja de ruta. Taxonomía y propagación de PII →

3. Registro de auditoría a prueba de manipulaciones

Cada llamada de herramienta escribe una fila en una tabla mcp_audit de solo añadidura — categorías de PII, huellas direccionables por contenido, cadena de hash sha256. audit verify recorre la cadena de nuevo y sale con código distinto de cero si se reescribió alguna fila pasada.

schemabrain audit verify   # exit 0 = chain clean

Cadena de auditoría a prueba de manipulaciones →

4. El fallo es un contrato, no una cadena

Cada llamada que no tiene éxito — rechazada, error o degradada — devuelve un bloque estructurado recovery.suggested_args, no un mensaje que parsear. Los bloqueos de PII (status: "refused") envían la entidad para reintentar; las dimensiones ambiguas y las entidades inalcanzables (status: "error") envían el candidato a elegir o la siguiente herramienta a llamar. Solo los rechazos de política son refused; «No voy a adivinar» es error con un payload de recuperación.

{ "status": "error", "kind": "ambiguous_time_dimension",
  "recovery": { "suggested_tool": "get_metric",
                "suggested_args": {"time_dimension": "order.placed_at"} } }

Recuperación estructurada →

5. Ruta de compilación: definiciones → SQL parametrizado

Las entidades, métricas y joins canónicos se compilan a SQL parametrizado que SchemaBrain ejecuta de su lado. El agente ve filas + el SQL que se ejecutó — nunca sentencias arbitrarias en tu base de datos. Las definiciones sugeridas por LLM durante init se revisan y aplican explícitamente. Construye tu capa semántica →

6. Conectable a cualquier bucle de agente

La misma superficie MCP stdio que ve Claude Desktop se expone a cualquier host MCP — incluido tu propio bucle de Anthropic, OpenAI o LangGraph. examples/anthropic_demo.py es un drop-in de ~260 LOC que conecta Claude Haiku 4.5 a schemabrain serve e imprime exactamente qué herramientas eligió el agente. Recorrido por el SDK de Anthropic →

---

Dashboard de observabilidad

SchemaBrain incluye un dashboard opcional de solo lectura sobre los mismos datos de auditoría + PII + rechazos que el servidor MCP ya está escribiendo. schemabrain dashboard arranca un sidecar local de FastAPI que sirve una UI estática pre-construida — sin runtime de Node, sin exposición de red, sin rutas de escritura.

pip install "schemabrain[ui]"
schemabrain dashboard
# → http://127.0.0.1:7878

Es un visor, no una consola — sin ajustes, sin pad de SQL, sin ruta de escritura. Nueve superficies de solo lectura, cada una respondiendo a una pregunta del operador que el sobre MCP por sí solo nunca muestra visualmente. La superficie insignia es el Grafo de Conocimiento — tu esquema renderizado como la misma proyección de entidad-relación contra la que la capa semántica compila los joins:

• Knowledge Graph (/graph) — ¿cómo se conecta realmente mi esquema? Entidades como nodos, uniones canónicas como aristas (sólidas para FKs declaradas, discontinuas para las extraídas de logs), entidades con PII marcadas y puntos críticos de rechazo resaltados, con la cardinalidad de las FKs declaradas mostrada en la ruta de unión resaltada — el esquema como un grafo, no como una lista de tablas.
• Overview (/overview) — la superficie de inicio: recuentos de entidades / métricas / uniones / PII catastrófica de un vistazo.
• Entities (/entities) — un índice ordenable; profundiza en las columnas, PII, métricas y uniones canónicas de cualquier entidad.
• Data Dictionary (/dict) — cada tabla, columna, tipo, clase de PII, unión y métrica, con exportación a Markdown con un clic (el mismo artefacto que escribe schemabrain docs).
• PII matrix (/pii) — ¿qué columnas contienen datos sensibles? Un mapa de calor con una fila por columna clasificada y una celda por categoría de PII, cada columna etiquetada como bloquear / redactar / permitir según su banda de asesoramiento. Las columnas en una categoría de fuga catastrófica (credential, payment_card, government_id) están bloqueadas de forma permanente independientemente de la política y fijadas en la parte superior — para que detectes una columna payment_card escondida dentro de users antes de apuntar un agente a un esquema nuevo, y veas de un vistazo qué activa la política predeterminada de --pii-block. Selecciona cualquier fila para profundizar en las columnas, métricas y uniones de su entidad.
• Refusals (/refusals) — ¿qué bloqueó SchemaBrain y qué vio el agente? Un feed cronológico de llamadas retenidas; expande cualquier fila para revelar el sobre completo en línea — el motivo que se activó (pii_blocked, allowlist_violation, fragment_unsafe, cost_cap_exceeded, ambiguous_resolution, schema_drift), el conjunto exacto de categorías que se cruzó con la política, y el error.recovery estructurado (herramienta sugerida + argumentos) que el agente recibió para recuperarse. Úsalo para evaluar "el agente dice que no puede acceder a eso" y para revisar si esas pistas realmente ayudaron.
• Audit Viewer (/audit) — ¿sigue intacta la cadena de auditoría? La cara visual del registro a prueba de manipulaciones: cada llamada de herramienta escribe exactamente una fila — sea cual sea el resultado — anclada por chain_hash = sha256(prev_hash || canonical(row)). Una franja de integridad lee not verified this session hasta que ejecutas una pasada, luego verified · n/N intact (o marca N rows edited after write); el botón Verify recorre la cadena de nuevo en el servidor y recalcula la prueba de inclusión Merkle RFC-6962 de cada fila visible en tu navegador. Seleccionar una fila abre el cuerpo completo (herramienta, estado, clase de costo, categorías de PII, huella digital, chain_hash y la escalera de pruebas hasta la raíz). Recarga para recoger nuevas llamadas.
• Policy (/policy) — la cuadrícula de bloquear / redactar / permitir que aplica el firewall, con el piso de fuga catastrófica siempre activo divulgado (no se puede eliminar). Los cambios se realizan mediante acciones de copiar-el-CLI — el panel nunca escribe.
• Drift (/drift) — desviación de configuración y enriquecimiento que el almacén puede detectar, cada una con una corrección de copiar-el-CLI.

Knowledge Graph — tu esquema como la proyección de entidad-relación contra la que la capa semántica compila uniones; entidades con PII catastrófica marcadas, la ruta de unión canónica trazada.

Más vistas del panel — Overview, PII matrix, Refusals, Audit, Entities, Data Dictionary, Policy & Drift

Overview — todo el límite en una pantalla: qué está vinculado, qué está protegido, qué se ha desviado.

PII matrix — qué columnas contienen datos sensibles y qué bloquea la política predeterminada.

Refusals — cada llamada bloqueada, el motivo que se activó y la pista de recuperación que recibió el agente.

Audit Viewer — la cadena a prueba de manipulaciones, verificada en el servidor hasta el enlace de hash de cada fila.

Entities — cada entidad de negocio vinculada desde el esquema crudo, con exposición de PII y recuentos de uniones.

Data Dictionary — cada tabla, columna, tipo y unión, exportable a Markdown para tu repositorio o wiki.

Policy — la cuadrícula de bloquear / redactar / permitir que aplica el firewall, con el piso siempre activo divulgado.

Drift — desviación de configuración y enriquecimiento que el almacén puede detectar, cada una con una corrección de copiar-el-CLI.

El panel vincula solo 127.0.0.1 — no hay una bandera --host, por diseño. Es de solo lectura y lee el mismo almacén SQLite al que escribe serve. Ningún agente habla con él.

Dashboard guide → · PII matrix → · Refusals → · Audit Viewer →

---

Funciona con

SchemaBrain habla el Model Context Protocol sobre stdio. schemabrain init --host <X> escribe configuración de primera parte para cuatro clientes MCP; todo lo demás que hable MCP stdio funciona a través de --host manual (imprime el fragmento, tú lo pegas).

Cableado de primera parte

schemabrain init --host <X> escribe la entrada MCP directamente en el archivo de configuración del host.

Cliente	Guía de configuración	Ruta de configuración
Claude Desktop	/setup/claude-desktop	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json
Claude Code	/setup/claude-code	Ejecuta claude mcp add
Cursor	/setup/cursor	~/.cursor/mcp.json
Windsurf	/setup/windsurf	~/.codeium/windsurf/mcp_config.json

Cualquier otro host MCP stdio

schemabrain init --host manual imprime la entrada JSON en stdout — pégala en la configuración del host que estés usando. Cualquier cliente que inicie un subproceso y hable MCP stdio debería funcionar en principio; no hemos probado exhaustivamente cada uno. Destinos comunes:

• Zed — tutorial completo en docs/setup/zed.md
• Codex CLI (ruta funcional para usuarios de ChatGPT) — tutorial completo en docs/setup/codex.md
• Cline (extensión de VS Code) — schemabrain init --host manual imprime el bloque mcpServers; pégalo en la configuración de Cline a través de MCP Servers → Configure MCP Servers. Tutorial completo en docs/setup/cline.md
• Continue — pega en ~/.continue/config.json
• Tu propio bucle de agente — consulta examples/anthropic_demo.py para una referencia de ~250 líneas del SDK de Anthropic

La superficie de 12 herramientas, el rechazo consciente de PII, la cadena de auditoría y los contratos de recuperación son independientes del transporte — cualquier cliente MCP stdio compatible obtiene las mismas garantías.

Marcos de agentes

La misma superficie MCP stdio es accesible desde cualquier marco que pueda generar un servidor MCP. La ruta del SDK de Anthropic está probada de primera parte; los demás funcionan en principio si la integración MCP del marco habla stdio.

• Anthropic SDK — tutorial de primera parte en docs/setup/manual.md; bucle de referencia en examples/anthropic_demo.py
• LangChain / LangGraph — a través de langchain-mcp-adapters
• Pydantic AI — a través de su soporte MCP integrado
• CrewAI / AutoGen / Agno / bucles personalizados — cualquier marco con un cliente MCP stdio funciona en principio; no hemos probado cada uno

No enviamos adaptadores por marco; el cliente MCP estándar del marco es suficiente.

Aún no compatible (hosts de nube / HTTPS)

SchemaBrain v0.6 incluye solo stdio — sin transporte HTTPS / SSE. Los clientes que requieren un endpoint HTTPS en la nube no funcionan hoy:

• ChatGPT Connectors — consulta la página de brecha honesta para soluciones alternativas y la hoja de ruta v0.5+
• Puertas de enlace MCP alojadas — por diseño (cuña local-primero; consulta vs Querybear)

Si necesitas soporte de ChatGPT hoy, un puente comunitario stdio→HTTPS (mcp-remote, mcp-proxy, etc.) puede funcionar; no hemos validado ningún puente específico contra las semánticas de PII / auditoría / recuperación.

Postura de seguridad para adquisiciones / revisión →

---

Sesión de muestra

Sesión real de Claude Desktop contra el fixture SaaS incluido (12 tablas, 84 columnas, 12 entidades). Condensada por longitud — un agente real explora list_metrics / suggest_joins primero, luego concluye que la ruta es inalcanzable:

Tú: Usando SchemaBrain, calcula nuestro volumen de uso desglosado por nivel de plan.

Claude: (llama a get_metric(name="usage_volume", group_by=["plan.title"]). La métrica se ancla en usage_event; llegar a plan requeriría una unión que no está en el esquema, por lo que se niega:)

{ "status": "error",
  "error": {
    "kind": "unreachable_entity",
    "message": "entity 'plan' is not reachable from metric anchor 'usage_event'; no canonical join exists. Run `schemabrain joins suggest` to surface candidate joins.",
    "recovery": { "suggested_tool": "resolve_join",
                  "suggested_args": { "entity_a": "usage_event", "entity_b": "plan" } } } }

(Claude confirma en la capa de uniones — resolve_join("usage_event", "plan") devuelve kind: no_canonical_join. usage_events lleva solo workspace_id, nunca un plan_id, y ninguna tabla conecta los dos.)

Veredicto desde el principio: no puedo calcular uso-por-plan, y no deberías querer que lo invente — no hay una relación modelada entre eventos de uso y planes en este esquema. usage_events registra un workspace_id, no un plan, y nada une los dos. "Volumen de uso por nivel de plan" no se puede responder hasta que ese vínculo exista — y no voy a inventarlo.

Lo que sí puedo darte — ingresos contratados por nivel de plan (esta ruta se resuelve completamente: subscription_item → subscription → plan, ambas uniones fk_constraint, confidence: HIGH):

SELECT p.title                                     AS plan_tier,
       SUM(si.unit_price_cents * si.seats) / 100.0  AS revenue   -- prices stored in integer cents
FROM   public.subscription_items si
JOIN   public.subscriptions      s ON si.subscription_id = s.id
JOIN   public.plans              p ON s.plan_id          = p.id
GROUP BY p.title
ORDER BY revenue DESC;

plan_tier	revenue
Enterprise	$379,620.00
Pro	$539.00
Free	$54.00

Dos advertencias honestas:

• Contratado, no cobrado. Esto es ingreso por partidas de suscripción (seats × unit_price_cents), no facturas pagadas. Para totales facturados, la métrica total_revenue se ancla en invoices en su lugar.
• Centavos enteros. unit_price_cents se almacena como un entero; el / 100.0 convierte a moneda.

El diferenciador es lo que no sucedió: la mayoría de las herramientas LLM-sobre-bases-de-datos, al pedirles uso-por-plan, emitirían con confianza JOIN plans p ON usage_events.plan_id = p.id contra una columna plan_id que no existe. SchemaBrain se negó — get_metric devolvió kind: unreachable_entity con recovery.suggested_tool: resolve_join, no prosa. El agente actuó sobre el contrato de recuperación estructurado programáticamente en lugar de fabricar una unión. Rechazo-no-fabricación es el mecanismo de seguridad, demostrado en vivo. Costo. ~$0.0004/columna con Claude Haiku 4.5 (las columnas con nombres crípticos pueden optar por Sonnet 4.6 vía --enable-sonnet). El fixture incluido de 12 tablas (84 columnas, 12 entidades + 5 métricas + 11 joins) viene pre-curado, por lo que la ruta de demostración lo aplica por $0 — sin clave API. Indexar esas 84 columnas con descripciones de columnas LLM cuesta alrededor de $0.03. La muestra de alquiler de DVD de Pagila (87 columnas después de la deduplicación de particiones) es la referencia medida directamente — $0.0299 en 105s. Re-indexar un esquema sin cambios es $0 — el fingerprinting direccionable por contenido omite la llamada LLM por completo.

Para verificar que el SQL de Claude es mecánicamente correcto (y que las advertencias marcadas son el comportamiento real de los datos), consulta Validando SQL que Claude genera.

Ejecuta esta sesión exacta tú mismo: schemabrain init te lleva a un Claude Desktop conectado en un solo comando; luego pídele a Claude "Usando SchemaBrain, calcula nuestro volumen de uso desglosado por nivel de plan." y observa el rechazo-y-luego-pivote en vivo.

---

Hacia dónde va

SchemaBrain está evolucionando hacia una capa de confianza e inteligencia entre agentes de IA y tu base de datos — le da al agente un mapa semántico de tu esquema, compila respuestas a partir de definiciones que tú controlas, y mantiene cada llamada consciente de PII y auditada. La seguridad en el límite SQL es un punto de prueba de esa capa, no toda su identidad.

Esa postura se apoya en un sustrato semántico. No puedes rechazar "esta consulta toca PII" sin saber qué columnas son PII. No puedes responder "une a través de esta unión" sin definiciones de joins canónicos. No puedes servir una métrica sin conocer su granularidad.

Así que el orden de ingeniería es inteligencia de esquema → sustrato semántico → primitivas de confianza. Hoy el agente nunca escribe SQL crudo: llama a get_metric y a las herramientas de la capa semántica, SchemaBrain compila SQL parametrizado que el agente nunca ve, y obtienes rechazo consciente de PII, recuperación estructurada en cada llamada rechazada o degradada, ejecución de solo lectura con timeouts de declaración y límites de filas, y una cadena de auditoría a prueba de manipulaciones. Esa postura impulsada por definiciones y SQL compilado es la predeterminada y la recomendada. Inspeccionar SQL arbitrario emitido por agentes (validate_query / execute) es una vía posterior, opcional y de aceptación explícita — no la dirección hacia la que estamos pivotando. Consulta la Hoja de ruta.

---

Hoja de ruta

Las etiquetas v0.5 / v1 / v2 / v3 son nombres de hitos de la hoja de ruta, no versiones de paquetes. El paquete sigue semver estricto — 1.0.0 está reservado para una API que ha sido probada en batalla por usuarios externos sin una ruptura forzada. Consulta ADR-0003.

La hoja de ruta completa y viva — incluidos los no-objetivos explícitos y cómo influir en las prioridades — vive en ROADMAP.md.

Ahora — enviando en v0.6.x

Lo que obtienes de pip install schemabrain:

• Servidor MCP, 12 herramientas de solo lectura — find_relevant_tables, find_relevant_entities, describe_table, describe_column, describe_entity, list_entities, list_metrics, list_joins, suggest_joins, resolve_join, get_example_queries, get_metric.
• Compilación impulsada por definiciones — el agente nunca escribe SQL crudo; las respuestas se compilan a partir de definiciones que tú controlas, con ejecución de solo lectura aplicada en la capa de base de datos más timeouts de declaración y límites de filas.
• Motor de inteligencia de esquema — indexa Postgres en un almacén SQLite local; enriquecimiento semántico LLM con límite de costo (con enrutamiento Sonnet opcional para columnas crípticas, --enable-sonnet); embeddings en el dispositivo (BAAI/bge-small ONNX); recuperación semántica de tablas (similitud coseno sobre esos embeddings, clasificadas por tabla según la columna de mejor coincidencia); identificación de entidades con justificación + confianza; minería de joins declarados-FK, registros de consultas y dbt-relationships; un grafo de joins canónicos persistido con BFS multi-salto; y una capa de métricas.
• Confianza y seguridad — clasificación de PII (60 reglas en 12 categorías) con confianza por columna, propagación de etiquetas, un piso de fuga catastrófica (agrupar por una columna PII se rechaza como divulgación a nivel de fila), una política editable (bloquear / redactar / permitir más anulaciones por columna), y un registro de auditoría encadenado por hash sha256 a prueba de manipulaciones con pruebas Merkle RFC-6962 verificables en navegador y audit verify.
• Panel liderado por grafos, 9 superficies — un Grafo de Conocimiento interactivo característico, más Resumen, Entidades (índice ordenable + desglose con panel semántico), Diccionario de Datos (Exportar a Markdown), matriz de PII, Rechazos, Visor de Auditoría, un editor de Política editable, e inteligencia de Deriva. Doble tema, opcional, solo lectura, solo 127.0.0.1.
• CLI — init, demo, index, import dbt, inspect, diff, check, entities, joins, metrics, policy {show, apply, tag}, docs, dashboard, doctor, serve, audit. Distribuido en PyPI (licencia Apache-2.0) y como imagen Docker sin cabeza.

Después — hoja de ruta (diferido; solo dirección futura)

Fase 2 — diferenciadores

• Estimación de costo de consultas (EXPLAIN del SQL compilado)
• Detección de aislamiento de inquilinos — verificaciones de filtro faltante y joins entre inquilinos
• Análisis de impacto en todas las definiciones
• Inteligencia de uso — detección de puntos calientes y tablas muertas
• Una gramática general de reglas de política
• Descubrimiento de FK implícitos sin registros de consultas
• Presupuesto de contexto para respuestas de herramientas

Fase 3 — exploratorio

• Memoria persistente del agente
• Coordinación multi-agente
• Transporte MCP remoto más un SDK de cliente ligero
• Una vía opcional y de aceptación explícita de SQL escrito por agentes (validate_query / execute) detrás de una bandera explícita. El SQL compilado impulsado por definiciones sigue siendo la postura predeterminada y recomendada; esta vía es para equipos que quieren análisis-antes-de-ejecución sobre SQL arbitrario emitido por agentes, si llegara a ocurrir. No está enviada, y no es un pivote planificado lejos del predeterminado impulsado por definiciones.

Todo en esta hoja de ruta es de código abierto.

---

Solución de problemas

Los cinco fallos más comunes en el primer uso. Solucionador completo en docs/setup/manual.md.

• pip install schemabrain me dio una versión anterior. Verifica schemabrain --version. Si no coincide con la última versión, tu caché de pip está obsoleta — ejecuta pip install --upgrade schemabrain. schemabrain init escribe la misma versión en el fragmento de Claude Desktop para que siga siendo reproducible entre reinicios. Cuando instalaste desde PyPI y uv está en tu PATH, el fragmento ejecuta uvx schemabrain==<pin> (aumenta el pin manualmente después de una actualización de pip); de lo contrario — una instalación no-PyPI (wheel local, editable o checkout de git) o sin uvx — fija la ruta absoluta del punto de entrada instalado de schemabrain, que sigue el entorno desde el que ejecutaste init.
• init informa source unreachable. Postgres puede no estar listo en el primer uso — espera unos segundos y vuelve a ejecutar. Para tu propia base de datos, verifica host, puerto y credenciales. Se aceptan URLs de conexión en cualquier forma (postgresql://, postgres://, postgresql+psycopg://).
• El primer init o schemabrain index se cuelga durante ~60 segundos. Normal. El primer índice descarga el modelo de embeddings ONNX (~67 MB) y hace una llamada LLM por columna. Las ejecuciones posteriores son rápidas.
• init falla en la etapa 6 "conectar host". Claude Desktop debe estar instalado primero — SchemaBrain escribe en su archivo de configuración, que no existe hasta que Claude Desktop se haya lanzado al menos una vez.
• Claude Desktop no muestra SchemaBrain después de reiniciar. Se requiere Cmd+Q (cerrar ventana no dispara una relectura de la configuración MCP). Ejecuta schemabrain doctor para verificar que la configuración llegó. Si doctor dice que todo está bien pero Claude Desktop aún no ve la herramienta, verifica ~/Library/Logs/Claude/mcp*.log.
• Apple Silicon + Python 3.12. La dependencia onnxruntime de fastembed no incluye wheel arm64 para Python 3.12+, por lo que los embeddings no pueden compilarse. init detecta esto en la verificación previa y te dice que uses Python 3.11 (por ejemplo, pyenv local 3.11.10) o que vuelvas a ejecutar con --no-embed (búsqueda por palabras clave en lugar de semántica — todo lo demás funciona).

---

Documentación

Doc	Qué contiene
docs/setup.md	Asistente de activación (recomendado) — elige un host, ejecuta el asistente, pregunta al agente (~60s)
docs/setup/docker.md	Instalación Docker (imagen con modelo de embeddings incluido, sin descarga en el primer uso)
docs/setup/manual.md	index manual, minería de consultas, configuración de registros, solución de problemas, MCP Inspector, escalera de validación SQL
docs/first-5-queries.md	Qué hacer realmente después de init — cinco consultas que ejercitan solo lectura, rechazo consciente de PII, cadena de auditoría y recuperación estructurada
docs/semantic-layer.md	Construcción de entidades, métricas (incluidas expresiones compuestas), joins canónicos (incluido multi-salto), importación dbt
docs/operations.md	inspect, check (deriva), index --dry-run, Docker compose
docs/observability.md	tail, registro de auditoría, exportación OTel, clasificación de PII
docs/reference/mcp-tools/overview.mdx	Referencia completa para las 12 herramientas MCP (resumen + 12 páginas por herramienta)
docs/architecture.mdx	Pipeline, contrato de recuperación, lógica de caché, modelo de costo, evaluación
docs/dashboard/overview.mdx	Panel de observabilidad de solo lectura — matriz de PII, rechazos, visor de auditoría
docs/landscape.md	Comparación vs Vanna / Atlan / dbt-mcp / WrenAI; "¿es esto una capa semántica?"
docs/threat-model.md	Modelo de seguridad + límites
docs/adr/	Registros de decisiones de arquitectura (taxonomía de auditoría/PII, protocolo de almacenamiento, política de versionado, bus de observabilidad)
examples/	Configuraciones MCP listas para copiar y pegar, bucle de agente sin cabeza, recorrido completo de comercio electrónico de extremo a extremo

---

Preguntas frecuentes

¿Mis datos salen de mi máquina? Solo las descripciones de columnas enriquecidas por LLM y los valores de muestra redactados que las alimentan. Tres pasadas de regex (correo electrónico, SSN de EE. UU., secuencias de dígitos con forma de tarjeta de crédito) se ejecutan en cada muestra antes de que salga del módulo de perfilado — consulta schemabrain/profiler/stats.py. La llamada a la API de Anthropic envía metadatos de columnas + muestras redactadas + contexto de columnas hermanas — sin filas crudas. Los embeddings se generan localmente vía fastembed (BAAI/bge-small-en-v1.5, ONNX, ~67 MB).

¿Qué bases de datos funcionan hoy? Postgres 16+ es el único conector fuente hoy (el almacén local en sí es un archivo SQLite). Un conector fuente SQLite, más Snowflake / BigQuery / MySQL, es principalmente una nueva implementación de DataSource más un ajuste del perfilador — en la hoja de ruta v1.x.

¿Por qué MCP y no una API REST? El consumidor es un agente, no un servicio. MCP estandariza el registro de herramientas, la descripción de esquemas y el transporte de solicitud/respuesta. Los agentes descubren SchemaBrain de forma nativa y obtienen su superficie de herramientas — sin envoltorio API, sin SDK que mantener por idioma.

¿Es esto una capa semántica como Cube o dbt Semantic Layer? No exactamente — SchemaBrain es la capa de confianza e inteligencia entre agentes de IA y tu base de datos, construida sobre un sustrato de capa semántica. Entidades, métricas y joins canónicos son definiciones persistidas de primera clase (list_entities, describe_entity, resolve_join, get_metric), y hacen posibles las primitivas de seguridad — solo lectura por arquitectura, rechazo consciente de PII, cadena de auditoría. El sustrato semántico es la base; la seguridad en el límite SQL, incluido el firewall, es un punto de prueba de la capa, no toda su identidad. Comparación completa vs Cube / dbt-mcp / Vanna / WrenAI en docs/landscape.md.

Más preguntas respondidas en docs/setup/manual.md (por qué embeddings locales, más solución de problemas).

---

¿Ejecutándolo en tu propio Postgres?

Si estás apuntando agentes de IA a un Postgres real (no de demostración), me gustaría mucho saber cómo te va: qué funcionó, qué falló, qué se sintió bien o mal. Abre una Discusión de GitHub o un issue de GitHub, o contáctame en GitHub (@Arun-kc). Estaré encantado de ayudarte a configurarlo.

---

Colaboradores

---

Contribución y Licencia

Se aceptan PRs. El listón es alto: consulta CONTRIBUTING.md para la lista de verificación de test-first / cobertura del 99% / conventional-commits / invariantes de arquitectura. CI lo hace cumplir todo.

Los errores y solicitudes de funciones usan las plantillas estructuradas en .github/ISSUE_TEMPLATE/. Los issues sin reproducción (errores) o sin un problema subyacente claro (funciones) se cierran con una solicitud de reapertura con la información correcta.

Apache 2.0.