Boyce
OfficialBoyce: Semantische Protokoll- und Sicherheitsebene für agentische Datenbank-Workflows
Die semantische Sicherheitsebene für agentische Datenbank-Workflows. Boyce verbindet LLMs mit aktivem Datenbankkontext unter Verwendung integrierter Sicherheitsmechanismen.
Benannt nach Raymond F. Boyce, dem Miterfinder von SQL (1974) und Mitautor der Boyce-Codd-Normalform (BCNF).
KI-Agenten, die Datenbanken ohne korrekten Kontext abfragen, generieren unzuverlässiges SQL — sie arbeiten mit unvollständigen Schemata, leiten Spaltennamen ab oder raten Join-Pfade. Boyce gibt Agenten die strukturierte Datenbankintelligenz, die sie benötigen, um jedes Mal korrektes, sicheres SQL zu generieren — durch drei miteinander verbundene Systeme:
Ebene | Funktion |
SQL-Compiler |
|
Datenbank-Inspektor |
|
Abfrage-Verifizierung | Pre-Flight |
Warum ist das wichtig? → Die Null-Falle: Das SQL Ihres KI-Agenten ist korrekt. Die Antwort ist trotzdem falsch.
Installation
Erfordert 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]"Aus dem Quellcode:
git clone https://github.com/boyce-io/boyce
uv pip install -e "boyce/"Related MCP server: mcp-database-tools
Schnellstart
Führen Sie nach der Installation boyce init aus, um Ihren MCP-Host automatisch zu konfigurieren:
boyce initDer Assistent erkennt Claude Desktop, Cursor, Claude Code und JetBrains (DataGrip, IntelliJ usw.) und schreibt den korrekten Konfigurationsblock für jeden.
Entwicklung aus dem Quellcode? Das Repository enthält ein Setup-Skript:
./quickstart.sh # detects uv or python, installs package, writes .env templateKonfigurieren Sie Ihren MCP-Host
Der schnellste Weg ist boyce init — es erkennt Ihren MCP-Host und schreibt die Konfiguration automatisch:
boyce initOder konfigurieren Sie manuell. Es gibt zwei Setup-Pfade, abhängig von Ihrem Host:
Pfad 1 — MCP-Hosts (Kein LLM-Schlüssel erforderlich)
Wenn Sie Claude Desktop, Cursor, Claude Code, Codex, Cline, Windsurf, JetBrains (DataGrip, IntelliJ) oder einen beliebigen MCP-kompatiblen Host verwenden, müssen Sie keinen LLM-Anbieter für Boyce konfigurieren. Das Modell des Hosts übernimmt das Reasoning — Boyce liefert den Schemakontext und den deterministischen SQL-Compiler über get_schema und ask_boyce. Nur BOYCE_DB_URL wird benötigt (und selbst das ist 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 im Projektstammverzeichnis):
{
"mcpServers": {
"boyce": {
"command": "boyce",
"env": {
"BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
}
}
}
}Pfad 2 — Mit Boyces integriertem NL→SQL
Wenn Sie die CLI (boyce ask), die HTTP-API oder einen Nicht-MCP-Client (z. B. die VS Code-Erweiterung) verwenden, konfigurieren Sie den internen Abfrageplaner von Boyce mit Ihrem LLM-Anbieter:
{
"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 unterstützt jeden LLM-Anbieter, der über LiteLLM verfügbar ist: Anthropic, OpenAI, Ollama (lokal), vLLM (lokal), Azure, Bedrock, Vertex, Mistral und mehr.
BOYCE_DB_URL ist auf beiden Pfaden optional. Ohne sie läuft Boyce im Nur-Schema-Modus — die SQL-Generierung funktioniert weiterhin; EXPLAIN-Pre-Flight und Live-Abfragetools geben "status": "unchecked" zurück.
Umgebungsvariablen
Variable | Wann benötigt | Beispiel | Zweck |
| Nur Pfad 2 (CLI/HTTP/Nicht-MCP) |
| LiteLLM-Anbietername |
| Nur Pfad 2 (CLI/HTTP/Nicht-MCP) |
| Modell-ID, die an LiteLLM übergeben wird |
| Bei Verwendung von Anthropic |
| Anthropic-Anmeldedaten |
| Bei Verwendung von OpenAI |
| OpenAI-Anmeldedaten |
| Optional (beide Pfade) |
| asyncpg DSN — aktiviert EXPLAIN-Pre-Flight + Live-Abfragetools |
| Nur Pfad 2 HTTP-API |
| Bearer-Token für |
| Optional |
| Timeout pro Anweisung in ms (Standard: 30s) |
MCP-Tools
Tool | Beschreibung |
| Parsen eines |
| Speichern einer zertifizierten Geschäftsdefinition — wird zur Abfragezeit automatisch eingefügt. |
| Rückgabe des vollständigen Schemakontexts + Dokumentation zum StructuredFilter-Format. Wird von MCP-Hosts verwendet, damit das Host-LLM Abfragen ohne Boyce-API-Schlüssel erstellen kann. |
| Vollständige NL→SQL-Pipeline: Abfrageplaner (LiteLLM) → deterministischer Kernel → NULL-Fallen-Prüfung → EXPLAIN-Pre-Flight. |
| Validierung von handgeschriebenem SQL — EXPLAIN-Pre-Flight, Redshift-Linting, NULL-Risiko — ohne Ausführung. |
| Ausführung eines schreibgeschützten |
| Null-%, eindeutige Anzahl, Min/Max für jede Spalte — Erkennung von Datenqualitätsproblemen, bevor sie Abfrageergebnisse beeinflussen. |
| Operativer Gesundheitscheck — DB-Konnektivität, Snapshot-Aktualität, umsetzbare Korrekturbefehle. Aufrufen, wenn Abfragen unerwartet fehlschlagen. |
Architektur
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 resultDialekt-Unterstützung: redshift, postgres, duckdb, bigquery
Redshift-Sicherheitsmechanismen (safety.py): Automatisches Linting für LATERAL, JSONB, REGEXP_COUNT, Lookahead-Regex-Muster und numerische Cast-Umschreibungen für 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/ --save10 Parser: dbt-Manifest, dbt-Projekt, LookML, SQLite, DDL, CSV, Parquet, Django, SQLAlchemy, Prisma.
Installation verifizieren
# 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
Das ingest_source-Tool akzeptiert ein SemanticSnapshot JSON-Dict. Minimalbeispiel:
{
"snapshot_id": "<sha256>",
"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": []
}Siehe boyce/tests/live_fire/mock_snapshot.json für ein vollständiges Feld/Entitäts-Beispiel.
Projektlayout
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 testsStatus
Fähigkeit | Status |
NL → SQL (deterministischer Kernel) | Operativ |
SemanticGraph (Join-Auflösung) | Operativ |
10 Quell-Parser | Operativ |
Scan-CLI ( | Operativ |
PostgresAdapter (schreibgeschützt) | Operativ |
EXPLAIN-Pre-Flight-Validierung | Operativ |
NULL-Fallen-Erkennung | Operativ |
Redshift 1.0 Sicherheits-Linting | Operativ |
Snapshot-Persistenz über Neustarts hinweg | Operativ |
Audit-Logging (nur anhängendes JSONL) | Operativ |
Geschäftsdefinitionen ( | Operativ |
DSN-Persistenz ( | Operativ |
Umgebungsdiagnose ( | Operativ |
Multi-Snapshot-Merge | Geplant |
Support
Fehlerbehebungsanleitung: docs/troubleshooting.md
Lokales LLM-Setup (Ollama/vLLM): docs/local-llm-setup.md
Fehlerberichte: GitHub Issues
Setup-Hilfe: GitHub Issues
E-Mail: will@convergentmethods.com — für Probleme mit Anmeldedaten oder sensibler Konfiguration
Copyright 2026 Convergent Methods, LLC. MIT-Lizenz.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Deterministic validation for AI-generated artifacts: JSON Schema, OpenAPI response, SQL syntax.
Database guardrails for AI agents: check SQL against your Vericto rules before it runs.
Review your AI agent's database changes on your schema, with plain-language risk, before they run.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI tools to understand a database, inspect schema, and run safe SELECT queries with SQL guardrails, plus optional codebase reading.MIT
- AlicenseAqualityDmaintenanceEnables AI agents to format SQL, explain queries in plain English, analyze schemas, build queries from natural language, and generate migrations, all without requiring a database connection.550 npmMIT
- AlicenseAqualityBmaintenanceRead-only-by-default MySQL/MariaDB, PostgreSQL and SQLite access for AI agents: explore schemas and foreign keys, search, sample, query and EXPLAIN with token-efficient TOON output. Writes only when enabled, always previewed and atomic.1141 PyPI1Apache 2.0
- AlicenseBqualityCmaintenanceEnables AI coding agents to perform deterministic database architecture audits and performance engineering for PostgreSQL and MySQL, covering migration analysis with schema health scoring, ESR-based composite index recommendations, N+1 query detection, EXPLAIN plan diagnosis, transaction and deadlock analysis, partitioning and archival design, and capacity or configuration tuning. It also generates phased Expand & Contract runbooks that turn blocking DDL into zero-downtime production migrations.8MIT