de en es ja ko ru zh

grane

Name: grane
Author: Nareik33L

by Nareik33L

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Grane

为 AI 代理提供受治理的分析和受控探索。

连接你的数据库，定义重要的业务指标，并让任何兼容 MCP 的代理获得对这些定义的受治理访问权限——以及对其他一切内容的授权探索。

自托管。确定性。语义优先，而非仅语义。

你的 AI 能写 SQL。但这不意味着它知道 Revenue 是什么意思。 Grane 告诉它哪些数字是权威的，哪些结论是探索性的。

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，并以只读方式执行。允许的原始仓库列可以作为 raw_dimensions / raw_metrics 请求，无需编写 SQL。
扇出安全。 Grane 知道关系基数和指标粒度。跨 one_to_many 连接的度量会以确定性方式预先聚合；会静默倍增行数的查询会被拒绝——包括探索性查询。
拒绝是一种信任特性。 请求一个未定义的指标，Grane 会返回结构化的 undefined_metric 响应并附上建议——它从不发明业务逻辑。仅当启用探索且列未被排除时，才允许使用原始列。
三个信任级别。 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

三步设置：

数据库 — 将 grane.yml 指向使用只读用户的 Postgres；在 YAML 中定义指标；运行 grane validate。
Grane MCP — 运行 grane serve（HTTP）或让代理启动 grane serve --stdio（本地桌面客户端）。
代理 — 使用 grane mcp connect <client>（Claude、Cursor、Gemini、VS Code、ChatGPT、Windsurf、Claude Code 或通用）注册 Grane，然后在聊天中提问。

代理	典型设置	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 驱动。其他引擎需要一个额外的包：

类型	额外安装
`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 表面

四个工具，刻意设计得难以误用：

工具	用途
`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"
  }
}

参见 docs/connect-an-agent.md 了解 ChatGPT、Claude、Gemini、Cursor 和 grane mcp connect。参见 docs/mcp-setup.md 了解 MCP 工具参考和配置文件格式。

信任契约

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

Need Help?

Related Servers

Related MCP Connectors

QueryBearOAuth
io.github.spencerpauly
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Databases RAG Systems
2
Veto — SQL Safety & Cost Oracle A
com.vetosql
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Databases Security Autonomous Agents
32
ContextfloOAuth
com.contextflo
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Databases Security
1
convalytics A
io.github.Dan-Cleary
Read-only analytics for Convex apps, queryable via MCP from Claude, Cursor, and other clients.
Developer Tools Monitoring Databases
1526

Related MCP Servers

django-mcp-sql
Databases RAG Systems
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.
Updated 11 hours ago (2026-10-15 15:15 UTC)
138 PyPI
4
MIT
FastAPI Database MCP Server
Databases Search
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.
Updated 2 months ago (2026-08-10 11:27 UTC)
1
-
readonly-postgres-mcp
Databases Developer Tools
amar141989-dev
A
license
A
quality
C
maintenance
Readonly PostgreSQL MCP server with SQL guardrails for analytical queries and schema introspection.
Updated a month ago (2026-09-09 19:40 UTC)
2
8 npm
MIT
mcp-sql-metrics
Databases Search
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.
Updated 2 months ago (2026-08-18 03:24 UTC)
MIT