Skip to main content
Glama
Boyce
by boyce-io

Boyce: エージェント型データベースワークフローのためのセマンティックプロトコル&安全レイヤー

エージェント型データベースワークフローのためのセマンティック安全レイヤー Boyceは、組み込みの安全レールを備えたライブデータベースコンテキストにLLMを接続します。

SQLの共同発明者(1974年)であり、Boyce-Codd正規形(BCNF)の共著者であるRaymond F. Boyceにちなんで名付けられました。

適切なコンテキストなしでデータベースをクエリするAIエージェントは、不完全なスキーマからの作業、列名の推論、結合パスの推測などにより、信頼性の低いSQLを生成します。Boyceは、3つの相互接続されたシステムを通じて、エージェントが毎回正確で安全なSQLを生成するために必要な構造化されたデータベースインテリジェンスを提供します。

レイヤー

機能

SQLコンパイラ

ask_boyce — NL → StructuredFilter → 決定論的SQL。SQLビルダーにLLMは一切使用しません。同じ入力であれば、毎回バイト単位で同じSQLが生成されます。

データベースインスペクター

query_database / profile_data — ライブのPostgres/Redshiftアダプターにより、エージェントはフィルターを記述する前に実際のスキーマとデータ分布を確認できます。

クエリ検証

生成されたすべてのクエリに対してプリフライトの EXPLAIN ループを実行します。不適切な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-database-tools

クイックスタート

インストール後、boyce init を実行してMCPホストを自動的に設定します:

boyce init

このウィザードは、Claude Desktop、Cursor、Claude Code、JetBrains(DataGrip、IntelliJなど)を検出し、それぞれに対して正しい設定ブロックを書き込みます。

ソースから開発する場合: リポジトリにはセットアップスクリプトが含まれています:

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

MCPホストの設定

最も速い方法は boyce init です。MCPホストを検出し、設定を自動的に書き込みます:

boyce init

または手動で設定します。ホストに応じて2つのセットアップパスがあります:


パス1 — MCPホスト(LLMキー不要)

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"
      }
    }
  }
}

パス2 — Boyceの組み込みNL→SQLを使用する場合

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" を返します。


環境変数

変数

必要な場合

例

目的

BOYCE_PROVIDER

パス2のみ (CLI/HTTP/非MCP)

anthropic

LiteLLMプロバイダー名

BOYCE_MODEL

パス2のみ (CLI/HTTP/非MCP)

claude-sonnet-4-6

LiteLLMに渡されるモデルID

ANTHROPIC_API_KEY

Anthropic使用時

sk-ant-...

Anthropic認証情報

OPENAI_API_KEY

OpenAI使用時

sk-...

OpenAI認証情報

BOYCE_DB_URL

オプション (両パス)

postgresql://user:pass@host:5432/db

asyncpg DSN — EXPLAINプリフライトとライブクエリツールを有効化

BOYCE_HTTP_TOKEN

パス2 HTTP APIのみ

my-secret-token

boyce serve --http 用のBearerトークン

BOYCE_STATEMENT_TIMEOUT_MS

オプション

30000

ステートメントごとのタイムアウト(ミリ秒、デフォルト: 30秒)


MCPツール

ツール

説明

ingest_source

dbtマニフェスト、dbtプロジェクト、LookML、DDL、SQLite、Django、SQLAlchemy、Prisma、CSV、またはParquetから SemanticSnapshot を解析します。

ingest_definition

認定されたビジネス定義を保存します。クエリ時に自動的に注入されます。

get_schema

完全なスキーマコンテキストとStructuredFilter形式のドキュメントを返します。MCPホストがBoyce APIキーなしでクエリを構築できるようにするために使用されます。

ask_boyce

完全なNL→SQLパイプライン:クエリプランナー(LiteLLM)→決定論的カーネル→NULLトラップチェック→EXPLAINプリフライト。

validate_sql

手書きのSQLを検証します。実行せずにEXPLAINプリフライト、Redshiftリント、NULLリスクチェックを行います。

query_database

ライブデータベースに対して読み取り専用の SELECT を実行します。書き込み操作は2つの独立したレイヤーで拒否されます。

profile_data

任意の列のNULL率、一意のカウント、最小/最大値を確認し、クエリ結果に影響が出る前にデータ品質の問題を表面化させます。

check_health

運用上の健全性チェック: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) 用の数値キャスト書き換えに対する自動リント機能。


スキャン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個のパーサー: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.

SemanticSnapshot形式

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 (boyce scan)

運用中

PostgresAdapter (読み取り専用)

運用中

EXPLAINプリフライト検証

運用中

NULLトラップ検出

運用中

Redshift 1.0安全リント

運用中

再起動後のスナップショット永続化

運用中

監査ログ (追記型JSONL)

運用中

ビジネス定義 (ingest_definition)

運用中

DSN永続化 (ConnectionStore)

運用中

環境診断 (boyce doctor / check_health)

運用中

マルチスナップショットマージ

計画中


サポート


Copyright 2026 Convergent Methods, LLC. MIT License.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI tools to understand a database, inspect schema, and run safe SELECT queries with SQL guardrails, plus optional codebase reading.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      5
      50 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Read-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.
      11
      41 PyPI
      1
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      8
      MIT