redash-mcp 2.2.1 → 3.0.0

package/dist/index.js

@@ -4,82 +4,22 @@ 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";
+import { REDASH_URL, REDASH_API_KEY, redashFetch, pollQueryResult, formatAsMarkdownTable, fetchSchema } from "./redash-client.js";
+import { registerBirdTools } from "./bird/tools.js";
 if (process.argv[2] === "setup") {
     const { main } = await import("./setup.js");
     await main();
     process.exit(0);
 }
-const REDASH_URL = process.env.REDASH_URL?.replace(/\/$/, "");
-const REDASH_API_KEY = process.env.REDASH_API_KEY;
 if (!REDASH_URL || !REDASH_API_KEY) {
     console.error("REDASH_URL and REDASH_API_KEY environment variables are required");
     process.exit(1);
 }
-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,
-        },
-    });
-    if (!res.ok) {
-        let hint = "";
-        if (res.status === 401)
-            hint = " (REDASH_API_KEY를 확인하세요)";
-        else if (res.status === 403)
-            hint = " (해당 리소스에 대한 접근 권한이 없습니다)";
-        else if (res.status === 404)
-            hint = " (리소스를 찾을 수 없습니다. ID를 확인하세요)";
-        throw new Error(`Redash API error: ${res.status} ${res.statusText}${hint}`);
-    }
-    if (res.status === 204 || res.headers.get("content-length") === "0") {
-        return null;
-    }
-    return res.json();
-}
-async function pollQueryResult(jobId, timeoutSecs = 30) {
-    for (let i = 0; i < timeoutSecs; i++) {
-        const job = await redashFetch(`/jobs/${jobId}`);
-        if (job.job.status === 3) { // 3 = success
-            return await redashFetch(`/query_results/${job.job.query_result_id}`);
-        }
-        if (job.job.status === 4) { // 4 = failure
-            throw new Error(`Query failed: ${job.job.error}`);
-        }
-        await new Promise((r) => setTimeout(r, 1000));
-    }
-    throw new Error(`Query timed out after ${timeoutSecs}s`);
-}
-function formatAsMarkdownTable(columns, rows) {
-    const escape = (s) => s.replace(/\|/g, "\\|");
-    const header = `| ${columns.map(escape).join(" | ")} |`;
-    const separator = `| ${columns.map(() => "---").join(" | ")} |`;
-    const body = rows
-        .map((row) => `| ${columns.map((c) => escape(String(row[c] ?? ""))).join(" | ")} |`)
-        .join("\n");
-    return `${header}\n${separator}\n${body}`;
-}
-// Schema cache: data_source_id → { schema, timestamp }
-const schemaCache = new Map();
-const CACHE_TTL_MS = 10 * 60 * 1000; // 10분
-async function fetchSchema(dataSourceId) {
-    const cached = schemaCache.get(dataSourceId);
-    if (cached && Date.now() - cached.ts < CACHE_TTL_MS) {
-        return cached.schema;
-    }
-    const result = await redashFetch(`/data_sources/${dataSourceId}/schema`);
-    const schema = result.schema ?? [];
-    schemaCache.set(dataSourceId, { schema, ts: Date.now() });
-    return schema;
-}
 const server = new McpServer({
     name: "redash-mcp",
-    version: "2.0.2",
+    version: "3.0.0",
 });
-// ─── Data Sources ────────────────────────────────────────────────────────────
-server.tool("list_data_sources", "Redash에 연결된 데이터소스 목록(id, name, type)을 반환합니다. 항상 이 툴을 먼저 호출해 data_source_id를 확인하세요.", {}, async () => {
+server.tool("list_data_sources", "List connected data sources (id, name, type). Call this first to get data_source_id.", {}, { readOnlyHint: true }, async () => {
     const data = await redashFetch("/data_sources");
     const sources = data.map((ds) => ({
         id: ds.id,
@@ -90,25 +30,29 @@ server.tool("list_data_sources", "Redash에 연결된 데이터소스 목록(id,
         content: [{ type: "text", text: JSON.stringify(sources, null, 2) }],
     };
 });
-// ─── Schema ───────────────────────────────────────────────────────────────────
-server.tool("list_tables", "데이터소스의 테이블 목록을 반환합니다. keyword로 관련 테이블을 검색할 수 있습니다. SQL 작성 전 반드시 이 툴로 테이블명을 확인하고, get_table_columns로 컬럼을 확인하세요.", {
-    data_source_id: z.number().describe("list_data_sources로 확인한 데이터소스 ID"),
-    keyword: z.string().optional().describe("테이블명 검색 키워드 (예: 'user', 'order')"),
-}, async ({ data_source_id, keyword }) => {
+server.tool("list_tables", "List tables in a data source. Use keyword to filter by name. Verify table names here before writing SQL.", {
+    data_source_id: z.number().describe("Data source ID from list_data_sources"),
+    keyword: z.string().optional().describe("Filter keyword for table names (e.g., 'user', 'order')"),
+}, { readOnlyHint: true }, async ({ data_source_id, keyword }) => {
     const schema = await fetchSchema(data_source_id);
     let tables = schema.map((t) => t.name);
     if (keyword) {
         tables = tables.filter((name) => name.toLowerCase().includes(keyword.toLowerCase()));
     }
-    const summary = `총 ${tables.length}개 테이블${keyword ? ` ('${keyword}' 포함)` : ""}\n\n${tables.join("\n")}`;
+    const total = tables.length;
+    const MAX_TABLES = 200;
+    const truncated = tables.length > MAX_TABLES;
+    if (truncated)
+        tables = tables.slice(0, MAX_TABLES);
+    const summary = `${total} tables${keyword ? ` (matching '${keyword}')` : ""}${truncated ? ` (showing first ${MAX_TABLES}, use keyword to filter)` : ""}\n\n${tables.join("\n")}`;
     return {
         content: [{ type: "text", text: summary }],
     };
 });
-server.tool("get_table_columns", "테이블의 컬럼명과 타입을 반환합니다. 쉼표로 여러 테이블을 동시에 조회할 수 있습니다. SQL 작성 전 실제 컬럼명을 반드시 확인하세요.", {
-    data_source_id: z.number().describe("list_data_sources로 확인한 데이터소스 ID"),
-    table_name: z.string().describe("테이블명, 쉼표로 여러 개 가능 (예: 'users' 또는 'users,orders')"),
-}, async ({ data_source_id, table_name }) => {
+server.tool("get_table_columns", "Get column names and types for one or more tables (comma-separated). Verify columns before writing SQL.", {
+    data_source_id: z.number().describe("Data source ID from list_data_sources"),
+    table_name: z.string().describe("Table name(s), comma-separated (e.g., 'users' or 'users,orders')"),
+}, { readOnlyHint: true }, async ({ data_source_id, table_name }) => {
     const schema = await fetchSchema(data_source_id);
     const tableNames = table_name.split(",").map((n) => n.trim()).filter(Boolean);
     const results = [];
@@ -118,41 +62,37 @@ server.tool("get_table_columns", "테이블의 컬럼명과 타입을 반환합
             table = schema.find((t) => t.name.toLowerCase().includes(name.toLowerCase()));
         }
         if (!table) {
-            results.push(`테이블 '${name}'을 찾을 수 없습니다. list_tables로 정확한 테이블명을 확인하세요.`);
+            results.push(`Table '${name}' not found. Use list_tables to verify the table name.`);
             continue;
         }
-        const cols = (table.columns ?? []).map((c) => `${c.name} (${c.type ?? "unknown"})`).join("\n");
+        const cols = (table.columns ?? []).map((c) => typeof c === "string" ? c : `${c.name} (${c.type ?? "unknown"})`).join("\n");
         results.push(`[${table.name}]\n${cols}`);
     }
     return {
         content: [{ type: "text", text: results.join("\n\n") }],
     };
 });
-// ─── 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().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 안전 가드
+server.tool("run_query", "Execute SQL against a data source and return results. Check schema with list_tables and get_table_columns first.", {
+    data_source_id: z.number().describe("Data source ID from list_data_sources"),
+    query: z.string().describe("SQL query to execute"),
+    max_age: z.number().optional().describe("Redash cache TTL in seconds. Defaults to REDASH_DEFAULT_MAX_AGE env var"),
+    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"),
+    timeout_secs: z.number().optional().default(30).describe("Query execution timeout in seconds"),
+}, { readOnlyHint: true }, async ({ data_source_id, query, max_age, max_rows, format, timeout_secs }) => {
     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}행만 표시합니다.`
+            ? `\n⚠️ Showing ${max_rows} of ${rows.length} rows.`
             : "";
         let body;
         if (format === "json") {
@@ -161,17 +101,16 @@ server.tool("run_query", "SQL을 데이터소스에 직접 실행하고 결과
         else {
             body = formatAsMarkdownTable(columns, displayRows);
         }
-        const cacheNote = "📦 MCP 캐시에서 반환된 결과입니다.\n\n";
+        const cacheNote = "Returned from MCP cache.\n\n";
         return {
             content: [
                 {
                     type: "text",
-                    text: `${warningPrefix}${cacheNote}총 ${rows.length}행 | 컬럼: ${columns.join(", ")}${truncated}\n\n${body}`,
+                    text: `${warningPrefix}${cacheNote}${rows.length} rows | Columns: ${columns.join(", ")}${truncated}\n\n${body}`,
                 },
             ],
         };
     }
-    // 3. Redash API 호출
     const res = await redashFetch("/query_results", {
         method: "POST",
         body: JSON.stringify({ data_source_id, query: effectiveQuery, max_age: effectiveMaxAge }),
@@ -186,12 +125,11 @@ 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}행만 표시합니다.`
+        ? `\n⚠️ Showing ${max_rows} of ${rows.length} rows.`
         : "";
     let body;
     if (format === "json") {
@@ -204,20 +142,20 @@ server.tool("run_query", "SQL을 데이터소스에 직접 실행하고 결과
         content: [
             {
                 type: "text",
-                text: `${warningPrefix}총 ${rows.length}행 | 컬럼: ${columns.join(", ")}${truncated}\n\n${body}`,
+                text: `${warningPrefix}${rows.length} rows | Columns: ${columns.join(", ")}${truncated}\n\n${body}`,
             },
         ],
     };
 });
-// ─── Saved Queries ────────────────────────────────────────────────────────────
-server.tool("list_queries", "Redash에 저장된 쿼리 목록을 조회합니다.", {
-    search: z.string().optional().describe("검색어"),
+server.tool("list_queries", "List saved queries in Redash.", {
+    search: z.string().optional().describe("Search keyword"),
     page: z.number().optional().default(1),
-    page_size: z.number().optional().default(20),
-}, async ({ search, page, page_size }) => {
+    page_size: z.number().optional().default(20).describe("Page size (max 100)"),
+}, { readOnlyHint: true }, async ({ search, page, page_size }) => {
+    const effectivePageSize = Math.min(page_size, 100);
     const params = new URLSearchParams({
         page: String(page),
-        page_size: String(page_size),
+        page_size: String(effectivePageSize),
         ...(search ? { q: search } : {}),
     });
     const data = await redashFetch(`/queries?${params}`);
@@ -232,11 +170,11 @@ server.tool("list_queries", "Redash에 저장된 쿼리 목록을 조회합니
         content: [{ type: "text", text: JSON.stringify(queries, null, 2) }],
     };
 });
-server.tool("get_query_result", "저장된 Redash 쿼리를 ID로 실행하고 결과를 반환합니다.", {
-    query_id: z.number().describe("저장된 쿼리 ID (list_queries로 확인)"),
-    max_rows: z.number().optional().default(100).describe("반환할 최대 행 수 (기본 100)"),
-    format: z.enum(["table", "json"]).optional().default("table").describe("결과 포맷: table(마크다운) 또는 json"),
-}, async ({ query_id, max_rows, format }) => {
+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 }) => {
     const res = await redashFetch(`/queries/${query_id}/results`, {
         method: "POST",
         body: JSON.stringify({}),
@@ -253,7 +191,7 @@ server.tool("get_query_result", "저장된 Redash 쿼리를 ID로 실행하고
     const columns = qr.data.columns.map((c) => c.name);
     const displayRows = rows.slice(0, max_rows);
     const truncated = rows.length > max_rows
-        ? `\n⚠️ 전체 ${rows.length}행 중 ${max_rows}행만 표시합니다.`
+        ? `\n⚠️ Showing ${max_rows} of ${rows.length} rows.`
         : "";
     let body;
     if (format === "json") {
@@ -266,14 +204,14 @@ server.tool("get_query_result", "저장된 Redash 쿼리를 ID로 실행하고
         content: [
             {
                 type: "text",
-                text: `쿼리 ID: ${query_id}\n총 ${rows.length}행 | 컬럼: ${columns.join(", ")}${truncated}\n\n${body}`,
+                text: `Query ID: ${query_id}\n${rows.length} rows | Columns: ${columns.join(", ")}${truncated}\n\n${body}`,
             },
         ],
     };
 });
-server.tool("get_query", "저장된 쿼리의 상세 정보(SQL, 시각화, 태그 등)를 반환합니다.", {
-    query_id: z.number().describe("쿼리 ID (list_queries로 확인)"),
-}, async ({ query_id }) => {
+server.tool("get_query", "Get saved query details (SQL, visualizations, tags).", {
+    query_id: z.number().describe("Query ID (from list_queries)"),
+}, { readOnlyHint: true }, async ({ query_id }) => {
     const data = await redashFetch(`/queries/${query_id}`);
     const result = {
         id: data.id,
@@ -293,13 +231,13 @@ server.tool("get_query", "저장된 쿼리의 상세 정보(SQL, 시각화, 태
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 });
-server.tool("create_query", "새 쿼리를 Redash에 저장합니다.", {
-    name: z.string().describe("쿼리 이름"),
-    query: z.string().describe("SQL 쿼리"),
-    data_source_id: z.number().describe("데이터소스 ID (list_data_sources로 확인)"),
-    description: z.string().optional().describe("쿼리 설명"),
-    tags: z.array(z.string()).optional().describe("태그 목록"),
-}, async ({ name, query, data_source_id, description, tags }) => {
+server.tool("create_query", "Save a new query to Redash.", {
+    name: z.string().describe("Query name"),
+    query: z.string().describe("SQL query"),
+    data_source_id: z.number().describe("Data source ID from list_data_sources"),
+    description: z.string().optional().describe("Query description"),
+    tags: z.array(z.string()).optional().describe("Tags"),
+}, { destructiveHint: true }, async ({ name, query, data_source_id, description, tags }) => {
     const body = { name, query, data_source_id };
     if (description !== undefined)
         body.description = description;
@@ -318,13 +256,13 @@ server.tool("create_query", "새 쿼리를 Redash에 저장합니다.", {
         ],
     };
 });
-server.tool("update_query", "저장된 쿼리의 이름, SQL, 설명, 태그를 수정합니다.", {
-    query_id: z.number().describe("수정할 쿼리 ID"),
-    name: z.string().optional().describe("새 이름"),
-    query: z.string().optional().describe("새 SQL"),
-    description: z.string().optional().describe("새 설명"),
-    tags: z.array(z.string()).optional().describe("새 태그 목록"),
-}, async ({ query_id, name, query, description, tags }) => {
+server.tool("update_query", "Update a saved query's name, SQL, description, or tags.", {
+    query_id: z.number().describe("Query ID to update"),
+    name: z.string().optional().describe("New name"),
+    query: z.string().optional().describe("New SQL"),
+    description: z.string().optional().describe("New description"),
+    tags: z.array(z.string()).optional().describe("New tags"),
+}, { destructiveHint: true }, async ({ query_id, name, query, description, tags }) => {
     const body = {};
     if (name !== undefined)
         body.name = name;
@@ -347,9 +285,9 @@ server.tool("update_query", "저장된 쿼리의 이름, SQL, 설명, 태그를
         ],
     };
 });
-server.tool("fork_query", "기존 쿼리를 복제(fork)합니다.", {
-    query_id: z.number().describe("복제할 쿼리 ID"),
-}, async ({ query_id }) => {
+server.tool("fork_query", "Fork (duplicate) an existing query.", {
+    query_id: z.number().describe("Query ID to fork"),
+}, { destructiveHint: true }, async ({ query_id }) => {
     const data = await redashFetch(`/queries/${query_id}/fork`, {
         method: "POST",
         body: JSON.stringify({}),
@@ -363,23 +301,23 @@ server.tool("fork_query", "기존 쿼리를 복제(fork)합니다.", {
         ],
     };
 });
-server.tool("archive_query", "쿼리를 아카이브(삭제)합니다. 복구 불가합니다.", {
-    query_id: z.number().describe("아카이브할 쿼리 ID"),
-}, async ({ query_id }) => {
+server.tool("archive_query", "Archive (delete) a query. This action is irreversible.", {
+    query_id: z.number().describe("Query ID to archive"),
+}, { destructiveHint: true }, async ({ query_id }) => {
     await redashFetch(`/queries/${query_id}`, { method: "DELETE" });
     return {
-        content: [{ type: "text", text: `쿼리 ${query_id}가 아카이브되었습니다.` }],
+        content: [{ type: "text", text: `Query ${query_id} has been archived.` }],
     };
 });
-// ─── Dashboards ───────────────────────────────────────────────────────────────
-server.tool("list_dashboards", "Redash 대시보드 목록을 조회합니다.", {
-    search: z.string().optional().describe("검색어"),
+server.tool("list_dashboards", "List dashboards in Redash.", {
+    search: z.string().optional().describe("Search keyword"),
     page: z.number().optional().default(1),
-    page_size: z.number().optional().default(20),
-}, async ({ search, page, page_size }) => {
+    page_size: z.number().optional().default(20).describe("Page size (max 100)"),
+}, { readOnlyHint: true }, async ({ search, page, page_size }) => {
+    const effectivePageSize = Math.min(page_size, 100);
     const params = new URLSearchParams({
         page: String(page),
-        page_size: String(page_size),
+        page_size: String(effectivePageSize),
         ...(search ? { q: search } : {}),
     });
     const data = await redashFetch(`/dashboards?${params}`);
@@ -394,9 +332,9 @@ server.tool("list_dashboards", "Redash 대시보드 목록을 조회합니다.",
         content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
     };
 });
-server.tool("get_dashboard", "대시보드 상세 정보와 위젯(시각화) 목록을 반환합니다.", {
-    dashboard_id_or_slug: z.string().describe("대시보드 ID 또는 slug (list_dashboards로 확인)"),
-}, async ({ dashboard_id_or_slug }) => {
+server.tool("get_dashboard", "Get dashboard details including widgets and visualizations.", {
+    dashboard_id_or_slug: z.string().describe("Dashboard ID or slug (from list_dashboards)"),
+}, { readOnlyHint: true }, async ({ dashboard_id_or_slug }) => {
     const data = await redashFetch(`/dashboards/${dashboard_id_or_slug}`);
     const result = {
         id: data.id,
@@ -418,9 +356,9 @@ server.tool("get_dashboard", "대시보드 상세 정보와 위젯(시각화)
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 });
-server.tool("create_dashboard", "새 대시보드를 생성합니다.", {
-    name: z.string().describe("대시보드 이름"),
-}, async ({ name }) => {
+server.tool("create_dashboard", "Create a new dashboard.", {
+    name: z.string().describe("Dashboard name"),
+}, { destructiveHint: true }, async ({ name }) => {
     const data = await redashFetch("/dashboards", {
         method: "POST",
         body: JSON.stringify({ name }),
@@ -434,12 +372,12 @@ server.tool("create_dashboard", "새 대시보드를 생성합니다.", {
         ],
     };
 });
-server.tool("add_widget", "대시보드에 시각화 위젯을 추가합니다. visualization_id는 get_query로 확인하세요.", {
-    dashboard_id: z.number().describe("대시보드 ID"),
-    visualization_id: z.number().describe("추가할 시각화 ID (get_query의 visualizations에서 확인)"),
-    text: z.string().optional().default("").describe("위젯 텍스트"),
-    width: z.number().optional().default(1).describe("위젯 너비 (1 또는 2)"),
-}, async ({ dashboard_id, visualization_id, text, width }) => {
+server.tool("add_widget", "Add a visualization widget to a dashboard. Get visualization_id from get_query.", {
+    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)"),
+}, { destructiveHint: true }, async ({ dashboard_id, visualization_id, text, width }) => {
     const data = await redashFetch("/widgets", {
         method: "POST",
         body: JSON.stringify({
@@ -459,8 +397,7 @@ server.tool("add_widget", "대시보드에 시각화 위젯을 추가합니다.
         ],
     };
 });
-// ─── Alerts ───────────────────────────────────────────────────────────────────
-server.tool("list_alerts", "Redash 알림(Alert) 목록을 조회합니다.", {}, async () => {
+server.tool("list_alerts", "List alerts in Redash.", {}, { readOnlyHint: true }, async () => {
     const data = await redashFetch("/alerts");
     const alerts = Array.isArray(data) ? data : [];
     const result = alerts.map((alert) => ({
@@ -475,9 +412,9 @@ server.tool("list_alerts", "Redash 알림(Alert) 목록을 조회합니다.", {}
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 });
-server.tool("get_alert", "특정 알림의 상세 정보(임계값, 대상 쿼리, 상태)를 반환합니다.", {
-    alert_id: z.number().describe("알림 ID (list_alerts로 확인)"),
-}, async ({ alert_id }) => {
+server.tool("get_alert", "Get alert details (threshold, linked query, state).", {
+    alert_id: z.number().describe("Alert ID (from list_alerts)"),
+}, { readOnlyHint: true }, async ({ alert_id }) => {
     const alert = await redashFetch(`/alerts/${alert_id}`);
     const result = {
         id: alert.id,
@@ -498,14 +435,14 @@ server.tool("get_alert", "특정 알림의 상세 정보(임계값, 대상 쿼
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 });
-server.tool("create_alert", "새 알림을 생성합니다. 쿼리 결과의 특정 컬럼값이 임계값을 초과하면 알림을 발생시킵니다.", {
-    name: z.string().describe("알림 이름"),
-    query_id: z.number().describe("모니터링할 쿼리 ID"),
-    column: z.string().describe("모니터링할 컬럼명"),
-    op: z.enum(["greater than", "less than", "equals"]).describe("비교 연산자"),
-    value: z.number().describe("임계값"),
-    rearm: z.number().optional().default(0).describe("재알림 간격(초), 0은 한번만"),
-}, async ({ name, query_id, column, op, value, rearm }) => {
+server.tool("create_alert", "Create a new alert. Triggers when a query result column crosses a threshold.", {
+    name: z.string().describe("Alert name"),
+    query_id: z.number().describe("Query ID to monitor"),
+    column: z.string().describe("Column name to monitor"),
+    op: z.enum(["greater than", "less than", "equals"]).describe("Comparison operator"),
+    value: z.number().describe("Threshold value"),
+    rearm: z.number().optional().default(0).describe("Rearm interval in seconds (0 = fire once)"),
+}, { destructiveHint: true }, async ({ name, query_id, column, op, value, rearm }) => {
     const data = await redashFetch("/alerts", {
         method: "POST",
         body: JSON.stringify({
@@ -524,5 +461,6 @@ server.tool("create_alert", "새 알림을 생성합니다. 쿼리 결과의 특
         ],
     };
 });
+registerBirdTools(server);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/query-cache.js

@@ -46,10 +46,8 @@ export function setCached(dataSourceId, sql, result) {
         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)

package/dist/redash-client.js

@@ -0,0 +1,64 @@
+const REDASH_URL = process.env.REDASH_URL?.replace(/\/$/, "");
+const REDASH_API_KEY = process.env.REDASH_API_KEY;
+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,
+        },
+    });
+    if (!res.ok) {
+        let hint = "";
+        if (res.status === 401)
+            hint = " (Check your REDASH_API_KEY)";
+        else if (res.status === 403)
+            hint = " (Access denied for this resource)";
+        else if (res.status === 404)
+            hint = " (Resource not found. Check the ID)";
+        throw new Error(`Redash API error: ${res.status} ${res.statusText}${hint}`);
+    }
+    if (res.status === 204 || res.headers.get("content-length") === "0") {
+        return null;
+    }
+    return res.json();
+}
+export async function pollQueryResult(jobId, timeoutSecs = 30) {
+    for (let i = 0; i < timeoutSecs; i++) {
+        const job = await redashFetch(`/jobs/${jobId}`);
+        if (job.job.status === 3) {
+            return await redashFetch(`/query_results/${job.job.query_result_id}`);
+        }
+        if (job.job.status === 4) {
+            throw new Error(`Query failed: ${job.job.error}`);
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    throw new Error(`Query timed out after ${timeoutSecs}s`);
+}
+export function formatAsMarkdownTable(columns, rows) {
+    const escape = (s) => s.replace(/\|/g, "\\|");
+    const header = `| ${columns.map(escape).join(" | ")} |`;
+    const separator = `| ${columns.map(() => "---").join(" | ")} |`;
+    const body = rows
+        .map((row) => `| ${columns.map((c) => escape(String(row[c] ?? ""))).join(" | ")} |`)
+        .join("\n");
+    return `${header}\n${separator}\n${body}`;
+}
+const schemaCache = new Map();
+const CACHE_TTL_MS = 10 * 60 * 1000;
+export async function fetchSchema(dataSourceId) {
+    const cached = schemaCache.get(dataSourceId);
+    if (cached && Date.now() - cached.ts < CACHE_TTL_MS) {
+        return cached.schema;
+    }
+    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),
+    }));
+    schemaCache.set(dataSourceId, { schema, ts: Date.now() });
+    return schema;
+}