Grane

Governierte Analytik und kontrollierte Exploration für KI-Agenten.

Verbinden Sie Ihre Datenbank, definieren Sie die geschäftlichen Kennzahlen, die zählen, und geben Sie jedem MCP-kompatiblen Agenten kontrollierten Zugriff auf diese Definitionen – plus berechtigte Exploration von allem anderen.

Self-hosted. Deterministisch. Semantik-zuerst, nicht nur semantisch.

Ihre KI kann SQL schreiben. Das bedeutet nicht, dass sie weiß, was Umsatz bedeutet. Grane sagt ihr, welche Zahlen maßgeblich sind und welche Schlussfolgerungen explorativ sind.

Was Grane tut

KI-Agenten können bereits SQL schreiben. Aber Ihre Datenbank kennt nicht die genehmigten Definitionen Ihres Unternehmens für Umsatz, MRR, aktive Kunden oder ARPU – und wenn ein LLM sie erfindet, entstehen plausibel aussehende, falsche Zahlen.

Grane sitzt zwischen Ihrer Datenbank und Ihren Agenten:

Claude / ChatGPT / Cursor / internal agents
                 |
                 |  MCP
                 v
              GRANE          metrics, dimensions, relationships,
                 |           deterministic compiler, validation,
                 |  SQL      join/grain safety, provenance
                 v
           Your Postgres

• Der Agent denkt. Grane setzt Wahrheit durch – und kennzeichnet Exploration. Agenten senden semantische Anfragen („Umsatz nach Land im letzten Monat“); Grane löst die genehmigten Definitionen auf, plant die Joins, kompiliert das SQL und führt es schreibgeschützt aus. Erlaubte rohe Warehouse-Spalten können als raw_dimensions / raw_metrics angefordert werden, ohne SQL zu schreiben.

• Fan-out-Sicherheit. Grane kennt Beziehungskardinalität und Metrik-Granularität. Messwerte über one_to_many-Joins werden deterministisch voraggregiert; Abfragen, die Zeilen stillschweigend vervielfachen würden, werden abgelehnt – auch explorative.

• Ablehnung ist eine Vertrauensfunktion. Fragen Sie nach einer Metrik, die nicht definiert ist, und Grane gibt eine strukturierte undefined_metric-Antwort mit Vorschlägen zurück – es erfindet nie Geschäftslogik. Rohe Spalten sind nur erlaubt, wenn Exploration aktiviert ist und die Spalte nicht ausgeschlossen ist.

• Drei Vertrauensstufen. governed (nur genehmigte Definitionen), mixed (genehmigte Metriken plus rohe Felder), exploratory (rohe Warehouse-Daten). Agenten dürfen Exploration nicht als genehmigte Geschäftswahrheit darstellen.

• Kein LLM im Inneren. Grane ist deterministische Infrastruktur. Keine API-Schlüssel, keine gehostete Datenebene, nichts verlässt Ihre Umgebung.

Related MCP server: FastAPI Database MCP Server

Verbinden Sie ChatGPT, Claude, Gemini oder einen beliebigen MCP-Agenten

Grane benötigt nicht Ihre OpenAI-, Anthropic- oder Google-API-Schlüssel. Sie verwenden Ihren eigenen Agenten-Abo oder API-Schlüssel auf der Chat-Seite; Grane sitzt in der Mitte und beantwortet governierte Analytik-Abfragen über MCP.

Your agent (ChatGPT / Claude / Gemini / Cursor)  — your LLM keys
        |
        | MCP
        v
Grane  — no LLM keys; metrics + SQL compiler
        |
        | read-only SQL
        v
Your Postgres  — DATABASE_URL

Einrichtung in drei Schritten:

1. Datenbank – weisen Sie grane.yml auf Postgres mit einem schreibgeschützten Benutzer; definieren Sie Metriken in YAML; führen Sie grane validate aus.

2. Grane MCP – führen Sie grane serve (HTTP) aus oder lassen Sie den Agenten grane serve --stdio starten (lokale Desktop-Clients).

3. Agent – registrieren Sie Grane mit grane mcp connect <client> (Claude, Cursor, Gemini, VS Code, ChatGPT, Windsurf, Claude Code oder generisch) und stellen Sie dann Fragen im Chat.

Vollständige Anleitung: docs/connect-an-agent.md

MCP-Toolreferenz: docs/mcp-setup.md

Warehouse-Verbindungen: docs/warehouses.md

Schnellstart (mit der Beispieldatenbank)

npm install -g grane-analytics @duckdb/node-api
git clone https://github.com/Nareik33L/grane.git
cd grane

# DuckDB (no Docker): seeded shop data in example/analytics-duckdb
grane -p example/analytics-duckdb validate
grane -p example/analytics-duckdb query revenue -d country --last 30d

# Or Postgres:
docker compose -f example/docker-compose.yml up -d --wait
grane -p example/analytics validate
grane -p example/analytics query revenue --dimension country --last last_month
grane -p example/analytics query revenue --raw-dimension customers.name --last 30d
grane -p example/analytics mcp doctor --offline --skip-mcp
grane -p example/analytics mcp print-config generic
grane -p example/analytics serve
# MCP  http://localhost:8080/mcp

Installation

npm install -g grane-analytics
# or: npx grane-analytics --help

Der CLI-Befehl ist weiterhin grane. Erfordert Node 20+. Warehouse-Treiber außer Postgres werden nicht mit dem CLI installiert – fügen Sie nur den hinzu, den Sie verwenden (siehe Warehouses unten). Das hält eine globale Installation frei von irrelevanten SDK-Deprecation-Warnungen.

Warehouses

Setzen Sie connection.type in grane.yml. Postgres und Redshift verwenden den gebündelten pg-Treiber. Andere Engines benötigen ein zusätzliches Paket:

Verbindungsbeispiele: docs/warehouses.md

Schnellstart (eigene Datenbank)

grane init                 # scaffolds grane.yml, metrics.yml, dimensions.yml, relationships.yml
export DATABASE_URL=postgres://readonly_user:...@host:5432/db
grane discover             # introspect tables, columns, FKs; infer relationships
# ... define entities, metrics, dimensions, relationships ...
grane validate             # the "type checker for analytics"
grane query revenue -d country --last 30d
grane serve                # or: grane serve --stdio

Verwenden Sie einen schreibgeschützten Datenbankbenutzer. Grane umschließt außerdem jede Abfrage in einer READ ONLY-Transaktion mit einem Statement-Timeout, aber die Datenbank bleibt die letzte Sicherheitsgrenze.

Metriken definieren

Konfiguration ist Code: YAML-Dateien, in Pull Requests überprüft, in Git versioniert, von Ihnen oder Ihrem Coding-Agenten bearbeitet.

# entities: the business objects metrics are counted at (their grain)
entities:
  order:
    table: orders
    primary_key: id

# metrics.yml
metrics:
  revenue:
    description: Net revenue from completed orders
    owner: finance
    entity: order
    type: sum                       # sum | count | count_distinct | avg | min | max | ratio
    sql: ${orders.net_amount}
    time_dimension: ${orders.completed_at}
    unit: GBP
    status: approved                # experimental | approved | deprecated
    synonyms: [sales, net sales]
    filters:
      orders.status: completed

# dimensions.yml
dimensions:
  country:
    entity: customer
    sql: ${customers.country}

# relationships.yml — cardinality powers the join-safety checks
relationships:
  orders_to_customers:
    from: orders.customer_id
    to: customers.id
    type: many_to_one

grane validate prüft jede Referenz gegen das Live-Schema, verifiziert Typen und erkennt unsicheren Fan-out, bevor ein Agent jemals eine Abfrage ausführt.

Die MCP-Schnittstelle

Vier Werkzeuge, die bewusst schwer zu missbrauchen sind:

Agenten senden analytische Absicht, nicht SQL:

{
  "metrics": ["revenue"],
  "dimensions": ["country"],
  "raw_dimensions": ["orders.discount_code"],
  "filters": [{ "field": "customer_type", "operator": "=", "value": "business" }],
  "time": { "from": "2026-07-01", "to": "2026-07-31", "grain": "month" },
  "order": [{ "field": "revenue", "direction": "desc" }],
  "limit": 100
}

Jedes Ergebnis trägt eine Vertrauensstufe und Provenienz:

{
  "trust": "mixed",
  "governed": ["revenue"],
  "ungoverned": ["orders.discount_code"],
  "warning": "orders.discount_code is not defined in the Grane semantic model",
  "provenance": {
    "query_id": "q_1faea438cc34",
    "trust": "mixed",
    "query_model": "v1",
    "metrics": { "revenue": { "definition_version": "a82cf1d3" } },
    "generated_sql": "SELECT ...",
    "executed_at": "2026-08-25T12:00:00Z"
  }
}

Siehe docs/connect-an-agent.md für ChatGPT, Claude, Gemini, Cursor und grane mcp connect. Siehe docs/mcp-setup.md für die MCP-Toolreferenz und Konfigurationsdateiformate.

Der Vertrauensvertrag

Grane ist semantik-zuerst, nicht nur semantisch. Ein Unternehmen sollte nicht sein gesamtes Warehouse modellieren müssen, bevor Agenten untersuchen können. Definieren Sie Umsatz, MRR, Kunden; lassen Sie Agenten discount_code oder device_type erkunden, wenn die Richtlinie es erlaubt. Grane kompiliert weiterhin das SQL – Agenten erhalten standardmäßig nie uneingeschränktes SQL.

Exploration in grane.yml aktivieren:

exploration:
  enabled: true
  schemas:
    - public
  exclude:
    - users.password_hash
    - customers.ssn

Setzen Sie enabled: false, um jede rohe Spalte abzulehnen. Ausgeschlossene Spalten sind nie abfragbar. Die von Grane verwendeten Datenbankanmeldeinformationen sollten schreibgeschützt bleiben.

Wenn ein rohes Feld wiederholt nützlich ist:

grane usage                          # orders.discount_code used in 47 analyses
grane promote orders.discount_code   # writes a governed dimension to dimensions.yml

Wenn Grane trust: governed zurückgibt, garantiert es, dass jede Metrik und jede Dimension explizit im semantischen Modell definiert wurde, jeder Join bekannt und kardinalitätssicher war, keine Geschäftslogik von einem LLM erfunden wurde, das SQL überprüfbar ist und die genauen Definitionsversionen identifiziert sind. Wenn Grane die angeforderte Bedeutung nicht sicher auflösen kann, lehnt es stattdessen ab.

Was Grane nicht ist

Keine Dashboards, kein Diagramm-Builder, kein eingebauter Chatbot, keine gehostete Datenebene, kein erforderlicher LLM-API-Schlüssel. Agenten besitzen die Präsentation; Grane besitzt die Analytik-Wahrheit – und sagt immer, welche Zahlen governiert und welche explorativ sind.

Entwicklung

npm install
npm run test:unit                                        # no database needed
docker compose -f example/docker-compose.yml up -d --wait
npm test                                                 # unit + integration

V0.1 unterstützt Postgres. Die Connector-Schnittstelle wird sich bei Bedarf für andere Datenbanken (MySQL, ClickHouse, DuckDB, Snowflake, ...) öffnen.

Lizenz

Apache-2.0