orionbelt-analytics

OrionBelt® Analytics

基于本体的 MCP 服务，让 Text-2-SQL 更便捷。

OrionBelt Analytics 是一款 MCP 服务，可分析关系数据库架构，并生成内嵌 SQL 映射的 RDF/OWL 本体。它提供感知关系的 Text-to-SQL、自动防止扇陷阱、用于智能发现架构的 GraphRAG，以及交互式图表功能——所有功能均可通过任何兼容 MCP 的 AI 客户端使用。

OrionBelt 生态系统

项目	用途
OrionBelt Analytics（本项目）	Schema 分析、本体生成、GraphRAG、文本转 SQL
OrionBelt Semantic Layer	声明式 YAML 模型，可编译为特定方言且无扇形陷阱的 SQL
OrionBelt Ontology Builder	可视化 OWL 本体编辑器，支持推理和图可视化（在线演示）
OrionBelt Chat	面向 Analytics + Semantic Layer 的 AI 聊天界面（Chainlit，支持多个大模型提供商）

在 Claude Desktop 中并排运行 Analytics 和 Semantic Layer，即可生成具备 Schema 感知能力的本体，并且确保 SQL 编译正确无误。

架构

• 8 个数据库连接器 -- PostgreSQL、MySQL、Snowflake、ClickHouse、Dremio、BigQuery、DuckDB/MotherDuck、Databricks SQL
• RDF/OWL 本体生成，支持 oba: 命名空间 SQL 注释和 W3C R2RML 映射
• GraphRAG -- 图遍历（最多 12 跳）+ ChromaDB 向量嵌入，用于语义 Schema 发现，在本地运行；多语言选项可让其他语言的问题也能找到对应的 Schema（德语 "Umsatz" 可以找到名为 "Net revenue" 的列）
• 通过持久化 Oxigraph RDF 存储提供 SPARQL 1.1 查询接口
• OBQC 验证 -- 根据本体确定性地检查 SQL（表/列是否存在、连接是否有效、类型是否匹配、是否存在扇形陷阱）
• 交互式图表 -- Plotly 图表，并通过 MCP-UI 在 Claude Desktop 中渲染
• 多 Schema 支持 -- 同时分析多个 Schema；每个 Schema 的本体和 GraphRAG 状态相互隔离
• 工作区持久化 -- 重新连接到同一数据库并恢复之前的会话
• MCP 采样 -- 当连接的客户端支持采样时（例如 OrionBelt Chat），suggest_semantic_names 会通过 sampling/createMessage 请求宿主大模型预先填入对晦涩标识符的重命名建议，将原先先审核再应用的流程合并为一次工具调用。不支持采样的客户端（例如 Claude Desktop）会自动回退到手动审核流程

OBQC —— 基于本体的查询检查

OrionBelt 的一项关键差异化优势是 OBQC（基于本体的查询检查），这是一种确定性的规则型 SQL 验证器，可在查询到达数据库之前捕获错误。与依赖模型“正确处理”的纯 LLM 方法不同，OBQC 会将生成的每条 SQL 语句与已加载的 RDF/OWL 本体进行交叉核对，以确保结构正确。

OBQC 的验证内容：

检查项	可捕获的问题
表是否存在	引用了架构中不存在的表
列是否存在	引用了表中不存在的列、未限定名称的列存在歧义
连接是否有效	缺少连接条件（笛卡尔积）、连接列与声明的外键不匹配
类型兼容性	WHERE/ON 中比较了不兼容的类型（例如，字符串与整数）
聚合正确性	使用聚合函数时，SELECT 列未包含在 GROUP BY 中
扇陷检测	在多个一对多连接上执行聚合，导致结果被悄然倍增

工作原理：

1. generate_ontology 或 load_my_ontology 会创建或加载带有 oba: 命名空间注释的本体，将 OWL 类和属性映射到实际数据库的表、列、类型和外键。
2. 调用 execute_sql_query 时，OBQC 会使用 sqlglot 解析 SQL，并根据本体的架构模型验证每个表、列、连接和聚合。
3. 问题会连同严重性级别（错误、警告、信息）与查询结果一起返回，以便 LLM 在用户看到错误数据之前自行纠正。

OBQC 完全确定性——不会调用 LLM，也不进行概率推理。它作为安全保障机制，以严格的结构保证补充 LLM 的 SQL 生成能力。错误会阻止查询执行；警告则会附加到响应中，供 LLM 处理。完整的规则参考、严重性行为和注释要求，请参阅 OBQC 文档。

快速开始

1. 安装

git clone https://github.com/ralforion/orionbelt-analytics
cd orionbelt-analytics
uv sync

需要 Python 3.13+ 和 uv。

2. 配置

cp .env.template .env

使用数据库凭据编辑 .env。至少需要为一个数据库设置相应变量（例如 POSTGRES_HOST、POSTGRES_PORT、POSTGRES_DATABASE、POSTGRES_USERNAME、POSTGRES_PASSWORD）。

有关所有环境变量、传输选项和故障排查，请参阅 docs/configuration.md。

3. 运行

uv run server.py

服务会在 http://localhost:9000 启动（HTTP 传输，可通过 MCP_SERVER_PORT 配置）。

连接 AI 客户端

Claude Desktop

启动服务，然后将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "OrionBelt-Analytics": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:9000/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

Claude Code

claude mcp add orionbelt-analytics http://localhost:9000/mcp

LibreChat

添加到 librechat.yaml：

mcpServers:
  OrionBelt-Analytics:
    type: streamable-http
    url: "http://host.docker.internal:9000/mcp"
    timeout: 60000
    startup: true

其他框架

OrionBelt 可与 LangChain、OpenAI Agents SDK、CrewAI、Google ADK、Vercel AI SDK、n8n 和 ChatGPT Custom GPTs 配合使用。设置示例请参阅 docs/integrations.md。

工具

OrionBelt 提供 26 个 MCP 工具。以下是按类别汇总的列表：

连接与架构

工具	描述
connect_database	使用 .env 凭据连接到任何受支持的数据库
list_databases	按名称和描述列出服务器上配置的数据库
list_schemas	列出已连接数据库中的可用架构
reset_cache	清除当前会话的缓存架构和本体数据
discover_schema	使用自动 GraphRAG 和本体生成分析架构结构
get_table_details	获取特定表的列、键和约束详细信息
cleanup_workspace	删除当前连接的所有工作区文件并重新开始

本体与语义

工具	描述
generate_ontology	根据架构生成带有 SQL 映射注释的 RDF/OWL 本体
suggest_semantic_names	检测缩写和晦涩名称，以便改用便于业务理解的名称
apply_semantic_names	将 LLM 建议的语义名称和描述应用到本体
load_my_ontology	从导入文件夹加载自定义 .ttl 本体文件
validate_relationship	根据数据检查关系，并将结论记录到本体中
download_artifact	将本体或 R2RML 映射下载为 Turtle 文件

查询与可视化

工具	描述
sample_table_data	预览表数据，并设置行数限制和注入防护
execute_sql_query	执行 SQL，并进行 OBQC 验证、安全检查和扇形陷阱检测
generate_chart	生成 Plotly 图表（柱状图、折线图、散点图、热力图），并使用 MCP-UI 渲染

GraphRAG

工具	描述
graphrag_search	语义搜索和架构概览（由 discover_schema 自动初始化）
graphrag_query_context	获取用于 SQL 生成的优化上下文（减少 85-95% 的 token）
graphrag_find_join_path	通过图遍历查找表之间的连接路径
reachable_from	锚点粒度可作为维度的表（多对一闭包）
measurable_from	锚点粒度可作为度量的表（一对多闭包）
plan_composite_query	为安全规避扇形陷阱的复合事实层（UNION ALL）提供分解建议

SPARQL 与 RDF

工具	描述
store_ontology_in_rdf	将本体持久化到 Oxigraph，以便通过 SPARQL 访问
query_sparql	执行 SPARQL 查询（SELECT、ASK、CONSTRUCT——自动检测）
add_rdf_knowledge	向 RDF 存储添加自定义元数据三元组

语义模型

工具	描述
save_semantic_model	将语义模型（例如 OBML YAML）保存到工作区
get_semantic_model	按名称检索已存储的语义模型
list_semantic_models	列出当前连接的所有已存储语义模型

完整的参数详情、返回值和示例，请参阅 docs/tools-reference.md。

典型工作流

完整分析会话：

connect_database("postgresql") -> discover_schema("public") -> generate_ontology() -> execute_sql_query(...)

快速数据探索：

connect_database("duckdb") -> list_schemas() -> sample_table_data("events")

使用可视化进行查询：

execute_sql_query(query) -> generate_chart(data, "bar", ...)

execute_sql_query 会在执行前运行 OBQC 验证、安全检查和扇陷检测，无需单独的验证步骤。

继续之前的会话（自动恢复工作区）：

connect_database("postgresql") -> execute_sql_query(...)

开发

uv sync 会安装所有依赖；uv run pytest、black/isort/ruff 和严格的 mypy 检查是合并门槛。开发指南包含完整的设置说明、项目布局和贡献检查清单。

在打开工作流文件之前，有一点值得了解：每个 GitHub Action 都固定到一个带有 # vX.Y.Z 注释的 40 字符提交 SHA，这就是为什么它们满是十六进制字符串。Git 标签是可移动的标签，因此 actions/checkout@v7 会在作业启动时运行该标签所指向的提交；SHA 则无法移动。注释写明确切的补丁版本，而不是 # v7，因为主版本标签会随着每次上游发布而移动。./scripts/check-action-pins.sh 会在上游解析每个标签；如果标签对应的提交不是固定的提交，就会失败——这正是区分真正升级与悄悄将哈希替换为来自分支版本的哈希的唯一方法。该脚本会在每个拉取请求中作为 pins 作业运行，也会作为两个发布工作流的第一步运行；--offline 会跳过上游查询，只检查 SHA 和注释格式。

文档

文档	内容
工具参考	完整的参数说明、返回值和用法示例
配置	环境变量、传输设置、故障排除
GraphRAG	基于图的架构智能和 OBML 工作流
OBQC 概览	简要说明 OBQC 在 OrionBelt Analytics 中的工作方式
OBQC	验证规则、严重级别、阻止行为、注释要求
扇陷防护	扇陷问题、检测方法和安全的 SQL 模式
集成	LangChain、OpenAI、CrewAI、Google ADK、Vercel、n8n、ChatGPT
开发	项目结构、测试、贡献

许可证

版权所有 2025-2026 RALFORION d.o.o.

根据 Business Source License 1.1 授权。授权作品将于 2030-03-16 转换为 Apache License 2.0。

向本项目贡献内容，即表示你同意 贡献者许可协议。

如有商业授权咨询，请联系：[email protected]

第三方软件

OrionBelt Analytics 基于开源软件构建。THIRD_PARTY_NOTICES.md 列出了每项捆绑依赖及其许可证，并特别说明了少数除署名外还附带其他义务的依赖（psycopg2 的 LGPL、wordfreq 的 CC-BY-SA 数据以及 MPL-2.0 组件）。

Docker 镜像会重新分发这些软件包，因此会在 /app/licenses/THIRD_PARTY_LICENSES.txt 中附带其许可证原文，并同时包含 /usr/share/doc/ 下的 Debian 版权文件。PyPI wheel 不捆绑任何第三方软件——它会声明依赖项，由安装程序从 PyPI 获取这些依赖。

---

版权 © 2026 RALFORION d.o.o.
OrionBelt® 是 RALFORION d.o.o. 的注册商标。