redash-mcp 2.1.1 → 2.2.2

package/.gitattributes

@@ -0,0 +1 @@
+package-lock.json linguist-generated=true

package/README.ko.md

@@ -0,0 +1,142 @@
+# redash-mcp
+
+[Redash](https://redash.io)를 Claude AI에 연결하는 MCP 서버 — 자연어로 데이터를 조회하고 대시보드를 관리하세요.
+
+**[English Documentation](README.md)**
+
+---
+
+## 기능
+
+### 툴 목록
+
+| 카테고리 | 툴 | 설명 |
+|---|---|---|
+| 데이터소스 | `list_data_sources` | 연결된 데이터소스 목록 조회 |
+| 스키마 | `list_tables` | 테이블 목록 조회 (키워드 검색 가능) |
+| 스키마 | `get_table_columns` | 테이블 컬럼명 및 타입 조회 |
+| 쿼리 실행 | `run_query` | SQL 직접 실행 후 결과 반환 |
+| 저장 쿼리 | `list_queries` | 저장된 쿼리 목록 조회 |
+| 저장 쿼리 | `get_query` | 쿼리 상세 정보 (SQL, 시각화 등) 조회 |
+| 저장 쿼리 | `get_query_result` | 저장된 쿼리 실행 결과 조회 |
+| 저장 쿼리 | `create_query` | 새 쿼리 저장 |
+| 저장 쿼리 | `update_query` | 쿼리 수정 |
+| 저장 쿼리 | `fork_query` | 쿼리 복제 |
+| 저장 쿼리 | `archive_query` | 쿼리 삭제 (아카이브) |
+| 대시보드 | `list_dashboards` | 대시보드 목록 조회 |
+| 대시보드 | `get_dashboard` | 대시보드 상세 및 위젯 목록 조회 |
+| 대시보드 | `create_dashboard` | 새 대시보드 생성 |
+| 대시보드 | `add_widget` | 대시보드에 시각화 위젯 추가 |
+| 알림 | `list_alerts` | 알림 목록 조회 |
+| 알림 | `get_alert` | 알림 상세 정보 조회 |
+| 알림 | `create_alert` | 새 알림 생성 |
+
+### SQL 안전 가드
+
+위험한 쿼리로부터 데이터베이스를 보호합니다:
+
+- **항상 차단**: `DROP`, `TRUNCATE`, `ALTER TABLE`, `GRANT/REVOKE`, `WHERE` 없는 `DELETE/UPDATE`
+- **경고 (warn 모드)** / **차단 (strict 모드)**: `SELECT *`, `WHERE`·`LIMIT` 없는 쿼리, PII 컬럼 접근
+- **자동 LIMIT**: `REDASH_AUTO_LIMIT` 설정 시 LIMIT 없는 쿼리에 자동으로 `LIMIT N` 추가
+
+### 쿼리 캐시
+
+중복 API 호출을 줄이기 위해 결과를 메모리에 캐싱합니다:
+
+- TTL: `REDASH_MCP_CACHE_TTL` 환경변수로 설정 (기본값: 300초)
+- 최대 메모리: `REDASH_MCP_CACHE_MAX_MB` 환경변수로 설정 (기본값: 50MB)
+
+---
+
+## 설치
+
+### 자동 설치 (권장)
+
+```bash
+npx redash-mcp setup
+```
+
+설치 마법사가 실행되며 Claude Desktop, Claude Code(CLI), 또는 둘 다 선택하여 설정할 수 있습니다.
+
+### 수동 설치
+
+#### 1. Redash API 키 발급
+
+Redash → 우측 상단 프로필 → **Edit Profile** → **API Key** 복사
+
+#### 2-A. Claude Desktop 설정
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` 파일을 열고 아래 내용을 추가합니다:
+
+```json
+{
+  "mcpServers": {
+    "redash-mcp": {
+      "command": "npx",
+      "args": ["-y", "redash-mcp"],
+      "env": {
+        "REDASH_URL": "https://your-redash-instance.com",
+        "REDASH_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+저장 후 Claude Desktop을 완전히 종료했다가 다시 시작합니다.
+
+#### 2-B. Claude Code (CLI) 설정
+
+`~/.claude/settings.json` 파일을 열고 아래 내용을 추가합니다:
+
+```json
+{
+  "mcpServers": {
+    "redash-mcp": {
+      "command": "npx",
+      "args": ["-y", "redash-mcp"],
+      "env": {
+        "REDASH_URL": "https://your-redash-instance.com",
+        "REDASH_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+> **macOS**: `npx`를 못 찾는 경우 `which npx` 명령어로 전체 경로를 확인 후 대체하세요.
+
+---
+
+## 환경 변수
+
+### 필수
+
+| 변수 | 설명 |
+|---|---|
+| `REDASH_URL` | Redash 인스턴스 URL (예: `https://redash.example.com`) |
+| `REDASH_API_KEY` | Redash 사용자 API 키 |
+
+### 선택
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `REDASH_SAFETY_MODE` | `warn` | SQL 안전 수준: `off` / `warn` / `strict` |
+| `REDASH_SAFETY_DISABLE_PII` | `false` | PII 감지 비활성화 |
+| `REDASH_SAFETY_DISABLE_COST` | `false` | 비용 경고 비활성화 |
+| `REDASH_AUTO_LIMIT` | `0` | LIMIT 없는 쿼리에 자동으로 `LIMIT N` 추가 (0 = 비활성화) |
+| `REDASH_DEFAULT_MAX_AGE` | `0` | Redash 캐시 TTL (초) |
+| `REDASH_MCP_CACHE_TTL` | `300` | MCP 쿼리 캐시 TTL (초, 0 = 비활성화) |
+| `REDASH_MCP_CACHE_MAX_MB` | `50` | MCP 쿼리 캐시 최대 메모리 (MB) |
+
+---
+
+## 사용 예시
+
+Claude에게 자연어로 요청하면 됩니다:
+
+- "users 테이블 컬럼 보여줘"
+- "최근 7일 주문 수를 SQL로 조회해줘"
+- "저장된 쿼리 목록 보여줘"
+- "매출 대시보드 위젯 목록 알려줘"
+- "일별 가입자 수가 100명 이하로 떨어지면 알림 만들어줘"

package/README.md

@@ -1,49 +1,72 @@
 # redash-mcp
 
-[Redash](https://redash.io)를 Claude AI에서 직접 조회하고 관리할 수 있는 MCP(Model Context Protocol) 서버입니다.
+MCP server that connects [Redash](https://redash.io) to Claude AI — query data, manage dashboards, and run SQL with natural language.
 
-## 기능
+**[한국어 문서](README.ko.md)**
 
-| 카테고리 | 툴 | 설명 |
+---
+
+## Features
+
+### Tools
+
+| Category | Tool | Description |
 |---|---|---|
-| 데이터소스 | `list_data_sources` | 연결된 데이터소스 목록 조회 |
-| 스키마 | `list_tables` | 테이블 목록 조회 (키워드 검색 가능) |
-| 스키마 | `get_table_columns` | 테이블 컬럼명/타입 조회 |
-| 쿼리 실행 | `run_query` | SQL 직접 실행 후 결과 반환 |
-| 저장 쿼리 | `list_queries` | 저장된 쿼리 목록 조회 |
-| 저장 쿼리 | `get_query` | 쿼리 상세 정보(SQL, 시각화 등) 조회 |
-| 저장 쿼리 | `get_query_result` | 저장된 쿼리 실행 결과 조회 |
-| 저장 쿼리 | `create_query` | 새 쿼리 저장 |
-| 저장 쿼리 | `update_query` | 쿼리 수정 |
-| 저장 쿼리 | `fork_query` | 쿼리 복제 |
-| 저장 쿼리 | `archive_query` | 쿼리 삭제 |
-| 대시보드 | `list_dashboards` | 대시보드 목록 조회 |
-| 대시보드 | `get_dashboard` | 대시보드 상세 및 위젯 목록 조회 |
-| 대시보드 | `create_dashboard` | 새 대시보드 생성 |
-| 대시보드 | `add_widget` | 대시보드에 시각화 위젯 추가 |
-| 알림 | `list_alerts` | 알림 목록 조회 |
-| 알림 | `get_alert` | 알림 상세 정보 조회 |
-| 알림 | `create_alert` | 새 알림 생성 |
-
-## 설치
-
-### 자동 설치 (권장)
+| Data Sources | `list_data_sources` | List connected data sources |
+| Schema | `list_tables` | List tables (supports keyword search) |
+| Schema | `get_table_columns` | Get column names and types |
+| Query | `run_query` | Execute SQL and return results |
+| Saved Queries | `list_queries` | List saved queries |
+| Saved Queries | `get_query` | Get query details (SQL, visualizations) |
+| Saved Queries | `get_query_result` | Run a saved query and get results |
+| Saved Queries | `create_query` | Save a new query |
+| Saved Queries | `update_query` | Update a saved query |
+| Saved Queries | `fork_query` | Fork a saved query |
+| Saved Queries | `archive_query` | Archive (delete) a query |
+| Dashboards | `list_dashboards` | List dashboards |
+| Dashboards | `get_dashboard` | Get dashboard details and widgets |
+| Dashboards | `create_dashboard` | Create a new dashboard |
+| Dashboards | `add_widget` | Add a visualization widget to a dashboard |
+| Alerts | `list_alerts` | List alerts |
+| Alerts | `get_alert` | Get alert details |
+| Alerts | `create_alert` | Create a new alert |
+
+### SQL Safety Guard
+
+Protects your database from dangerous queries:
+
+- **Blocked always**: `DROP`, `TRUNCATE`, `ALTER TABLE`, `GRANT/REVOKE`, `DELETE/UPDATE` without `WHERE`
+- **Warned (warn mode)** / **Blocked (strict mode)**: `SELECT *`, queries without `WHERE` or `LIMIT`, PII column access
+- **Auto-LIMIT**: Automatically appends `LIMIT N` when `REDASH_AUTO_LIMIT` is set
+
+### Query Cache
+
+Results are cached in-memory to reduce redundant API calls:
+
+- TTL: configurable via `REDASH_MCP_CACHE_TTL` (default: 300s)
+- Max memory: configurable via `REDASH_MCP_CACHE_MAX_MB` (default: 50MB)
+
+---
+
+## Installation
+
+### Auto Setup (Recommended)
 
 ```bash
 npx redash-mcp setup
 ```
 
-설치 마법사가 실행되며 Claude Desktop, Claude Code(CLI), 또는 둘 다 선택하여 설정할 수 있습니다.
+The setup wizard will guide you through configuring Claude Desktop, Claude Code (CLI), or both.
 
-### 수동 설치
+### Manual Setup
 
-#### 1. Redash API 키 발급
+#### 1. Get your Redash API Key
 
-Redash → 우측 상단 프로필 → **Edit Profile** → **API Key** 복사
+Go to Redash → Profile (top right) → **Edit Profile** → Copy **API Key**
 
-#### 2-A. Claude Desktop 설정
+#### 2-A. Claude Desktop
 
-`~/Library/Application Support/Claude/claude_desktop_config.json` 파일을 열고 아래 내용을 추가합니다:
+Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add:
 
 ```json
 {
@@ -60,11 +83,11 @@ Redash → 우측 상단 프로필 → **Edit Profile** → **API Key** 복사
 }
 ```
 
-설정 저장 후 Claude Desktop을 완전히 종료했다가 다시 시작합니다.
+Fully quit and restart Claude Desktop after saving.
 
-#### 2-B. Claude Code (CLI) 설정
+#### 2-B. Claude Code (CLI)
 
-`~/.claude/settings.json` 파일을 열고 아래 내용을 추가합니다:
+Open `~/.claude/settings.json` and add:
 
 ```json
 {
@@ -81,23 +104,39 @@ Redash → 우측 상단 프로필 → **Edit Profile** → **API Key** 복사
 }
 ```
 
-새 Claude Code 세션에서 바로 사용할 수 있습니다.
+> **macOS**: If `npx` is not found, run `which npx` to get the full path and use that instead.
 
-> **Windows/Linux**: `command`를 `npx`로 그대로 사용하면 됩니다.
-> **macOS**: `npx`를 못 찾는 경우 `which npx` 명령어로 전체 경로를 확인 후 대체하세요.
+---
 
-## 환경 변수
+## Environment Variables
 
-| 변수 | 필수 | 설명 |
+### Required
+
+| Variable | Description |
+|---|---|
+| `REDASH_URL` | Redash instance URL (e.g. `https://redash.example.com`) |
+| `REDASH_API_KEY` | Redash user API key |
+
+### Optional
+
+| Variable | Default | Description |
 |---|---|---|
-| `REDASH_URL` | ✅ | Redash 인스턴스 URL (예: `https://redash.example.com`) |
-| `REDASH_API_KEY` | ✅ | Redash 사용자 API 키 |
+| `REDASH_SAFETY_MODE` | `warn` | SQL safety level: `off` / `warn` / `strict` |
+| `REDASH_SAFETY_DISABLE_PII` | `false` | Disable PII detection |
+| `REDASH_SAFETY_DISABLE_COST` | `false` | Disable cost warnings |
+| `REDASH_AUTO_LIMIT` | `0` | Auto-append `LIMIT N` to queries without one (0 = disabled) |
+| `REDASH_DEFAULT_MAX_AGE` | `0` | Redash cache TTL in seconds |
+| `REDASH_MCP_CACHE_TTL` | `300` | MCP query cache TTL in seconds (0 = disabled) |
+| `REDASH_MCP_CACHE_MAX_MB` | `50` | Max memory for MCP query cache in MB |
+
+---
 
-## 사용 예시
+## Usage Examples
 
-Claude에게 자연어로 요청하면 됩니다:
+Just ask Claude in natural language:
 
-- "Redash에서 users 테이블 컬럼 보여줘"
-- "최근 7일 주문 수를 SQL로 조회해줘"
-- "저장된 쿼리 목록 보여줘"
-- "매출 대시보드 위젯 목록 알려줘"
+- "Show me the columns in the users table"
+- "Run a query to get order counts for the last 7 days"
+- "List all saved queries"
+- "Show widgets in the revenue dashboard"
+- "Create an alert when daily signups drop below 100"

package/dist/index.js

@@ -2,6 +2,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { analyzeQuery } from "./sql-guard.js";
+import { getCached, setCached } from "./query-cache.js";
 if (process.argv[2] === "setup") {
     const { main } = await import("./setup.js");
     await main();
@@ -127,17 +129,52 @@ server.tool("get_table_columns", "테이블의 컬럼명과 타입을 반환합
     };
 });
 // ─── Query Execution ──────────────────────────────────────────────────────────
+const DEFAULT_MAX_AGE = parseInt(process.env.REDASH_DEFAULT_MAX_AGE ?? "0", 10) || 0;
 server.tool("run_query", "SQL을 데이터소스에 직접 실행하고 결과를 반환합니다. SQL 작성 전 list_tables → get_table_columns로 스키마를 먼저 확인하세요.", {
     data_source_id: z.number().describe("list_data_sources로 확인한 데이터소스 ID"),
     query: z.string().describe("실행할 SQL 쿼리"),
-    max_age: z.number().optional().default(0).describe("캐시 유지 시간(초), 0이면 항상 새로 실행"),
+    max_age: z.number().optional().describe("Redash 캐시 유지 시간(초). 미지정 시 REDASH_DEFAULT_MAX_AGE 환경변수 사용"),
     max_rows: z.number().optional().default(100).describe("반환할 최대 행 수 (기본 100)"),
     format: z.enum(["table", "json"]).optional().default("table").describe("결과 포맷: table(마크다운) 또는 json"),
     timeout_secs: z.number().optional().default(30).describe("쿼리 실행 타임아웃(초)"),
 }, async ({ data_source_id, query, max_age, max_rows, format, timeout_secs }) => {
+    // 1. SQL 안전 가드
+    const guard = analyzeQuery(query);
+    if (guard.blocked) {
+        return { content: [{ type: "text", text: guard.message }] };
+    }
+    // auto-LIMIT이 적용된 경우 변환된 쿼리 사용
+    const effectiveQuery = guard.modifiedQuery ?? query;
+    const effectiveMaxAge = max_age ?? DEFAULT_MAX_AGE;
+    // 2. MCP 레이어 캐시 조회
+    const cached = getCached(data_source_id, effectiveQuery);
+    if (cached) {
+        const { rows, columns, warningPrefix } = cached;
+        const displayRows = rows.slice(0, max_rows);
+        const truncated = rows.length > max_rows
+            ? `\n⚠️ 전체 ${rows.length}행 중 ${max_rows}행만 표시합니다.`
+            : "";
+        let body;
+        if (format === "json") {
+            body = JSON.stringify(displayRows, null, 2);
+        }
+        else {
+            body = formatAsMarkdownTable(columns, displayRows);
+        }
+        const cacheNote = "📦 MCP 캐시에서 반환된 결과입니다.\n\n";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${warningPrefix}${cacheNote}총 ${rows.length}행 | 컬럼: ${columns.join(", ")}${truncated}\n\n${body}`,
+                },
+            ],
+        };
+    }
+    // 3. Redash API 호출
     const res = await redashFetch("/query_results", {
         method: "POST",
-        body: JSON.stringify({ data_source_id, query, max_age }),
+        body: JSON.stringify({ data_source_id, query: effectiveQuery, max_age: effectiveMaxAge }),
     });
     let result;
     if (res.job) {
@@ -149,6 +186,9 @@ server.tool("run_query", "SQL을 데이터소스에 직접 실행하고 결과
     const qr = result.query_result;
     const rows = qr.data.rows;
     const columns = qr.data.columns.map((c) => c.name);
+    // 4. MCP 캐시에 저장
+    const warningPrefix = guard.message ? `${guard.message}\n\n` : "";
+    setCached(data_source_id, effectiveQuery, { rows, columns, warningPrefix });
     const displayRows = rows.slice(0, max_rows);
     const truncated = rows.length > max_rows
         ? `\n⚠️ 전체 ${rows.length}행 중 ${max_rows}행만 표시합니다.`
@@ -164,7 +204,7 @@ server.tool("run_query", "SQL을 데이터소스에 직접 실행하고 결과
         content: [
             {
                 type: "text",
-                text: `총 ${rows.length}행 | 컬럼: ${columns.join(", ")}${truncated}\n\n${body}`,
+                text: `${warningPrefix}총 ${rows.length}행 | 컬럼: ${columns.join(", ")}${truncated}\n\n${body}`,
             },
         ],
     };

package/dist/query-cache.js

@@ -0,0 +1,74 @@
+import { createHash } from "crypto";
+const cache = new Map();
+let totalSizeBytes = 0;
+function getCacheTtlMs() {
+    const ttl = parseInt(process.env.REDASH_MCP_CACHE_TTL ?? "300", 10);
+    return (isNaN(ttl) ? 300 : ttl) * 1000;
+}
+function getMaxSizeBytes() {
+    const mb = parseInt(process.env.REDASH_MCP_CACHE_MAX_MB ?? "50", 10);
+    return (isNaN(mb) ? 50 : mb) * 1024 * 1024;
+}
+function normalizeSQL(sql) {
+    return sql
+        .replace(/--[^\n]*/g, " ")
+        .replace(/\/\*[\s\S]*?\*\//g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+function makeCacheKey(dataSourceId, sql) {
+    return createHash("sha256")
+        .update(`${dataSourceId}:${normalizeSQL(sql)}`)
+        .digest("hex");
+}
+function roughSize(obj) {
+    return JSON.stringify(obj).length * 2;
+}
+export function getCached(dataSourceId, sql) {
+    const ttl = getCacheTtlMs();
+    if (ttl === 0)
+        return null;
+    const key = makeCacheKey(dataSourceId, sql);
+    const entry = cache.get(key);
+    if (!entry)
+        return null;
+    if (Date.now() - entry.ts > ttl) {
+        totalSizeBytes -= entry.size;
+        cache.delete(key);
+        return null;
+    }
+    return entry.result;
+}
+export function setCached(dataSourceId, sql, result) {
+    const ttl = getCacheTtlMs();
+    if (ttl === 0)
+        return;
+    const maxSize = getMaxSizeBytes();
+    const size = roughSize(result);
+    // 단일 결과가 전체 한도의 20% 초과 시 캐시하지 않음
+    if (size > maxSize * 0.2)
+        return;
+    // 한도 초과 시 오래된 항목부터 제거
+    while (totalSizeBytes + size > maxSize && cache.size > 0) {
+        const oldestKey = cache.keys().next().value;
+        if (!oldestKey)
+            break;
+        const old = cache.get(oldestKey);
+        totalSizeBytes -= old.size;
+        cache.delete(oldestKey);
+    }
+    const key = makeCacheKey(dataSourceId, sql);
+    const existing = cache.get(key);
+    if (existing)
+        totalSizeBytes -= existing.size;
+    cache.set(key, { result, ts: Date.now(), size });
+    totalSizeBytes += size;
+}
+export function getCacheStats() {
+    return {
+        entries: cache.size,
+        sizeMb: (totalSizeBytes / 1024 / 1024).toFixed(2),
+        ttlSecs: getCacheTtlMs() / 1000,
+    };
+}

package/dist/sql-guard.js

@@ -0,0 +1,159 @@
+function getConfig() {
+    const raw = process.env.REDASH_SAFETY_MODE ?? "warn";
+    const mode = ["off", "warn", "strict"].includes(raw) ? raw : "warn";
+    return {
+        mode,
+        disablePii: process.env.REDASH_SAFETY_DISABLE_PII === "true",
+        disableCost: process.env.REDASH_SAFETY_DISABLE_COST === "true",
+        autoLimit: parseInt(process.env.REDASH_AUTO_LIMIT ?? "0", 10) || 0,
+    };
+}
+function normalizeForAnalysis(sql) {
+    return sql
+        .replace(/--[^\n]*/g, " ")
+        .replace(/\/\*[\s\S]*?\*\//g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toUpperCase();
+}
+function hasWhere(sql) {
+    return /\bWHERE\b/.test(sql);
+}
+function hasLimit(sql) {
+    return /\bLIMIT\b/.test(sql);
+}
+function isSelect(sql) {
+    return /^\s*(SELECT|WITH)\b/i.test(sql);
+}
+function injectLimit(sql, limit) {
+    if (/\bLIMIT\b/i.test(sql))
+        return sql;
+    if (!isSelect(sql))
+        return sql;
+    return `${sql.trimEnd()} LIMIT ${limit}`;
+}
+export function analyzeQuery(sql) {
+    const config = getConfig();
+    if (config.mode === "off") {
+        return { blocked: false, warnings: [], message: "" };
+    }
+    const upper = normalizeForAnalysis(sql);
+    const warnings = [];
+    let modifiedQuery;
+    // ── Destructive (차단: warn/strict 모두) ────────────────────────────────────
+    if (/\bDROP\s+(TABLE|DATABASE|SCHEMA|VIEW|INDEX|FUNCTION)\b/.test(upper)) {
+        return {
+            blocked: true,
+            warnings: [],
+            message: "🚫 쿼리가 차단되었습니다.\n\n사유: DROP 문은 데이터/스키마를 영구 삭제합니다.\n규칙: DESTRUCTIVE / DROP\n\n해제가 필요하다면 REDASH_SAFETY_MODE=off 로 설정하세요.",
+        };
+    }
+    if (/\bTRUNCATE\b/.test(upper)) {
+        return {
+            blocked: true,
+            warnings: [],
+            message: "🚫 쿼리가 차단되었습니다.\n\n사유: TRUNCATE 문은 전체 테이블 데이터를 삭제합니다.\n규칙: DESTRUCTIVE / TRUNCATE",
+        };
+    }
+    if (/\bALTER\s+TABLE\b/.test(upper)) {
+        return {
+            blocked: true,
+            warnings: [],
+            message: "🚫 쿼리가 차단되었습니다.\n\n사유: ALTER TABLE은 스키마 변경으로 사전 협의가 필요합니다.\n규칙: DESTRUCTIVE / ALTER_TABLE",
+        };
+    }
+    if (/\b(GRANT|REVOKE)\b/.test(upper)) {
+        return {
+            blocked: true,
+            warnings: [],
+            message: "🚫 쿼리가 차단되었습니다.\n\n사유: GRANT/REVOKE는 권한 변경으로 허용되지 않습니다.\n규칙: DESTRUCTIVE / PRIVILEGE_CHANGE",
+        };
+    }
+    if (/\bDELETE\s+FROM\b/.test(upper) && !hasWhere(upper)) {
+        return {
+            blocked: true,
+            warnings: [],
+            message: "🚫 쿼리가 차단되었습니다.\n\n사유: WHERE 조건 없는 DELETE는 전체 데이터를 삭제합니다.\n규칙: DESTRUCTIVE / DELETE_WITHOUT_WHERE\n\n안전한 예시:\n  DELETE FROM orders WHERE created_at < '2024-01-01'",
+        };
+    }
+    if (/\bUPDATE\b/.test(upper) && /\bSET\b/.test(upper) && !hasWhere(upper)) {
+        return {
+            blocked: true,
+            warnings: [],
+            message: "🚫 쿼리가 차단되었습니다.\n\n사유: WHERE 조건 없는 UPDATE는 전체 데이터를 수정합니다.\n규칙: DESTRUCTIVE / UPDATE_WITHOUT_WHERE\n\n안전한 예시:\n  UPDATE orders SET status = 'cancelled' WHERE created_at < '2024-01-01'",
+        };
+    }
+    // DELETE/UPDATE with WHERE — 경고만
+    if (/\bDELETE\s+FROM\b/.test(upper)) {
+        warnings.push("[DESTRUCTIVE] DELETE 쿼리입니다. WHERE 조건을 다시 확인하세요.");
+    }
+    if (/\bUPDATE\b/.test(upper) && /\bSET\b/.test(upper)) {
+        warnings.push("[DESTRUCTIVE] UPDATE 쿼리입니다. WHERE 조건을 다시 확인하세요.");
+    }
+    // ── Cost (warn: 경고 후 실행, strict: 차단) ────────────────────────────────
+    if (!config.disableCost && isSelect(sql)) {
+        const hasSelectStar = /SELECT\s+\*/.test(upper) || /SELECT\s+[\w.]+\.\*/.test(upper);
+        const noWhere = !hasWhere(upper);
+        const noLimit = !hasLimit(upper);
+        if (hasSelectStar) {
+            warnings.push("[COST] SELECT *를 사용하고 있습니다. 필요한 컬럼만 명시하면 BigQuery 스캔 비용을 줄일 수 있습니다.");
+        }
+        if (noWhere) {
+            warnings.push("[COST] WHERE 조건이 없습니다. 날짜 또는 조건 필터를 추가하는 것을 권장합니다.");
+        }
+        if (noLimit) {
+            if (config.autoLimit > 0) {
+                modifiedQuery = injectLimit(sql, config.autoLimit);
+                warnings.push(`[COST] LIMIT이 없어 자동으로 LIMIT ${config.autoLimit}을 추가했습니다. 전체 조회가 필요하면 명시적으로 LIMIT을 지정하세요.`);
+            }
+            else {
+                warnings.push("[COST] LIMIT이 없습니다. 대용량 테이블에서는 전체 데이터가 반환되어 비용이 발생할 수 있습니다.");
+            }
+        }
+        if (config.mode === "strict") {
+            const costWarnings = warnings.filter((w) => w.startsWith("[COST]"));
+            if (costWarnings.length > 0) {
+                return {
+                    blocked: true,
+                    warnings: [],
+                    message: `🚫 쿼리가 차단되었습니다 (strict 모드).\n\n${costWarnings.join("\n")}\n\nwarn 모드로 변경하려면 REDASH_SAFETY_MODE=warn 으로 설정하세요.`,
+                };
+            }
+        }
+    }
+    // ── PII (warn: 경고 후 실행, strict: 차단) ────────────────────────────────
+    if (!config.disablePii) {
+        const piiPatterns = [
+            "EMAIL",
+            "PHONE",
+            "PASSWORD",
+            "PASSWD",
+            "SSN",
+            "SOCIAL_SECURITY",
+            "CREDIT_CARD",
+            "CARD_NUMBER",
+            "주민",
+            "휴대폰",
+            "핸드폰",
+            "생년월일",
+        ];
+        const matched = piiPatterns.filter((k) => upper.includes(k));
+        if (matched.length > 0) {
+            warnings.push(`[PII] 민감 정보 관련 컬럼이 감지되었습니다: ${matched.join(", ")}. 개인정보 처리 규정을 확인하세요.`);
+        }
+        if (config.mode === "strict") {
+            const piiWarnings = warnings.filter((w) => w.startsWith("[PII]"));
+            if (piiWarnings.length > 0) {
+                return {
+                    blocked: true,
+                    warnings: [],
+                    message: `🚫 쿼리가 차단되었습니다 (strict 모드).\n\n${piiWarnings.join("\n")}\n\nwarn 모드로 변경하려면 REDASH_SAFETY_MODE=warn 으로 설정하세요.`,
+                };
+            }
+        }
+    }
+    const message = warnings.length > 0
+        ? `⚠️ 안전 경고 (쿼리는 실행됩니다)\n\n${warnings.join("\n")}\n\n---`
+        : "";
+    return { blocked: false, warnings, message, modifiedQuery };
+}

package/docs/sql-safety-guard.md

@@ -0,0 +1,197 @@
+# SQL Safety Guard — 설계 문서
+
+## 개요
+
+`redash-mcp`에 SQL 안전 가드 레이어를 추가하여 MCP를 통해 실행되는 쿼리로 인한
+비용 발생, 데이터 손실, 개인정보 노출을 사전에 방지한다.
+
+---
+
+## 배경 및 목적
+
+- Redash를 MCP로 연결하면 AI가 자동으로 쿼리를 생성·실행하는 환경이 된다
+- 사용자가 SQL을 직접 검토하지 않는 경우가 많아 위험 쿼리가 그대로 실행될 수 있음
+- BigQuery는 스캔한 데이터 용량 기준으로 과금되어 예상치 못한 비용 발생 가능
+- AI가 생성한 쿼리에 DROP, DELETE 등이 포함될 경우 데이터 손실 위험
+
+---
+
+## 아키텍처
+
+### 위치
+
+```
+AI (Claude)
+    ↓ tool call
+run_query (MCP 도구)
+    ↓
+[SQL Safety Guard]  ← 여기에 삽입
+    ↓ 통과 시
+Redash API
+    ↓
+BigQuery
+```
+
+### 패턴
+
+미들웨어/인터셉터 패턴. `run_query` 핸들러 내부에서 Redash API 호출 전에 실행.
+
+```typescript
+// src/sql-guard.ts
+export function analyzeQuery(sql: string, mode: SafetyMode): SafetyResult
+
+// src/index.ts (run_query 핸들러)
+const result = analyzeQuery(query, safetyMode);
+if (result.blocked) {
+  return { content: [{ type: "text", text: result.message }] };
+}
+// ... Redash API 호출
+```
+
+---
+
+## 감지 규칙
+
+### Category 1: 데이터 파괴 (Destructive) — 기본: 차단
+
+| 규칙 | 패턴 예시 | 기본 동작 |
+|---|---|---|
+| DDL 변경 | `DROP TABLE`, `TRUNCATE`, `ALTER TABLE` | 차단 |
+| 조건 없는 삭제 | `DELETE FROM table` (WHERE 없음) | 차단 |
+| 조건 없는 수정 | `UPDATE table SET ...` (WHERE 없음) | 차단 |
+| 권한 변경 | `GRANT`, `REVOKE` | 차단 |
+
+### Category 2: 비용 위험 (Cost) — 기본: 경고
+
+| 규칙 | 패턴 예시 | 기본 동작 |
+|---|---|---|
+| WHERE 없는 SELECT | `SELECT ... FROM table` (WHERE 없음) | 경고 |
+| SELECT * | `SELECT * FROM ...` | 경고 |
+| 집계 없는 대량 조회 | 조건 없이 raw 데이터 전체 조회 | 경고 |
+
+### Category 3: 개인정보 (PII) — 기본: 경고
+
+| 규칙 | 감지 컬럼명 키워드 | 기본 동작 |
+|---|---|---|
+| 민감 컬럼 SELECT | `email`, `phone`, `password`, `ssn`, `social`, `주민`, `휴대폰`, `핸드폰` | 경고 |
+
+> PII 규칙은 컬럼명 기반 휴리스틱이며 오탐이 발생할 수 있다.
+> 환경변수로 비활성화 가능.
+
+---
+
+## 동작 모드
+
+```
+REDASH_SAFETY_MODE=off|warn|strict
+```
+
+| 모드 | Destructive | Cost | PII |
+|---|---|---|---|
+| `off` | 통과 | 통과 | 통과 |
+| `warn` (기본) | **차단** | 경고 후 실행 | 경고 후 실행 |
+| `strict` | **차단** | **차단** | **차단** |
+
+- Destructive는 모든 모드에서 `warn` 이상이면 차단 (데이터 손실은 되돌릴 수 없음)
+- `off`는 완전히 비활성화가 필요한 경우를 위해 제공 (내부 관리자용 등)
+
+---
+
+## 환경변수
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `REDASH_SAFETY_MODE` | `warn` | 전체 안전 모드 |
+| `REDASH_SAFETY_DISABLE_PII` | `false` | PII 감지 비활성화 |
+| `REDASH_SAFETY_DISABLE_COST` | `false` | 비용 경고 비활성화 |
+
+---
+
+## 응답 포맷
+
+### 차단 시
+
+```
+🚫 쿼리가 차단되었습니다.
+
+사유: WHERE 조건 없이 전체 테이블을 수정하는 쿼리는 실행할 수 없습니다.
+규칙: DESTRUCTIVE / UPDATE_WITHOUT_WHERE
+
+안전한 쿼리 예시:
+  UPDATE orders SET status = 'cancelled' WHERE created_at < '2024-01-01'
+
+안전 모드 해제가 필요하다면 REDASH_SAFETY_MODE=off 로 설정하세요.
+```
+
+### 경고 시 (warn 모드)
+
+```
+⚠️ 안전 경고 (쿼리는 실행됩니다)
+
+[COST] SELECT *를 사용하고 있습니다. 필요한 컬럼만 명시하면 비용을 줄일 수 있습니다.
+[COST] WHERE 조건이 없습니다. 날짜 또는 조건 필터를 추가하는 것을 권장합니다.
+
+---
+(쿼리 결과)
+```
+
+---
+
+## 파일 구조
+
+```
+src/
+  index.ts          # 기존 — run_query에 가드 연결
+  sql-guard.ts      # 신규 — 안전 가드 핵심 로직
+  setup.ts          # 기존 — 설치 마법사에 SAFETY_MODE 설정 추가
+```
+
+---
+
+## setup 마법사 변경
+
+```
+? BigQuery 안전 모드를 선택하세요
+  ○ off    — 제한 없음 (관리자 전용)
+  ● warn   — 위험 패턴 경고 후 실행 (권장)
+  ○ strict — 위험 쿼리 차단
+
+? 개인정보(PII) 컬럼 감지를 활성화하시겠습니까?
+  ● 예 / ○ 아니오
+```
+
+---
+
+## 구현 범위 (v2.2.0)
+
+### 포함
+- [x] Destructive 쿼리 차단 (DDL, DELETE/UPDATE without WHERE)
+- [x] Cost 경고/차단 (WHERE 없는 SELECT, SELECT *)
+- [x] PII 컬럼 경고 (컬럼명 기반)
+- [x] `REDASH_SAFETY_MODE` 환경변수
+- [x] setup 마법사 안전 모드 설정 추가
+- [x] 단위 테스트 (vitest)
+
+### 제외 (추후 검토)
+- Cartesian JOIN 감지 (SQL 파서 필요, 복잡도 높음)
+- 쿼리 실행 횟수 기반 Rate limiting (상태 관리 필요)
+- 실제 BQ 스캔 바이트 추정 (BQ 직접 접근 불가)
+
+---
+
+## 공식 플러그인 등록
+
+### MCP 공식 레지스트리
+- `modelcontextprotocol/servers` GitHub 레포에 PR 제출
+- 요건: npm 패키지, README, 설치 가이드
+
+### Claude Desktop
+- 현재 Claude Desktop 플러그인 = MCP 서버
+- 공식 디렉토리 등록은 Anthropic 신청 필요 (초대제 운영 중)
+- 단기적으로는 MCP 커뮤니티 레지스트리 등록으로 대응
+
+### 등록 준비 체크리스트
+- [ ] README 영문화 (설치, 환경변수, 도구 목록)
+- [ ] 라이선스 명시 (MIT)
+- [ ] 버전 관리 전략 (semver)
+- [ ] CHANGELOG 작성

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "redash-mcp",
-  "version": "2.1.1",
+  "version": "2.2.2",
   "description": "MCP server for Redash",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seob717/redash-mcp.git"
+  },
+  "homepage": "https://github.com/seob717/redash-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/seob717/redash-mcp/issues"
+  },
   "type": "module",
   "main": "dist/index.js",
   "bin": {