OrionBelt Analytics

Онтологический MCP-сервер для удобной работы с Text-2-SQL.

OrionBelt Analytics — MCP-сервер, который анализирует схемы реляционных баз данных и генерирует RDF/OWL-онтологии со встроенными SQL-маппингами. Предоставляет Text-to-SQL с учётом связей между таблицами и автоматической защитой от fan-trap, GraphRAG для интеллектуального обнаружения схемы и интерактивные графики — всё доступно через любой MCP-совместимый AI-клиент.

Экосистема OrionBelt

Проект	Назначение
OrionBelt Analytics (этот)	Анализ схем, генерация онтологий, GraphRAG, Text-to-SQL
OrionBelt Semantic Layer	Декларативные YAML-модели, компилируемые в диалект-специфичный SQL без fan-trap
OrionBelt Ontology Builder	Визуальный редактор OWL-онтологий с рассуждением и графической визуализацией (live demo)
OrionBelt Chat	AI-чат для Analytics + Semantic Layer (Chainlit, несколько LLM-провайдеров)

Запустите Analytics и Semantic Layer параллельно в Claude Desktop для схемно-осознанной генерации онтологий и гарантированно корректной компиляции SQL.

Архитектура

8 коннекторов к базам данных — PostgreSQL, MySQL, Snowflake, ClickHouse, Dremio, BigQuery, DuckDB/MotherDuck, Databricks SQL
Генерация RDF/OWL-онтологий с SQL-аннотациями в пространстве имён oba: и маппингами W3C R2RML
GraphRAG — обход графа (до 12 переходов) + векторные эмбеддинги ChromaDB для семантического обнаружения схемы
Интерфейс SPARQL 1.1 через постоянное RDF-хранилище Oxigraph
Валидация OBQC — детерминированные SQL-проверки на соответствие онтологии (существование таблиц/столбцов, корректность JOIN, несоответствие типов, fan-trap)
Интерактивные графики — Plotly-диаграммы с MCP-UI рендерингом в Claude Desktop
Поддержка нескольких схем — одновременный анализ нескольких схем; состояние онтологии и GraphRAG изолировано для каждой схемы
Сохранение рабочего пространства — повторное подключение к той же базе данных с восстановлением предыдущей сессии
MCP sampling — если клиент поддерживает sampling (например, OrionBelt Chat), suggest_semantic_names запрашивает у хост-LLM предложения по переименованию криптических идентификаторов через sampling/createMessage. Клиенты без sampling (например, Claude Desktop) автоматически переходят к ручному пути

OBQC — Ontology-Based Query Check

Ключевое отличие OrionBelt — OBQC (Ontology-Based Query Check): детерминированный, основанный на правилах SQL-валидатор, перехватывающий ошибки до того, как запросы достигают базы данных. В отличие от подходов, полагающихся только на LLM, OBQC сверяет каждый сгенерированный SQL-оператор с загруженной RDF/OWL-онтологией, обеспечивая структурную корректность.

Что проверяет OBQC:

Проверка	Что обнаруживает
Существование таблиц	Ссылки на таблицы, отсутствующие в схеме
Существование столбцов	Ссылки на несуществующие столбцы, неоднозначные неквалифицированные столбцы
Корректность JOIN	Отсутствующие условия JOIN (декартовы произведения), столбцы JOIN, не совпадающие с объявленными внешними ключами
Совместимость типов	Сравнения WHERE/ON между несовместимыми типами (например, строка и целое число)
Корректность агрегации	Столбцы SELECT, отсутствующие в GROUP BY при использовании агрегатов
Обнаружение fan-trap	Агрегации через несколько связей «один ко многим», которые молча умножают результаты

Принцип работы:

generate_ontology или load_my_ontology создаёт/загружает онтологию с аннотациями в пространстве имён oba:, связывающими классы и свойства OWL с реальными таблицами, столбцами, типами и внешними ключами.
При вызове execute_sql_query OBQC парсит SQL с помощью sqlglot и проверяет каждую таблицу, столбец, JOIN и агрегацию на соответствие схемной модели онтологии.
Проблемы возвращаются с уровнями серьёзности (error, warning, info) вместе с результатами запроса, чтобы LLM мог исправиться до того, как пользователь увидит неверные данные.

OBQC полностью детерминирован — никаких вызовов LLM, никакого вероятностного рассуждения. Действует как страховочная сеть, дополняя генерацию SQL от LLM жёсткими структурными гарантиями. Ошибки блокируют выполнение запроса; предупреждения прикладываются к ответу для обработки LLM.

Быстрый старт

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).

3. Запуск

uv run server.py

Сервер стартует на http://localhost:9000 (HTTP transport, порт настраивается через 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

Установите MCP_TRANSPORT=sse в .env, перезапустите сервер, затем добавьте в librechat.yaml:

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

Другие фреймворки

OrionBelt работает с LangChain, OpenAI Agents SDK, CrewAI, Google ADK, Vercel AI SDK, n8n и ChatGPT Custom GPTs.

Инструменты

OrionBelt предоставляет 26 MCP-инструментов, сгруппированных по категориям:

Подключение и схема

Инструмент	Описание
`connect_database`	Подключение к любой поддерживаемой БД по учётным данным из `.env`
`list_schemas`	Список доступных схем в подключённой БД
`reset_cache`	Очистка кэша схемы и онтологии для текущей сессии
`discover_schema`	Анализ структуры схемы с автоматической генерацией GraphRAG + онтологии
`get_table_details`	Подробная информация о столбцах, ключах и ограничениях для конкретной таблицы
`cleanup_workspace`	Удаление всех файлов рабочего пространства для текущего подключения

Онтология и семантика

Инструмент	Описание
`generate_ontology`	Генерация RDF/OWL-онтологии из схемы с аннотациями SQL-маппингов
`suggest_semantic_names`	Обнаружение аббревиатур и криптических имён для удобного переименования
`apply_semantic_names`	Применение предложенных LLM семантических имён и описаний к онтологии
`load_my_ontology`	Загрузка пользовательского файла онтологии `.ttl` из папки импорта
`download_artifact`	Скачивание онтологии или R2RML-маппинга как Turtle-файла

Запросы и визуализация

Инструмент	Описание
`sample_table_data`	Предпросмотр данных таблицы с ограничением строк и защитой от инъекций
`execute_sql_query`	Выполнение SQL с валидацией OBQC, проверками безопасности и обнаружением fan-trap
`generate_chart`	Генерация Plotly-диаграмм (bar, line, scatter, heatmap) с MCP-UI рендерингом

GraphRAG

Инструмент	Описание
`graphrag_search`	Семантический поиск + обзор схемы (автоинициализируется через `discover_schema`)
`graphrag_query_context`	Оптимизированный контекст для генерации SQL (снижение токенов на 85–95%)
`graphrag_find_join_path`	Обнаружение путей JOIN между таблицами через обход графа
`reachable_from`	Таблицы-измерения, доступные из опорного зерна (замыкание «многие к одному»)
`measurable_from`	Таблицы-меры, доступные из опорного зерна (замыкание «один ко многим»)
`plan_composite_query`	Рекомендации по безопасному от fan-trap разложению Composite Fact Layer (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`	Список всех сохранённых семантических моделей для текущего подключения

Типичные рабочие процессы

Полная аналитическая сессия:

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, проверки безопасности и обнаружение fan-trap перед выполнением — отдельный шаг валидации не нужен.

Возобновление предыдущей сессии (автовосстановление рабочего пространства):

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

Документация

Документ	Содержание
Tools Reference	Полная документация параметров, возвращаемые значения и примеры использования
Configuration	Переменные окружения, настройка транспорта, устранение неполадок
GraphRAG	Графовая аналитика схемы и рабочий процесс OBML
OBQC	Правила валидации, уровни серьёзности, блокирующее поведение
Fan-Trap Prevention	Проблема fan-trap, обнаружение и безопасные SQL-паттерны
Integrations	LangChain, OpenAI, CrewAI, Google ADK, Vercel, n8n, ChatGPT

Лицензия

Лицензирован по Business Source License 1.1. Лицензируемый продукт перейдёт под Apache License 2.0 с 2030-03-16.

По вопросам коммерческого лицензирования: licensing@ralforion.com

Orionbelt AnalyticsOrionBelt Analytics

Установка