redash-mcp 2.2.2 → 3.0.1

package/dist/bird/feedback.js

@@ -0,0 +1,154 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { ensureConfigDir, getDataSourcePath, loadConfig } from "./config.js";
+import { addExample } from "./few-shot.js";
+export async function loadFeedback(dataSourceId) {
+    try {
+        const raw = await readFile(getDataSourcePath("feedback", dataSourceId), "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed.entries ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+async function saveFeedback(dataSourceId, entries) {
+    await ensureConfigDir();
+    const data = { dataSourceId, entries };
+    await writeFile(getDataSourcePath("feedback", dataSourceId), JSON.stringify(data, null, 2), "utf-8");
+}
+export async function recordFeedback(dataSourceId, entry) {
+    const entries = await loadFeedback(dataSourceId);
+    const errorType = entry.rating === "down" && entry.correctSql
+        ? classifyError(entry.generatedSql, entry.correctSql)
+        : undefined;
+    const newEntry = {
+        ...entry,
+        id: `fb_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+        errorType,
+        promotedToFewShot: false,
+        createdAt: new Date().toISOString(),
+    };
+    entries.push(newEntry);
+    await saveFeedback(dataSourceId, entries);
+    if (newEntry.rating === "down" && newEntry.correctSql && newEntry.errorType) {
+        const config = await loadConfig();
+        if (config.bird.feedback.enabled) {
+            const sameErrorCount = entries.filter((e) => e.errorType === newEntry.errorType && e.rating === "down" && !e.promotedToFewShot).length;
+            if (sameErrorCount >= config.bird.feedback.autoPromoteThreshold) {
+                await promoteToFewShot(dataSourceId, newEntry);
+                newEntry.promotedToFewShot = true;
+                await saveFeedback(dataSourceId, entries);
+            }
+        }
+    }
+    return newEntry;
+}
+export function classifyError(generatedSql, correctSql) {
+    const genTables = extractTables(generatedSql);
+    const correctTables = extractTables(correctSql);
+    const genColumns = extractColumns(generatedSql);
+    const correctColumns = extractColumns(correctSql);
+    const tableDiff = symmetricDifference(genTables, correctTables);
+    if (tableDiff.size > 0) {
+        return "wrong_table";
+    }
+    const colDiff = symmetricDifference(genColumns, correctColumns);
+    if (colDiff.size > 0) {
+        const genJoins = extractJoins(generatedSql);
+        const correctJoins = extractJoins(correctSql);
+        if (genJoins !== correctJoins) {
+            return "wrong_join";
+        }
+        return "wrong_column";
+    }
+    const genWhere = extractWhere(generatedSql);
+    const correctWhere = extractWhere(correctSql);
+    if (genWhere !== correctWhere) {
+        return "wrong_filter";
+    }
+    const genGroup = extractGroupBy(generatedSql);
+    const correctGroup = extractGroupBy(correctSql);
+    if (genGroup !== correctGroup) {
+        return "wrong_aggregation";
+    }
+    return "other";
+}
+async function promoteToFewShot(dataSourceId, entry) {
+    if (!entry.correctSql)
+        return;
+    const tables = [...extractTables(entry.correctSql)];
+    await addExample(dataSourceId, {
+        question: entry.question,
+        sql: entry.correctSql,
+        tables,
+        tags: [entry.errorType ?? "correction"],
+        notes: `Auto-promoted from feedback. Original error: ${entry.errorType}`,
+        source: "feedback",
+    });
+}
+function extractTables(sql) {
+    const tables = new Set();
+    const normalized = sql.toLowerCase().replace(/\s+/g, " ");
+    const fromMatch = normalized.match(/\bfrom\s+(\w+)/g);
+    if (fromMatch) {
+        for (const m of fromMatch) {
+            const t = m.replace(/^from\s+/i, "").trim();
+            if (t && !SQL_KEYWORDS.has(t))
+                tables.add(t);
+        }
+    }
+    const joinMatch = normalized.match(/\bjoin\s+(\w+)/g);
+    if (joinMatch) {
+        for (const m of joinMatch) {
+            const t = m.replace(/^join\s+/i, "").trim();
+            if (t && !SQL_KEYWORDS.has(t))
+                tables.add(t);
+        }
+    }
+    return tables;
+}
+function extractColumns(sql) {
+    const columns = new Set();
+    const normalized = sql.toLowerCase().replace(/\s+/g, " ");
+    const selectMatch = normalized.match(/select\s+(.*?)\s+from/);
+    if (selectMatch) {
+        const cols = selectMatch[1].split(",").map((c) => c.trim().replace(/.*\bas\b\s*/i, ""));
+        for (const c of cols) {
+            if (c !== "*")
+                columns.add(c.replace(/.*\./, ""));
+        }
+    }
+    return columns;
+}
+function extractWhere(sql) {
+    const normalized = sql.toLowerCase().replace(/\s+/g, " ");
+    const match = normalized.match(/\bwhere\s+(.*?)(?:\bgroup\b|\border\b|\blimit\b|\bhaving\b|$)/);
+    return match ? match[1].trim() : "";
+}
+function extractGroupBy(sql) {
+    const normalized = sql.toLowerCase().replace(/\s+/g, " ");
+    const match = normalized.match(/\bgroup\s+by\s+(.*?)(?:\border\b|\blimit\b|\bhaving\b|$)/);
+    return match ? match[1].trim() : "";
+}
+function extractJoins(sql) {
+    const normalized = sql.toLowerCase().replace(/\s+/g, " ");
+    const matches = normalized.match(/\bjoin\s+.*?\bon\s+.*?(?=\bjoin\b|\bwhere\b|\bgroup\b|\border\b|\blimit\b|$)/g);
+    return matches ? matches.sort().join("; ") : "";
+}
+function symmetricDifference(a, b) {
+    const diff = new Set();
+    for (const item of a)
+        if (!b.has(item))
+            diff.add(item);
+    for (const item of b)
+        if (!a.has(item))
+            diff.add(item);
+    return diff;
+}
+const SQL_KEYWORDS = new Set([
+    "select", "from", "where", "join", "inner", "left", "right", "outer",
+    "cross", "on", "and", "or", "not", "in", "exists", "between", "like",
+    "is", "null", "true", "false", "as", "case", "when", "then", "else",
+    "end", "group", "by", "order", "having", "limit", "offset", "union",
+    "all", "distinct", "set", "values", "into", "insert", "update", "delete",
+]);

package/dist/bird/few-shot.js

@@ -0,0 +1,95 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { ensureConfigDir, getDataSourcePath } from "./config.js";
+export async function loadExamples(dataSourceId) {
+    try {
+        const raw = await readFile(getDataSourcePath("few-shot", dataSourceId), "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed.examples ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function saveExamples(dataSourceId, examples) {
+    await ensureConfigDir();
+    const data = { dataSourceId, examples };
+    await writeFile(getDataSourcePath("few-shot", dataSourceId), JSON.stringify(data, null, 2), "utf-8");
+}
+export async function addExample(dataSourceId, example) {
+    const examples = await loadExamples(dataSourceId);
+    const newExample = {
+        ...example,
+        id: `ex_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+        createdAt: new Date().toISOString(),
+    };
+    examples.push(newExample);
+    await saveExamples(dataSourceId, examples);
+    return newExample;
+}
+export async function removeExample(dataSourceId, exampleId) {
+    const examples = await loadExamples(dataSourceId);
+    const filtered = examples.filter((e) => e.id !== exampleId);
+    if (filtered.length === examples.length)
+        return false;
+    await saveExamples(dataSourceId, filtered);
+    return true;
+}
+export function findRelevantExamples(question, prunedTableNames, allExamples, maxCount) {
+    if (allExamples.length === 0)
+        return [];
+    const questionTokens = tokenize(question);
+    const scored = allExamples.map((example) => {
+        let score = 0;
+        const tableOverlap = example.tables.filter((t) => prunedTableNames.some((pt) => pt.toLowerCase() === t.toLowerCase())).length;
+        score += tableOverlap * 3;
+        const exampleTokens = tokenize(`${example.question} ${example.tags.join(" ")}`);
+        const keywordOverlap = questionTokens.filter((t) => exampleTokens.includes(t)).length;
+        score += keywordOverlap;
+        return { example, score };
+    });
+    return scored
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxCount)
+        .map((s) => s.example);
+}
+export function formatExamplesForPrompt(examples) {
+    if (examples.length === 0)
+        return "";
+    const lines = ["## Similar query examples:\n"];
+    examples.forEach((ex, i) => {
+        lines.push(`### Example ${i + 1}: "${ex.question}"`);
+        lines.push("```sql");
+        lines.push(ex.sql);
+        lines.push("```");
+        if (ex.notes) {
+            lines.push(`> Note: ${ex.notes}`);
+        }
+        lines.push("");
+    });
+    return lines.join("\n");
+}
+function tokenize(text) {
+    const STOP_WORDS = new Set([
+        "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+        "have", "has", "had", "do", "does", "did", "will", "would", "could",
+        "should", "may", "might", "shall", "can", "need", "dare", "ought",
+        "to", "of", "in", "for", "on", "with", "at", "by", "from", "as",
+        "into", "through", "during", "before", "after", "above", "below",
+        "and", "but", "or", "not", "no", "nor", "so", "yet", "both",
+        "each", "all", "any", "few", "more", "most", "other", "some",
+        "such", "than", "too", "very", "just", "about",
+        "me", "my", "i", "you", "your", "we", "our", "they", "their",
+        "it", "its", "this", "that", "these", "those", "what", "which",
+        "who", "whom", "how", "where", "when", "why",
+        "show", "give", "tell", "get", "find", "list", "display",
+        "의", "���", "이", "은", "는", "을", "를", "에", "에서", "와", "과",
+        "도", "로", "으로", "만", "까지", "부터", "에게", "한테", "께",
+        "좀", "해줘", "알려줘", "보여줘", "해", "하는", "된", "인",
+    ]);
+    return text
+        .toLowerCase()
+        .replace(/[^\w\sㄱ-ㅎㅏ-ㅣ가-힣]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 1 && !STOP_WORDS.has(w));
+}

package/dist/bird/keyword-map.js

@@ -0,0 +1,56 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { ensureConfigDir, getConfigDir } from "./config.js";
+import path from "node:path";
+const DEFAULT_KEYWORD_MAP = {};
+function getMapPath(dataSourceId) {
+    return path.join(getConfigDir(), "keyword-map", `${dataSourceId}.json`);
+}
+export async function loadKeywordMap(dataSourceId) {
+    try {
+        const raw = await readFile(getMapPath(dataSourceId), "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed.mappings ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+async function saveKeywordMap(dataSourceId, mappings) {
+    await ensureConfigDir();
+    const data = {
+        dataSourceId,
+        mappings,
+        updatedAt: new Date().toISOString(),
+    };
+    await writeFile(getMapPath(dataSourceId), JSON.stringify(data, null, 2), "utf-8");
+}
+export async function addMappings(dataSourceId, newMappings) {
+    const existing = await loadKeywordMap(dataSourceId);
+    for (const [key, values] of Object.entries(newMappings)) {
+        const existingValues = existing[key] ?? [];
+        existing[key] = [...new Set([...existingValues, ...values])];
+    }
+    await saveKeywordMap(dataSourceId, existing);
+    return existing;
+}
+export async function removeMappings(dataSourceId, keywords) {
+    const existing = await loadKeywordMap(dataSourceId);
+    for (const key of keywords) {
+        delete existing[key];
+    }
+    await saveKeywordMap(dataSourceId, existing);
+    return existing;
+}
+export async function resetMappings(dataSourceId) {
+    await saveKeywordMap(dataSourceId, {});
+}
+export async function getEffectiveMap(dataSourceId) {
+    const custom = await loadKeywordMap(dataSourceId);
+    const merged = { ...DEFAULT_KEYWORD_MAP };
+    for (const [key, values] of Object.entries(custom)) {
+        const existing = merged[key] ?? [];
+        merged[key] = [...new Set([...existing, ...values])];
+    }
+    return merged;
+}
+export { DEFAULT_KEYWORD_MAP };

package/dist/bird/llm-table-selector.js

@@ -0,0 +1,59 @@
+import Anthropic from "@anthropic-ai/sdk";
+let client = null;
+function getClient() {
+    if (client)
+        return client;
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+        return null;
+    client = new Anthropic({ apiKey });
+    return client;
+}
+export function isLLMAvailable() {
+    return !!process.env.ANTHROPIC_API_KEY;
+}
+/**
+ * Uses Claude Haiku to select relevant tables from a list based on a natural language question.
+ * Returns table names that are likely relevant to the question.
+ */
+export async function selectTablesWithLLM(question, fullSchema, topK) {
+    const anthropic = getClient();
+    if (!anthropic)
+        return [];
+    try {
+        const tableList = fullSchema
+            .map((t) => {
+            const cols = (t.columns ?? []).map((c) => c.name).join(", ");
+            return `- ${t.name} (${cols})`;
+        })
+            .join("\n");
+        const response = await anthropic.messages.create({
+            model: "claude-haiku-4-5-20251001",
+            max_tokens: 300,
+            messages: [
+                {
+                    role: "user",
+                    content: `Given this database schema, select the ${topK} most relevant tables for the question.
+
+Question: ${question}
+
+Tables:
+${tableList}
+
+Reply with ONLY a JSON array of table names, e.g. ["User", "Order"]. No explanation.`,
+                },
+            ],
+        });
+        const text = response.content[0].type === "text" ? response.content[0].text : "";
+        const match = text.match(/\[.*\]/s);
+        if (!match)
+            return [];
+        const parsed = JSON.parse(match[0]);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((name) => typeof name === "string" && fullSchema.some((t) => t.name === name));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/bird/schema-pruning.js

@@ -0,0 +1,107 @@
+export function pruneSchema(question, fullSchema, fewShotExamples, topK, keywordMap) {
+    const tokens = tokenizeQuestion(question);
+    if (tokens.length === 0) {
+        return fullSchema.slice(0, topK).map((t) => ({
+            name: t.name,
+            columns: t.columns ?? [],
+            score: 0,
+        }));
+    }
+    const fewShotTableSet = new Set();
+    for (const ex of fewShotExamples) {
+        for (const t of ex.tables) {
+            fewShotTableSet.add(t.toLowerCase());
+        }
+    }
+    const scored = fullSchema.map((table) => {
+        const score = scoreTable(table, tokens, fewShotTableSet, keywordMap);
+        return {
+            name: table.name,
+            columns: table.columns ?? [],
+            score,
+        };
+    });
+    return scored
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK);
+}
+function expandTokens(tokens, keywordMap) {
+    if (!keywordMap)
+        return tokens;
+    const expanded = [...tokens];
+    for (const token of tokens) {
+        if (keywordMap[token]) {
+            expanded.push(...keywordMap[token]);
+            continue;
+        }
+        for (const [keyword, mappings] of Object.entries(keywordMap)) {
+            if (token.includes(keyword) || keyword.includes(token)) {
+                expanded.push(...mappings);
+            }
+        }
+    }
+    return [...new Set(expanded)];
+}
+function scoreTable(table, tokens, fewShotTables, keywordMap) {
+    let score = 0;
+    const tableLower = table.name.toLowerCase();
+    const expandedTokens = expandTokens(tokens, keywordMap);
+    for (const token of expandedTokens) {
+        if (tableLower.includes(token)) {
+            score += 3;
+        }
+        else if (tableLower.replace(/_/g, "").includes(token)) {
+            score += 1;
+        }
+    }
+    for (const col of table.columns ?? []) {
+        const colLower = col.name.toLowerCase();
+        for (const token of expandedTokens) {
+            if (colLower.includes(token)) {
+                score += 1;
+                break;
+            }
+        }
+    }
+    if (fewShotTables.has(tableLower)) {
+        score += 2;
+    }
+    return score;
+}
+export function formatPrunedSchema(tables) {
+    const lines = ["## Relevant tables:\n"];
+    for (const table of tables) {
+        lines.push(`### ${table.name}`);
+        if (table.columns.length > 0) {
+            lines.push("| Column | Type |");
+            lines.push("| --- | --- |");
+            for (const col of table.columns) {
+                lines.push(`| ${col.name} | ${col.type ?? "unknown"} |`);
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function tokenizeQuestion(question) {
+    const STOP_WORDS = new Set([
+        "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+        "have", "has", "had", "do", "does", "did", "will", "would", "could",
+        "should", "may", "might", "can", "need",
+        "to", "of", "in", "for", "on", "with", "at", "by", "from", "as",
+        "and", "but", "or", "not", "no", "so",
+        "me", "my", "i", "you", "your", "we", "our", "they", "their",
+        "it", "its", "this", "that", "what", "which", "how", "where", "when", "why",
+        "show", "give", "tell", "get", "find", "list", "display", "many", "much",
+        "select", "count", "sum", "avg", "all", "each", "every",
+        "의", "가", "이", "은", "는", "을", "를", "에", "에서", "와", "과",
+        "도", "로", "으로", "만", "까지", "부터",
+        "좀", "해줘", "알려줘", "보여줘", "해", "하는", "된", "인", "수",
+        "총", "전체", "모든", "몇", "얼마나",
+    ]);
+    return question
+        .toLowerCase()
+        .replace(/[^\w\sㄱ-ㅎㅏ-ㅣ가-힣]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 1 && !STOP_WORDS.has(w));
+}

package/dist/bird/smart-query.js

@@ -0,0 +1,117 @@
+import { fetchSchema } from "../redash-client.js";
+import { loadConfig } from "./config.js";
+import { loadExamples, findRelevantExamples, formatExamplesForPrompt } from "./few-shot.js";
+import { pruneSchema, formatPrunedSchema } from "./schema-pruning.js";
+import { assessComplexity } from "./complexity.js";
+import { getEffectiveMap } from "./keyword-map.js";
+import { isLLMAvailable, selectTablesWithLLM } from "./llm-table-selector.js";
+export async function handleSmartQuery(params) {
+    const { question, data_source_id, context } = params;
+    const config = await loadConfig();
+    let fullSchema;
+    try {
+        fullSchema = await fetchSchema(data_source_id);
+    }
+    catch (e) {
+        return { action: "explain", explanation: `Schema fetch failed: ${e.message}` };
+    }
+    // Defensive: ensure columns are objects
+    for (const table of fullSchema) {
+        table.columns = (table.columns ?? []).map((c) => typeof c === "string" ? { name: c, type: "unknown" } : c);
+    }
+    const allExamples = config.bird.fewShot.enabled
+        ? await loadExamples(data_source_id)
+        : [];
+    const keywordMap = await getEffectiveMap(data_source_id);
+    const combinedQuestion = context ? `${question} ${context}` : question;
+    let prunedTables;
+    if (config.bird.schemaPruning.enabled) {
+        prunedTables = pruneSchema(combinedQuestion, fullSchema, allExamples, config.bird.schemaPruning.topK, keywordMap);
+    }
+    else {
+        prunedTables = fullSchema.slice(0, 10).map((t) => ({
+            name: t.name,
+            columns: t.columns ?? [],
+            score: 0,
+        }));
+    }
+    // LLM fallback: when token matching fails to find relevant tables
+    const maxScore = Math.max(...prunedTables.map((t) => t.score), 0);
+    if (maxScore === 0 && isLLMAvailable()) {
+        const llmSelected = await selectTablesWithLLM(combinedQuestion, fullSchema, config.bird.schemaPruning.topK);
+        if (llmSelected.length > 0) {
+            const selectedSet = new Set(llmSelected);
+            prunedTables = fullSchema
+                .filter((t) => selectedSet.has(t.name))
+                .map((t) => ({
+                name: t.name,
+                columns: t.columns ?? [],
+                score: 1,
+            }));
+        }
+    }
+    if (!context) {
+        const clarifications = detectVagueness(question, prunedTables);
+        if (clarifications.length > 0) {
+            return {
+                action: "clarify",
+                clarificationQuestions: clarifications,
+            };
+        }
+    }
+    const prunedTableNames = prunedTables.map((t) => t.name);
+    const matchedExamples = findRelevantExamples(question, prunedTableNames, allExamples, config.bird.fewShot.maxExamplesPerQuery);
+    const complexity = config.bird.complexity.enabled
+        ? assessComplexity(context ? `${question} ${context}` : question, prunedTables)
+        : undefined;
+    const guidanceParts = [];
+    if (context) {
+        guidanceParts.push(`User clarification: ${context}`);
+    }
+    if (complexity) {
+        guidanceParts.push(`Difficulty: ${complexity.level} (${complexity.reasoning})`);
+        if (complexity.hints.length > 0) {
+            guidanceParts.push(`Hints: ${complexity.hints.join(". ")}`);
+        }
+    }
+    return {
+        action: "generate",
+        schema: formatPrunedSchema(prunedTables),
+        fewShotExamples: formatExamplesForPrompt(matchedExamples),
+        complexity,
+        guidance: guidanceParts.join("\n"),
+    };
+}
+function detectVagueness(question, prunedTables) {
+    const clarifications = [];
+    const q = question.toLowerCase();
+    const timeKeywords = [
+        "recent", "lately", "last", "previous", "this",
+        "최근", "지난", "이번", "저번", "올해", "작년",
+    ];
+    const timeSpecifiers = [
+        "day", "week", "month", "year", "quarter", "hour",
+        "일", "주", "월", "년", "분기", "시간",
+        /\d{4}[-\/]\d{1,2}/, /\d{1,2}[-\/]\d{1,2}/,
+    ];
+    const hasTimeKeyword = timeKeywords.some((kw) => q.includes(kw));
+    const hasTimeSpecifier = timeSpecifiers.some((spec) => spec instanceof RegExp ? spec.test(q) : q.includes(spec));
+    if (hasTimeKeyword && !hasTimeSpecifier) {
+        clarifications.push("Which specific time period? (e.g., last 7 days, last month, 2025-01-01 ~ 2025-03-31)");
+    }
+    const wordCount = question.trim().split(/\s+/).length;
+    if (wordCount < 4) {
+        clarifications.push("Could you provide more details about what data you need?");
+    }
+    const maxScore = Math.max(...prunedTables.map((t) => t.score), 0);
+    if (maxScore === 0 && prunedTables.length > 0) {
+        clarifications.push("I couldn't identify which tables are relevant. Could you mention specific entities (e.g., users, orders, payments)?");
+    }
+    if (maxScore > 0) {
+        const topTables = prunedTables.filter((t) => t.score === maxScore);
+        if (topTables.length > 3) {
+            clarifications.push(`Multiple tables match your question (${topTables.slice(0, 5).map((t) => t.name).join(", ")}). Could you be more specific about which data you need?`);
+        }
+    }
+    return clarifications;
+}