에이전트 데이터베이스 워크플로우를 위한 의미론적 안전 계층. Boyce는 내장된 안전 장치를 통해 LLM을 실시간 데이터베이스 컨텍스트에 연결합니다.
SQL의 공동 발명가(1974)이자 Boyce-Codd 정규형(BCNF)의 공동 저자인 Raymond F. Boyce의 이름을 따서 명명되었습니다.
적절한 컨텍스트 없이 데이터베이스를 쿼리하는 AI 에이전트는 불완전한 스키마 작업, 열 이름 추론, 조인 경로 추측 등으로 인해 신뢰할 수 없는 SQL을 생성합니다. Boyce는 세 가지 상호 연결된 시스템을 통해 에이전트가 매번 정확하고 안전한 SQL을 생성하는 데 필요한 구조화된 데이터베이스 지능을 제공합니다.
계층 | 기능 |
SQL 컴파일러 |
|
데이터베이스 검사기 |
|
쿼리 검증 | 생성된 모든 쿼리에 대해 사전 |
왜 중요한가? → The Null Trap: 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 전용 |
|
|
| 선택 사항 |
| 문장당 타임아웃(ms) (기본값: 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.
