de en es ja ko ru zh

grane

Name: grane
Author: Nareik33L

by Nareik33L

Overview Schema Related Servers Score Discussions

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은 관계 카디널리티와 지표의 입자(grain)를 알고 있습니다. 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와 함께 설치되지 않습니다 — 사용하는 드라이버만 추가하세요(아래 Warehouses 참조). 이렇게 하면 전역 설치에 관련 없는 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()`	실행 없이 쿼리 드라이런(dry-run)
`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 installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

license - permissive license

Not graded

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

0dRelease cycle

10Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

django-mcp-sql
Databases RAG Systems
thepapermen
A
license
Not graded
quality
A
maintenance
Provides a read-only PostgreSQL SQL surface for LLM agents via MCP, with defense-in-depth security layers for safe database queries.
Updated 19 days ago (2026-08-12 09:52 UTC)
3
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 21 days ago (2026-08-10 11:27 UTC)
1
readonly-postgres-mcp
Databases Developer Tools
amar141989-dev
A
license
Not graded
quality
C
maintenance
Readonly PostgreSQL MCP server with SQL guardrails for analytical queries and schema introspection.
Updated 2 months ago (2026-06-29 15:48 UTC)
34
MIT
slcg
Databases Developer Tools
aadhyathmik
A
license
Not graded
quality
C
maintenance
Provides a read-only PostgreSQL MCP server with schema introspection. Enforces least-privilege database roles to prevent any writes, even from malicious SQL.
Updated a month ago (2026-08-05 06:44 UTC)
MIT

View all related MCP servers

Related MCP Connectors

nlqdb — analytical memory for AI agents
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Yandex Metrika MCP
Read-only Yandex Metrika MCP. Query visits, sources, geo, devices and more in plain language.
PlainQuery | MCP DB Agent
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Nareik33L/grane'

If you have feedback or need assistance with the MCP directory API, please join our Discord server