{
  "markdown": "# Boyce: Semantic Protocol & Safety Layer for Agentic Database Workflows\n\n<!-- mcp-name: io.github.boyce-io/boyce -->\n\n> **The semantic safety layer for agentic database workflows.**\n> Boyce connects LLMs to live database context with built-in safety rails.\n\nNamed for [Raymond F. Boyce](https://en.wikipedia.org/wiki/Raymond_F._Boyce), co-inventor of SQL (1974) and co-author of Boyce-Codd Normal Form (BCNF).\n\nAI 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:\n\n| Layer | What it does |\n|---|---|\n| **SQL Compiler** | `ask_boyce` — NL → StructuredFilter → deterministic SQL. Zero LLM in the SQL builder. Same inputs, same SQL, byte-for-byte, every time. |\n| **Database Inspector** | `query_database` / `profile_data` — Live Postgres/Redshift adapters let your agent see real schema and real data distributions before writing a single filter. |\n| **Query Verification** | Pre-flight `EXPLAIN` loops on every generated query. Bad SQL is caught at planning time, not at 2am in your on-call rotation. |\n\n**Why does this matter?** → [The Null Trap: Your AI Agent's SQL Is Correct. The Answer Is Still Wrong.](https://convergentmethods.com/boyce/null-trap/)\n\n---\n\n## Install\n\n**Requires Python 3.10+**\n\n```bash\npip install boyce\n\n# With live Postgres/Redshift adapter (enables EXPLAIN pre-flight + column profiling)\npip install \"boyce[postgres]\"\n```\n\n```bash\n# uv (recommended)\nuv pip install boyce\nuv pip install \"boyce[postgres]\"\n```\n\n**From source:**\n```bash\ngit clone https://github.com/boyce-io/boyce\nuv pip install -e \"boyce/\"\n```\n\n---\n\n## Quickstart\n\nAfter installing, run `boyce init` to configure your MCP host automatically:\n\n```bash\nboyce init\n```\n\nThe wizard detects Claude Desktop, Cursor, Claude Code, and JetBrains (DataGrip, IntelliJ, etc.), and writes the correct config block for each.\n\n**Developing from source?** The repo includes a setup script:\n\n```bash\n./quickstart.sh   # detects uv or python, installs package, writes .env template\n```\n\n---\n\n## Configure Your MCP Host\n\nThe fastest path is `boyce init` — it detects your MCP host and writes the config automatically:\n\n```bash\nboyce init\n```\n\nOr configure manually. **There are two setup paths depending on your host:**\n\n---\n\n### Path 1 — MCP Hosts (No LLM key required)\n\nIf you're using **Claude Desktop, Cursor, Claude Code, Codex, Cline, Windsurf, JetBrains (DataGrip,\nIntelliJ), or any MCP-compatible host**, you do not need to configure an LLM provider for Boyce.\nThe host's own model handles reasoning — Boyce supplies the schema context and deterministic SQL\ncompiler via `get_schema` and `ask_boyce`. Only `BOYCE_DB_URL` is needed (and even that is optional).\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"boyce\": {\n      \"command\": \"boyce\",\n      \"env\": {\n        \"BOYCE_DB_URL\": \"postgresql://user:pass@host:5432/db\"\n      }\n    }\n  }\n}\n```\n\n**Cursor** (`.cursor/mcp.json` in project root):\n\n```json\n{\n  \"mcpServers\": {\n    \"boyce\": {\n      \"command\": \"boyce\",\n      \"env\": {\n        \"BOYCE_DB_URL\": \"postgresql://user:pass@host:5432/db\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### Path 2 — With Boyce's Built-in NL→SQL\n\nIf you're using the CLI (`boyce ask`), HTTP API, or a non-MCP client (e.g., the VS Code\nextension), configure Boyce's internal query planner with your LLM provider:\n\n```json\n{\n  \"mcpServers\": {\n    \"boyce\": {\n      \"command\": \"boyce\",\n      \"env\": {\n        \"BOYCE_PROVIDER\": \"anthropic\",\n        \"BOYCE_MODEL\": \"claude-sonnet-4-6\",\n        \"ANTHROPIC_API_KEY\": \"sk-ant-...\",\n        \"BOYCE_DB_URL\": \"postgresql://user:pass@host:5432/db\"\n      }\n    }\n  }\n}\n```\n\nBoyce supports any LLM provider available through [LiteLLM](https://docs.litellm.ai/docs/providers):\nAnthropic, OpenAI, Ollama (local), vLLM (local), Azure, Bedrock, Vertex, Mistral, and more.\n\n---\n\n`BOYCE_DB_URL` is optional on both paths. Without it, Boyce runs in schema-only mode — SQL\ngeneration still works; EXPLAIN pre-flight and live query tools return `\"status\": \"unchecked\"`.\n\n---\n\n## Environment Variables\n\n| Variable | When needed | Example | Purpose |\n|---|---|---|---|\n| `BOYCE_PROVIDER` | Path 2 only (CLI/HTTP/non-MCP) | `anthropic` | LiteLLM provider name |\n| `BOYCE_MODEL` | Path 2 only (CLI/HTTP/non-MCP) | `claude-sonnet-4-6` | Model ID passed to LiteLLM |\n| `ANTHROPIC_API_KEY` | When using Anthropic | `sk-ant-...` | Anthropic credentials |\n| `OPENAI_API_KEY` | When using OpenAI | `sk-...` | OpenAI credentials |\n| `BOYCE_DB_URL` | Optional (either path) | `postgresql://user:pass@host:5432/db` | asyncpg DSN — enables EXPLAIN pre-flight + live query tools |\n| `BOYCE_HTTP_TOKEN` | Path 2 HTTP API only | `my-secret-token` | Bearer token for `boyce serve --http` |\n| `BOYCE_STATEMENT_TIMEOUT_MS` | Optional | `30000` | Per-statement timeout in ms (default: 30s) |\n\n---\n\n## MCP Tools\n\n| Tool | Description |\n|---|---|\n| `ingest_source` | Parse a `SemanticSnapshot` from dbt manifest, dbt project, LookML, DDL, SQLite, Django, SQLAlchemy, Prisma, CSV, or Parquet. |\n| `ingest_definition` | Store a certified business definition — injected automatically at query time. |\n| `get_schema` | Return full schema context + StructuredFilter format docs. Used by MCP hosts so the host LLM can construct queries without a Boyce API key. |\n| `ask_boyce` | Full NL → SQL pipeline: query planner (LiteLLM) → deterministic kernel → NULL trap check → EXPLAIN pre-flight. |\n| `validate_sql` | Validate hand-written SQL — EXPLAIN pre-flight, Redshift lint, NULL risk — without executing. |\n| `query_database` | Execute a read-only `SELECT` against the live database. Write operations rejected at two independent layers. |\n| `profile_data` | Null %, distinct count, min/max for any column — surface data quality issues before they affect query results. |\n| `check_health` | Operational health check — DB connectivity, snapshot freshness, actionable fix commands. Call when queries fail unexpectedly. |\n\n---\n\n## Architecture\n\n```\nSemanticSnapshot (JSON)\n        │\n        ▼  ingest_source\n ┌─────────────────────────────────────────────┐\n │          SemanticGraph (NetworkX)            │  ← in-memory, loaded per session\n │  nodes = entities (tables/views/dbt models) │\n │  edges = joins  (weighted by confidence)    │\n └─────────────────────────────────────────────┘\n        │                         │\n        ▼  ask_boyce              ▼  (internal)\n  QueryPlanner                 Dijkstra\n  (LiteLLM)                    join resolver\n  NL → StructuredFilter             │\n        │                           │\n        └──────────┬────────────────┘\n                   ▼\n           kernel.process_request()          ← ZERO LLM HERE\n           SQLBuilder (dialect-aware)\n                   │\n                   ▼\n           EXPLAIN pre-flight                ← Query Verification\n           (PostgresAdapter)\n                   │\n                   ▼\n            SQL + validation result\n```\n\n**Dialect support:** `redshift`, `postgres`, `duckdb`, `bigquery`\n\n**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).\n\n---\n\n## Scan CLI\n\n```bash\n# Scan a single file\nboyce scan demo/magic_moment/manifest.json\n\n# Scan a directory (auto-detects all parseable sources)\nboyce scan ./my-project/ -v\n\n# Save snapshots for MCP server use\nboyce scan ./my-project/ --save\n```\n\n10 parsers: dbt manifest, dbt project, LookML, SQLite, DDL, CSV, Parquet, Django, SQLAlchemy, Prisma.\n\n---\n\n## Verify the Install\n\n```bash\n# Unit tests — no DB required, runs in ~4 seconds\npython boyce/tests/verify_eyes.py\n\n# Expected output:\n# Ran 15 tests in 3.5s\n# OK\n# ✅  All checks passed.\n```\n\n---\n\n## SemanticSnapshot Format\n\nThe `ingest_source` tool accepts a `SemanticSnapshot` JSON dict. Minimal example:\n\n```json\n{\n  \"snapshot_id\": \"<sha256>\",\n  \"source_system\": \"dbt\",\n  \"entities\": {\n    \"entity:orders\": {\n      \"id\": \"entity:orders\",\n      \"name\": \"orders\",\n      \"schema\": \"public\",\n      \"fields\": [\"field:orders:order_id\", \"field:orders:revenue\"]\n    }\n  },\n  \"fields\": {\n    \"field:orders:order_id\": {\n      \"id\": \"field:orders:order_id\",\n      \"entity_id\": \"entity:orders\",\n      \"name\": \"order_id\",\n      \"field_type\": \"ID\",\n      \"data_type\": \"INTEGER\"\n    }\n  },\n  \"joins\": []\n}\n```\n\nSee `boyce/tests/live_fire/mock_snapshot.json` for a complete field/entity example.\n\n---\n\n## Project Layout\n\n```\nboyce/                          ← PRIMARY — headless FastMCP server + pip package\n├── boyce/\n│   ├── server.py               ← MCP entry point (8 tools)\n│   ├── kernel.py               ← Deterministic SQL kernel\n│   ├── graph.py                ← SemanticGraph (NetworkX)\n│   ├── safety.py               ← Redshift compatibility rails\n│   ├── types.py                ← Protocol contract (Pydantic)\n│   ├── scan.py                 ← Scan CLI (boyce scan)\n│   ├── connections.py          ← DSN persistence (ConnectionStore)\n│   ├── doctor.py               ← Environment diagnostics (boyce doctor)\n│   ├── sql/                    ← SQLBuilder, dialect layer, join resolver\n│   ├── parsers/                ← 10 parsers (dbt, lookml, ddl, sqlite, csv, etc.)\n│   ├── planner/                ← QueryPlanner (LiteLLM → StructuredFilter)\n│   └── adapters/               ← PostgresAdapter (Eyes)\n└── tests/\n    ├── verify_eyes.py          ← 15-test suite, no DB required\n    ├── test_parsers.py         ← Parser tests (all 10 parsers)\n    ├── test_scan.py            ← Scan CLI tests\n    └── live_fire/              ← Docker Compose integration tests\n```\n\n---\n\n## Status\n\n| Capability | Status |\n|---|---|\n| NL → SQL (deterministic kernel) | Operational |\n| SemanticGraph (join resolution) | Operational |\n| 10 source parsers | Operational |\n| Scan CLI (`boyce scan`) | Operational |\n| PostgresAdapter (read-only) | Operational |\n| EXPLAIN pre-flight validation | Operational |\n| NULL Trap detection | Operational |\n| Redshift 1.0 safety linting | Operational |\n| Snapshot persistence across restarts | Operational |\n| Audit logging (append-only JSONL) | Operational |\n| Business definitions (`ingest_definition`) | Operational |\n| DSN persistence (`ConnectionStore`) | Operational |\n| Environment diagnostics (`boyce doctor` / `check_health`) | Operational |\n| Multi-snapshot merge | Planned |\n\n---\n\n## Support\n\n- **Troubleshooting guide:** [docs/troubleshooting.md](docs/troubleshooting.md)\n- **Local LLM setup (Ollama/vLLM):** [docs/local-llm-setup.md](docs/local-llm-setup.md)\n- **Bug reports:** [GitHub Issues](https://github.com/boyce-io/boyce/issues/new?template=bug_report.yml)\n- **Setup help:** [GitHub Issues](https://github.com/boyce-io/boyce/issues/new?template=setup_help.yml)\n- **Email:** [will@convergentmethods.com](mailto:will@convergentmethods.com) — for issues involving credentials or sensitive config\n\n---\n\n*Copyright 2026 Convergent Methods, LLC. MIT License.*\n",
  "bytes": 11165,
  "sha": "530c87da7bef27bfee0fdc5b455fe9adef05185f65ffa557f8893addb9646733",
  "repo_slug": "boyce-io/boyce",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_boyce_io_boyce_103853f2/readme"
}