エージェント型データベースワークフローのためのセマンティック安全レイヤー Boyceは、組み込みの安全レールを備えたライブデータベースコンテキストにLLMを接続します。
SQLの共同発明者（1974年）であり、Boyce-Codd正規形（BCNF）の共著者であるRaymond F. Boyceにちなんで名付けられました。
適切なコンテキストなしでデータベースをクエリするAIエージェントは、不完全なスキーマからの作業、列名の推論、結合パスの推測などにより、信頼性の低いSQLを生成します。Boyceは、3つの相互接続されたシステムを通じて、エージェントが毎回正確で安全なSQLを生成するために必要な構造化されたデータベースインテリジェンスを提供します。
レイヤー | 機能 |
SQLコンパイラ |
|
データベースインスペクター |
|
クエリ検証 | 生成されたすべてのクエリに対してプリフライトの |
なぜこれが重要なのか？ → The Null Trap: Your AI Agent's SQL Is Correct. The Answer Is Still Wrong.
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または手動で設定します。ホストに応じて2つのセットアップパスがあります：
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ホストがBoyce APIキーなしでクエリを構築できるようにするために使用されます。 |
| 完全なNL→SQLパイプライン：クエリプランナー（LiteLLM）→決定論的カーネル→NULLトラップチェック→EXPLAINプリフライト。 |
| 手書きのSQLを検証します。実行せずにEXPLAINプリフライト、Redshiftリント、NULLリスクチェックを行います。 |
| ライブデータベースに対して読み取り専用の |
| 任意の列のNULL率、一意のカウント、最小/最大値を確認し、クエリ結果に影響が出る前にデータ品質の問題を表面化させます。 |
| 運用上の健全性チェック：DB接続性、スナップショットの鮮度、実行可能な修正コマンド。クエリが予期せず失敗したときに呼び出します。 |
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、先読み正規表現パターン、および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安全リント | 運用中 |
再起動後のスナップショット永続化 | 運用中 |
監査ログ (追記型JSONL) | 運用中 |
ビジネス定義 ( | 運用中 |
DSN永続化 ( | 運用中 |
環境診断 ( | 運用中 |
マルチスナップショットマージ | 計画中 |
トラブルシューティングガイド: docs/troubleshooting.md
ローカルLLMセットアップ (Ollama/vLLM): docs/local-llm-setup.md
バグ報告: GitHub Issues
セットアップヘルプ: GitHub Issues
メール: will@convergentmethods.com — 認証情報や機密設定に関する問題について
Copyright 2026 Convergent Methods, LLC. MIT License.
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.
