{ "markdown": "\n

\n \"OrionBelt\n

\n\n

OrionBelt® Analytics

\n\n

The Ontology-based MCP server for your Text-2-SQL convenience.

\n\n[![Version 2.0.3](https://img.shields.io/badge/version-2.0.3-purple.svg)](https://github.com/ralforion/orionbelt-analytics/releases)\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-orange.svg)](https://github.com/ralforion/orionbelt-analytics/blob/main/LICENSE)\n[![FastMCP](https://img.shields.io/badge/FastMCP-3.3.1+-blue)](https://github.com/jlowin/fastmcp)\n[![RDF/OWL](https://img.shields.io/badge/RDF%2FOWL-Ontology-orange)](https://www.w3.org/OWL/)\n\n[![BigQuery](https://img.shields.io/badge/BigQuery-669DF6.svg?logo=googlebigquery&logoColor=white)](https://cloud.google.com/bigquery)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1.svg?logo=postgresql&logoColor=white)](https://www.postgresql.org)\n[![Snowflake](https://img.shields.io/badge/Snowflake-29B5E8.svg?logo=snowflake&logoColor=white)](https://www.snowflake.com)\n[![ClickHouse](https://img.shields.io/badge/ClickHouse-FFCC01.svg?logo=clickhouse&logoColor=black)](https://clickhouse.com)\n[![Dremio](https://img.shields.io/badge/Dremio-31B48D.svg)](https://www.dremio.com)\n[![Databricks](https://img.shields.io/badge/Databricks-FF3621.svg?logo=databricks&logoColor=white)](https://www.databricks.com)\n[![DuckDB](https://img.shields.io/badge/DuckDB-FFF000.svg?logo=duckdb&logoColor=black)](https://duckdb.org)\n[![MySQL](https://img.shields.io/badge/MySQL-4479A1.svg?logo=mysql&logoColor=white)](https://www.mysql.com)\n\n[![Docker Hub](https://img.shields.io/docker/v/ralforion/orionbelt-analytics?logo=docker&logoColor=white&label=Docker%20Hub&color=2496ED&sort=semver)](https://hub.docker.com/r/ralforion/orionbelt-analytics/tags)\n[![Docker pulls](https://img.shields.io/docker/pulls/ralforion/orionbelt-analytics?logo=docker&logoColor=white&color=2496ED)](https://hub.docker.com/r/ralforion/orionbelt-analytics)\n[![Image size](https://img.shields.io/docker/image-size/ralforion/orionbelt-analytics/latest?logo=docker&logoColor=white&color=2496ED)](https://hub.docker.com/r/ralforion/orionbelt-analytics)\n\nOrionBelt Analytics is an MCP server that analyzes relational database schemas and generates RDF/OWL ontologies with embedded SQL mappings. It provides relationship-aware Text-to-SQL with automatic fan-trap prevention, GraphRAG for intelligent schema discovery, and interactive charting -- all accessible through any MCP-compatible AI client.\n\n## The OrionBelt Ecosystem\n\n| Project | Purpose |\n| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |\n| **OrionBelt Analytics** (this) | Schema analysis, ontology generation, GraphRAG, Text-to-SQL |\n| [**OrionBelt Semantic Layer**](https://github.com/ralfbecher/orionbelt-semantic-layer) | Declarative YAML models compiled into dialect-specific, fan-trap-free SQL |\n| [**OrionBelt Ontology Builder**](https://github.com/ralfbecher/orionbelt-ontology-builder) | Visual OWL ontology editor with reasoning and graph visualization ([live demo](https://orionbelt.streamlit.app/)) |\n| [**OrionBelt Chat**](https://github.com/ralfbecher/orionbelt-chat) | AI chat UI for Analytics + Semantic Layer (Chainlit, multiple LLM providers) |\n\nRun Analytics and Semantic Layer side-by-side in Claude Desktop for schema-aware ontology generation **and** guaranteed-correct SQL compilation.\n\n## Architecture\n\n

\n \"OrionBelt\n

\n\n- **8 database connectors** -- PostgreSQL, MySQL, Snowflake, ClickHouse, Dremio, BigQuery, DuckDB/MotherDuck, Databricks SQL\n- **RDF/OWL ontology generation** with `oba:` namespace SQL annotations and W3C R2RML mappings\n- **GraphRAG** -- graph traversal (up to 12 hops) + ChromaDB vector embeddings for semantic schema discovery\n- **SPARQL 1.1** query interface via persistent Oxigraph RDF store\n- **OBQC validation** -- deterministic SQL checks against the ontology (table/column existence, join validity, type mismatches, fan-traps)\n- **Interactive charting** -- Plotly charts with MCP-UI rendering in Claude Desktop\n- **Multi-schema support** -- analyze multiple schemas simultaneously; ontology and GraphRAG state are isolated per schema\n- **Workspace persistence** -- reconnect to the same database and restore your previous session\n- **MCP sampling** -- when the connected client supports sampling (e.g. [OrionBelt Chat](https://github.com/ralfbecher/orionbelt-chat)), `suggest_semantic_names` asks the host LLM to pre-fill rename suggestions for cryptic identifiers via `sampling/createMessage`, collapsing the previous review-then-apply flow into a single tool call. Clients without sampling support (e.g. Claude Desktop) silently fall back to the manual review path\n\n## OBQC -- Ontology-Based Query Check\n\nA key differentiator of OrionBelt is **OBQC** (Ontology-Based Query Check), a deterministic, rule-based SQL validator that catches errors _before_ queries reach the database. Unlike LLM-only approaches that rely on the model \"getting it right,\" OBQC cross-references every generated SQL statement against the loaded RDF/OWL ontology to enforce structural correctness.\n\n**What OBQC validates:**\n\n| Check | What it catches |\n| --------------------------- | ------------------------------------------------------------------------------------------------- |\n| **Table existence** | References to tables that don't exist in the schema |\n| **Column existence** | References to columns not present in their table, ambiguous unqualified columns |\n| **Join validity** | Missing join conditions (Cartesian products), join columns that don't match declared foreign keys |\n| **Type compatibility** | WHERE/ON comparisons between incompatible types (e.g. string vs. integer) |\n| **Aggregation correctness** | SELECT columns missing from GROUP BY when aggregates are used |\n| **Fan-trap detection** | Aggregations across multiple one-to-many joins that silently multiply results |\n\n**How it works:**\n\n1. `generate_ontology` or `load_my_ontology` creates/loads an ontology with `oba:` namespace annotations that map OWL classes and properties to actual database tables, columns, types, and foreign keys.\n2. When `execute_sql_query` is called, OBQC parses the SQL with [sqlglot](https://github.com/tobymao/sqlglot) and validates every table, column, join, and aggregation against the ontology's schema model.\n3. Issues are returned with severity levels (error, warning, info) alongside the query results, so the LLM can self-correct before the user sees wrong data.\n\nOBQC is fully deterministic -- no LLM calls, no probabilistic reasoning. It acts as a safety net that complements the LLM's SQL generation with hard structural guarantees. Errors **block query execution**; warnings are attached to the response for the LLM to act on. See [OBQC documentation](docs/obqc.md) for the full rule reference, severity behavior, and annotation requirements.\n\n## Quick Start\n\n### 1. Install\n\n```bash\ngit clone https://github.com/ralforion/orionbelt-analytics\ncd orionbelt-analytics\nuv sync\n```\n\n> Requires **Python 3.13+** and [**uv**](https://github.com/astral-sh/uv).\n\n### 2. Configure\n\n```bash\ncp .env.template .env\n```\n\nEdit `.env` with your database credentials. At minimum, set the variables for one database (e.g. `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DATABASE`, `POSTGRES_USERNAME`, `POSTGRES_PASSWORD`).\n\nSee [docs/configuration.md](docs/configuration.md) for all environment variables, transport options, and troubleshooting.\n\n### 3. Run\n\n```bash\nuv run server.py\n```\n\nThe server starts on `http://localhost:9000` (HTTP transport, configurable via `MCP_SERVER_PORT`).\n\n## Connect Your AI Client\n\n### Claude Desktop\n\nStart the server, then add to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"OrionBelt-Analytics\": {\n \"command\": \"npx\",\n \"args\": [\n \"mcp-remote\",\n \"http://localhost:9000/mcp\",\n \"--transport\",\n \"http-only\"\n ]\n }\n }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add orionbelt-analytics http://localhost:9000/mcp\n```\n\n### LibreChat\n\nSet `MCP_TRANSPORT=sse` in `.env`, restart the server, then add to `librechat.yaml`:\n\n```yaml\nmcpServers:\n OrionBelt-Analytics:\n url: \"http://host.docker.internal:9000/sse\"\n timeout: 60000\n startup: true\n```\n\n### Other Frameworks\n\nOrionBelt works with LangChain, OpenAI Agents SDK, CrewAI, Google ADK, Vercel AI SDK, n8n, and ChatGPT Custom GPTs. See [docs/integrations.md](docs/integrations.md) for setup examples.\n\n## Tools\n\nOrionBelt exposes 26 MCP tools. Here is a summary by category:\n\n### Connection & Schema\n\n| Tool | Description |\n| ------------------- | ---------------------------------------------------------------------- |\n| `connect_database` | Connect to any supported database using `.env` credentials |\n| `list_schemas` | List available schemas in the connected database |\n| `reset_cache` | Clear cached schema and ontology data for the current session |\n| `discover_schema` | Analyze schema structure with automatic GraphRAG + ontology generation |\n| `get_table_details` | Get detailed column, key, and constraint info for a specific table |\n| `cleanup_workspace` | Delete all workspace files for the current connection and start fresh |\n\n### Ontology & Semantic\n\n| Tool | Description |\n| ------------------------ | --------------------------------------------------------------------- |\n| `generate_ontology` | Generate RDF/OWL ontology from schema with SQL mapping annotations |\n| `suggest_semantic_names` | Detect abbreviations and cryptic names for business-friendly renaming |\n| `apply_semantic_names` | Apply LLM-suggested semantic names and descriptions to ontology |\n| `load_my_ontology` | Load a custom `.ttl` ontology file from an import folder |\n| `download_artifact` | Download ontology or R2RML mapping as a Turtle file |\n\n### Query & Visualization\n\n| Tool | Description |\n| ------------------- | -------------------------------------------------------------------------- |\n| `sample_table_data` | Preview table data with row limit and injection protection |\n| `execute_sql_query` | Execute SQL with OBQC validation, security checks, and fan-trap detection |\n| `generate_chart` | Generate Plotly charts (bar, line, scatter, heatmap) with MCP-UI rendering |\n\n### GraphRAG\n\n| Tool | Description |\n| ------------------------- | ------------------------------------------------------------------------- |\n| `graphrag_search` | Semantic search + schema overview (auto-initialized by `discover_schema`) |\n| `graphrag_query_context` | Get optimized context for SQL generation (85-95% token reduction) |\n| `graphrag_find_join_path` | Discover join paths between tables via graph traversal |\n| `reachable_from` | Dimension-capable tables for an anchor grain (many-to-one closure) |\n| `measurable_from` | Measure-capable tables for an anchor grain (one-to-many closure) |\n| `plan_composite_query` | Advise a fan-trap-safe Composite Fact Layer (UNION ALL) decomposition |\n\n### SPARQL & RDF\n\n| Tool | Description |\n| ----------------------- | --------------------------------------------------------------- |\n| `store_ontology_in_rdf` | Persist ontology in Oxigraph for SPARQL access |\n| `query_sparql` | Execute SPARQL queries (SELECT, ASK, CONSTRUCT — auto-detected) |\n| `add_rdf_knowledge` | Add custom metadata triples to the RDF store |\n\n### Semantic Models\n\n| Tool | Description |\n| ---------------------- | ---------------------------------------------------------- |\n| `save_semantic_model` | Save a semantic model (e.g., OBML YAML) to the workspace |\n| `get_semantic_model` | Retrieve a stored semantic model by name |\n| `list_semantic_models` | List all stored semantic models for the current connection |\n\nFor full parameter details, return values, and examples, see [docs/tools-reference.md](docs/tools-reference.md).\n\n## Typical Workflows\n\n**Full analysis session:**\n\n```\nconnect_database(\"postgresql\") -> discover_schema(\"public\") -> generate_ontology() -> execute_sql_query(...)\n```\n\n**Quick data exploration:**\n\n```\nconnect_database(\"duckdb\") -> list_schemas() -> sample_table_data(\"events\")\n```\n\n**Query with visualization:**\n\n```\nexecute_sql_query(query) -> generate_chart(data, \"bar\", ...)\n```\n\n`execute_sql_query` runs OBQC validation, security checks, and fan-trap detection before executing — no separate validation step is needed.\n\n**Resume a previous session (auto-restores workspace):**\n\n```\nconnect_database(\"postgresql\") -> execute_sql_query(...)\n```\n\n## Development\n\n`uv sync` installs everything; `uv run pytest`, `black`/`isort`/`ruff` and strict\n`mypy` are the gates. The [Development guide](docs/development.md) has the full\nsetup, project layout, and contribution checklist.\n\nOne thing worth knowing before you open a workflow file: every GitHub Action is\npinned to a 40-character commit SHA carrying a `# vX.Y.Z` comment, which is why\nthey are full of hex. A git tag is a movable label, so `actions/checkout@v7` runs\nwhatever commit that label points at when the job starts; a SHA cannot move. The\ncomments name exact patch releases rather than `# v7`, because a major tag moves\nwith every upstream release. `./scripts/check-action-pins.sh` resolves each tag\nupstream and fails when the commit it names is not the one pinned -- which is the\nonly thing that distinguishes a real bump from a hash quietly swapped for one\ntaken from a fork. It runs as the `pins` job on every pull request and as the\nfirst step of both publishing workflows; `--offline` skips the upstream lookups\nand checks only the SHA and comment format.\n\n## Documentation\n\n| Document | Contents |\n| -------------------------------------------------- | ----------------------------------------------------------------------------- |\n| [Tools Reference](docs/tools-reference.md) | Full parameter docs, return values, and usage examples |\n| [Configuration](docs/configuration.md) | Environment variables, transport setup, troubleshooting |\n| [GraphRAG](docs/graphrag.md) | Graph-based schema intelligence and OBML workflow |\n| [OBQC Overview](docs/obqc-overview.md) | Short explanation of how OBQC works inside OrionBelt Analytics |\n| [OBQC](docs/obqc.md) | Validation rules, severity levels, blocking behavior, annotation requirements |\n| [Fan-Trap Prevention](docs/fan-trap-prevention.md) | The fan-trap problem, detection, and safe SQL patterns |\n| [Integrations](docs/integrations.md) | LangChain, OpenAI, CrewAI, Google ADK, Vercel, n8n, ChatGPT |\n| [Development](docs/development.md) | Project structure, testing, contributing |\n\n## License\n\nCopyright 2025-2026 [RALFORION d.o.o.](https://ralforion.com)\n\nLicensed under the [Business Source License 1.1](LICENSE). The Licensed Work will convert to Apache License 2.0 on 2030-03-16.\n\nBy contributing to this project, you agree to the [Contributor License Agreement](CLA.md).\n\nFor commercial licensing inquiries, contact: licensing@ralforion.com\n\n### Third-party software\n\nOrionBelt Analytics builds on open source. [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) lists every bundled dependency with its licence, and calls out the few that carry obligations beyond attribution (psycopg2's LGPL, wordfreq's CC-BY-SA data, the MPL-2.0 components).\n\nThe Docker image redistributes those packages, so it ships their verbatim licence texts at `/app/licenses/THIRD_PARTY_LICENSES.txt`, alongside the Debian copyright files under `/usr/share/doc/`. The PyPI wheel bundles nothing third-party — it declares its dependencies and the installer fetches them from PyPI.\n\n---\n\n

\n \n \"RALFORION\n \n

\n\n

\n Copyright © 2026 RALFORION d.o.o.
\n OrionBelt® is a registered trademark of RALFORION d.o.o.\n

\n", "bytes": 18286, "sha": "672b91c5a2523e0b0c6d3bd156a478e8eeaa7aa3cad0319171d9e3abfcd66032", "repo_slug": "ralfbecher/orionbelt-analytics", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ralfbecher_orionbelt_analytics_73bbc4ce/readme" }