metabase-ai-assistant 3.3.0 → 3.4.1

package/README_MCP.md

@@ -45,7 +45,7 @@ After updating the configuration file, restart your MCP client to load the new s
 
 ---
 
-## Available Tools (107 Total)
+## Available Tools (111 Total)
 
 ### Database Operations
 - **db_list**: List all databases in Metabase
@@ -55,6 +55,10 @@ After updating the configuration file, restart your MCP client to load the new s
 
 ### SQL Operations
 - **sql_execute**: Execute native SQL query
+- **sql_submit**: Asynchronously create a long-running SQL query job
+- **sql_status**: Check the status of a SQL job
+- **sql_cancel**: Cancel a running SQL job
+- **db_table_profile**: Profile a table (smart dim/ref detection)
 - **ai_sql_generate**: Generate SQL from natural language description
 - **ai_sql_optimize**: Optimize SQL query for performance
 - **ai_sql_explain**: Explain what a SQL query does
@@ -213,6 +217,32 @@ After updating the configuration file, restart your MCP client to load the new s
 }
 ```
 
+### sql_submit (Async Query)
+```json
+{
+  "database_id": 1,
+  "sql": "SELECT SLEEP(120)",
+  "timeout_seconds": 300
+}
+```
+
+### sql_status
+```json
+{
+  "job_id": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+### db_table_profile
+```json
+{
+  "database_id": 1,
+  "schema": "public",
+  "table": "dim_customers",
+  "sample_rows": 3
+}
+```
+
 ### ai_sql_generate
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metabase-ai-assistant",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "mcpName": "io.github.enessari/metabase-ai-assistant",
   "description": "The most powerful MCP Server for Metabase - 111+ tools for AI-powered SQL generation, dashboard automation, user management & enterprise BI. Works with Claude, Cursor, and any MCP-compatible AI.",
   "main": "src/index.js",
@@ -96,4 +96,4 @@
     "eslint": "^8.56.0",
     "jest": "^29.7.0"
   }
-}
+}

package/src/mcp/job-store.js

@@ -0,0 +1,199 @@
+import { randomUUID } from 'crypto';
+import { logger } from '../utils/logger.js';
+
+/**
+ * QueryJobStore - Manages async query jobs
+ * Tracks job status, results, and handles cleanup
+ */
+export class QueryJobStore {
+    constructor() {
+        this.jobs = new Map();
+
+        // Auto-cleanup every 10 minutes
+        this.cleanupInterval = setInterval(() => this.cleanup(), 10 * 60 * 1000);
+    }
+
+    /**
+     * Create a new query job
+     */
+    create(databaseId, sql, timeoutSeconds = 300) {
+        const jobId = randomUUID();
+        const job = {
+            id: jobId,
+            database_id: databaseId,
+            sql: sql,
+            status: 'pending', // pending | running | complete | failed | timeout | cancelled
+            submitted_at: Date.now(),
+            started_at: null,
+            completed_at: null,
+            timeout_ms: timeoutSeconds * 1000,
+            result: null,
+            error: null,
+            row_count: 0,
+            abortController: new AbortController()
+        };
+
+        this.jobs.set(jobId, job);
+        logger.info(`Query job created: ${jobId}`);
+        return job;
+    }
+
+    /**
+     * Get job by ID
+     */
+    get(jobId) {
+        return this.jobs.get(jobId);
+    }
+
+    /**
+     * Update job properties
+     */
+    update(jobId, updates) {
+        const job = this.jobs.get(jobId);
+        if (job) {
+            Object.assign(job, updates);
+            logger.debug(`Job ${jobId} updated: ${updates.status || 'props'}`);
+        }
+        return job;
+    }
+
+    /**
+     * Mark job as running
+     */
+    markRunning(jobId) {
+        return this.update(jobId, {
+            status: 'running',
+            started_at: Date.now()
+        });
+    }
+
+    /**
+     * Mark job as complete with results
+     */
+    markComplete(jobId, result, rowCount) {
+        return this.update(jobId, {
+            status: 'complete',
+            completed_at: Date.now(),
+            result: result,
+            row_count: rowCount
+        });
+    }
+
+    /**
+     * Mark job as failed
+     */
+    markFailed(jobId, error) {
+        return this.update(jobId, {
+            status: 'failed',
+            completed_at: Date.now(),
+            error: error.message || String(error)
+        });
+    }
+
+    /**
+     * Mark job as timed out
+     */
+    markTimeout(jobId) {
+        const job = this.jobs.get(jobId);
+        return this.update(jobId, {
+            status: 'timeout',
+            completed_at: Date.now(),
+            error: `Query timed out after ${job?.timeout_ms / 1000} seconds`
+        });
+    }
+
+    /**
+     * Mark job as cancelled
+     */
+    markCancelled(jobId) {
+        return this.update(jobId, {
+            status: 'cancelled',
+            completed_at: Date.now(),
+            error: 'Query cancelled by user'
+        });
+    }
+
+    /**
+     * Get elapsed time for a job in seconds
+     */
+    getElapsedSeconds(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job) return 0;
+
+        const startTime = job.started_at || job.submitted_at;
+        const endTime = job.completed_at || Date.now();
+        return Math.round((endTime - startTime) / 1000);
+    }
+
+    /**
+     * List all jobs (optionally filtered by status)
+     */
+    list(status = null) {
+        const jobs = [];
+        for (const [id, job] of this.jobs) {
+            if (!status || job.status === status) {
+                jobs.push({
+                    id: job.id,
+                    database_id: job.database_id,
+                    status: job.status,
+                    submitted_at: job.submitted_at,
+                    elapsed_seconds: this.getElapsedSeconds(job.id)
+                });
+            }
+        }
+        return jobs;
+    }
+
+    /**
+     * Get running jobs count
+     */
+    getRunningCount() {
+        let count = 0;
+        for (const job of this.jobs.values()) {
+            if (job.status === 'running' || job.status === 'pending') {
+                count++;
+            }
+        }
+        return count;
+    }
+
+    /**
+     * Cleanup old completed jobs (older than 1 hour)
+     */
+    cleanup() {
+        const oneHourAgo = Date.now() - 3600000;
+        let cleaned = 0;
+
+        for (const [id, job] of this.jobs) {
+            if (job.status !== 'running' && job.status !== 'pending') {
+                if (job.submitted_at < oneHourAgo) {
+                    this.jobs.delete(id);
+                    cleaned++;
+                }
+            }
+        }
+
+        if (cleaned > 0) {
+            logger.info(`Cleaned up ${cleaned} old query jobs`);
+        }
+    }
+
+    /**
+     * Stop the cleanup interval (for graceful shutdown)
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+        }
+    }
+}
+
+// Singleton instance
+let instance = null;
+
+export function getJobStore() {
+    if (!instance) {
+        instance = new QueryJobStore();
+    }
+    return instance;
+}

package/src/mcp/server.js

@@ -28,6 +28,7 @@ import {
 // Utils
 import { CacheManager, CacheKeys, globalCache } from '../utils/cache.js';
 import { config as appConfig } from '../utils/config.js';
+import { getJobStore } from './job-store.js';
 import {
   ResponseFormat,
   formatListResponse,
@@ -209,10 +210,43 @@ class MetabaseMCPServer {
               required: ['database_id'],
             },
           },
+          {
+            name: 'db_table_profile',
+            description: 'Get comprehensive table profile: row count, column types, distinct values, sample data. Auto-detects dimension/reference tables (dim_, ref_, lookup_ prefix). Ideal for understanding lookup tables before writing queries.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                database_id: {
+                  type: 'number',
+                  description: 'Database ID',
+                },
+                table_name: {
+                  type: 'string',
+                  description: 'Table name (with or without schema prefix)',
+                },
+                schema_name: {
+                  type: 'string',
+                  description: 'Schema name (default: public)',
+                  default: 'public',
+                },
+                show_distinct_values: {
+                  type: 'boolean',
+                  description: 'Show distinct values for each column (auto-enabled for dim/ref tables)',
+                  default: true,
+                },
+                sample_rows: {
+                  type: 'number',
+                  description: 'Number of sample rows to display (default: 3)',
+                  default: 3,
+                },
+              },
+              required: ['database_id', 'table_name'],
+            },
+          },
           // === SQL EXECUTION ===
           {
             name: 'sql_execute',
-            description: 'Run SQL queries against database - supports SELECT, DDL with security controls, returns formatted results',
+            description: 'Run SQL queries against database - supports SELECT, DDL with security controls, returns formatted results. For long-running queries (>60s), use sql_submit instead.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -224,10 +258,65 @@ class MetabaseMCPServer {
                   type: 'string',
                   description: 'SQL query to execute',
                 },
+                full_results: {
+                  type: 'boolean',
+                  description: 'Set to true to disable result truncation (useful for DDL/definitions)',
+                },
+              },
+              required: ['database_id', 'sql'],
+            },
+          },
+          {
+            name: 'sql_submit',
+            description: 'Submit a long-running SQL query asynchronously. Returns immediately with job_id. Use sql_status to check progress. Ideal for queries that may take minutes.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                database_id: {
+                  type: 'number',
+                  description: 'Database ID',
+                },
+                sql: {
+                  type: 'string',
+                  description: 'SQL query to execute',
+                },
+                timeout_seconds: {
+                  type: 'number',
+                  description: 'Query timeout in seconds (default: 300, max: 1800)',
+                  default: 300,
+                },
               },
               required: ['database_id', 'sql'],
             },
           },
+          {
+            name: 'sql_status',
+            description: 'Check status of an async query submitted via sql_submit. Returns results when complete.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                job_id: {
+                  type: 'string',
+                  description: 'Job ID returned from sql_submit',
+                },
+              },
+              required: ['job_id'],
+            },
+          },
+          {
+            name: 'sql_cancel',
+            description: 'Cancel a running async query. Also attempts to cancel on database server.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                job_id: {
+                  type: 'string',
+                  description: 'Job ID to cancel',
+                },
+              },
+              required: ['job_id'],
+            },
+          },
           // === METABASE OBJECTS ===
           {
             name: 'mb_question_create',
@@ -3147,10 +3236,18 @@ class MetabaseMCPServer {
             return await this.handleGetDatabaseSchemas(args.database_id);
           case 'db_tables':
             return await this.handleGetDatabaseTables(args.database_id);
+          case 'db_table_profile':
+            return await this.handleTableProfile(args);
 
           // SQL execution
           case 'sql_execute':
-            return await this.handleExecuteSQL(args.database_id, args.sql);
+            return await this.handleExecuteSQL(args);
+          case 'sql_submit':
+            return await this.handleSQLSubmit(args);
+          case 'sql_status':
+            return await this.handleSQLStatus(args);
+          case 'sql_cancel':
+            return await this.handleSQLCancel(args);
 
           // Metabase objects
           case 'mb_question_create':
@@ -3452,7 +3549,7 @@ class MetabaseMCPServer {
       } catch (error) {
         logger.error(`Tool ${name} failed:`, error);
 
-        // Specific error handling
+        // Specific error handling with clearer messages
         let errorMessage = error.message;
         let errorCode = ErrorCode.InternalError;
 
@@ -3468,6 +3565,15 @@ class MetabaseMCPServer {
         } else if (error.message.includes('not found')) {
           errorMessage = `Resource not found: ${error.message}`;
           errorCode = ErrorCode.InvalidRequest;
+        } else if (error.message.includes('is not a function')) {
+          errorMessage = `Unexpected API response format. Metabase API may have changed or data is not an array. Details: ${error.message.substring(0, 100)}`;
+          errorCode = ErrorCode.InternalError;
+        } else if (error.message.includes('Cannot read properties of undefined') || error.message.includes('Cannot read property')) {
+          errorMessage = `Expected data not found. Check Metabase API response. Details: ${error.message.substring(0, 100)}`;
+          errorCode = ErrorCode.InternalError;
+        } else if (error.message.includes('timeout') || error.message.includes('ETIMEDOUT')) {
+          errorMessage = `Request timed out. Try a smaller query or use LIMIT.`;
+          errorCode = ErrorCode.InternalError;
         }
 
         throw new McpError(errorCode, errorMessage);
@@ -3565,9 +3671,13 @@ class MetabaseMCPServer {
     };
   }
 
-  async handleExecuteSQL(databaseId, sql) {
+  async handleExecuteSQL(args) {
     await this.ensureInitialized();
 
+    const databaseId = args.database_id;
+    const sql = args.sql;
+    const fullResults = args.full_results === true;
+
     if (this.initError) {
       throw new McpError(ErrorCode.InternalError, `Failed to initialize: ${this.initError.message}`);
     }
@@ -3613,44 +3723,78 @@ class MetabaseMCPServer {
       const rows = result.data.rows || [];
       const columns = result.data.cols || [];
 
-      let output = `✅ **Query executed successfully!**\\n\\n`;
-      output += `📊 **Results Summary:**\\n`;
-      output += `• Database ID: ${databaseId}\\n`;
-      output += `• Columns: ${columns.length} (${columns.map(col => col.name).join(', ')})\\n`;
-      output += `• Rows returned: ${rows.length}\\n`;
-      output += `• Execution time: ${executionTime}ms\\n\\n`;
+      let output = `✅ **Query successful** (${executionTime}ms)\\n`;
+      output += `📊 ${columns.length} columns, ${rows.length} rows\\n\\n`;
 
       if (rows.length > 0) {
-        output += `📋 **Sample Data (first 5 rows):**\\n\`\`\`\\n`;
-
-        // Create table header
+        // Show sample data (max 5 rows)
+        output += `**Data:**\\n\`\`\`\\n`;
         const headers = columns.map(col => col.name);
         output += headers.join(' | ') + '\\n';
         output += headers.map(() => '---').join(' | ') + '\\n';
 
-        // Add data rows
         rows.slice(0, 5).forEach((row) => {
           const formattedRow = row.map(cell => {
             if (cell === null) return 'NULL';
-            if (typeof cell === 'string' && cell.length > 50) {
-              return cell.substring(0, 47) + '...';
+
+            // Smart truncation logic
+            let truncateLimit = 100; // Increased base limit from 30
+
+            // Disable truncation for small result sets (DDL/procedures) or explicit full_results
+            if (fullResults || rows.length <= 2) {
+              truncateLimit = 50000;
+            }
+            // Check specific DDL-related column names
+            else if (columns.some(c => /definition|ddl|source|create_statement|routine_definition/i.test(c.name))) {
+              truncateLimit = 10000;
+            }
+
+            if (typeof cell === 'string' && cell.length > truncateLimit) {
+              return cell.substring(0, truncateLimit - 3) + '...';
             }
             return String(cell);
           });
           output += formattedRow.join(' | ') + '\\n';
         });
-
         output += '\`\`\`\\n';
 
         if (rows.length > 5) {
-          output += `\\n... and ${rows.length - 5} more rows\\n`;
+          output += `_+${rows.length - 5} more rows_\\n`;
+        }
+
+        // Large result warning
+        if (rows.length > 100) {
+          output += `\\n⚠️ **Large result:** ${rows.length} rows returned. Use LIMIT for better performance.\\n`;
         }
       } else {
-        output += `ℹ️ No data returned by the query.\\n`;
+        // Empty result - smart detection
+        output += `ℹ️ No results.\\n`;
+
+        // Try to detect if table has data but query returned nothing
+        try {
+          const fromMatch = sql.match(/FROM\s+["']?([^\s"'.(]+)["']?/i) ||
+            sql.match(/FROM\s+["']?[^"'.]+["']?\.["']?([^\s"']+)["']?/i);
+          if (fromMatch) {
+            const tableName = fromMatch[1];
+            const countQuery = `SELECT COUNT(*) FROM ${tableName} LIMIT 1`;
+            try {
+              const countResult = await this.metabaseClient.executeNativeQuery(databaseId, countQuery);
+              const tableRowCount = countResult.data?.rows?.[0]?.[0] || 0;
+
+              if (tableRowCount > 0) {
+                output += `\\n⚠️ **Note:** \`${tableName}\` has ${tableRowCount.toLocaleString()} rows but query returned nothing.\\n`;
+                output += `Possible causes: WHERE clause too restrictive, column name typo, JOIN mismatch\\n`;
+                output += `💡 Use \`db_table_profile\` to inspect table structure.\\n`;
+              }
+            } catch (e) { /* ignore */ }
+          }
+        } catch (e) { /* ignore */ }
       }
 
-      // Add query info
-      output += `\\n🔍 **Query Details:**\\n\`\`\`sql\\n${sql}\\n\`\`\``;
+      // Tool suggestions (only for SELECT queries with few results)
+      if (sql.toLowerCase().trim().startsWith('select') && rows.length <= 5) {
+        output += `\\n💡 Related: \`db_table_profile\`, \`mb_field_values\`\\n`;
+      }
 
       return {
         content: [
@@ -3678,12 +3822,9 @@ class MetabaseMCPServer {
         });
       }
 
-      const output = `❌ **Query execution failed!**\\n\\n` +
-        `🚫 **Error Details:**\\n` +
-        `• Database ID: ${databaseId}\\n` +
-        `• Execution time: ${executionTime}ms\\n` +
-        `• Error: ${err.message}\\n\\n` +
-        `🔍 **Failed Query:**\\n\`\`\`sql\\n${sql}\\n\`\`\``;
+      // Compact error format - no query repetition
+      const shortSql = sql.length > 80 ? sql.substring(0, 77) + '...' : sql;
+      const output = `❌ SQL Error: ${err.message}\\nQuery: ${shortSql}`;
 
       return {
         content: [
@@ -3696,6 +3837,201 @@ class MetabaseMCPServer {
     }
   }
 
+  /**
+   * Submit a long-running SQL query asynchronously
+   * Returns immediately with job_id, executes query in background
+   */
+  async handleSQLSubmit(args) {
+    try {
+      await this.ensureInitialized();
+
+      const databaseId = args.database_id;
+      const sql = args.sql;
+      const timeoutSeconds = Math.min(args.timeout_seconds || 300, 1800); // Max 30 minutes
+
+      // Check read-only mode for write operations
+      if (isReadOnlyMode() && detectWriteOperation(sql)) {
+        return {
+          content: [{ type: 'text', text: '❌ Write operations blocked in read-only mode' }],
+        };
+      }
+
+      // Get job store and create job
+      const jobStore = getJobStore();
+      const job = jobStore.create(databaseId, sql, timeoutSeconds);
+
+      // Add job marker to SQL for cancellation support
+      const markedSql = `/* job:${job.id} */ ${sql}`;
+
+      // Start query execution in background (non-blocking)
+      this.executeQueryBackground(job.id, databaseId, markedSql, timeoutSeconds * 1000);
+
+      const output = `✅ **Query Submitted**\\n` +
+        `📋 Job ID: \`${job.id}\`\\n` +
+        `⏱️ Timeout: ${timeoutSeconds} seconds\\n` +
+        `📊 Status: pending\\n\\n` +
+        `💡 Use \`sql_status\` with this job_id to check progress.`;
+
+      return {
+        content: [{ type: 'text', text: output }],
+      };
+
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: `❌ Failed to submit query: ${error.message}` }],
+      };
+    }
+  }
+
+  /**
+   * Execute query in background and update job status
+   */
+  async executeQueryBackground(jobId, databaseId, sql, timeoutMs) {
+    const jobStore = getJobStore();
+    const job = jobStore.get(jobId);
+
+    if (!job) return;
+
+    jobStore.markRunning(jobId);
+
+    try {
+      const result = await this.metabaseClient.executeNativeQueryWithTimeout(
+        databaseId,
+        sql,
+        timeoutMs,
+        job.abortController.signal
+      );
+
+      const rows = result.data?.rows || [];
+      jobStore.markComplete(jobId, result, rows.length);
+
+      logger.info(`Query job ${jobId} completed with ${rows.length} rows`);
+
+    } catch (error) {
+      if (error.message.includes('cancelled')) {
+        jobStore.markCancelled(jobId);
+      } else if (error.message.includes('timed out')) {
+        jobStore.markTimeout(jobId);
+        // Try to cancel on database
+        await this.metabaseClient.cancelPostgresQuery(databaseId, `job:${jobId}`);
+      } else {
+        jobStore.markFailed(jobId, error);
+      }
+
+      logger.error(`Query job ${jobId} failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Check status of an async query
+   */
+  async handleSQLStatus(args) {
+    try {
+      const jobStore = getJobStore();
+      const job = jobStore.get(args.job_id);
+
+      if (!job) {
+        return {
+          content: [{ type: 'text', text: `❌ Job not found: ${args.job_id}` }],
+        };
+      }
+
+      const elapsedSeconds = jobStore.getElapsedSeconds(args.job_id);
+
+      let output = `📋 **Job Status: ${job.id}**\\n`;
+      output += `📊 Status: ${job.status}\\n`;
+      output += `⏱️ Elapsed: ${elapsedSeconds} seconds\\n`;
+
+      if (job.status === 'running' || job.status === 'pending') {
+        output += `\\n💡 Query is still running. Check again later or use \`sql_cancel\` to stop.`;
+      } else if (job.status === 'complete') {
+        const rows = job.result?.data?.rows || [];
+        const columns = job.result?.data?.cols || [];
+
+        output += `✅ **Query Complete!**\\n`;
+        output += `📊 ${columns.length} columns, ${rows.length} rows\\n\\n`;
+
+        if (rows.length > 0) {
+          output += `**Data:**\\n\`\`\`\\n`;
+          const headers = columns.map(col => col.name);
+          output += headers.join(' | ') + '\\n';
+          output += headers.map(() => '---').join(' | ') + '\\n';
+
+          rows.slice(0, 5).forEach((row) => {
+            const formattedRow = row.map(cell => {
+              if (cell === null) return 'NULL';
+              const str = String(cell);
+              return str.length > 30 ? str.substring(0, 27) + '...' : str;
+            });
+            output += formattedRow.join(' | ') + '\\n';
+          });
+          output += '\`\`\`\\n';
+
+          if (rows.length > 5) {
+            output += `_+${rows.length - 5} more rows_\\n`;
+          }
+        }
+      } else if (job.status === 'failed' || job.status === 'timeout' || job.status === 'cancelled') {
+        output += `\\n❌ ${job.error || 'Query did not complete'}`;
+      }
+
+      return {
+        content: [{ type: 'text', text: output }],
+      };
+
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: `❌ Failed to check status: ${error.message}` }],
+      };
+    }
+  }
+
+  /**
+   * Cancel a running async query
+   */
+  async handleSQLCancel(args) {
+    try {
+      const jobStore = getJobStore();
+      const job = jobStore.get(args.job_id);
+
+      if (!job) {
+        return {
+          content: [{ type: 'text', text: `❌ Job not found: ${args.job_id}` }],
+        };
+      }
+
+      if (job.status !== 'running' && job.status !== 'pending') {
+        return {
+          content: [{ type: 'text', text: `ℹ️ Job is not running (status: ${job.status})` }],
+        };
+      }
+
+      // Abort the HTTP request
+      job.abortController.abort();
+
+      // Try to cancel on database
+      const dbCancelled = await this.metabaseClient.cancelPostgresQuery(
+        job.database_id,
+        `job:${job.id}`
+      );
+
+      jobStore.markCancelled(args.job_id);
+
+      const output = `✅ **Query Cancelled**\\n` +
+        `📋 Job ID: ${args.job_id}\\n` +
+        `🗄️ Database cancel: ${dbCancelled ? 'sent' : 'not available'}`;
+
+      return {
+        content: [{ type: 'text', text: output }],
+      };
+
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: `❌ Failed to cancel: ${error.message}` }],
+      };
+    }
+  }
+
   async handleCreateQuestion(args) {
     const question = await this.metabaseClient.createSQLQuestion(
       args.name,
@@ -3863,16 +4199,47 @@ class MetabaseMCPServer {
         args.parameter_mappings
       );
 
-      return {
-        content: [{
-          type: 'text',
-          text: `✅ Card added to dashboard successfully!\\nCard ID: ${result.id}\\nPosition: Row ${args.position?.row || 0}, Col ${args.position?.col || 0}`
-        }],
-      };
+      // VERIFICATION: Check if card was actually added
+      try {
+        const dashboard = await this.metabaseClient.getDashboard(args.dashboard_id);
+        const cardExists = dashboard.ordered_cards?.some(c => c.card_id === args.question_id);
+        const cardCount = dashboard.ordered_cards?.length || 0;
+
+        if (cardExists) {
+          return {
+            content: [{
+              type: 'text',
+              text: `✅ Card verified!\\n` +
+                `Dashboard: ${dashboard.name} (ID: ${args.dashboard_id})\\n` +
+                `Total cards: ${cardCount}`
+            }],
+          };
+        } else {
+          return {
+            content: [{
+              type: 'text',
+              text: `⚠️ Card addition appears to have failed!\\n` +
+                `API reported success but card was not found on dashboard.\\n` +
+                `Dashboard ID: ${args.dashboard_id}, Question ID: ${args.question_id}\\n` +
+                `Please verify the question ID is valid.`
+            }],
+          };
+        }
+      } catch (verifyError) {
+        // Verification failed but original call might have succeeded
+        return {
+          content: [{
+            type: 'text',
+            text: `✅ Card added (verification unavailable)\\n` +
+              `Dashboard ID: ${args.dashboard_id}\\n` +
+              `Card ID: ${result?.id || 'N/A'}`
+          }],
+        };
+      }
 
     } catch (error) {
       return {
-        content: [{ type: 'text', text: `❌ Error adding card to dashboard: ${error.message}` }],
+        content: [{ type: 'text', text: `❌ Card addition error: ${error.message}` }],
       };
     }
   }
@@ -5962,6 +6329,147 @@ class MetabaseMCPServer {
     }
   }
 
+  /**
+   * Handle table profile request - comprehensive table analysis
+   * Automatically detects dim/ref tables and shows distinct values
+   */
+  async handleTableProfile(args) {
+    try {
+      await this.ensureInitialized();
+
+      const schemaName = args.schema_name || 'public';
+      const tableName = args.table_name;
+      const showDistinct = args.show_distinct_values !== false;
+      const sampleRows = args.sample_rows || 3;
+
+      // Detect if this is a dimension/reference table
+      const isDimTable = /^(dim_|ref_|lookup_|lkp_|d_|r_)/i.test(tableName);
+
+      // Get row count first
+      const countQuery = `SELECT COUNT(*) as cnt FROM "${schemaName}"."${tableName}"`;
+      const countResult = await this.metabaseClient.executeNativeQuery(args.database_id, countQuery);
+      const rowCount = countResult.data?.rows?.[0]?.[0] || 0;
+
+      // Get column info
+      const columnsQuery = `
+        SELECT 
+          column_name,
+          data_type,
+          is_nullable,
+          column_default
+        FROM information_schema.columns 
+        WHERE table_schema = '${schemaName}' AND table_name = '${tableName}'
+        ORDER BY ordinal_position
+      `;
+      const columnsResult = await this.metabaseClient.executeNativeQuery(args.database_id, columnsQuery);
+      const columns = columnsResult.data?.rows || [];
+
+      let output = '';
+
+      // Header with dim table indicator
+      if (isDimTable) {
+        output += `📊 **Dimension Table: ${schemaName}.${tableName}**\\n`;
+        output += `🏷️ _Detected as lookup/reference table_\\n\\n`;
+      } else {
+        output += `📊 **Table Profile: ${schemaName}.${tableName}**\\n\\n`;
+      }
+
+      output += `📈 **Overview:**\\n`;
+      output += `• Row count: ${rowCount.toLocaleString()}\\n`;
+      output += `• Columns: ${columns.length}\\n\\n`;
+
+      // Column details
+      output += `📋 **Columns:**\\n`;
+      columns.forEach(([name, type, nullable, defaultVal]) => {
+        const nullIndicator = nullable === 'YES' ? '?' : '';
+        output += `• \`${name}\` (${type}${nullIndicator})\\n`;
+      });
+      output += `\\n`;
+
+      // For dim tables or small tables, show distinct values
+      if ((isDimTable || rowCount < 1000) && showDistinct && columns.length > 0) {
+        output += `🔑 **Distinct Values:**\\n`;
+
+        // Get distinct counts and values for key columns (limit to first 5 columns)
+        const keyColumns = columns.slice(0, 5);
+        for (const [colName, colType] of keyColumns) {
+          try {
+            const distinctQuery = `
+              SELECT "${colName}", COUNT(*) as cnt 
+              FROM "${schemaName}"."${tableName}" 
+              GROUP BY "${colName}" 
+              ORDER BY cnt DESC 
+              LIMIT 10
+            `;
+            const distinctResult = await this.metabaseClient.executeNativeQuery(args.database_id, distinctQuery);
+            const distinctRows = distinctResult.data?.rows || [];
+
+            if (distinctRows.length > 0) {
+              const totalDistinct = distinctRows.length;
+              const values = distinctRows.slice(0, 5).map(r => r[0] === null ? 'NULL' : String(r[0])).join(', ');
+              output += `• \`${colName}\`: ${values}${totalDistinct > 5 ? ` (+${totalDistinct - 5} more)` : ''}\\n`;
+            }
+          } catch (e) {
+            // Skip columns that can't be queried
+          }
+        }
+        output += `\\n`;
+      }
+
+      // Sample data
+      if (sampleRows > 0 && rowCount > 0) {
+        try {
+          const sampleQuery = `SELECT * FROM "${schemaName}"."${tableName}" LIMIT ${sampleRows}`;
+          const sampleResult = await this.metabaseClient.executeNativeQuery(args.database_id, sampleQuery);
+          const sampleData = sampleResult.data?.rows || [];
+          const sampleCols = sampleResult.data?.cols || [];
+
+          if (sampleData.length > 0) {
+            output += `📝 **Sample Data (${sampleData.length} rows):**\\n\`\`\`\\n`;
+            // Header
+            const headers = sampleCols.map(c => c.name);
+            output += headers.join(' | ') + '\\n';
+            output += headers.map(() => '---').join(' | ') + '\\n';
+            // Data
+            sampleData.forEach(row => {
+              const formattedRow = row.map(cell => {
+                if (cell === null) return 'NULL';
+                const str = String(cell);
+                return str.length > 20 ? str.substring(0, 17) + '...' : str;
+              });
+              output += formattedRow.join(' | ') + '\\n';
+            });
+            output += '\`\`\`\\n';
+          }
+        } catch (e) {
+          output += `_Could not fetch sample data: ${e.message}_\\n`;
+        }
+      }
+
+      // Recommendations
+      output += `\\n💡 **Tips:**\\n`;
+      if (isDimTable) {
+        output += `• Use this table for JOINs as a lookup\\n`;
+        output += `• Use \`mb_field_values\` to see all values for a specific column\\n`;
+      }
+      if (rowCount === 0) {
+        output += `• ⚠️ Table is empty - data may need to be loaded\\n`;
+      }
+      if (rowCount > 100000) {
+        output += `• Large table - use LIMIT in queries\\n`;
+      }
+
+      return {
+        content: [{ type: 'text', text: output }]
+      };
+
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: `❌ Table profile error: ${error.message}` }]
+      };
+    }
+  }
+
   async handleIndexUsage(args) {
     try {
       await this.ensureInitialized();
@@ -6205,8 +6713,19 @@ class MetabaseMCPServer {
       };
 
     } catch (error) {
+      // Better error messages for common issues
+      let userMessage = error.message;
+
+      if (error.message.includes('already exists') || error.response?.status === 409) {
+        userMessage = `Collection already exists with this name: "${args.name}"`;
+      } else if (error.message.includes('permission') || error.response?.status === 403) {
+        userMessage = `Permission denied. Contact admin for collection creation access.`;
+      } else if (error.message.includes('parent') || (error.message.includes('not found') && args.parent_id)) {
+        userMessage = `Parent collection not found: ID ${args.parent_id}`;
+      }
+
       return {
-        content: [{ type: 'text', text: `❌ Collection creation failed: ${error.message}` }]
+        content: [{ type: 'text', text: `❌ Collection creation failed: ${userMessage}` }]
       };
     }
   }

package/src/metabase/client.js

@@ -8,8 +8,10 @@ export class MetabaseClient {
     this.password = config.password;
     this.apiKey = config.apiKey;
     this.sessionToken = null;
+    this.defaultQueryTimeout = config.queryTimeout || 60000; // 60 seconds default
     this.client = axios.create({
       baseURL: this.baseURL,
+      timeout: this.defaultQueryTimeout,
       headers: {
         'Content-Type': 'application/json'
       }
@@ -79,7 +81,7 @@ export class MetabaseClient {
 
   async getDatabaseConnectionInfo(id) {
     await this.ensureAuthenticated();
-    
+
     // Önce gerçek credentials'ları MetabaseappDB'den al
     try {
       const realCredentials = await this.getRealCredentials(id);
@@ -89,11 +91,11 @@ export class MetabaseClient {
     } catch (error) {
       logger.warn('Could not get real credentials, using API response:', error.message);
     }
-    
+
     // Fallback: Normal API response
     const response = await this.client.get(`/api/database/${id}`);
     const db = response.data;
-    
+
     return {
       id: db.id,
       name: db.name,
@@ -116,13 +118,13 @@ export class MetabaseClient {
       FROM metabase_database 
       WHERE id = ${databaseId}
     `;
-    
+
     const result = await this.executeNativeQuery(6, query, { enforcePrefix: false }); // MetabaseappDB
-    
+
     if (result.data.rows.length > 0) {
       const [name, engine, details] = result.data.rows[0];
       const detailsObj = JSON.parse(details);
-      
+
       return {
         id: databaseId,
         name: name,
@@ -137,13 +139,13 @@ export class MetabaseClient {
         tunnel_enabled: detailsObj['tunnel-enabled'] || false
       };
     }
-    
+
     return null;
   }
 
   buildConnectionString(db) {
     const details = db.details;
-    
+
     switch (db.engine) {
       case 'postgres':
         return `postgresql://${details.user}:${details.password}@${details.host}:${details.port}/${details.dbname}`;
@@ -252,7 +254,7 @@ export class MetabaseClient {
 
   async createParametricQuestion(questionData) {
     await this.ensureAuthenticated();
-    
+
     // Build native query with parameters
     const nativeQuery = {
       type: 'native',
@@ -304,17 +306,17 @@ export class MetabaseClient {
   // SQL Operations
   async executeNativeQuery(databaseId, sql, options = {}) {
     await this.ensureAuthenticated();
-    
-    // Güvenlik kontrolü - DDL operasyonları için prefix zorunluluğu
+
+    // Security check - DDL operations require prefix
     if (options.enforcePrefix !== false && this.isDDLOperation(sql)) {
       this.validateDDLPrefix(sql);
     }
 
-    // DDL operations için farklı endpoint kullan
+    // DDL operations use different endpoint
     if (this.isDDLOperation(sql)) {
       return await this.executeDDLOperation(databaseId, sql);
     }
-    
+
     const query = {
       database: databaseId,
       type: 'native',
@@ -325,6 +327,68 @@ export class MetabaseClient {
     return await this.runQuery(query);
   }
 
+  /**
+   * Execute query with custom timeout and abort signal
+   * Used for async query management
+   */
+  async executeNativeQueryWithTimeout(databaseId, sql, timeoutMs, abortSignal = null) {
+    await this.ensureAuthenticated();
+
+    const query = {
+      database: databaseId,
+      type: 'native',
+      native: {
+        query: sql
+      }
+    };
+
+    const config = {
+      timeout: timeoutMs
+    };
+
+    // Add abort signal if provided
+    if (abortSignal) {
+      config.signal = abortSignal;
+    }
+
+    try {
+      const response = await this.client.post('/api/dataset', query, config);
+      return response.data;
+    } catch (error) {
+      if (error.name === 'AbortError' || error.code === 'ERR_CANCELED') {
+        throw new Error('Query cancelled');
+      }
+      if (error.code === 'ECONNABORTED' || error.message.includes('timeout')) {
+        throw new Error(`Query timed out after ${timeoutMs / 1000} seconds`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Cancel a running query on PostgreSQL database
+   * This sends pg_cancel_backend to stop the query on the server side
+   */
+  async cancelPostgresQuery(databaseId, queryMarker) {
+    try {
+      // Find and cancel queries containing the marker
+      const cancelSql = `
+        SELECT pg_cancel_backend(pid)
+        FROM pg_stat_activity
+        WHERE query LIKE '%${queryMarker}%'
+          AND state = 'active'
+          AND pid != pg_backend_pid()
+      `;
+
+      await this.executeNativeQuery(databaseId, cancelSql, { enforcePrefix: false });
+      logger.info(`Attempted to cancel query with marker: ${queryMarker}`);
+      return true;
+    } catch (error) {
+      logger.warn(`Failed to cancel query: ${error.message}`);
+      return false;
+    }
+  }
+
   async executeDDLOperation(databaseId, sql) {
     try {
       // DDL için action endpoint kullan
@@ -333,7 +397,7 @@ export class MetabaseClient {
         sql: sql,
         type: 'query'
       });
-      
+
       return {
         status: 'success',
         message: 'DDL operation completed',
@@ -350,7 +414,7 @@ export class MetabaseClient {
             query: sql
           }
         };
-        
+
         await this.runQuery(query);
         return {
           status: 'success',
@@ -360,7 +424,7 @@ export class MetabaseClient {
         };
       } catch (secondError) {
         logger.warn('DDL execution warning:', secondError.message);
-        
+
         // DDL işlemi başarılı olmuş olabilir, kontrol et
         if (secondError.message.includes('Select statement did not produce a ResultSet')) {
           return {
@@ -371,7 +435,7 @@ export class MetabaseClient {
             warning: secondError.message
           };
         }
-        
+
         throw secondError;
       }
     }
@@ -380,29 +444,29 @@ export class MetabaseClient {
   isDDLOperation(sql) {
     const upperSQL = sql.toUpperCase().trim();
     return upperSQL.startsWith('CREATE TABLE') ||
-           upperSQL.startsWith('CREATE VIEW') ||
-           upperSQL.startsWith('CREATE MATERIALIZED VIEW') ||
-           upperSQL.startsWith('CREATE INDEX') ||
-           upperSQL.startsWith('DROP TABLE') ||
-           upperSQL.startsWith('DROP VIEW') ||
-           upperSQL.startsWith('DROP MATERIALIZED VIEW') ||
-           upperSQL.startsWith('DROP INDEX');
+      upperSQL.startsWith('CREATE VIEW') ||
+      upperSQL.startsWith('CREATE MATERIALIZED VIEW') ||
+      upperSQL.startsWith('CREATE INDEX') ||
+      upperSQL.startsWith('DROP TABLE') ||
+      upperSQL.startsWith('DROP VIEW') ||
+      upperSQL.startsWith('DROP MATERIALIZED VIEW') ||
+      upperSQL.startsWith('DROP INDEX');
   }
 
   validateDDLPrefix(sql) {
     const upperSQL = sql.toUpperCase();
-    
+
     // CREATE operations için prefix kontrolü
-    if (upperSQL.includes('CREATE TABLE') || upperSQL.includes('CREATE VIEW') || 
-        upperSQL.includes('CREATE MATERIALIZED VIEW') || upperSQL.includes('CREATE INDEX')) {
+    if (upperSQL.includes('CREATE TABLE') || upperSQL.includes('CREATE VIEW') ||
+      upperSQL.includes('CREATE MATERIALIZED VIEW') || upperSQL.includes('CREATE INDEX')) {
       if (!sql.toLowerCase().includes('claude_ai_')) {
         throw new Error('DDL operations must use claude_ai_ prefix for object names');
       }
     }
-    
+
     // DROP operations için sadece prefix'li objelere izin
-    if (upperSQL.includes('DROP TABLE') || upperSQL.includes('DROP VIEW') || 
-        upperSQL.includes('DROP MATERIALIZED VIEW') || upperSQL.includes('DROP INDEX')) {
+    if (upperSQL.includes('DROP TABLE') || upperSQL.includes('DROP VIEW') ||
+      upperSQL.includes('DROP MATERIALIZED VIEW') || upperSQL.includes('DROP INDEX')) {
       if (!sql.toLowerCase().includes('claude_ai_')) {
         throw new Error('Can only drop objects with claude_ai_ prefix');
       }
@@ -470,14 +534,14 @@ export class MetabaseClient {
 
   async addCardToDashboard(dashboardId, cardId, options = {}) {
     await this.ensureAuthenticated();
-    
+
     try {
       // Try the API first (various endpoints)
       const endpoints = [
         `/api/dashboard/${dashboardId}/cards`,
         `/api/dashboard/${dashboardId}/dashcard`
       ];
-      
+
       for (const endpoint of endpoints) {
         try {
           const response = await this.client.post(endpoint, {
@@ -494,10 +558,10 @@ export class MetabaseClient {
           continue;
         }
       }
-      
+
       // If API fails, use direct database insertion as fallback
       return await this.addCardToDashboardDirect(dashboardId, cardId, options);
-      
+
     } catch (error) {
       throw new Error(`Failed to add card to dashboard: ${error.message}`);
     }
@@ -523,10 +587,10 @@ export class MetabaseClient {
         $1, $2, $3, $4, $5, $6, $7, $8
       ) RETURNING id
     `;
-    
+
     const values = [
       options.sizeX || 4,
-      options.sizeY || 4, 
+      options.sizeY || 4,
       options.row || 0,
       options.col || 0,
       cardId,
@@ -534,7 +598,7 @@ export class MetabaseClient {
       JSON.stringify(options.parameter_mappings || []),
       JSON.stringify(options.visualization_settings || {})
     ];
-    
+
     // This would need database connection - placeholder for now
     return { id: 'inserted_via_sql', method: 'direct_sql' };
   }
@@ -547,11 +611,11 @@ export class MetabaseClient {
 
   async addDashboardFilter(dashboardId, filter) {
     await this.ensureAuthenticated();
-    
+
     // Get current dashboard to add filter
     const dashboard = await this.client.get(`/api/dashboard/${dashboardId}`);
     const currentFilters = dashboard.data.parameters || [];
-    
+
     // Create proper Metabase filter format
     const newFilter = {
       id: this.generateFilterId(),
@@ -567,9 +631,9 @@ export class MetabaseClient {
     } else if (filter.default_value !== undefined) {
       newFilter.default = filter.default_value;
     }
-    
+
     const updatedFilters = [...currentFilters, newFilter];
-    
+
     return await this.updateDashboard(dashboardId, {
       parameters: updatedFilters
     });