Boyce
OfficialBoyce: Семантический протокол и уровень безопасности для агентских рабочих процессов с базами данных
Семантический уровень безопасности для агентских рабочих процессов с базами данных. Boyce подключает LLM к контексту работающей базы данных со встроенными механизмами безопасности.
Назван в честь Рэймонда Ф. Бойса, соавтора SQL (1974) и соавтора нормальной формы Бойса-Кодда (BCNF).
ИИ-агенты, запрашивающие базы данных без надлежащего контекста, генерируют ненадежный SQL — работая с неполными схемами, выводя имена столбцов и угадывая пути соединения. Boyce предоставляет агентам структурированную интеллектуальную работу с базами данных, необходимую для генерации правильного и безопасного SQL каждый раз — через три взаимосвязанные системы:
Уровень | Что он делает |
SQL-компилятор |
|
Инспектор БД |
|
Верификация запросов | Предварительные циклы |
Почему это важно? → Ловушка NULL: 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-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Или настройте вручную. Существует два пути настройки в зависимости от вашего хоста:
Путь 1 — Хосты MCP (ключ LLM не требуется)
Если вы используете Claude Desktop, Cursor, Claude Code, Codex, Cline, Windsurf, JetBrains (DataGrip, IntelliJ) или любой другой хост, совместимый с MCP, вам не нужно настраивать провайдера LLM для Boyce. Собственная модель хоста берет на себя рассуждения — Boyce предоставляет контекст схемы и детерминированный SQL-компилятор через get_schema и ask_boyce. Требуется только 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 — Со встроенным NL→SQL от Boyce
Если вы используете CLI (boyce ask), HTTP API или клиент, не поддерживающий MCP (например, расширение VS Code), настройте внутренний планировщик запросов Boyce с вашим провайдером LLM:
{
"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 поддерживает любого провайдера LLM, доступного через LiteLLM: 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) |
| ID модели, передаваемый в LiteLLM |
| При использовании Anthropic |
| Учетные данные Anthropic |
| При использовании OpenAI |
| Учетные данные OpenAI |
| Необязательно (любой путь) |
| asyncpg DSN — включает предварительную проверку EXPLAIN + инструменты для живых запросов |
| Только путь 2 HTTP API |
| Bearer-токен для |
| Необязательно |
| Тайм-аут для каждого оператора в мс (по умолчанию: 30 с) |
Инструменты MCP
Инструмент | Описание |
| Парсинг |
| Сохранение сертифицированного бизнес-определения — внедряется автоматически во время запроса. |
| Возврат полного контекста схемы + документации формата StructuredFilter. Используется хостами MCP, чтобы LLM хоста могла создавать запросы без API-ключа Boyce. |
| Полный конвейер NL → SQL: планировщик запросов (LiteLLM) → детерминированное ядро → проверка ловушки NULL → предварительная проверка EXPLAIN. |
| Проверка написанного вручную SQL — предварительная проверка EXPLAIN, линтинг Redshift, риск NULL — без выполнения. |
| Выполнение |
| Процент 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, шаблонов регулярных выражений с опережающим просмотром и переписывание числовых приведений для 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/ --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.Формат SemanticSnapshot
Инструмент ingest_source принимает словарь JSON SemanticSnapshot. Минимальный пример:
{
"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
Email: will@convergentmethods.com — для вопросов, связанных с учетными данными или конфиденциальной настройкой
Авторское право 2026 Convergent Methods, LLC. Лицензия MIT.
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