# Boyce

> AI agents querying databases without Boyce generate SQL that looks correct and returns wrong answers. A naive equality filter on a column with 30% NULLs silently drops those rows — no error, no warning, just missing data. Boyce catches this before the query runs.

Boyce is an MCP server exposing 8 tools. Deterministic SQL compiler — same inputs produce identical SQL, byte-for-byte, every time. Zero LLM calls in the SQL compiler. MIT licensed. Python 3.10+.

## Install

```
pip install boyce
pip install "boyce[postgres]"  # adds asyncpg for live DB adapter
```

## Quick Start

Run `boyce init` to auto-detect your MCP host and write the config. Supported hosts: Claude Code, Cursor, VS Code, Codex, DataGrip/JetBrains, Claude Desktop, Windsurf. No Boyce API key needed for MCP hosts.

## MCP Configuration

Add `boyce` to your mcpServers config. Set `BOYCE_DB_URL` to your PostgreSQL DSN (optional — omit for schema-only mode; EXPLAIN pre-flight returns `"unchecked"` without it).

MCP hosts do not need a Boyce API key or any credentials. The host LLM calls `get_schema`, constructs a StructuredFilter, and passes it to `ask_boyce` for deterministic compilation. `BOYCE_PROVIDER` + `BOYCE_MODEL` are only required for the CLI (`boyce ask`) and HTTP API (`boyce serve --http`).

## MCP Tools

- `ingest_source`: Teach Boyce about a database — accepts 10+ formats (DDL, dbt, LookML, SQLite, Django, SQLAlchemy, Prisma, CSV, Parquet, live PostgreSQL DSN), auto-detected
- `ingest_definition`: Store certified business definitions — injected automatically at query time
- `get_schema`: See what the database actually contains before writing a query — tables, columns, nullable flags, join confidence weights
- `ask_boyce`: Answer data questions with SQL safety-checked against actual data — NULL trap detection, EXPLAIN pre-flight, dialect compatibility on every call
- `validate_sql`: Check SQL against data reality before running it — catches NULL traps, broken execution plans, Redshift dialect traps without executing
- `query_database`: Run SQL against the live database — read-only, with NULL risk scan and EXPLAIN pre-flight on every query
- `profile_data`: See how a column actually behaves — null rate, distinct count, min/max
- `check_health`: Operational health check — DB connectivity, snapshot freshness, actionable fix commands. Call when queries fail unexpectedly.

## Response Format

Every successful tool response includes behavioral fields before the data payload:
- `next_step` (always present): Directive language — the exact next tool and action to take
- `present_to_user` (only when material): Loss-framed finding when something will corrupt results — e.g., "30% of rows excluded by NULL filter." Not present on clean queries.
- `data_reality` (only when relevant): Column insights from snapshot metadata for columns the query touched in WHERE, GROUP BY, or JOIN ON. Facts the model could not have known from schema alone.

## Recommended Workflow

`ingest_source` → `get_schema` → `ask_boyce` (compile SQL) → `query_database` (execute)

Use `profile_data` before filtering or joining on any column whose NULL distribution is unknown.

## Supported Databases

Redshift, Postgres, DuckDB, BigQuery

## Key Facts

- Python 3.10+ required, MIT licensed
- 10 source parsers with auto-detection via `boyce scan`
- Setup wizard: `boyce init` (detects Claude Code, Cursor, VS Code, Codex, DataGrip, Claude Desktop, Windsurf)
- MCP hosts do NOT need an API key

## Detailed Reference

- Full agent docs: https://convergentmethods.com/boyce/llms-full.txt
- The Null Trap (essay): https://convergentmethods.com/boyce/null-trap/
- GitHub: https://github.com/boyce-io/boyce
- PyPI: https://pypi.org/project/boyce/