orionbelt-analytics

OrionBelt® Analytics

Text-2-SQL を便利に使える、オントロジーベースの MCP サーバー。

OrionBelt Analytics は、リレーショナルデータベースのスキーマを分析し、SQL マッピングを組み込んだ RDF/OWL オントロジーを生成する MCP サーバーです。リレーションシップを考慮した Text-to-SQL、自動的なファントラップ防止、インテリジェントなスキーマ探索を可能にする GraphRAG、インタラクティブなチャート機能を提供し、MCP 互換の AI クライアントから利用できます。

OrionBelt エコシステム

プロジェクト	目的
OrionBelt Analytics（本プロジェクト）	スキーマ分析、オントロジー生成、GraphRAG、テキストからの SQL 生成
OrionBelt Semantic Layer	宣言型 YAML モデルを、ダイアレクト固有でファントラップのない SQL にコンパイルします
OrionBelt Ontology Builder	推論機能とグラフ可視化を備えた、ビジュアルな OWL オントロジーエディター（ライブデモ）
OrionBelt Chat	Analytics + Semantic Layer 向け AI チャット UI（Chainlit、複数の LLM プロバイダー）

Claude Desktop で Analytics と Semantic Layer を並行して実行すると、スキーマを考慮したオントロジーの生成と、正確性が保証された SQL のコンパイルが可能になります。

アーキテクチャ

• 8 種類のデータベースコネクター -- PostgreSQL、MySQL、Snowflake、ClickHouse、Dremio、BigQuery、DuckDB/MotherDuck、Databricks SQL
• oba: 名前空間の SQL アノテーションと W3C R2RML マッピングによる RDF/OWL オントロジー生成
• GraphRAG -- グラフ探索（最大 12 ホップ）と ChromaDB のベクトル埋め込みを使用した、スキーマのセマンティック検索をローカルで実行します。多言語オプションを使うと、他の言語での質問からスキーマを検索できます（ドイツ語の 「Umsatz」 で 「Net revenue」 という名前のカラムを検索できます）
• 永続 Oxigraph RDF ストアを介した SPARQL 1.1 クエリーインターフェース
• OBQC 検証 -- オントロジーに基づく決定論的な SQL 検査（テーブル／カラムの存在、結合の妥当性、型の不一致、ファントラップ）
• インタラクティブなチャート作成 -- Claude Desktop での MCP-UI レンダリングに対応した Plotly チャート
• 複数スキーマのサポート -- 複数のスキーマを同時に分析します。オントロジーと GraphRAG の状態はスキーマごとに分離されます
• ワークスペースの永続化 -- 同じデータベースに再接続し、前回のセッションを復元します
• MCP サンプリング -- 接続先のクライアントがサンプリングに対応している場合（例：OrionBelt Chat）、suggest_semantic_names は sampling/createMessage を介してホストの LLM に、判読しにくい識別子の名前変更候補を事前入力するよう依頼します。これにより、確認してから適用する従来の手順を 1 回のツール呼び出しにまとめます。サンプリングに対応していないクライアント（例：Claude Desktop）では、手動確認の手順に自動的に切り替わります

OBQC -- オントロジーベースのクエリチェック

OrionBeltの大きな差別化要因は、データベースにクエリが到達する前にエラーを検出する、決定論的なルールベースのSQLバリデーター OBQC（オントロジーベースのクエリチェック）です。「正しく処理する」ことをモデルに頼るLLMのみのアプローチとは異なり、OBQCは生成されたすべてのSQL文を読み込まれたRDF/OWLオントロジーと照合し、構造上の正しさを保証します。

OBQCの検証内容：

チェック	検出する問題
テーブルの存在確認	スキーマに存在しないテーブルへの参照
カラムの存在確認	テーブルに存在しないカラムへの参照、修飾されていない曖昧なカラム
結合の妥当性	結合条件の欠落（直積）、宣言された外部キーと一致しない結合カラム
型の互換性	互換性のない型同士のWHERE/ON比較（例：文字列と整数）
集約の正しさ	集約関数の使用時にGROUP BYに含まれていないSELECTカラム
ファントラップの検出	複数の1対多結合をまたぐ集約による、結果の暗黙的な重複増加

仕組み：

1. generate_ontologyまたはload_my_ontologyは、OWLクラスとプロパティを実際のデータベースのテーブル、カラム、型、外部キーに対応付けるoba:名前空間アノテーションを含むオントロジーを作成または読み込みます。
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を編集して、データベースの認証情報を設定します。最低限、1つのデータベースの変数を設定してください（例：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	OBQC 検証、セキュリティチェック、ファントラップ検出を行いながら SQL を実行します
generate_chart	MCP-UI レンダリングで Plotly チャート（棒、折れ線、散布図、ヒートマップ）を生成します

GraphRAG

ツール	説明
graphrag_search	セマンティック検索とスキーマ概要を提供します（discover_schema により自動初期化されます）
graphrag_query_context	SQL 生成に最適化されたコンテキストを取得します（トークンを 85～95％削減）
graphrag_find_join_path	グラフ探索によりテーブル間の結合パスを検出します
reachable_from	アンカー粒度からディメンションとして利用可能なテーブルを返します（多対一の閉包）
measurable_from	アンカー粒度からメジャーとして利用可能なテーブルを返します（一対多の閉包）
plan_composite_query	ファントラップを回避する複合ファクトレイヤー（UNION ALL）の分解を提案します

SPARQL と RDF

ツール	説明
store_ontology_in_rdf	SPARQL アクセスのためにオントロジーを Oxigraph に永続化します
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で固定されているため、16進数の文字列だらけです。Gitタグは移動可能なラベルなので、actions/checkout@v7はジョブ開始時にそのラベルが指しているコミットを実行します。一方、SHAは移動しません。メジャータグは上流でリリースがあるたびに移動するため、コメントには# v7ではなく、正確なパッチリリースを記載しています。./scripts/check-action-pins.shは上流の各タグを解決し、タグが指すコミットが固定されているものと一致しない場合に失敗します。これにより、正規の更新と、フォーク由来のハッシュへの気付かれにくい差し替えを区別できます。このスクリプトは、すべてのプルリクエストでpinsジョブとして実行され、両方の公開ワークフローでは最初のステップとして実行されます。--offlineを指定すると上流への照会を省略し、SHAとコメントの形式だけをチェックします。

ドキュメント

ドキュメント	内容
ツールリファレンス	パラメーター、戻り値、使用例の詳細
設定	環境変数、トランスポートの設定、トラブルシューティング
GraphRAG	グラフベースのスキーマインテリジェンスとOBMLワークフロー
OBQCの概要	OrionBelt AnalyticsにおけるOBQCの仕組みの簡単な説明
OBQC	検証ルール、重大度レベル、ブロック動作、注釈の要件
ファントラップの防止	ファントラップの問題、検出、安全なSQLパターン
インテグレーション	LangChain、OpenAI、CrewAI、Google ADK、Vercel、n8n、ChatGPT
開発	プロジェクト構成、テスト、コントリビューション

ライセンス

Copyright 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 から取得します。

---

Copyright © 2026 RALFORION d.o.o.
OrionBelt® は RALFORION d.o.o. の登録商標です。