Orionbelt Semantic Layer

OrionBelt® Semantic Layer MCP

OrionBelt® Semantic Layer REST API に処理を委譲する薄型 MCP サーバー

すべてのビジネスロジックを HTTP 経由で OrionBelt® Semantic Layer REST API に委譲する薄型の MCP サーバーです。組み込みエンジンはなく、API をそのまま中継します。

アーキテクチャ

OrionBelt® Semantic Layer プラットフォームには、2 つのデプロイモードがあります。この MCP サーバーはどちらにも対応しています。

• スタンドアロン — OrionBelt® Semantic Layer API を Cloud Run、Docker、localhost など任意の環境にデプロイし、API_BASE_URL を介してこの MCP サーバーから接続します。
• ホステッド — ローカルでのセットアップを一切行わず、公開されている Cloud Run のデプロイに接続します（下記の ホステッド MCP サーバー を参照してください）。

┌────────────┐       ┌──────────────────────────────────────────────────────┐
│ LLM Client │       │                OrionBelt® Platform                   │
│            │       │                                                      │
│  Claude,   │──MCP──│──> server.py  ──HTTP /v1──>  Semantic Layer REST API │
│  Cursor,   │       │    (FastMCP                   (FastAPI: parse OBML,  │
│  any MCP   │       │     + httpx)                   validate, compile     │
│  client    │       │                                to SQL)               │
└────────────┘       └──────────────────────────────────────────────────────┘

• ビジネスロジックなし — すべてのツール呼び出しは REST API（v1 エンドポイント）に委譲されます。
• デュアルモード — 起動時にシングルモデルまたはマルチモデルの API モードを自動検出します。
• セッション管理の自動化 — 最初のツール呼び出し時に API セッションを作成し、その ID をキャッシュします（マルチモデルモード）。
• クエリ（QueryObject）、実行、バッチ、検出、ディメンション値検索、構成可能性（ACR）、サンプル、図、RDF/SPARQL、アーティファクトとクエリのリネージ、ビジネスルール（一覧、説明、評価）、オントロジーリンク（概念マッピング、名前空間、未マッピングのアーティファクト）、OSI エクスポート、モデル検証（オフラインまたは稼働中のデータソースに対して）、OBML リファレンス + 関数カタログ + JSON スキーマのためのツール 26 個（シングルモデルモード）またはツール 30 個（マルチモデルモード）があります。（全体では異なるツールが 31 個あります。API モードによって有効になるサブセットが選択され、25 個は重複します。クライアントが 31 個すべてを同時に利用することはありません。）設計時フェーズおよびクエリ実行が無効な場合は、表示される機能がさらに絞り込まれます（設計時と実行時のツール切り替え を参照してください）。
• OBML / OBSQL リファレンス、ビジネスルール、利用ガイダンスのためのプロンプト 5 個 + リソース 2 個

ライブデモ

OrionBelt® Semantic Layer API の公開デモは、以下で利用できます。

API エンドポイント： https://orionbelt.ralforion.com — Swagger UI | ReDoc | Gradio UI

.env ファイルで API_BASE_URL=https://orionbelt.ralforion.com を設定して利用します（.env.example を参照してください）。

インストール

uv sync

開発用（pytest、respx、ruff を含みます）：

uv sync --all-groups

使い方

stdio（デフォルト）

uv run server.py

HTTP トランスポート

MCP_TRANSPORT=http uv run python server.py

HTTP トランスポートはデフォルトで ステートレス に実行されます（MCP_STATELESS_HTTP=true）。 各リクエストは独立しており、Mcp-Session-Id、ストリームの再開機能、サーバー起点のメッセージはありません。この構成では状態を必要とする処理はありません。ツールフェーズは接続ではなく明示的に読み込まれたモデルの状態から決まり、進捗、サンプリング、エリシテーションのリクエストを送信するツールもありません。そのため、インスタンスはセッションアフィニティなしでロードバランサーの背後に配置できます。接続ごとのセッションを復元するには MCP_STATELESS_HTTP=false を設定します。sse は接続ごとの長時間ストリームであるため、常にステートフルで実行されます。

これは トランスポート セッションのみを指す点に注意してください。上流 API セッションと読み込まれたモデルのセットはプロセス全体で共有され、インスタンスのすべてのクライアントで共通です。このフラグによる変更はありません。

トランスポートのセキュリティ

HTTP/SSE トランスポートはTLS を終端せず、呼び出し元を認証しません。 その両方を行う前段のイングレスを想定しています。これは別々の役割であり、 デフォルトですべてを担ってくれるプラットフォームはありません。

想定されているデプロイ先の Cloud Run では、TLS は自動的に有効になります。 サービス URL は HTTPS で提供され、プレーン HTTP はコンテナーに転送されます。 アクセス制御は自動ではありません。 これはデプロイ時に選択するもので、 IAM 呼び出し元権限、--ingress による制限、または前段に置く認証付きロードバランサーの いずれかで設定します。どれも設定しない場合、--allow-unauthenticated によって、 URL を知っている人なら誰でも、認証情報なしで HTTPS 経由でサービスにアクセスできます。 暗号化されていることと、アクセスが制限されていることは別です。

この違いは、2 つの通信経路で答えが異なるため重要です。

通信経路	セキュリティ
MCP クライアント → このサーバー	stdio：子プロセスへのパイプであり、ソケットはまったく使用しません。http/sse：前段のイングレスが提供するものに従います。イングレスがなければ何もありません
このサーバー → API	API_BASE_URL が https:// の場合（デフォルト）、常に TLS を使用し、httpx のデフォルト CA バンドル（certifi）に対して証明書を検証します。プライベート CA の場合は API_CA_CERT に対して検証します。API_CLIENT_CERT を設定すると、相互 TLS 用のクライアント証明書を追加します。verify=False はなく、http:// の URL を使う以外に TLS を無効にする方法はありません

HTTP トランスポートを直接公開するのは避けるべきです。ポートに到達できるものなら何でも、 登録されているすべてのツールを呼び出せます。機能が有効な場合の execute_query も含まれます。 その場合、このサーバー自身の API_KEY を API に対して使用でき、通信経路上で読み取れる状態になります。 認証情報そのものがこの通信経路を通過することはありませんが、それによって得られるアクセス権は通過します。

サーバーはこれを検出すると、起動時に警告します。Cloud Run 以外で、ループバック以外の アドレスにバインドされた http/sse トランスポートがあり、MCP_BEHIND_PROXY=true が 設定されていない場合です。MCP_SERVER_HOST をループバックにバインドするか、 認証付き TLS イングレスを前段に配置するか、サーバーからは確認できないプロキシがあることを 示すために MCP_BEHIND_PROXY=true を設定してください。

Cloud Run では、この警告の代わりに情報メッセージをログに記録し、まだユーザー側で対応が 必要な部分を示します。TLS は処理されますが、アクセス制御はデプロイ時の設定によります。 ここで何も表示されないからといって、サービスへのアクセスが制限されている証拠にはなりません。 プロセスは自身の IAM ポリシーやイングレス設定を読み取れないためです。上記の 3 つのいずれかが 設定されていることを確認してください。設定されている場合は、MCP_BEHIND_PROXY=true によって その状態を記録し、このメッセージを表示しないようにできます。

API 自身の *_TLS_* 設定はサーバー側のものであり、ここではどれも読み取られません。 PGWIRE_TLS_* と FLIGHT_TLS_*（2.28.0）は、このサーバーが接続することのない リスナーを保護します。API_TLS_*（2.29.0）は REST API 自体に HTTPS を提供させ、 API_TLS_CLIENT_CA はクライアント証明書を必須にします。以下の設定は、そのために使います。

API への TLS 接続

API がプライベート CA の証明書で HTTPS を提供する場合、または相互 TLS を必須とする場合 （API の API_TLS_CLIENT_CA、あるいは前段でクライアント証明書を要求するゲートウェイ）には、 このサーバーに証明書などのファイルを指定してください。

API_BASE_URL=https://obsl.internal:8000
API_CA_CERT=/certs/ca.crt            # trust this CA instead of the default store
API_CLIENT_CERT=/certs/mcp.crt       # present this certificate…
API_CLIENT_KEY=/certs/mcp.key        # …with this key (omit if it is in the same PEM)

証明書はすべてのトランスポートでサーバーの起動時に読み込まれます。そのため、パスが存在しない、 読み取り不能、または指定内容と異なる場合は、HTTP クライアント内で後から SSL エラーが発生するのではなく、 設定名とファイル名を示して起動が停止します。起動時のバナーにある API TLS: の行には、 この通信経路で最終的に使用された設定が表示されます。

• API_CA_CERT はデフォルトの信頼ストアを置き換えるものであり、拡張するものではありません。 未設定の場合、httpx のデフォルト（certifi、または SSL_CERT_FILE / SSL_CERT_DIR）を使って検証します。 クライアント証明書を追加しても、この設定は変わりません。
• これらの設定には https:// の API_BASE_URL が必要です。 http:// ではハンドシェイクがないため、 証明書を提示することも検証することもできません。この構成は TLS として誤解されないよう、拒否されます。
• パスワードで保護されたキーは拒否され、入力を求められることもありません。 stdio では標準入力が MCP のパイプであるため、OpenSSL の端末入力要求によってプロトコルが破損したり、処理が停止したりします。 復号済みのキーを指定し、ファイル権限またはシークレットマウントで保護してください。

MCP クライアントの設定

MCP クライアントの設定に追加します（例：claude_desktop_config.json）。

{
  "mcpServers": {
    "orionbelt": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/orionbelt-semantic-layer-mcp"
    }
  }
}

設定

環境変数または.envファイル（pydantic-settings）を使用します。デフォルト値については.env.exampleを参照してください。

変数	デフォルト値	説明
API_BASE_URL	—（必須）	OrionBelt® Semantic Layer REST API の URL
API_KEY	—（未設定）	API 認証情報。API が AUTH_MODE=api_key で実行されている場合にのみ必要です
API_KEY_HEADER	X-API-Key	認証情報を送信するヘッダー。API の API_KEY_HEADER と一致する必要があります
API_CA_CERT	—（未設定）	API の検証に使用する PEM CA バンドル。デフォルトのトラストストアを置き換えます。プライベート CA 用です。https:// の API_BASE_URL が必要です。詳しくはAPI への TLS 接続を参照してください
API_CLIENT_CERT	—（未設定）	API に提示する PEM クライアント証明書。相互 TLS 用（API の API_TLS_CLIENT_CA、または証明書を要求するゲートウェイ）
API_CLIENT_KEY	—（未設定）	API_CLIENT_CERT 用の PEM 秘密鍵。鍵が同じファイルに含まれている場合は省略します。暗号化されていない鍵のみ
MCP_TRANSPORT	stdio	stdio、http、または sse
MCP_SERVER_HOST	localhost	HTTP/SSE のバインド先ホスト
MCP_SERVER_PORT	9000	HTTP/SSE のバインド先ポート
MCP_BEHIND_PROXY	false	HTTP トランスポートの前段にあり、TLS を終端し、かつ呼び出し元を認証するイングレスがあることを明示します。どちらか一方ではなく、両方が必要です。公開に関する警告を抑制するだけであり、サーバーに機能を付与したり、動作を変更したりするものではありません
MCP_STATELESS_HTTP	true	接続ごとの MCP セッション（Mcp-Session-Id、ストリームの再開機能なし）を使用せずに HTTP トランスポートを実行し、セッションアフィニティなしでインスタンスをスケールできるようにします。stdio では無視され、sse では強制的にオフになります
LOG_LEVEL	INFO	ログレベル
API_TIMEOUT	30	HTTP タイムアウト（秒）

ツール

モデルのライフサイクル

MCP ツール	説明
get_obml_reference()	OBML フォーマット仕様の全文を返します
load_model(model? | osi_yaml?, dedup=True)	モデルを解析、検証して保存します（health と model_load を返します）。model（OBML JSON）または osi_yaml（OSI YAML。サーバー側で OBML に変換）を渡します
validate_model(model? | model_yaml?, extends?, inherits?, online=False, dialect?)	モデルを読み込まずに検証します。online=True を指定すると、宣言されたすべてのテーブルと列について、設定済みデータソースも調査します。これにより、構造チェックでは検出できない差異（DATASOURCE_*）を報告します。extends / inherits はマルチモデル専用です。ステートレスルートのシングルモデルモードでは両方が無視されるため、黙って破棄する代わりに指定を拒否します
describe_model(model_id)	データオブジェクト、ディメンション、メジャー、メトリクスを調べます
remove_model(model_id)	現在のセッションからモデルを削除します
list_models()	現在のセッションに読み込まれているすべてのモデルを一覧表示します
export_model_to_osi(model_id, ...)	読み込み済みのモデルを OSI YAML としてエクスポートします

モデルの検索

MCP ツール	説明
find_artefacts(model_id, query?, kind?, name?)	成果物を検索します。query を指定すると → あいまい検索とランキング（あいまいな用語を解決します：完全一致／同義語／あいまい一致）。query を指定しないと → 完全一致の決定的な検索（すべての成果物、1 種類の成果物、または名前を指定した成果物 1 つを、完全なレコードで返します）
explain_artefact(model_id, name)	ディメンション、メジャー、またはメトリックの系譜を説明します
search_values(dimension, search?, where_json?, limit?, dialect?, model_id?)	ディメンション値の検索 — フィルター値を指定する前に、その値を確かめます（Germany と DE と GERMANY）。search を指定すると → 完全一致／前方一致／部分一致／あいまい一致でランキング検索します。指定しない場合は → リストされた値、または日付／数値ディメンションの最小値と最大値を返します。クエリを実行するため、クエリ実行が必要です。valueSearch: false を宣言したディメンションは拒否されます
get_lineage(name? | query_json?, kind?, dialect?, output_format="text", model_id)	ディメンション、メジャー、メトリック、またはビジネスルールの系譜グラフを返します。クエリ全体を指定することもでき、その場合はプランナーが選択した結合（pathName とロール結合を含む）から、読み取り対象のテーブルまでをたどります。kind は省略可能です（すべての種類を試します。メジャーと同じ名前のルールがある場合は両方を返します）。output_format：text、mermaid、turtle（OBSL グラフの IRI に対する prov:wasDerivedFrom。get_model_graph とマージします）、または json
list_examples(model_id, intent?)	作成済みのクエリ例を一覧表示します（インテントタグで絞り込み可能です）
get_example(model_id, name)	クエリとコンパイル済み SQL のプレビューを含む、1 つの例を取得します
get_join_graph(model_id)	結合グラフを隣接リストとして返します
find_composables(query_json?, anchors?, anchor_type?, model_id?)	ACR — 進行中のクエリまたは名前付きアンカーを基に、有効でファンアウトのない結果に引き続き組み合わせ可能なディメンション／メジャー／メトリック（および CFL の候補）を返します。コンパイルが保証されます

クエリ、実行、図

MCP ツール	説明
execute_query(...)	QueryObject をコンパイルして実行し、SQL と行を返します
run_batch(queries, ...)	1 回の操作でモデルを読み込み、N 個のクエリを並列実行します
get_model_diagram(model_id)	読み込み済みモデルの Mermaid ER 図を生成します

セマンティックグラフ（RDF／SPARQL）

MCP ツール	説明
get_model_graph(model_id)	モデルを OBSL-Core RDF（Turtle）として返します
query_model_graph_by_sparql(query, ...)	読み取り専用の SPARQL クエリ（SELECT／ASK）を実行します

ビジネスルール

MCP ツール	説明
list_rules(model_id)	モデルの rules: と、タイプ、レベル（行レベル／集計）、重大度、実行可能性ごとの統計を返します
explain_rule(name, model_id)	ルールの詳細を返します。定義、参照するデータ、背後にあるテーブル、依存関係、オントロジーへのリンク、およびコンパイル後の SQL を含みます
evaluate_rule(name, limit?, dialect?, format_values?, model_id)	1 つのルールを実行し、結果を一覧表示します。分類／適格性の場合はメンバー、検証／制約の場合は違反を返します。クエリ実行が有効である必要があります
evaluate_rules(types?, severities?, executable_only?, max_rules?, limit=5, dry_run?, dialect?, model_id)	すべてのルール（または一部のルール）を実行し、ルールごとのステータス、件数、サンプル結果、エラーを含むレポートを返します。dry_run=True の場合はコンパイルのみを行い、実行が無効でも動作します

オントロジーリンク（外部概念マッピング）

MCP ツール	説明
find_concept_mappings(concept?, namespace?, relation?, types?, model_id)	externalConceptMappings の各エントリーについて、成果物、SKOS 関係、展開された IRI、来歴を返します。概念、名前空間、関係、成果物タイプで絞り込めます
list_concept_namespaces(model_id)	モデルがリンクしている外部オントロジーを使用頻度の高い順に返し、どのマッピングでも使われていない宣言済みプレフィックスも表示します
list_unmapped_artefacts(types?, model_id)	マッピング対象範囲内にあり、まだリンクされていない成果物を返します

リファレンス

MCP ツール	説明
get_obml_reference()	OBML（モデル作成）文法のリファレンス
get_function_catalog()	OBML 式で使用できる移植可能なスカラー関数と、固定されたクロスダイアレクトのセマンティクスを返します
get_json_schema(name)	obml（モデル）または query（QueryObject）の JSON Schema を返します

ユーティリティ

MCP ツール	説明
list_dialects()	利用可能な SQL ダイアレクトと機能を一覧表示します

設計時と実行時のツール切り替え

サーバーはフェーズに応じたツールセットを提示します。すべてのツールを一度に一覧表示するのではなく、 モデルのライフサイクルのどの段階にいるかに応じて、適切なツールのみを表示します。ツールのおよそ半分は モデルを読み込むまで意味を持ちません（execute_query、describe_model、find_artefacts など）。残りは モデルの作成やリファレンスに関するものです（get_obml_reference、get_function_catalog、 get_json_schema、validate_model、list_dialects）。これらを分けることでツールセットを小さく保ち、 モデルが読み込まれていない状態でクエリツールを呼び出すような、一連のエラーを防止します。

3 つのバケットをフェーズごとに切り替え

ツールは 3 つのバケットに分かれます。表示されるツール群は、ロード／アンロード時に切り替わるものであり、追加されるわけではありません。実行フェーズでは、設計／リファレンスツールは表示されません。

バケット	表示されるタイミング	ツール
常時	常に（両方のフェーズ）	load_model、remove_model（遷移用の動詞。実行フェーズでも引き続き利用可能なため、セッション中に 2 つ目のモデルをロードできます。上限は max_models_per_session です）；run_batch と validate_model（自己完結型で、それぞれモデルをインラインで受け取るため、事前のセッション状態は不要です）；get_json_schema（QueryObject／OBML スキーマ。両方のフェーズで必要です）
設計専用	モデルがロードされていない場合のみ	get_obml_reference、get_function_catalog、list_dialects
実行専用	モデルがロードされている場合のみ	describe_model、get_model_diagram、find_artefacts、explain_artefact、search_values、get_lineage、execute_query、list_examples、get_example、get_model_graph、get_join_graph、find_composables、query_model_graph_by_sparql、list_rules、explain_rule、evaluate_rule、evaluate_rules、find_concept_mappings、list_concept_namespaces、list_unmapped_artefacts、list_models、export_model_to_osi

                       load_model  (returns "re-list" signal)
   ┌─────────────────┐ ────────────────────────────────▶ ┌───────────────┐
   │ design phase    │                                   │ run phase     │
   │ always + design │ ◀───────────────────────────────  │ always + run  │
   └─────────────────┘  remove_model (last model) / TTL  └───────────────┘
                        expiry — back to design phase

つまり、設計フェーズ → 常時 + 設計専用、実行フェーズ → 常時 + 実行専用です。 モデルがロードされると設計／リファレンスツールは非表示になり、実行時のツール群はクエリに集中します。

再一覧表示

MCP の tools/list レスポンスは、アクティブなフェーズに合わせてフィルタリングされます。ステートレスな MCP 仕様ではプッシュ通知（notifications/tools/list_changed）が確実に機能しないため、遷移はプルベースです。load_model（設計 → 実行）と remove_model（実行 → 設計、モデルが残っていない場合）は、ツール群が切り替わったことをクライアントに知らせ、ツールを再一覧表示するよう促す短いシグナルを返します。

早すぎる呼び出しを防止

クライアントが設計フェーズ中に実行専用の動詞を呼び出した場合（まだ再一覧表示していない古いホストなど）、サーバーは不透明な失敗ではなく、構造化エラーを返します。

モデルがロードされていません — 'execute_query' は実行時ツールであり、まだ利用できません。まず load_model を呼び出してから、ツールを再一覧表示してください。

機能によるゲーティング（フェーズとは独立）

ライフサイクルのフェーズとは別に、サーバーがその機能をサポートしないように_設定_されているために、ツールが非表示になることがあります。クエリを実行するツールである execute_query、evaluate_rule、search_values は、API の query_execute 機能によって制御されます。サーバーがコンパイル専用で動作している場合、これらは tools/list から除外され、呼び出すと構造化エラーが返されます。これはフェーズ制御と組み合わさります。動詞が一覧に表示されるのは、そのフェーズがアクティブで、かつその機能が有効な場合のみです。この仕組みは汎用的な機能レジストリであるため、将来「この環境ではサーバーが X を実行できない」というフラグが追加された場合も、同じ方法で該当ツールを非表示にできます。

単一モデルモード

API が単一モデルモードで実行される場合、起動時にモデルが事前ロードされるため、 サーバーは常に実行時フェーズにあります。該当するすべてのツールが最初のリクエストから 一覧に表示され、load_model の手順はありません。

キャッシュヒントに関する注記。 2026-07-28 の MCP 仕様では、tools/list に ttlMs / cacheScope ヒントが追加されます（SEP-2549）。これらは意図的にまだ設定していません。これらの フィールドはリリース候補であり、FastMCP の list-tools フックが公開するのはツール一覧のみで、 結果のエンベロープは公開しないためです。それまでは、上記の明示的な再リスト通知が 主な（かつ仕様で推奨される）遷移メカニズムです。

サポート対象の SQL 方言

postgres、snowflake、clickhouse、databricks、dremio、bigquery、duckdb

ワークフロー

1. リファレンスを取得 — get_obml_reference() を呼び出して OBML の構文を確認します
2. モデルをロード — load_model(model_yaml) を呼び出して model_id を取得します
3. 探索 — describe_model(model_id) を呼び出すか、探索ツール（find_artefacts、explain_artefact、get_lineage）を使用します
4. 実行 — execute_query(model_id, query_json='{"select": {"dimensions": [...], "measures": [...]}}') を呼び出して SQL をコンパイル、実行し、行を返します（API で QUERY_EXECUTE=true が必要です。QueryObject の形式については get_json_schema("query") を参照してください）

統合ガイド

OrionBelt® Semantic Layer MCP サーバーを、人気の AI エージェントフレームワークや自動化プラットフォームで使用できます。

フレームワーク	トランスポート	ガイド
OpenAI Agents SDK	stdio、HTTP、SSE	docs/integrations/openai-agents-sdk.md
LangChain	stdio、HTTP	docs/integrations/langchain.md
Google ADK	stdio、HTTP、SSE	docs/integrations/google-adk.md
n8n	HTTP、SSE	docs/integrations/n8n.md
CrewAI	stdio、HTTP	docs/integrations/crewai.md

各ガイドには、クイックスタートの例、マルチエージェントのパターン、ホスト型デモとセルフホスト環境の両方に対応した接続オプションが含まれています。

開発

# Run tests
uv run pytest

# Lint and format
uv run ruff check server.py
uv run ruff format server.py tests/

# Set up pre-commit hooks (recommended)
./scripts/setup-hooks.sh

GitHub Actions のピン留め

.github/workflows 内のすべての uses: は、40 文字のコミット SHA にピン留めされており、 その SHA が取得された正確なパッチリリースを示すコメントが付いています。

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

v7 のようなタグは変更可能なラベルです。アクションの所有者はいつでも参照先を変更できるため、 @v7 はジョブの開始時点でそのタグが指しているコミットを実行します。一方、SHA は変更されません。 すべてのワークフローは読み取り専用（permissions: contents: read）で開始し、書き込み権限は必要なジョブにのみ付与されます（PyPI 公開ジョブの id-token: write のみ）。

ただし、ピン留めすると各参照が読み取りにくくなり、SHA とその横にあるコメントが一致していることを 自動的に保証するものもありません。プルリクエストで、フォークから取得したハッシュに差し替え、 # v7.0.1 はそのままにしても、差分は通常の依存関係更新のように見えてしまう可能性があります。 scripts/check-action-pins.sh はこの問題を解消します。このスクリプトは、有効な SHA、 ALLOWED_OWNERS の許可リストに含まれる所有者、正確なパッチリリースを示すバージョンコメントを 要求したうえで、git ls-remote を使って上流のタグを解決し、そのタグが指すコミットが ピン留めされたコミットと異なる場合は失敗します。

./scripts/check-action-pins.sh            # every check, including upstream lookups
./scripts/check-action-pins.sh --offline  # skip the network; SHA and comment format only

このスクリプトは CI の pins ジョブとして実行され、タグをトリガーとする両方の公開ワークフローでも、 チェックアウト後の最初のステップとして再度実行されます。これにより、ピン留めが一度も検証されていない ステップでビルドされたアーティファクトがリリースされることはありません。アクションを更新する際は、 SHA とコメントを一緒に更新してください。新しいアクションの所有者を ALLOWED_OWNERS に追加するときは、 ピン留めは誰が公開したかに関係なく、対応するタグに対して検証されるため、慎重に判断してください。

リリースプロセス

リリーススクリプト（scripts/release.sh）には、v2.8.2 のフォーマット問題のような不具合を防ぐための包括的な事前チェックが含まれています。

• コードフォーマットチェック - ruff format がパスすることを確認します
• Lint チェック - ruff check がパスすることを確認します
• CI ステータスチェック - CI がグリーンでない場合に警告します
• テストスイート - すべてのテストを実行します
• バージョンの整合性 - ファイル間でバージョンが一致していることを確認します
• 変更履歴 - 変更履歴のエントリーが存在することを確認します

問題を早期に検出するための pre-commit フックを利用できます。./scripts/setup-hooks.sh を実行してインストールしてください。

ホスト型 MCP サーバー

この MCP サーバーの公開ホスト型インスタンスは Google Cloud Run 上で稼働し、 稼働中の OrionBelt® Semantic Layer デモ API に接続されています。ローカルへのインストールも、API キーも不要です。

エンドポイント

https://orionbelt.ralforion.com/mcp

ストリーミング可能な HTTP（MCP spec 2025-03-26）。ステートフルのため、クライアントは initialize ハンドシェイクを送信し、返された Mcp-Session-Id ヘッダーを再利用してください。

Claude Desktop ですぐに始める

Claude Desktop の設定スキーマが受け付けるのは stdio ランチャーのみです。リモート MCP サーバーには、stdio↔HTTP ブリッジの mcp-remote を使用してください（npx が自動取得するため、手動インストールは不要です）。

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集し、次を追加します。

{
  "mcpServers": {
    "orionbelt": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://orionbelt.ralforion.com/mcp",
        "--transport",
        "http"
      ]
    }
  }
}

Claude Desktop を完全に終了し（macOS では ⌘Q を押してください。ウィンドウを閉じるだけでは終了しません）、再度開きます。すると、ツールメニューに OrionBelt® のツールが表示されます。

新しいビルドの Claude Desktop では、Settings → Connectors → Add custom connector を選択し、上記の URL を貼り付ける方法もあります。ファイル編集も npx も不要です。

なぜ mcp-remote なのですか？ Claude Desktop の claude_desktop_config.json スキーマは 現在、stdio エントリー（command + args）のみを検証します。{"url": "…"} のみのエントリーは、 "not valid MCP server configurations and were skipped" というエラーで拒否されます。mcp-remote は、HTTPS エンドポイントに転送する ローカルの stdio ブリッジを実行するため、Claude Desktop には通常の stdio サーバーとして認識されます。Claude Code は {"type": "url", "url": "…"} をネイティブにサポートしています。以下を参照してください。

Claude Code ですぐに始める

任意のリポジトリの .mcp.json（またはグローバル設定の ~/.config/claude-code/.mcp.json）に追加します。

{
  "mcpServers": {
    "orionbelt": {
      "type": "url",
      "url": "https://orionbelt.ralforion.com/mcp"
    }
  }
}

その他の MCP クライアント

ストリーミング可能な HTTP トランスポート（MCP spec 2025-03-26）をサポートするクライアントであれば、上記の URL を指定できます。 エンドポイントは Accept: application/json, text/event-stream を付けた POST /mcp を受け付けます。ハンドシェイク全体を実行する、標準ライブラリのみを使用した Python のスモークテストについては、 tests/cloudrun/test_mcp_cloudrun.sh を参照してください。

注意事項

• ホスト型インスタンスはアイドル時にゼロまでスケールダウンするため、 コールド状態の後の最初のリクエストは約 1～2 秒余分にかかります。
• 公開デモ API（https://orionbelt.ralforion.com）に接続します。データも 方言も同じで、認証は不要です。本番データをここ経由で読み込まないでください。
• セルフホストする場合は、上記のインストールセクションと Dockerfileを参照してください。

ライセンス

Copyright 2026 RALFORION d.o.o.

Apache License, Version 2.0 のもとでライセンスされています。詳細は LICENSE を参照してください。

サードパーティライセンス

PyPI パッケージには server.py のみが含まれています。依存関係は宣言されているだけで、同梱されていないため、サードパーティのコードは再配布されません。

Docker イメージには依存関係も同梱されており、そのライセンスは次の3か所に含まれています。

イメージ内の場所	対象
/app/.venv/lib/*/site-packages/*.dist-info/licenses/	各 Python パッケージ。各パッケージの作成者が配布した形式のもの
/app/THIRD_PARTY_NOTICES.md	同じライセンス文を1つのファイルにまとめたもの
/usr/share/doc/*/copyright	python:3.14-slim から継承した Debian ベースパッケージ

集約したファイルは THIRD_PARTY_NOTICES.md としてコミットされ、イメージにコピーされます。そのため、何も取得せずに内容を確認でき、変更の原因となった依存関係の変更と同じ差分でレビューできます。CI はすべての PR でロック済みの依存関係セットからファイルを再生成し、コミット済みのコピーと異なる場合は失敗します。これにより、内容のずれを防いでいます。特定のタグのイメージに実際に含まれているライセンスを確認するには、次のコマンドを実行してください。

docker run --rm --entrypoint cat ralforion/orionbelt-semantic-layer-mcp:latest \
    /app/THIRD_PARTY_NOTICES.md

Linux 上で scripts/third_party_notices.py を使って再生成できます。このスクリプトはホストではなく、イメージのターゲット向けに依存関係を解決します。macOS 上でホスト向けに解決すると、jeepney と SecretStorage が気づかないうちに除外されます。

Python の依存関係は、2つの例外を除いて許諾的なライセンスです。 読者の推測に委ねるのではなく、どちらの例外も scripts/third_party_notices.py の ACKNOWLEDGED に記録されています。certifi は MPL-2.0 で、docutils は GPL を含む複数の選択肢を提示しています。MPL-2.0 はファイル単位のコピーレフトであり、影響が及ぶのはファイル自体であって、それをインポートするプログラムではありません。そのため、変更せずにこの通知とともに同梱すれば要件を満たします。docutils の選択はリリース前に文書で明示する必要があり、明示されるまでジェネレーターは失敗します。それ以外はすべて MIT、BSD、Apache-2.0、ISC、Unlicense、または PSF-2.0 であり、サーバー独自のコードに影響するものはありません。

Debian ベースについては別途考慮が必要です。 python:3.14-slim には約87個のシステムパッケージが含まれており、その多くは GPL/LGPL（coreutils、libc6、bash など）です。これは Debian ベースのすべてのイメージと同様です。これらは改変されていない上流パッケージであり、通常の OS コンポーネントとして呼び出されます。サーバーにリンクされたり、サーバーから派生したりするものではなく、ライセンスと書面による提供の案内文は、イメージ内の /usr/share/doc/ と /usr/share/common-licenses/ に含まれています。配布ポリシー上、これらを完全に避ける必要がある場合は、distroless または Alpine ベースから FROM して再ビルドしてください。

---

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