Skip to main content
Glama
deenesjakoruzh
boyce-io

Boyce

Official
by boyce-io
OverviewSchemaRelated ServersScoreDiscussions
Hybrid

Boyce：面向智能体数据库工作流的语义协议与安全层

面向智能体数据库工作流的语义安全层。 Boyce 通过内置的安全护栏将大语言模型（LLM）连接到实时数据库上下文。

以 Raymond F. Boyce 的名字命名，他是 SQL 的共同发明者（1974 年）以及 Boyce-Codd 范式（BCNF）的共同作者。

AI 智能体在缺乏适当上下文的情况下查询数据库会生成不可靠的 SQL——它们往往基于不完整的模式、推断列名或猜测连接路径。Boyce 通过三个互联的系统，为智能体提供生成正确、安全 SQL 所需的结构化数据库智能：

层级

功能

SQL 编译器

ask_boyce — 自然语言 → StructuredFilter → 确定性 SQL。SQL 构建器中零 LLM 参与。相同的输入，每次都能得到字节级一致的相同 SQL。

数据库检查器

query_database / profile_data — 实时 Postgres/Redshift 适配器让你的智能体在编写任何过滤器之前就能看到真实的模式和数据分布。

查询验证

对每个生成的查询进行预检 EXPLAIN 循环。在规划阶段即可捕获糟糕的 SQL，而不是等到凌晨值班时才发现。

为什么这很重要？ → 空值陷阱：你的 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-postgres

快速入门

安装后，运行 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 的主机，你不需要为 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 主机使用，以便主机 LLM 无需 Boyce API 密钥即可构建查询。

ask_boyce

完整的 NL → SQL 流水线：查询规划器 (LiteLLM) → 确定性内核 → NULL 陷阱检查 → EXPLAIN 预检。

validate_sql

验证手写 SQL — EXPLAIN 预检、Redshift lint、NULL 风险 — 无需执行。

query_database

对实时数据库执行只读 SELECT。写操作在两个独立的层级被拒绝。

profile_data

任何列的空值百分比、唯一计数、最小值/最大值 — 在数据质量问题影响查询结果之前将其暴露出来。

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 的自动 linting，前瞻正则表达式模式，以及针对 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 安全 linting

可用

重启后的快照持久化

可用

审计日志 (仅追加 JSONL)

可用

业务定义 (ingest_definition)

可用

DSN 持久化 (ConnectionStore)

可用

环境诊断 (boyce doctor / check_health)

可用

多快照合并

计划中

支持

版权所有 2026 Convergent Methods, LLC. MIT 许可证。

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • SQLite MCP Server

    u1pns
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides comprehensive SQLite database interaction for AI agents, including data manipulation, schema inspection, and automated query logging. It features a unique context preservation pattern that uses a dedicated meta-table to help autonomous agents maintain self-documenting database architectures.
    36
    1
    MIT

  • mcp-postgres

    Filipescordeiro2
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to execute SQL queries and introspect PostgreSQL schemas, tables, and indexes with read-only safety by default. Supports optional write operations and works with Claude, LangChain, and other agents via stdio or HTTP transports.

  • QueryShield

    bch1212
    A
    license
    Not graded
    quality
    A
    maintenance
    Secure SQL proxy for AI agents. Translates natural language to safe SQL via Claude, validates at the AST level (SELECT-only, no DDL/DML), enforces per-agent row-level security, and audit-logs every query.
    1
    MIT
  • Bollard MCP by Bollard-db

    Bollard MCPofficial

    Bollard-db
    A
    license
    A
    quality
    B
    maintenance
    Enables safe, AI-driven database interactions with schema discovery, intent validation, and session memory, supporting multiple databases.
    14
    2
    AGPL 3.0

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/boyce-io/boyce'

If you have feedback or need assistance with the MCP directory API, please join our Discord server