Skip to main content
Glama
Boyce
by boyce-io

Boyce: Семантический протокол и уровень безопасности для агентских рабочих процессов с базами данных

Семантический уровень безопасности для агентских рабочих процессов с базами данных. Boyce подключает LLM к контексту работающей базы данных со встроенными механизмами безопасности.

Назван в честь Рэймонда Ф. Бойса, соавтора SQL (1974) и соавтора нормальной формы Бойса-Кодда (BCNF).

ИИ-агенты, запрашивающие базы данных без надлежащего контекста, генерируют ненадежный SQL — работая с неполными схемами, выводя имена столбцов и угадывая пути соединения. Boyce предоставляет агентам структурированную интеллектуальную работу с базами данных, необходимую для генерации правильного и безопасного SQL каждый раз — через три взаимосвязанные системы:

Уровень

Что он делает

SQL-компилятор

ask_boyce — NL → StructuredFilter → детерминированный SQL. Ноль LLM в построителе SQL. Одинаковые входные данные, одинаковый SQL, байт в байт, каждый раз.

Инспектор БД

query_database / profile_data — Адаптеры для Postgres/Redshift позволяют вашему агенту видеть реальную схему и распределение данных перед написанием любого фильтра.

Верификация запросов

Предварительные циклы EXPLAIN для каждого сгенерированного запроса. Плохой SQL обнаруживается на этапе планирования, а не в 2 часа ночи во время вашего дежурства.

Почему это важно? → Ловушка 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".


Переменные окружения

Переменная

Когда нужна

Пример

Назначение

BOYCE_PROVIDER

Только путь 2 (CLI/HTTP/не-MCP)

anthropic

Имя провайдера LiteLLM

BOYCE_MODEL

Только путь 2 (CLI/HTTP/не-MCP)

claude-sonnet-4-6

ID модели, передаваемый в LiteLLM

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

Bearer-токен для boyce serve --http

BOYCE_STATEMENT_TIMEOUT_MS

Необязательно

30000

Тайм-аут для каждого оператора в мс (по умолчанию: 30 с)


Инструменты MCP

Инструмент

Описание

ingest_source

Парсинг SemanticSnapshot из манифеста dbt, проекта dbt, LookML, DDL, SQLite, Django, SQLAlchemy, Prisma, CSV или Parquet.

ingest_definition

Сохранение сертифицированного бизнес-определения — внедряется автоматически во время запроса.

get_schema

Возврат полного контекста схемы + документации формата StructuredFilter. Используется хостами MCP, чтобы LLM хоста могла создавать запросы без API-ключа Boyce.

ask_boyce

Полный конвейер NL → SQL: планировщик запросов (LiteLLM) → детерминированное ядро → проверка ловушки NULL → предварительная проверка EXPLAIN.

validate_sql

Проверка написанного вручную SQL — предварительная проверка EXPLAIN, линтинг Redshift, риск NULL — без выполнения.

query_database

Выполнение SELECT только для чтения в реальной базе данных. Операции записи отклоняются на двух независимых уровнях.

profile_data

Процент NULL, количество уникальных значений, мин/макс для любого столбца — выявление проблем с качеством данных до того, как они повлияют на результаты запроса.

check_health

Проверка работоспособности — подключение к БД, свежесть снимка, команды для исправления. Вызывайте, если запросы неожиданно завершаются с ошибкой.


Архитектура

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 принимает словарь 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 (boyce scan)

Работает

PostgresAdapter (только чтение)

Работает

Предварительная проверка EXPLAIN

Работает

Обнаружение ловушки NULL

Работает

Линтинг безопасности Redshift 1.0

Работает

Сохранение снимка между перезапусками

Работает

Журнал аудита (JSONL только для добавления)

Работает

Бизнес-определения (ingest_definition)

Работает

Сохранение DSN (ConnectionStore)

Работает

Диагностика окружения (boyce doctor / check_health)

Работает

Объединение нескольких снимков

Запланировано


Поддержка


Авторское право 2026 Convergent Methods, LLC. Лицензия MIT.

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