redash-mcp 3.0.4 → 3.1.0

package/README.ko.md

@@ -136,6 +136,10 @@ Redash → 우측 상단 프로필 → **Edit Profile** → **API Key** 복사
 | `REDASH_DEFAULT_MAX_AGE` | `0` | Redash 캐시 TTL (초) |
 | `REDASH_MCP_CACHE_TTL` | `300` | MCP 쿼리 캐시 TTL (초, 0 = 비활성화) |
 | `REDASH_MCP_CACHE_MAX_MB` | `50` | MCP 쿼리 캐시 최대 메모리 (MB) |
+| `REDASH_MCP_CONFIG_DIR` | `~/.redash-mcp` | BIRD few-shot/피드백/평가/키워드맵 저장 디렉터리 |
+| `REDASH_BIRD_ENABLED` | `true` | `false`로 설정하면 BIRD smart query 도구 비활성화 |
+| `REDASH_HTTP_TIMEOUT_SECS` | `30` | Redash API 요청 단위 HTTP 타임아웃 |
+| `ANTHROPIC_API_KEY` | — | 설정 시 BIRD smart_query가 키워드 매칭 실패 시 Claude Haiku로 테이블 선택 폴백 |
 
 ---
 

package/README.md

@@ -136,6 +136,10 @@ Open `~/.claude/settings.json` and add:
 | `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 |
+| `REDASH_MCP_CONFIG_DIR` | `~/.redash-mcp` | Directory for BIRD few-shot, feedback, eval, keyword-map data |
+| `REDASH_BIRD_ENABLED` | `true` | Set to `false` to disable BIRD smart query tools |
+| `REDASH_HTTP_TIMEOUT_SECS` | `30` | Per-request HTTP timeout against the Redash API |
+| `ANTHROPIC_API_KEY` | — | If set, BIRD smart_query falls back to Claude Haiku for table selection when keyword scoring fails |
 
 ---
 

package/dist/bird/evaluation.js

@@ -1,6 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { ensureConfigDir, getDataSourcePath } from "./config.js";
-import { redashFetch } from "../redash-client.js";
+import { redashFetch, pollQueryResult } from "../redash-client.js";
 export async function loadTestSuite(dataSourceId) {
     try {
         const raw = await readFile(getDataSourcePath("eval", dataSourceId), "utf-8");
@@ -135,19 +135,7 @@ async function executeQuery(dataSourceId, sql) {
     });
     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");
+        result = await pollQueryResult(res.job.id, 30);
     }
     else {
         result = res;

package/dist/bird/feedback.js

@@ -29,7 +29,6 @@ export async function recordFeedback(dataSourceId, entry) {
         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) {
@@ -37,10 +36,10 @@ export async function recordFeedback(dataSourceId, entry) {
             if (sameErrorCount >= config.bird.feedback.autoPromoteThreshold) {
                 await promoteToFewShot(dataSourceId, newEntry);
                 newEntry.promotedToFewShot = true;
-                await saveFeedback(dataSourceId, entries);
             }
         }
     }
+    await saveFeedback(dataSourceId, entries);
     return newEntry;
 }
 export function classifyError(generatedSql, correctSql) {

package/dist/bird/few-shot.js

@@ -83,7 +83,7 @@ function tokenize(text) {
         "it", "its", "this", "that", "these", "those", "what", "which",
         "who", "whom", "how", "where", "when", "why",
         "show", "give", "tell", "get", "find", "list", "display",
-        "의", "���", "이", "은", "는", "을", "를", "에", "에서", "와", "과",
+        "의", "가", "이", "은", "는", "을", "를", "에", "에서", "와", "과",
         "도", "로", "으로", "만", "까지", "부터", "에게", "한테", "께",
         "좀", "해줘", "알려줘", "보여줘", "해", "하는", "된", "인",
     ]);

package/dist/bird/smart-query.js

@@ -99,8 +99,13 @@ function detectVagueness(question, prunedTables) {
     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) {
+    const trimmed = question.trim();
+    const wordCount = trimmed.split(/\s+/).length;
+    const hasCJK = /[ㄱ-힝]/.test(trimmed);
+    const tooShort = hasCJK
+        ? trimmed.replace(/\s+/g, "").length < 6
+        : wordCount < 4;
+    if (tooShort) {
         clarifications.push("Could you provide more details about what data you need?");
     }
     const maxScore = Math.max(...prunedTables.map((t) => t.score), 0);

package/dist/bird/tools.js

@@ -64,7 +64,7 @@ export function registerBirdTools(server) {
             .optional()
             .describe("Example to add (required when action=add)"),
         example_id: z.string().optional().describe("Example ID to remove (required when action=remove)"),
-    }, { destructiveHint: true }, async ({ data_source_id, action, example, example_id }) => {
+    }, {}, async ({ data_source_id, action, example, example_id }) => {
         try {
             if (action === "list") {
                 const examples = await loadExamples(data_source_id);
@@ -118,7 +118,7 @@ export function registerBirdTools(server) {
         generated_sql: z.string().describe("Generated SQL"),
         correct_sql: z.string().optional().describe("Correct SQL (provide when rating=down for automatic learning)"),
         rating: z.enum(["up", "down"]).describe("Rating: up (correct) or down (incorrect)"),
-    }, { destructiveHint: true }, async ({ data_source_id, question, generated_sql, correct_sql, rating }) => {
+    }, {}, async ({ data_source_id, question, generated_sql, correct_sql, rating }) => {
         try {
             const entry = await recordFeedback(data_source_id, {
                 question,
@@ -159,7 +159,7 @@ export function registerBirdTools(server) {
         }))
             .optional()
             .describe("List of SQL to evaluate (required when action=run)"),
-    }, { destructiveHint: true }, async ({ data_source_id, action, test_case, test_case_id, generated_sqls }) => {
+    }, {}, async ({ data_source_id, action, test_case, test_case_id, generated_sqls }) => {
         try {
             if (action === "list_tests") {
                 const store = await loadTestSuite(data_source_id);
@@ -227,14 +227,14 @@ export function registerBirdTools(server) {
         data_source_id: z.number().describe("Data source ID"),
         action: z.enum(["list", "add", "remove", "reset"]).describe("Action to perform"),
         mappings: z
-            .record(z.array(z.string()))
+            .record(z.string(), z.array(z.string()))
             .optional()
             .describe("Mappings to add (required when action=add). e.g., {\"revenue\": [\"payment\", \"billing\"]}"),
         keywords: z
             .array(z.string())
             .optional()
             .describe("Keywords to remove (required when action=remove). e.g., [\"revenue\", \"order\"]"),
-    }, { destructiveHint: true }, async ({ data_source_id, action, mappings, keywords }) => {
+    }, {}, async ({ data_source_id, action, mappings, keywords }) => {
         try {
             if (action === "list") {
                 const effective = await getEffectiveMap(data_source_id);

package/dist/index.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -16,9 +19,20 @@ if (!REDASH_URL || !REDASH_API_KEY) {
     console.error("REDASH_URL and REDASH_API_KEY environment variables are required");
     process.exit(1);
 }
+function readPackageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkgPath = path.join(here, "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
 const server = new McpServer({
     name: "redash-mcp",
-    version: "3.0.0",
+    version: readPackageVersion(),
 });
 server.tool("list_data_sources", "List connected data sources (id, name, type). Call this first to get data_source_id.", {}, { readOnlyHint: true }, async () => {
     try {
@@ -174,9 +188,10 @@ server.tool("list_queries", "List saved queries in Redash.", {
     page_size: z.number().optional().default(20).describe("Page size (max 100)"),
 }, { readOnlyHint: true }, async ({ search, page, page_size }) => {
     try {
-        const effectivePageSize = Math.min(page_size, 100);
+        const effectivePageSize = Math.max(1, Math.min(page_size, 100));
+        const effectivePage = Math.max(1, page);
         const params = new URLSearchParams({
-            page: String(page),
+            page: String(effectivePage),
             page_size: String(effectivePageSize),
             ...(search ? { q: search } : {}),
         });
@@ -200,7 +215,8 @@ server.tool("get_query_result", "Execute a saved query by ID and return results.
     query_id: z.number().describe("Saved query ID (from list_queries)"),
     max_rows: z.number().optional().default(100).describe("Max rows to return (default 100)"),
     format: z.enum(["table", "json"]).optional().default("table").describe("Output format: table (markdown) or json"),
-}, { readOnlyHint: true }, async ({ query_id, max_rows, format }) => {
+    timeout_secs: z.number().optional().default(30).describe("Query execution timeout in seconds"),
+}, { readOnlyHint: true }, async ({ query_id, max_rows, format, timeout_secs }) => {
     try {
         const res = await redashFetch(`/queries/${query_id}/results`, {
             method: "POST",
@@ -208,7 +224,7 @@ server.tool("get_query_result", "Execute a saved query by ID and return results.
         });
         let result;
         if (res.job) {
-            result = await pollQueryResult(res.job.id);
+            result = await pollQueryResult(res.job.id, timeout_secs);
         }
         else {
             result = res;
@@ -371,9 +387,10 @@ server.tool("list_dashboards", "List dashboards in Redash.", {
     page_size: z.number().optional().default(20).describe("Page size (max 100)"),
 }, { readOnlyHint: true }, async ({ search, page, page_size }) => {
     try {
-        const effectivePageSize = Math.min(page_size, 100);
+        const effectivePageSize = Math.max(1, Math.min(page_size, 100));
+        const effectivePage = Math.max(1, page);
         const params = new URLSearchParams({
-            page: String(page),
+            page: String(effectivePage),
             page_size: String(effectivePageSize),
             ...(search ? { q: search } : {}),
         });
@@ -447,7 +464,7 @@ server.tool("add_widget", "Add a visualization widget to a dashboard. Get visual
     dashboard_id: z.number().describe("Dashboard ID"),
     visualization_id: z.number().describe("Visualization ID (from get_query's visualizations)"),
     text: z.string().optional().default("").describe("Widget text"),
-    width: z.number().optional().default(1).describe("Widget width (1 or 2)"),
+    width: z.union([z.literal(1), z.literal(2)]).optional().default(1).describe("Widget width (1 = half, 2 = full)"),
 }, { destructiveHint: true }, async ({ dashboard_id, visualization_id, text, width }) => {
     try {
         const data = await redashFetch("/widgets", {

package/dist/query-cache.js

@@ -25,6 +25,17 @@ function makeCacheKey(dataSourceId, sql) {
 function roughSize(obj) {
     return JSON.stringify(obj).length * 2;
 }
+function purgeExpired(ttl) {
+    if (ttl === 0)
+        return;
+    const now = Date.now();
+    for (const [key, entry] of cache) {
+        if (now - entry.ts > ttl) {
+            totalSizeBytes -= entry.size;
+            cache.delete(key);
+        }
+    }
+}
 export function getCached(dataSourceId, sql) {
     const ttl = getCacheTtlMs();
     if (ttl === 0)
@@ -38,6 +49,9 @@ export function getCached(dataSourceId, sql) {
         cache.delete(key);
         return null;
     }
+    // Touch entry to maintain LRU order via insertion-order Map semantics.
+    cache.delete(key);
+    cache.set(key, entry);
     return entry.result;
 }
 export function setCached(dataSourceId, sql, result) {
@@ -48,6 +62,7 @@ export function setCached(dataSourceId, sql, result) {
     const size = roughSize(result);
     if (size > maxSize * 0.2)
         return;
+    purgeExpired(ttl);
     while (totalSizeBytes + size > maxSize && cache.size > 0) {
         const oldestKey = cache.keys().next().value;
         if (!oldestKey)

package/dist/redash-client.js

@@ -24,16 +24,35 @@ function validateRedashUrl(raw) {
 }
 const REDASH_URL = validateRedashUrl(process.env.REDASH_URL);
 const REDASH_API_KEY = process.env.REDASH_API_KEY;
+const HTTP_TIMEOUT_MS = (() => {
+    const raw = parseInt(process.env.REDASH_HTTP_TIMEOUT_SECS ?? "30", 10);
+    return (isNaN(raw) || raw <= 0 ? 30 : raw) * 1000;
+})();
 export { REDASH_URL, REDASH_API_KEY };
 export async function redashFetch(path, options) {
-    const res = await fetch(`${REDASH_URL}/api${path}`, {
-        ...options,
-        headers: {
-            "Authorization": `Key ${REDASH_API_KEY}`,
-            "Content-Type": "application/json",
-            ...options?.headers,
-        },
-    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
+    let res;
+    try {
+        res = await fetch(`${REDASH_URL}/api${path}`, {
+            ...options,
+            signal: options?.signal ?? controller.signal,
+            headers: {
+                "Authorization": `Key ${REDASH_API_KEY}`,
+                "Content-Type": "application/json",
+                ...options?.headers,
+            },
+        });
+    }
+    catch (err) {
+        if (err?.name === "AbortError") {
+            throw new Error(`Redash request timed out after ${HTTP_TIMEOUT_MS / 1000}s`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
     if (!res.ok) {
         let hint = "";
         if (res.status === 401)
@@ -50,7 +69,9 @@ export async function redashFetch(path, options) {
     return res.json();
 }
 export async function pollQueryResult(jobId, timeoutSecs = 30) {
-    for (let i = 0; i < timeoutSecs; i++) {
+    const deadline = Date.now() + timeoutSecs * 1000;
+    let delayMs = 250;
+    while (Date.now() < deadline) {
         const job = await redashFetch(`/jobs/${jobId}`);
         if (job.job.status === 3) {
             return await redashFetch(`/query_results/${job.job.query_result_id}`);
@@ -58,7 +79,11 @@ export async function pollQueryResult(jobId, timeoutSecs = 30) {
         if (job.job.status === 4) {
             throw new Error(`Query failed: ${job.job.error}`);
         }
-        await new Promise((r) => setTimeout(r, 1000));
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await new Promise((r) => setTimeout(r, Math.min(delayMs, remaining)));
+        delayMs = Math.min(delayMs * 2, 2000);
     }
     throw new Error(`Query timed out after ${timeoutSecs}s`);
 }
@@ -73,16 +98,27 @@ export function formatAsMarkdownTable(columns, rows) {
 }
 const schemaCache = new Map();
 const CACHE_TTL_MS = 10 * 60 * 1000;
+const SCHEMA_CACHE_MAX_ENTRIES = 32;
 export async function fetchSchema(dataSourceId) {
     const cached = schemaCache.get(dataSourceId);
     if (cached && Date.now() - cached.ts < CACHE_TTL_MS) {
+        schemaCache.delete(dataSourceId);
+        schemaCache.set(dataSourceId, cached);
         return cached.schema;
     }
+    if (cached)
+        schemaCache.delete(dataSourceId);
     const result = await redashFetch(`/data_sources/${dataSourceId}/schema`);
     const schema = (result.schema ?? []).map((table) => ({
         ...table,
         columns: (table.columns ?? []).map((c) => typeof c === "string" ? { name: c, type: "unknown" } : c),
     }));
+    while (schemaCache.size >= SCHEMA_CACHE_MAX_ENTRIES) {
+        const oldest = schemaCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        schemaCache.delete(oldest);
+    }
     schemaCache.set(dataSourceId, { schema, ts: Date.now() });
     return schema;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "redash-mcp",
   "mcpName": "io.github.seob717/redash-mcp",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "MCP server for Redash",
   "license": "MIT",
   "author": "seob717",
@@ -32,17 +32,20 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.80.0",
-    "@clack/prompts": "^1.1.0",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.0.0"
+    "@anthropic-ai/sdk": "^0.95.2",
+    "@clack/prompts": "^1.4.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.6"
   }
 }