Orionbelt Semantic Layer

关键词

数据库连接本体生成关系模式分析Fan-Trap防护交互式数据可视化

项目简介

Orionbelt Semantic Layer 是一个生产级的Python MCP服务器，专注于连接 PostgreSQL、Snowflake 和 Dremio 等关系型数据库，自动分析数据库模式信息，并生成符合语义网标准的RDF/OWL本体。它通过本体提供丰富的语义上下文，支持LLM客户端进行准确的文本转SQL查询，自动防范Fan-Trap问题，并集成了安全的SQL验证与执行机制，附带交互式数据可视化功能。

主要功能点

  • 数据库连接与管理：支持PostgreSQL、Snowflake和Dremio，包含连接池、重试及超时管理。
  • 自动模式分析：获取数据库表、列、主键、外键及注释，并缓存模式信息供快速复用。
  • 语义本体生成：构建带有数据库专用注释的RDF/OWL语义本体，支持本体加载和语义验证。
  • R2RML映射生成：自动创建W3C标准的关系数据库到RDF的映射文件，便于数据集成。
  • Fan-Trap检测与防护：识别多对多聚合陷阱，提供安全联结和Union All模式建议。
  • SQL语法及安全验证：结合模式和本体进行静态语法检测，阻止注入和危险操作。
  • 安全SQL执行：受限结果规模，支持多种安全模式，实时性能监控。
  • 交互式图表生成：集成Plotly和Matplotlib，生成静态或动态图表，可嵌入Claude Desktop。
  • 会话隔离管理：每个用户会话独立管理数据库连接及本体状态，保障隔离和安全。
  • 与主流LLM客户端集成支持：内建Claude Desktop和LibreChat示例配置说明。

安装步骤

  1. 克隆代码库：

    git clone https://github.com/ralfbecher/database-ontology-mcp
cd database-ontology-mcp

  2. 确保系统已安装Python 3.13及以上。

  3. 使用推荐的'uv'包管理安装所有依赖：

    uv sync

    或手动创建虚拟环境并安装依赖：

    python3.13 -m venv .venv
source .venv/bin/activate   # Windows使用 .venv\Scripts\activate
pip install -e .

  4. 创建并编辑 '.env' 文件配置数据库及服务器参数，示例：

    POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=mydb
POSTGRES_USERNAME=user
POSTGRES_PASSWORD=pass

MCP_TRANSPORT=http
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=9000

ONTOLOGY_BASE_URI=http://example.com/ontology/
R2RML_BASE_IRI=http://mycompany.com/
OUTPUT_DIR=tmp

服务器配置（示例供MCP客户端使用）

{
  "name": "Orionbelt-Semantic-Layer",
  "command": "uv",
  "args": ["run", "server.py"],
  "description": "启动Orionbelt Semantic Layer MCP服务器，支持PostgreSQL, Snowflake, Dremio数据库",
  "env": {
    "MCP_TRANSPORT": "http",
    "MCP_SERVER_HOST": "localhost",
    "MCP_SERVER_PORT": "9000"
  }
}
  • name: MCP服务器显示名
  • command: 启动服务器的命令行工具（此处为'uv'）
  • args: 启动脚本及参数
  • env: 环境变量配置，包含MCP协议传输类型、主机与端口

基本使用方法

  1. 启动服务器：

    uv run server.py

  2. 在LLM客户端（如Claude Desktop）配置并连接MCP服务器（参考上文JSON配置）。

  3. 推荐工作流程：

    • 连接数据库：调用'connect_database(db_type)'，支持'postgresql|snowflake|dremio'
    • 列出模式：调用'list_schemas()'
    • 模式分析：调用'analyze_schema(schema_name)'，生成包含关系的完整模式信息
    • 生成本体：调用'generate_ontology(schema_name)'，创建语义本体文件
    • 语义名称建议：调用'suggest_semantic_names()'获取语义改善建议
    • 应用语义名称：调用'apply_semantic_names(suggestions)' 将LLM建议应用到本体
    • SQL验证：调用'validate_sql_syntax(sql_query)'确保查询安全与合理
    • 执行查询：调用'execute_sql_query(sql_query, limit, checklist_completed=True)'安全执行
    • 数据可视化：调用'generate_chart(data_source, chart_type, x_column, y_column)'生成图表

  4. 其他辅助操作：

    • 加载自定义本体：调用'load_my_ontology(import_folder)'
    • 清理缓存：调用'reset_cache()'清除模式及本体缓存

  5. 参考代码库'README.md'及示例提供的详细操作指导。

服务器信息

访问项目