Skip to main content
Glama
deenesjakoruzh
Nareik33L

grane

by Nareik33L
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Grane

AIエージェント向けの、管理された分析と制御された探索。

データベースを接続し、重要なビジネス指標を定義すれば、MCP互換の任意のエージェントに、それらの定義への管理されたアクセスを許可できます。さらに、その他すべてに対する権限付きの探索も可能です。

セルフホスト。決定論的。セマンティックファーストであり、セマンティックオンリーではない。

あなたのAIはSQLを書けます。だからといって、Revenueの意味を知っているわけではありません。 Graneは、どの数値が正式で、どの結論が探索的なものかをAIに伝えます。

Graneの機能

AIエージェントはすでにSQLを書けます。しかし、あなたのデータベースは、自社の承認されたRevenue、MRR、Active Customer、ARPUの定義を知りません。LLMにそれらを独自に作らせると、もっともらしく見えて間違った数字が生まれます。

Graneはデータベースとエージェントの間に位置します:

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

  • エージェントは推論します。Graneは真実を強制し、探索にラベルを付けます。 エージェントはセマンティックなリクエスト（「先月の国別売上」）を送信します。Graneは承認された定義を解決し、結合を計画し、SQLをコンパイルして、読み取り専用で実行します。許可された生のウェアハウス列は、SQLを書かずに raw_dimensions / raw_metrics としてリクエストできます。

  • ファンアウトの安全性。 Graneはリレーションシップのカーディナリティと指標の粒度を把握しています。one_to_many 結合をまたぐメジャーは決定論的に事前集計されます。暗黙のうちに行を増やすクエリは、探索的なものであっても拒否されます。

  • 拒否は信頼の機能です。 定義されていない指標を要求すると、Graneは提案付きの構造化された undefined_metric レスポンスを返します。ビジネスロジックを独自に作り出すことは決してありません。生の列が許可されるのは、探索が有効で、その列が除外されていない場合のみです。

  • 3つの信頼レベル。 governed（承認された定義のみ）、mixed（承認された指標と生のフィールド）、exploratory（生のウェアハウスデータ）。エージェントは探索を承認されたビジネス上の真実として提示してはなりません。

  • LLMを内蔵しない。 Graneは決定論的なインフラストラクチャです。APIキーも、ホスト型データプレーンもなく、あなたの環境から何も出て行きません。

Related MCP server: FastAPI Database MCP Server

ChatGPT、Claude、Gemini、または任意のMCPエージェントを接続する

GraneはあなたのOpenAI、Anthropic、GoogleのAPIキーを必要としません。チャット側ではご自身のエージェントのサブスクリプションまたはAPIキーを使用します。Graneはその中間に位置し、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

3つのステップでセットアップ:

  1. データベース — 読み取り専用ユーザーで grane.yml をPostgresに向けます。YAMLで指標を定義し、grane validate を実行します。

  2. Grane MCP — grane serve（HTTP）を実行するか、エージェントに grane serve --stdio（ローカルデスクトップクライアント）を起動させます。

  3. エージェント — grane mcp connect <client> でGraneを登録し（Claude、Cursor、Gemini、VS Code、ChatGPT、Windsurf、Claude Code、または汎用）、チャットで質問します。

エージェント

一般的なセットアップ

Graneのトランスポート

Claude Desktop

grane mcp connect claude

stdio（ローカル）またはHTTPS（リモート）

ChatGPT

grane mcp connect chatgpt（HTTPSの手順を表示）

HTTPSのみ — Graneを公開デプロイする

Gemini CLI

grane mcp connect gemini

stdioまたはHTTP

Cursor / VS Code

grane mcp connect cursor または vscode

stdioまたはローカルHTTP

詳細なウォークスルー: docs/connect-an-agent.md

MCPツールリファレンス: docs/mcp-setup.md

ウェアハウス接続: docs/warehouses.md

クイックスタート（サンプルデータベースを使用）

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

インストール

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

CLIコマンドは引き続き grane です。Node 20+ が必要です。Postgres以外のウェアハウスドライバーはCLIと一緒にインストールされません。使用するものだけを追加してください（下記の「ウェアハウス」を参照）。これにより、グローバルインストールに無関係なSDKの非推奨警告が含まれないようになります。

ウェアハウス

grane.yml の connection.type を設定します。PostgresとRedshiftはバンドルされた pg ドライバーを使用します。その他のエンジンには追加のパッケージが1つ必要です:

タイプ

追加インストール

postgres / redshift

（バンドル済み）

mysql

npm install mysql2

snowflake

npm install snowflake-sdk

bigquery

npm install @google-cloud/bigquery

duckdb

npm install @duckdb/node-api

clickhouse

npm install @clickhouse/client

databricks

npm install @databricks/sql

接続例: docs/warehouses.md

クイックスタート（ご自身のデータベース）

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

読み取り専用のデータベースユーザーを使用してください。Graneはまた、すべてのクエリをステートメントタイムアウト付きの READ ONLY トランザクションでラップしますが、最終的なセキュリティ境界はデータベースです。

指標の定義

設定はコードです。YAMLファイルはプルリクエストでレビューされ、Gitでバージョン管理され、あなたまたはコーディングエージェントによって編集されます。

# 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 は、すべての参照をライブスキーマと照合し、型を検証し、エージェントがクエリを実行する前に安全でないファンアウトを検出します。

MCPサーフェス

意図的に誤用しにくく設計された4つのツール:

ツール

目的

catalog()

指標、ディメンション、エンティティ、同義語、および（有効な場合）探索可能なウェアハウス列を検出します

query()

Query Model v1リクエストを実行: 解決 → 検証 → コンパイル → 実行 → 来歴

validate()

実行せずにクエリをドライランする

explain()

定義、信頼レベル、結合プラン、および正確なSQLを検査します

エージェントは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
}

すべての結果には信頼レベルと来歴が含まれます:

{
  "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"
  }
}

ChatGPT、Claude、Gemini、Cursor、および grane mcp connect については docs/connect-an-agent.md を参照してください。MCPツールリファレンスと設定ファイル形式については docs/mcp-setup.md を参照してください。

信頼の契約

Graneはセマンティックファーストであり、セマンティックオンリーではありません。企業は、エージェントが調査できるようになる前に、ウェアハウス全体をモデル化する必要はないはずです。Revenue、MRR、Customersを定義し、ポリシーで許可されている場合はエージェントに discount_code や device_type の探索をさせます。Graneは依然としてSQLをコンパイルします。エージェントがデフォルトで無制限のSQLを取得することはありません。

trust

意味

governed

すべてのフィールドが承認されたGrane定義を経由しています。ビジネス上の真実として提示します。

mixed

承認された指標と許可された生のウェアハウスフィールドの組み合わせ。有力な手がかりであり、承認された結論ではありません。

exploratory

生のウェアハウスデータのみ。調査であり、管理された分析ではありません。

grane.yml で探索を有効にします:

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

enabled: false に設定すると、すべての生の列が拒否されます。除外された列は決してクエリ可能になりません。Graneが使用するデータベース資格情報は読み取り専用のままにしてください。

生のフィールドが繰り返し役立つ場合:

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

Graneが trust: governed を返す場合、すべての指標とディメンションがセマンティックモデルで明示的に定義され、すべての結合が既知かつカーディナリティ安全であり、LLMによってビジネスロジックが作り出されておらず、SQLが検査可能であり、正確な定義バージョンが特定されていることを保証します。Graneが要求された意味を安全に解決できない場合は、代わりに拒否します。

Graneではないもの

ダッシュボードも、チャートビルダーも、組み込みチャットボットも、ホスト型データプレーンも、必須のLLM APIキーもありません。プレゼンテーションはエージェントが担い、分析の真実はGraneが担います。そして、どの数値が管理されたもので、どの数値が探索的なものかを常に明示します。

開発

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はPostgresをサポートしています。コネクタインターフェースは、需要に応じて他のデータベース（MySQL、ClickHouse、DuckDB、Snowflake、...）にも開放される予定です。

ライセンス

Apache-2.0

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • django-mcp-sql

    thepapermen
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides a read-only PostgreSQL SQL surface for LLM agents via MCP, with defense-in-depth security layers for safe database queries.
    138 PyPI
    4
    MIT

  • FastAPI Database MCP Server

    amararun
    F
    license
    Not graded
    quality
    F
    maintenance
    Provides read-only SQL query access to Postgres and DuckDB databases via MCP tools, with extensive security hardening for public endpoints.
    1
    -

  • mcp-sql-metrics

    JuanPinilla198
    A
    license
    Not graded
    quality
    C
    maintenance
    Exposes read-only PostgreSQL queries as typed MCP tools, enabling natural-language data analysis while keeping raw tables hidden and enforcing safety limits.
    MIT