面向智能体数据库工作流的语义安全层。 Boyce 通过内置的安全护栏将大语言模型（LLM）连接到实时数据库上下文。
以 Raymond F. Boyce 的名字命名，他是 SQL 的共同发明者（1974 年）以及 Boyce-Codd 范式（BCNF）的共同作者。
AI 智能体在缺乏适当上下文的情况下查询数据库会生成不可靠的 SQL——它们往往基于不完整的模式、推断列名或猜测连接路径。Boyce 通过三个互联的系统，为智能体提供生成正确、安全 SQL 所需的结构化数据库智能：
层级 | 功能 |
SQL 编译器 |
|
数据库检查器 |
|
查询验证 | 对每个生成的查询进行预检 |
为什么这很重要？ → 空值陷阱：你的 AI 智能体生成的 SQL 是正确的，但答案依然是错的。
需要 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]"从源码安装：
git clone https://github.com/boyce-io/boyce
uv pip install -e "boyce/"Related MCP server: MCP Guide Schema Query
安装后，运行 boyce init 自动配置你的 MCP 主机：
boyce init该向导会自动检测 Claude Desktop、Cursor、Claude Code 和 JetBrains（DataGrip、IntelliJ 等），并为每个工具写入正确的配置块。
从源码开发？ 仓库中包含一个安装脚本：
./quickstart.sh # detects uv or python, installs package, writes .env template最快的方法是使用 boyce init——它会自动检测你的 MCP 主机并写入配置：
boyce init或者手动配置。根据你的主机，有两种设置路径：
如果你正在使用 Claude Desktop、Cursor、Claude Code、Codex、Cline、Windsurf、JetBrains (DataGrip, IntelliJ) 或任何兼容 MCP 的主机，你不需要为 Boyce 配置 LLM 提供商。主机的模型负责推理——Boyce 通过 get_schema 和 ask_boyce 提供模式上下文和确定性 SQL 编译器。仅需 BOYCE_DB_URL（甚至该项也是可选的）。
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 在项目根目录):
{
"mcpServers": {
"boyce": {
"command": "boyce",
"env": {
"BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
}
}
}
}如果你正在使用 CLI (boyce ask)、HTTP API 或非 MCP 客户端（例如 VS Code 扩展），请使用你的 LLM 提供商配置 Boyce 的内部查询规划器：
{
"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 支持通过 LiteLLM 提供的任何 LLM 提供商：Anthropic、OpenAI、Ollama (本地)、vLLM (本地)、Azure、Bedrock、Vertex、Mistral 等。
BOYCE_DB_URL 在两条路径中都是可选的。如果没有它，Boyce 将以仅模式模式运行——SQL 生成仍然有效；EXPLAIN 预检和实时查询工具将返回 "status": "unchecked"。
变量 | 何时需要 | 示例 | 用途 |
| 仅路径 2 (CLI/HTTP/非 MCP) |
| LiteLLM 提供商名称 |
| 仅路径 2 (CLI/HTTP/非 MCP) |
| 传递给 LiteLLM 的模型 ID |
| 使用 Anthropic 时 |
| Anthropic 凭据 |
| 使用 OpenAI 时 |
| OpenAI 凭据 |
| 可选 (任一路径) |
| asyncpg DSN — 启用 EXPLAIN 预检 + 实时查询工具 |
| 仅路径 2 HTTP API |
|
|
| 可选 |
| 单条语句超时时间（毫秒，默认：30秒） |
工具 | 描述 |
| 从 dbt 清单、dbt 项目、LookML、DDL、SQLite、Django、SQLAlchemy、Prisma、CSV 或 Parquet 解析 |
| 存储经过认证的业务定义——在查询时自动注入。 |
| 返回完整的模式上下文 + StructuredFilter 格式文档。供 MCP 主机使用，以便主机 LLM 无需 Boyce API 密钥即可构建查询。 |
| 完整的 NL → SQL 流水线：查询规划器 (LiteLLM) → 确定性内核 → NULL 陷阱检查 → EXPLAIN 预检。 |
| 验证手写 SQL — EXPLAIN 预检、Redshift lint、NULL 风险 — 无需执行。 |
| 对实时数据库执行只读 |
| 任何列的空值百分比、唯一计数、最小值/最大值 — 在数据质量问题影响查询结果之前将其暴露出来。 |
| 操作健康检查 — 数据库连接性、快照新鲜度、可操作的修复命令。在查询意外失败时调用。 |
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方言支持： redshift, postgres, duckdb, bigquery
Redshift 安全护栏 (safety.py)：针对 LATERAL、JSONB、REGEXP_COUNT 的自动 linting，前瞻正则表达式模式，以及针对 Redshift 1.0 (PG 8.0.2) 的数字类型转换重写。
# 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 个解析器：dbt 清单、dbt 项目、LookML、SQLite、DDL、CSV、Parquet、Django、SQLAlchemy、Prisma。
# 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.ingest_source 工具接受一个 SemanticSnapshot JSON 字典。最小示例：
{
"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": []
}查看 boyce/tests/live_fire/mock_snapshot.json 获取完整的字段/实体示例。
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功能 | 状态 |
NL → SQL (确定性内核) | 可用 |
SemanticGraph (连接解析) | 可用 |
10 个源解析器 | 可用 |
扫描 CLI ( | 可用 |
PostgresAdapter (只读) | 可用 |
EXPLAIN 预检验证 | 可用 |
NULL 陷阱检测 | 可用 |
Redshift 1.0 安全 linting | 可用 |
重启后的快照持久化 | 可用 |
审计日志 (仅追加 JSONL) | 可用 |
业务定义 ( | 可用 |
DSN 持久化 ( | 可用 |
环境诊断 ( | 可用 |
多快照合并 | 计划中 |
故障排除指南： docs/troubleshooting.md
本地 LLM 设置 (Ollama/vLLM)： docs/local-llm-setup.md
错误报告： GitHub Issues
设置帮助： GitHub Issues
电子邮件： will@convergentmethods.com — 用于涉及凭据或敏感配置的问题
版权所有 2026 Convergent Methods, LLC. MIT 许可证。
This server cannot be deployed
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.
Generate, fix, explain and run read-only SQL on PostgreSQL, MySQL and SQL Server
Paid deterministic data-quality and execution-verification tools for AI agents.
