Boyce

Boyce: Semantic Protocol & Safety Layer for Agentic Database Workflows

The semantic safety layer for agentic database workflows.

Boyce connects LLMs to live database context with built-in safety rails.

Named for Raymond F. Boyce, co-inventor of SQL (1974) and co-author of Boyce-Codd Normal Form (BCNF).

AI agents querying databases without proper context generate unreliable SQL — working from incomplete schemas, inferring column names, guessing join paths. Boyce gives agents the structured database intelligence they need to generate correct, safe SQL every time — through three interconnected systems:

Why does this matter? → The Null Trap: Your AI Agent's SQL Is Correct. The Answer Is Still Wrong.

---

Install

Requires Python 3.10+

pip install boyce

With live Postgres/Redshift adapter (enables EXPLAIN pre-flight + column profiling)

pip install "boyce[postgres]"

# uv (recommended)

uv pip install boyce uv pip install "boyce[postgres]"

From source:

git clone https://github.com/boyce-io/boyce

uv pip install -e "boyce/"

---

Quickstart

After installing, run boyce init to configure your MCP host automatically:

boyce init

The wizard detects Claude Desktop, Cursor, Claude Code, and JetBrains (DataGrip, IntelliJ, etc.), and writes the correct config block for each.

Developing from source? The repo includes a setup script:

./quickstart.sh   # detects uv or python, installs package, writes .env template

---

Configure Your MCP Host

The fastest path is boyce init — it detects your MCP host and writes the config automatically:

boyce init

Or configure manually. There are two setup paths depending on your host:

---

Path 1 — MCP Hosts (No LLM key required)

If you're using Claude Desktop, Cursor, Claude Code, Codex, Cline, Windsurf, JetBrains (DataGrip, IntelliJ), or any MCP-compatible host, you do not need to configure an LLM provider for Boyce. The host's own model handles reasoning — Boyce supplies the schema context and deterministic SQL compiler via get_schema and ask_boyce. Only BOYCE_DB_URL is needed (and even that is optional).

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{

"mcpServers": { "boyce": { "command": "boyce", "env": { "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db" } } } }

Cursor (.cursor/mcp.json in project root):

{

"mcpServers": { "boyce": { "command": "boyce", "env": { "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db" } } } }

---

Path 2 — With Boyce's Built-in NL→SQL

If you're using the CLI (boyce ask), HTTP API, or a non-MCP client (e.g., the VS Code extension), configure Boyce's internal query planner with your LLM provider:

{

"mcpServers": { "boyce": { "command": "boyce", "env": { "BOYCE_PROVIDER": "anthropic", "BOYCE_MODEL": "claude-sonnet-4-6", "ANTHROPIC_API_KEY": "sk-ant-...", "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db" } } } }

Boyce supports any LLM provider available through LiteLLM: Anthropic, OpenAI, Ollama (local), vLLM (local), Azure, Bedrock, Vertex, Mistral, and more.

---

BOYCE_DB_URL is optional on both paths. Without it, Boyce runs in schema-only mode — SQL generation still works; EXPLAIN pre-flight and live query tools return "status": "unchecked".

---

Environment Variables

---

MCP Tools

---

Architecture

SemanticSnapshot (JSON)

│ ▼ ingest_source ┌─────────────────────────────────────────────┐ │ SemanticGraph (NetworkX) │ ← in-memory, loaded per session │ nodes = entities (tables/views/dbt models) │ │ edges = joins (weighted by confidence) │ └─────────────────────────────────────────────┘ │ │ ▼ ask_boyce ▼ (internal) QueryPlanner Dijkstra (LiteLLM) join resolver NL → StructuredFilter │ │ │ └──────────┬────────────────┘ ▼ kernel.process_request() ← ZERO LLM HERE SQLBuilder (dialect-aware) │ ▼ EXPLAIN pre-flight ← Query Verification (PostgresAdapter) │ ▼ SQL + validation result

Dialect support: redshift, postgres, duckdb, bigquery

Redshift safety rails (safety.py): Automatic linting for LATERAL, JSONB, REGEXP_COUNT, lookahead regex patterns, and numeric cast rewrites for Redshift 1.0 (PG 8.0.2).

---

Scan CLI

# Scan a single file

boyce scan demo/magic_moment/manifest.json

Scan a directory (auto-detects all parseable sources)

boyce scan ./my-project/ -v

Save snapshots for MCP server use

boyce scan ./my-project/ --save

10 parsers: dbt manifest, dbt project, LookML, SQLite, DDL, CSV, Parquet, Django, SQLAlchemy, Prisma.

---

Verify the Install

# Unit tests — no DB required, runs in ~4 seconds

python boyce/tests/verify_eyes.py

Expected output:

Ran 15 tests in 3.5s

OK

✅ All checks passed.

---

SemanticSnapshot Format

The ingest_source tool accepts a SemanticSnapshot JSON dict. Minimal example:

{

"snapshot_id": " ", "source_system": "dbt", "entities": { "entity:orders": { "id": "entity:orders", "name": "orders", "schema": "public", "fields": ["field:orders:order_id", "field:orders:revenue"] } }, "fields": { "field:orders:order_id": { "id": "field:orders:order_id", "entity_id": "entity:orders", "name": "order_id", "field_type": "ID", "data_type": "INTEGER" } }, "joins": [] }

See boyce/tests/live_fire/mock_snapshot.json for a complete field/entity example.

---

Project Layout

boyce/                          ← PRIMARY — headless FastMCP server + pip package

├── boyce/ │ ├── server.py ← MCP entry point (8 tools) │ ├── kernel.py ← Deterministic SQL kernel │ ├── graph.py ← SemanticGraph (NetworkX) │ ├── safety.py ← Redshift compatibility rails │ ├── types.py ← Protocol contract (Pydantic) │ ├── scan.py ← Scan CLI (boyce scan) │ ├── connections.py ← DSN persistence (ConnectionStore) │ ├── doctor.py ← Environment diagnostics (boyce doctor) │ ├── sql/ ← SQLBuilder, dialect layer, join resolver │ ├── parsers/ ← 10 parsers (dbt, lookml, ddl, sqlite, csv, etc.) │ ├── planner/ ← QueryPlanner (LiteLLM → StructuredFilter) │ └── adapters/ ← PostgresAdapter (Eyes) └── tests/ ├── verify_eyes.py ← 15-test suite, no DB required ├── test_parsers.py ← Parser tests (all 10 parsers) ├── test_scan.py ← Scan CLI tests └── live_fire/ ← Docker Compose integration tests

---

Status

---

Support

• Troubleshooting guide: docs/troubleshooting.md
• Local LLM setup (Ollama/vLLM): docs/local-llm-setup.md
• Bug reports: GitHub Issues
• Setup help: GitHub Issues
• Email: will@convergentmethods.com — for issues involving credentials or sensitive config

---

*Copyright 2026 Convergent Methods, LLC. MIT License.*