redash-mcp 2.2.2 → 3.0.1

package/.mcpregistry_github_token

@@ -0,0 +1 @@
+ghu_dsrWVzfpwaX2kRTPNSRLrvL3zmHffn3VITVr

package/.mcpregistry_registry_token

@@ -0,0 +1 @@
+{"token":"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtY3AtcmVnaXN0cnkiLCJleHAiOjE3NzQ3OTU0NjgsIm5iZiI6MTc3NDc5NTE2OCwiaWF0IjoxNzc0Nzk1MTY4LCJhdXRoX21ldGhvZCI6ImdpdGh1Yi1hdCIsImF1dGhfbWV0aG9kX3N1YiI6InNlb2I3MTciLCJwZXJtaXNzaW9ucyI6W3siYWN0aW9uIjoicHVibGlzaCIsInJlc291cmNlIjoiaW8uZ2l0aHViLnNlb2I3MTcvKiJ9XX0.Pkr8qgN33oPEpJbyouEcfZf3fbEL0gcQ4-_fuqHbBrjqPFzN3It0AbrNMBSVTkHNLkdF9PWF1kj3U61refW4Aw","expires_at":1774795468}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 seob717
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -58,6 +58,14 @@ npx redash-mcp setup
 
 설치 마법사가 실행되며 Claude Desktop, Claude Code(CLI), 또는 둘 다 선택하여 설정할 수 있습니다.
 
+### 셸 스크립트로 설치
+
+Node.js, Claude Desktop, MCP 설정을 한번에 처리합니다:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/seob717/redash-mcp/main/install.sh | bash
+```
+
 ### 수동 설치
 
 #### 1. Redash API 키 발급
@@ -140,3 +148,76 @@ Claude에게 자연어로 요청하면 됩니다:
 - "저장된 쿼리 목록 보여줘"
 - "매출 대시보드 위젯 목록 알려줘"
 - "일별 가입자 수가 100명 이하로 떨어지면 알림 만들어줘"
+
+### 예제 1: 자연어로 데이터 조회
+
+> **프롬프트**: "이번 달 신규 가입자 수 알려줘"
+
+**실행 흐름:**
+1. `list_data_sources` → 데이터소스 목록 확인
+2. `smart_query` → 질문 분석, 관련 테이블(`User`) 자동 선택, SQL 생성 가이드 제공
+3. `run_query` → 생성된 SQL 실행
+
+**결과:**
+```
+이번 달 신규 가입자는 18,197명입니다.
+```
+
+### 예제 2: 복잡한 비즈니스 질문
+
+> **프롬프트**: "지난주 신규 가입자 중 결제한 사용자 비율은?"
+
+**실행 흐름:**
+1. `smart_query` → 질문 분석, `User`·`Payment` 테이블 자동 선택, JOIN 쿼리 가이드 제공
+2. `run_query` → SQL 실행
+
+**결과:**
+```
+지난주 신규 가입자 1,204명 중 결제한 사용자는 312명 (25.9%)입니다.
+```
+
+### 예제 3: 쿼리 저장 + 대시보드 생성
+
+> **프롬프트**: "월별 매출 추이 쿼리를 만들고 대시보드에 추가해줘"
+
+**실행 흐름:**
+1. `smart_query` → 매출 관련 테이블 분석
+2. `create_query` → "월별 매출 추이" 쿼리 저장
+3. `create_dashboard` → "매출 대시보드" 생성
+4. `get_query` → 저장된 쿼리의 시각화 ID 확인
+5. `add_widget` → 대시보드에 차트 위젯 추가
+
+**결과:**
+```
+"매출 대시보드"가 생성되었고, 월별 매출 추이 차트가 추가되었습니다.
+Redash에서 확인: https://your-redash.com/dashboard/monthly-revenue
+```
+
+---
+
+## Privacy Policy
+
+### 데이터 수집 및 처리
+
+redash-mcp는 **로컬 MCP 서버**로, 사용자의 Redash 인스턴스와 직접 통신합니다. 중간 서버를 거치지 않습니다.
+
+| 항목 | 설명 |
+|------|------|
+| **Redash API Key** | 로컬 환경변수(`REDASH_API_KEY`)로만 저장. 외부 전송 없음 |
+| **쿼리 내용 및 결과** | MCP 프로토콜을 통해 로컬 클라이언트(Claude Desktop/Code)에만 전달 |
+| **BIRD SQL 설정** | 로컬 파일(`~/.redash-mcp/`)에만 저장. Few-shot 예제, 키워드 맵, 피드백 등 |
+| **LLM Fallback** | `ANTHROPIC_API_KEY` 설정 시, 테이블명 목록만 Anthropic API로 전송. 쿼리 데이터·결과는 전송하지 않음 |
+
+### 제3자 공유
+
+사용자 데이터를 제3자에게 판매하거나 공유하지 않습니다. LLM Fallback 기능 사용 시 Anthropic API로 테이블명 목록만 전송되며, 이는 사용자가 `ANTHROPIC_API_KEY`를 설정한 경우에만 활성화됩니다.
+
+### 데이터 보존
+
+- 설정 파일: `~/.redash-mcp/` 디렉토리에 로컬 저장 (사용자가 직접 삭제 가능)
+- 쿼리 캐시: 메모리에만 저장, 서버 종료 시 소멸
+- 스키마 캐시: 메모리에만 저장, 10분 TTL 후 자동 소멸
+
+### 연락처
+
+문의 및 보안 이슈 보고: [GitHub Issues](https://github.com/seob717/redash-mcp/issues)

package/README.md

@@ -58,6 +58,14 @@ npx redash-mcp setup
 
 The setup wizard will guide you through configuring Claude Desktop, Claude Code (CLI), or both.
 
+### Shell Script Install
+
+Installs Node.js, Claude Desktop, and MCP config all at once:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/seob717/redash-mcp/main/install.sh | bash
+```
+
 ### Manual Setup
 
 #### 1. Get your Redash API Key
@@ -140,3 +148,76 @@ Just ask Claude in natural language:
 - "List all saved queries"
 - "Show widgets in the revenue dashboard"
 - "Create an alert when daily signups drop below 100"
+
+### Example 1: Query data with natural language
+
+> **Prompt**: "How many new users signed up this month?"
+
+**Tool flow:**
+1. `list_data_sources` → Identify the target data source
+2. `smart_query` → Analyze the question, auto-select the `User` table, provide SQL generation guidance
+3. `run_query` → Execute the generated SQL
+
+**Result:**
+```
+There were 18,197 new signups this month.
+```
+
+### Example 2: Complex business questions
+
+> **Prompt**: "What percentage of last week's new users made a purchase?"
+
+**Tool flow:**
+1. `smart_query` → Analyze the question, auto-select `User` and `Payment` tables, provide JOIN query guidance
+2. `run_query` → Execute the SQL
+
+**Result:**
+```
+Out of 1,204 new users last week, 312 made a purchase (25.9%).
+```
+
+### Example 3: Create a query and dashboard
+
+> **Prompt**: "Create a monthly revenue trend query and add it to a dashboard"
+
+**Tool flow:**
+1. `smart_query` → Analyze revenue-related tables
+2. `create_query` → Save the "Monthly Revenue Trend" query
+3. `create_dashboard` → Create a "Revenue Dashboard"
+4. `get_query` → Get the visualization ID from the saved query
+5. `add_widget` → Add the chart widget to the dashboard
+
+**Result:**
+```
+Created "Revenue Dashboard" with the monthly revenue trend chart.
+View in Redash: https://your-redash.com/dashboard/monthly-revenue
+```
+
+---
+
+## Privacy Policy
+
+### Data Collection and Processing
+
+redash-mcp is a **local MCP server** that communicates directly with your Redash instance. No intermediate servers are involved.
+
+| Item | Description |
+|------|-------------|
+| **Redash API Key** | Stored only as a local environment variable (`REDASH_API_KEY`). Never transmitted externally. |
+| **Query content & results** | Delivered only to the local MCP client (Claude Desktop/Code) via the MCP protocol. |
+| **BIRD SQL settings** | Stored only in local files (`~/.redash-mcp/`). Includes few-shot examples, keyword maps, and feedback. |
+| **LLM Fallback** | When `ANTHROPIC_API_KEY` is set, only table name lists are sent to the Anthropic API. Query data and results are never transmitted. |
+
+### Third-Party Sharing
+
+We do not sell or share user data with third parties. When the LLM Fallback feature is active, only table name lists are sent to the Anthropic API, and only when the user has explicitly configured an `ANTHROPIC_API_KEY`.
+
+### Data Retention
+
+- **Config files**: Stored locally in `~/.redash-mcp/` (user can delete at any time)
+- **Query cache**: In-memory only, cleared on server shutdown
+- **Schema cache**: In-memory only, auto-expires after 10-minute TTL
+
+### Contact
+
+For inquiries and security reports: [GitHub Issues](https://github.com/seob717/redash-mcp/issues)

package/dist/bird/complexity.js

@@ -0,0 +1,87 @@
+export function assessComplexity(question, prunedTables) {
+    let score = 0;
+    const hints = [];
+    const reasons = [];
+    const q = question.toLowerCase();
+    const relevantTables = prunedTables.filter((t) => t.score > 0).length;
+    if (relevantTables > 1) {
+        score += (relevantTables - 1) * 2;
+        reasons.push(`${relevantTables} tables involved`);
+    }
+    const joinKeywords = ["join", "combine", "relate", "between tables", "연결", "결합", "조인"];
+    if (joinKeywords.some((kw) => q.includes(kw))) {
+        score += 2;
+        reasons.push("explicit join requested");
+        hints.push("Verify JOIN conditions match the correct foreign keys.");
+    }
+    const subqueryKeywords = [
+        "for each", "among those", "within", "nested", "sub",
+        "중에서", "각각", "그중", "해당하는",
+    ];
+    if (subqueryKeywords.some((kw) => q.includes(kw))) {
+        score += 2;
+        reasons.push("subquery likely needed");
+        hints.push("Consider using CTEs for readability.");
+    }
+    const windowKeywords = [
+        "ranking", "rank", "running total", "cumulative", "previous",
+        "percentile", "top n", "nth",
+        "순위", "누적", "이전", "상위",
+    ];
+    if (windowKeywords.some((kw) => q.includes(kw))) {
+        score += 3;
+        reasons.push("window functions may be needed");
+        hints.push("Use window functions (ROW_NUMBER, RANK, LAG/LEAD) as appropriate.");
+    }
+    const pivotKeywords = [
+        "compare across", "breakdown by", "pivot", "crosstab",
+        "비교", "교차", "피벗", "대비",
+    ];
+    if (pivotKeywords.some((kw) => q.includes(kw))) {
+        score += 2;
+        reasons.push("cross-comparison or pivoting needed");
+        hints.push("Consider CASE WHEN for pivot-style queries.");
+    }
+    const timeCompareKeywords = [
+        "year over year", "month over month", "yoy", "mom",
+        "growth rate", "change rate", "trend",
+        "전년", "전월", "증감", "추이", "변화율", "성장률",
+    ];
+    if (timeCompareKeywords.some((kw) => q.includes(kw))) {
+        score += 2;
+        reasons.push("time-based comparison needed");
+        hints.push("Use LAG() or self-join for period-over-period comparisons.");
+    }
+    const ratioKeywords = [
+        "ratio", "rate", "conversion", "percentage", "proportion",
+        "비율", "전환율", "퍼센트", "점유율",
+    ];
+    if (ratioKeywords.some((kw) => q.includes(kw))) {
+        score += 1;
+        reasons.push("ratio calculation involved");
+    }
+    let level;
+    if (score <= 2) {
+        level = "simple";
+    }
+    else if (score <= 5) {
+        level = "medium";
+    }
+    else {
+        level = "complex";
+    }
+    if (level === "simple" && hints.length === 0) {
+        hints.push("Straightforward query. Focus on correct column names and filter values.");
+    }
+    if (level === "medium" && hints.length === 0) {
+        hints.push("Moderate complexity. Double-check JOIN conditions and GROUP BY columns.");
+    }
+    if (level === "complex" && hints.length === 0) {
+        hints.push("Complex query. Consider breaking into CTEs for clarity and correctness.");
+    }
+    return {
+        level,
+        reasoning: reasons.length > 0 ? reasons.join("; ") : "single table with basic filtering",
+        hints,
+    };
+}

package/dist/bird/config.js

@@ -0,0 +1,73 @@
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const DEFAULT_CONFIG = {
+    bird: {
+        enabled: true,
+        schemaPruning: {
+            enabled: true,
+            topK: 7,
+            includeSampleValues: true,
+            maxSampleValues: 5,
+        },
+        fewShot: {
+            enabled: true,
+            maxExamplesPerQuery: 3,
+        },
+        feedback: {
+            enabled: true,
+            autoPromoteThreshold: 3,
+        },
+        complexity: {
+            enabled: true,
+        },
+    },
+};
+export function getConfigDir() {
+    return process.env.REDASH_MCP_CONFIG_DIR || path.join(os.homedir(), ".redash-mcp");
+}
+export async function ensureConfigDir() {
+    const dir = getConfigDir();
+    for (const sub of ["", "few-shot", "feedback", "eval", "keyword-map"]) {
+        const p = path.join(dir, sub);
+        if (!existsSync(p)) {
+            await mkdir(p, { recursive: true });
+        }
+    }
+}
+export function getDataSourcePath(subdir, dataSourceId) {
+    return path.join(getConfigDir(), subdir, `${dataSourceId}.json`);
+}
+export async function loadConfig() {
+    const configPath = path.join(getConfigDir(), "config.json");
+    try {
+        const raw = await readFile(configPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return deepMerge(DEFAULT_CONFIG, parsed);
+    }
+    catch {
+        return DEFAULT_CONFIG;
+    }
+}
+export async function saveConfig(config) {
+    await ensureConfigDir();
+    const configPath = path.join(getConfigDir(), "config.json");
+    await writeFile(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        if (source[key] &&
+            typeof source[key] === "object" &&
+            !Array.isArray(source[key]) &&
+            target[key] &&
+            typeof target[key] === "object") {
+            result[key] = deepMerge(target[key], source[key]);
+        }
+        else {
+            result[key] = source[key];
+        }
+    }
+    return result;
+}

package/dist/bird/evaluation.js

@@ -0,0 +1,184 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { ensureConfigDir, getDataSourcePath } from "./config.js";
+import { redashFetch } from "../redash-client.js";
+export async function loadTestSuite(dataSourceId) {
+    try {
+        const raw = await readFile(getDataSourcePath("eval", dataSourceId), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { dataSourceId, testCases: [], runs: [] };
+    }
+}
+async function saveTestSuite(dataSourceId, store) {
+    await ensureConfigDir();
+    await writeFile(getDataSourcePath("eval", dataSourceId), JSON.stringify(store, null, 2), "utf-8");
+}
+export async function addTestCase(dataSourceId, testCase) {
+    const store = await loadTestSuite(dataSourceId);
+    const newCase = {
+        ...testCase,
+        id: `tc_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+    };
+    store.testCases.push(newCase);
+    await saveTestSuite(dataSourceId, store);
+    return newCase;
+}
+export async function removeTestCase(dataSourceId, testCaseId) {
+    const store = await loadTestSuite(dataSourceId);
+    const filtered = store.testCases.filter((tc) => tc.id !== testCaseId);
+    if (filtered.length === store.testCases.length)
+        return false;
+    store.testCases = filtered;
+    await saveTestSuite(dataSourceId, store);
+    return true;
+}
+export async function runEvaluation(dataSourceId, generatedSqls) {
+    const store = await loadTestSuite(dataSourceId);
+    const results = [];
+    for (const { testCaseId, generatedSql } of generatedSqls) {
+        const testCase = store.testCases.find((tc) => tc.id === testCaseId);
+        if (!testCase) {
+            results.push({
+                testCaseId,
+                generatedSql,
+                match: false,
+                details: "Test case not found",
+            });
+            continue;
+        }
+        try {
+            const match = await compareQueryResults(dataSourceId, testCase.groundTruthSql, generatedSql);
+            results.push({
+                testCaseId,
+                generatedSql,
+                match: match.isMatch,
+                details: match.details,
+            });
+        }
+        catch (err) {
+            results.push({
+                testCaseId,
+                generatedSql,
+                match: false,
+                details: `Execution error: ${err.message}`,
+            });
+        }
+    }
+    const matchCount = results.filter((r) => r.match).length;
+    const total = results.length;
+    const byDifficulty = (level) => {
+        const relevant = generatedSqls
+            .map((gs) => ({
+            ...gs,
+            testCase: store.testCases.find((tc) => tc.id === gs.testCaseId),
+        }))
+            .filter((gs) => gs.testCase?.difficulty === level);
+        if (relevant.length === 0)
+            return 0;
+        const matches = relevant.filter((gs) => results.find((r) => r.testCaseId === gs.testCaseId)?.match).length;
+        return matches / relevant.length;
+    };
+    const run = {
+        runId: `run_${Date.now()}`,
+        timestamp: new Date().toISOString(),
+        results,
+        accuracy: {
+            overall: total > 0 ? matchCount / total : 0,
+            simple: byDifficulty("simple"),
+            medium: byDifficulty("medium"),
+            complex: byDifficulty("complex"),
+        },
+    };
+    store.runs.push(run);
+    if (store.runs.length > 10) {
+        store.runs = store.runs.slice(-10);
+    }
+    await saveTestSuite(dataSourceId, store);
+    return run;
+}
+async function compareQueryResults(dataSourceId, groundTruthSql, generatedSql) {
+    const [gtResult, genResult] = await Promise.all([
+        executeQuery(dataSourceId, groundTruthSql),
+        executeQuery(dataSourceId, generatedSql),
+    ]);
+    const gtCols = new Set(gtResult.columns);
+    const genCols = new Set(genResult.columns);
+    if (gtCols.size !== genCols.size || ![...gtCols].every((c) => genCols.has(c))) {
+        return {
+            isMatch: false,
+            details: `Column mismatch: expected [${[...gtCols].join(", ")}], got [${[...genCols].join(", ")}]`,
+        };
+    }
+    if (gtResult.rows.length !== genResult.rows.length) {
+        return {
+            isMatch: false,
+            details: `Row count mismatch: expected ${gtResult.rows.length}, got ${genResult.rows.length}`,
+        };
+    }
+    const gtSorted = sortRows(gtResult.rows, gtResult.columns);
+    const genSorted = sortRows(genResult.rows, genResult.columns);
+    for (let i = 0; i < gtSorted.length; i++) {
+        if (gtSorted[i] !== genSorted[i]) {
+            return {
+                isMatch: false,
+                details: `Data mismatch at row ${i + 1}`,
+            };
+        }
+    }
+    return { isMatch: true, details: "Exact match" };
+}
+async function executeQuery(dataSourceId, sql) {
+    const res = await redashFetch("/query_results", {
+        method: "POST",
+        body: JSON.stringify({ data_source_id: dataSourceId, query: sql, max_age: 0 }),
+    });
+    let result;
+    if (res.job) {
+        for (let i = 0; i < 30; i++) {
+            const job = await redashFetch(`/jobs/${res.job.id}`);
+            if (job.job.status === 3) {
+                result = await redashFetch(`/query_results/${job.job.query_result_id}`);
+                break;
+            }
+            if (job.job.status === 4) {
+                throw new Error(`Query failed: ${job.job.error}`);
+            }
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+        if (!result)
+            throw new Error("Query timed out");
+    }
+    else {
+        result = res;
+    }
+    const qr = result.query_result;
+    return {
+        columns: qr.data.columns.map((c) => c.name),
+        rows: qr.data.rows,
+    };
+}
+function sortRows(rows, columns) {
+    return rows
+        .map((row) => columns.map((c) => String(row[c] ?? "")).join("|"))
+        .sort();
+}
+export function formatEvalResults(run) {
+    const lines = [
+        `## Evaluation Results (${run.timestamp})`,
+        "",
+        `**Overall Accuracy**: ${(run.accuracy.overall * 100).toFixed(1)}% (${run.results.filter((r) => r.match).length}/${run.results.length})`,
+        `- Simple: ${(run.accuracy.simple * 100).toFixed(1)}%`,
+        `- Medium: ${(run.accuracy.medium * 100).toFixed(1)}%`,
+        `- Complex: ${(run.accuracy.complex * 100).toFixed(1)}%`,
+        "",
+    ];
+    const failures = run.results.filter((r) => !r.match);
+    if (failures.length > 0) {
+        lines.push("### Failed Cases:");
+        for (const f of failures) {
+            lines.push(`- **${f.testCaseId}**: ${f.details}`);
+        }
+    }
+    return lines.join("\n");
+}