convez.ai
MCP ServerDados & AnalyticsIntermediário
ralfbecher

OrionBelt Semantic Layer MCP

ralfbecher/orionbelt-semantic-layer-mcp

Semantic layer MCP para consultas analytics em linguagem natural

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que conecta LLMs à plataforma OrionBelt Semantic Layer via REST API, permitindo exploração de modelos semânticos e execução de queries analíticas em linguagem natural. Suporta múltiplos data warehouses como BigQuery, Snowflake, PostgreSQL e Databricks.

Instalação

$npx convez-ai ralfbecher/orionbelt-semantic-layer-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
2
Acompanhando
1
Saúde
57%
Último commit
há 2 dias
Versão
v3.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar queries SQL complexas via conversação natural com Claude
  • Explorar e descobrir dimensões e métricas em modelos de dados semânticos
  • Integrar analytics em agents inteligentes para BI e relatórios automatizados

Veredito

Solução sólida para democratizar acesso a dados via linguagem natural, eliminando necessidade de SQL manual. Especialmente útil para equipes que já usam OrionBelt e buscam integração profunda com Claude.

README

A tradução para o português deste README ainda está na fila.

Version 2.8.4 OrionBelt Semantic Layer 2.8 Python 3.12+ License: Apache 2.0 FastMCP Pydantic v2 Ruff

BigQuery PostgreSQL Snowflake ClickHouse Dremio Databricks DuckDB MySQL

A thin MCP server that delegates all business logic to the OrionBelt Semantic Layer REST API via HTTP. No embedded engine — pure API pass-through.

Architecture

The OrionBelt Semantic Layer platform has two deployment modes. This MCP server supports both:

  • Standalone — Deploy the OrionBelt Semantic Layer API anywhere (Cloud Run, Docker, localhost) and point this MCP server at it via API_BASE_URL.
  • Hosted — Connect to the public Cloud Run deployment with zero local setup (see Hosted MCP Server below).
┌────────────┐       ┌──────────────────────────────────────────────────────┐
│ 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)               │
└────────────┘       └──────────────────────────────────────────────────────┘
  • No business logic — all tool calls delegate to the REST API (v1 endpoints)
  • Dual-mode — auto-detects single-model or multi-model API mode at startup
  • Auto-session management — creates an API session on first tool call, caches the ID (multi-model mode)
  • 15 tools (single-model mode) or 20 tools (multi-model mode) for querying (QueryObject), execution, batch, discovery, examples, diagrams, RDF/SPARQL, OSI import/export, and OBML reference + JSON schemas. The visible surface is smaller in the design-time phase and when query execution is disabled (see Design-time vs run-time tool switching)
  • 4 prompts + 2 resources for OBML / OBSQL reference and usage guidance

Live Demo

A public demo of the OrionBelt Semantic Layer API is available at:

API endpoint: https://orionbelt.ralforion.com — Swagger UI | ReDoc | Gradio UI

Set API_BASE_URL=https://orionbelt.ralforion.com in your .env file to use it (see .env.example).

Installation

uv sync

For development (includes pytest, respx, ruff):

uv sync --all-groups

Usage

stdio (default)

uv run server.py

HTTP transport

MCP_TRANSPORT=http uv run python server.py

MCP client configuration

Add to your MCP client config (e.g. claude_desktop_config.json):

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

Configuration

Environment variables or .env file (pydantic-settings). See .env.example for defaults.

VariableDefaultDescription
API_BASE_URL— (required)OrionBelt Semantic Layer REST API URL
MCP_TRANSPORTstdiostdio, http, or sse
MCP_SERVER_HOSTlocalhostBind host for HTTP/SSE
MCP_SERVER_PORT9000Bind port for HTTP/SSE
LOG_LEVELINFOLogging level
API_TIMEOUT30HTTP timeout in seconds

Tools

Model lifecycle

MCP ToolDescription
get_obml_reference()Returns the full OBML format specification
load_model(model? | osi_yaml?, dedup=True)Parse, validate, and store a model (returns health + model_load). Pass model (OBML JSON) or osi_yaml (OSI YAML, converted to OBML server-side)
describe_model(model_id)Inspect data objects, dimensions, measures, metrics
remove_model(model_id)Remove a model from the current session
list_models()List all models loaded in the current session
export_model_to_osi(model_id, ...)Export a loaded model as OSI YAML

Model discovery

MCP ToolDescription
find_artefacts(model_id, query?, kind?, name?)Look up artefacts. With query → fuzzy, ranked search (resolve a vague term: exact / synonym / fuzzy). Without query → exact, deterministic lookup (all artefacts, one kind, or one named artefact, full records)
explain_artefact(model_id, name)Explain lineage of a dimension, measure, or metric
list_examples(model_id, intent?)List authored example queries (filterable by intent tag)
get_example(model_id, name)Get one example with query + compiled SQL preview
get_join_graph(model_id)Return the join graph as an adjacency list

Query, execution & diagrams

MCP ToolDescription
execute_query(...)Compile and execute a QueryObject, returning SQL + rows
run_batch(queries, ...)One-shot: load a model + run N queries in parallel
get_model_diagram(model_id)Generate a Mermaid ER diagram for a loaded model

Semantic graph (RDF / SPARQL)

MCP ToolDescription
get_model_graph(model_id)Return the model as OBSL-Core RDF (Turtle)
query_model_graph_by_sparql(query, ...)Run a read-only SPARQL query (SELECT / ASK)

References

MCP ToolDescription
get_obml_reference()OBML (model authoring) grammar reference
get_json_schema(name)JSON Schema for obml (model) or query (QueryObject)

Utilities

MCP ToolDescription
list_dialects()List available SQL dialects and capabilities

Design-time vs run-time tool switching

The server presents a phase-scoped tool surface: instead of listing all all tools at once, it shows only the tools that make sense for where you are in the model lifecycle. About half the tools are meaningless until a model is loaded (execute_query, describe_model, find_artefacts, …) and the rest are about authoring or reference (get_obml_reference, get_json_schema, list_dialects). Splitting them keeps the surface small and prevents a whole class of error — calling a query tool with no model loaded.

Three buckets, swapped by phase

Tools fall into three buckets. The visible surface is a swap at the load/unload transition, not additive — the run phase does not show the design/reference tools:

BucketListed whenTools
Alwaysalways (both phases)load_model, remove_model (transition verbs — stay available in the run phase so a second model can be loaded mid-session, up to max_models_per_session); run_batch (self-contained one-shot — loads/references a model inline, so it needs no prior session state); get_json_schema (QueryObject/OBML schemas — needed in both phases)
Design-onlyonly when no model loadedget_obml_reference, list_dialects
Run-onlyonly when a model is loadeddescribe_model, get_model_diagram, find_artefacts, explain_artefact, execute_query, list_examples, get_example, get_model_graph, get_join_graph, query_model_graph_by_sparql, 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

So design phase → always + design-only, run phase → always + run-only. Design/reference tools are hidden once a model is loaded, keeping the run surface focused on querying.

Re-listing

The MCP tools/list response is filtered to the active phase. Because the stateless MCP spec makes push notifications (notifications/tools/list_changed) unreliable, transitions are pull-based: load_model (design → run) and remove_model (run → design, once no models remain) return a short signal telling the client to re-list its tools and pick up the swapped surface.

Guard against premature calls

If a client calls a run-only verb while still in the design phase (e.g. a stale host that hasn't re-listed yet), the server returns a structured error rather than an opaque failure:

No model loaded — 'execute_query' is a run-time tool and is not available yet. Call load_model first, then re-list tools.

Capability gating (orthogonal to phase)

Separately from lifecycle phase, a tool can be hidden because the server is configured not to support it. The execution tool execute_query is gated on the API's query_execute capability: when the server runs compile-only it is dropped from tools/list and calling it returns a structured error. This composes with phase — a verb is listed only if its phase is active and its capability is enabled. The mechanism is a general capability registry, so future "the server can't do X here" flags hide their tools the same way.

Single-model mode

When the API runs in single-model mode a model is pre-loaded at startup, so the server is permanently in the run-time phase — every applicable tool is listed from the first request and there is no load_model step.

Note on caching hints. The 2026-07-28 MCP spec adds ttlMs / cacheScope hints on tools/list (SEP-2549). These are intentionally not set yet — the fields are a release candidate, and FastMCP's list-tools hook exposes only the tool list, not the result envelope. The explicit re-list signal above is the primary (and spec-recommended) transition mechanism in the meantime.

Supported SQL Dialects

postgres, snowflake, clickhouse, databricks, dremio, bigquery, duckdb

Workflow

  1. Get reference — call get_obml_reference() to learn OBML syntax
  2. Load model — call load_model(model_yaml) to get a model_id
  3. Explore — call describe_model(model_id) or use discovery tools (find_artefacts, explain_artefact)
  4. Execute — call execute_query(model_id, query_json='{"select": {"dimensions": [...], "measures": [...]}}') to compile and run SQL, returning rows (requires QUERY_EXECUTE=true on the API; see get_json_schema("query") for the QueryObject shape)

Integration Guides

Use the OrionBelt Semantic Layer MCP server with popular AI agent frameworks and automation platforms:

FrameworkTransportGuide
OpenAI Agents SDKstdio, HTTP, SSEdocs/integrations/openai-agents-sdk.md
LangChainstdio, HTTPdocs/integrations/langchain.md
Google ADKstdio, HTTP, SSEdocs/integrations/google-adk.md
n8nHTTP, SSEdocs/integrations/n8n.md
CrewAIstdio, HTTPdocs/integrations/crewai.md

Each guide includes quick-start examples, multi-agent patterns, and connection options for both the hosted demo and self-hosted deployments.

Development

# 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

Release Process

The release script (scripts/release.sh) includes comprehensive pre-flight checks to prevent issues like the v2.8.2 formatting problem:

  • Code formatting check - Ensures ruff format passes
  • Linting check - Ensures ruff check passes
  • CI status check - Warns if CI is not green
  • Test suite - Runs all tests
  • Version consistency - Verifies version across files
  • Changelog - Ensures changelog entry exists

Pre-commit hooks are available to catch issues early. Run ./scripts/setup-hooks.sh to install them.

Hosted MCP Server

A public hosted instance of this MCP server runs on Google Cloud Run, connected to the live OrionBelt Semantic Layer demo API. No local install, no API key.

Endpoint

https://orionbelt.ralforion.com/mcp

Streamable HTTP (MCP spec 2025-03-26). Stateful — clients should send the initialize handshake and reuse the returned Mcp-Session-Id header.

Quick start with Claude Desktop

Claude Desktop's config schema accepts only stdio launchers — for a remote MCP server, use the mcp-remote stdio↔HTTP bridge (auto-fetched by npx, no manual install).

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

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

Fully quit Claude Desktop (⌘Q on macOS — closing the window isn't enough) and reopen. The OrionBelt tools then appear in the tools menu.

Alternatively, in newer Claude Desktop builds: Settings → Connectors → Add custom connector, paste the URL above. No file editing or npx required.

Why mcp-remote? Claude Desktop's claude_desktop_config.json schema currently only validates stdio entries (command + args). A bare {"url": "…"} entry is rejected with "not valid MCP server configurations and were skipped". mcp-remote runs a local stdio bridge that forwards to the HTTPS endpoint, so Claude Desktop sees a normal stdio server. Claude Code does support {"type": "url", "url": "…"} natively — see below.

Quick start with Claude Code

Add to .mcp.json in any repo (or ~/.config/claude-code/.mcp.json globally):

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

Other MCP clients

Any client that supports Streamable HTTP transport (MCP spec 2025-03-26) can point at the URL above. The endpoint accepts POST /mcp with Accept: application/json, text/event-stream. See tests/cloudrun/test_mcp_cloudrun.sh for a stdlib-only Python smoke test that walks the full handshake.

Notes

  • The hosted instance scales to zero when idle, so the first request after a cold period takes ~1–2 seconds longer.
  • It connects to the public demo API at https://orionbelt.ralforion.com — same data, same dialects, no authentication. Don't load production data through it.
  • For self-hosting, see the Installation section above and the Dockerfile.

License

Copyright 2025 RALFORION d.o.o.

Licensed under the Apache License, Version 2.0. See LICENSE for details.


Ver o original no GitHub

Bom para

Relacionados