redash-mcp 2.2.1 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Jiro Developers
+
+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

@@ -0,0 +1,223 @@
+# 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), 또는 둘 다 선택하여 설정할 수 있습니다.
+
+### 셸 스크립트로 설치
+
+Node.js, Claude Desktop, MCP 설정을 한번에 처리합니다:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/seob717/redash-mcp/main/install.sh | bash
+```
+
+### 수동 설치
+
+#### 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명 이하로 떨어지면 알림 만들어줘"
+
+### 예제 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

@@ -1,49 +1,80 @@
 # 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.
 
-### 수동 설치
+### Shell Script Install
 
-#### 1. Redash API 키 발급
+Installs Node.js, Claude Desktop, and MCP config all at once:
 
-Redash → 우측 상단 프로필 → **Edit Profile** → **API Key** 복사
+```bash
+curl -fsSL https://raw.githubusercontent.com/seob717/redash-mcp/main/install.sh | bash
+```
+
+### Manual Setup
+
+#### 1. Get your Redash API Key
 
-#### 2-A. Claude Desktop 설정
+Go to Redash → Profile (top right) → **Edit Profile** → Copy **API Key**
 
-`~/Library/Application Support/Claude/claude_desktop_config.json` 파일을 열고 아래 내용을 추가합니다:
+#### 2-A. Claude Desktop
+
+Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add:
 
 ```json
 {
@@ -60,11 +91,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 +112,112 @@ 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.
+
+---
+
+## Environment Variables
 
-> **Windows/Linux**: `command`를 `npx`로 그대로 사용하면 됩니다.
-> **macOS**: `npx`를 못 찾는 경우 `which npx` 명령어로 전체 경로를 확인 후 대체하세요.
+### 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
+
+Just ask Claude in natural language:
+
+- "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"
+
+### 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
 
-Claude에게 자연어로 요청하면 됩니다:
+### Contact
 
-- "Redash에서 users 테이블 컬럼 보여줘"
-- "최근 7일 주문 수를 SQL로 조회해줘"
-- "저장된 쿼리 목록 보여줘"
-- "매출 대시보드 위젯 목록 알려줘"
+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;
+}