@onmartech/metabase-ai-assistant 4.0.0

package/src/mcp/handlers/collections.js

@@ -0,0 +1,244 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { logger } from '../../utils/logger.js';
+
+export class CollectionsHandler {
+    constructor(metabaseClient) {
+        this.metabaseClient = metabaseClient;
+    }
+
+    routes() {
+        return {
+            'mb_collection_create': (args) => this.handleCollectionCreate(args),
+            'mb_collection_list': (args) => this.handleCollectionList(args),
+            'mb_collection_move': (args) => this.handleCollectionMove(args),
+            'mb_collection_copy': (args) => this.handleCollectionCopy(args),
+            'mb_collection_permissions_get': (args) => this.handleCollectionPermissionsGet(args),
+            'mb_collection_permissions_update': (args) => this.handleCollectionPermissionsUpdate(args),
+        };
+    }
+
+  async handleCollectionCreate(args) {
+    try {
+      await this.ensureInitialized();
+
+      const collectionData = {
+        name: args.name,
+        description: args.description || '',
+        parent_id: args.parent_id || null,
+        color: args.color || '#509EE3'
+      };
+
+      const collection = await this.metabaseClient.request('POST', '/api/collection', collectionData);
+
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ **Collection Created!**\\n\\n` +
+            `🆔 Collection ID: ${collection.id}\\n` +
+            `📁 Name: ${collection.name}\\n` +
+            `📝 Description: ${collection.description || 'None'}\\n` +
+            `🎨 Color: ${collection.color}\\n` +
+            `📂 Parent: ${args.parent_id || 'Root'}`
+        }]
+      };
+
+    } 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: ${userMessage}` }]
+      };
+    }
+  }
+
+  async handleCollectionList(args) {
+    try {
+      await this.ensureInitialized();
+
+      let endpoint = '/api/collection';
+      if (args.parent_id) {
+        endpoint = `/api/collection/${args.parent_id}/items`;
+      }
+
+      const collections = await this.metabaseClient.request('GET', '/api/collection');
+
+      let output = `📂 **Collections**\\n\\n`;
+
+      const rootCollections = collections.filter(c => !c.personal_owner_id);
+      rootCollections.slice(0, 20).forEach((col, i) => {
+        output += `${i + 1}. **${col.name}** (ID: ${col.id})\\n`;
+        if (col.description) output += `   ${col.description.substring(0, 50)}...\\n`;
+      });
+
+      output += `\\n📊 Total Collections: ${collections.length}`;
+
+      return {
+        content: [{ type: 'text', text: output }]
+      };
+
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: `❌ Collection list failed: ${error.message}` }]
+      };
+    }
+  }
+
+  async handleCollectionMove(args) {
+    try {
+      await this.ensureInitialized();
+
+      let endpoint;
+      const updateData = { collection_id: args.target_collection_id };
+
+      switch (args.item_type) {
+        case 'card':
+          endpoint = `/api/card/${args.item_id}`;
+          break;
+        case 'dashboard':
+          endpoint = `/api/dashboard/${args.item_id}`;
+          break;
+        case 'collection':
+          endpoint = `/api/collection/${args.item_id}`;
+          updateData.parent_id = args.target_collection_id;
+          delete updateData.collection_id;
+          break;
+        default:
+          throw new Error(`Unknown item type: ${args.item_type}`);
+      }
+
+      await this.metabaseClient.request('PUT', endpoint, updateData);
+
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ **Item Moved!**\\n\\n` +
+            `📦 Type: ${args.item_type}\\n` +
+            `🆔 Item ID: ${args.item_id}\\n` +
+            `📂 Target Collection: ${args.target_collection_id || 'Root'}`
+        }]
+      };
+
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: `❌ Move failed: ${error.message}` }]
+      };
+    }
+  }
+
+  async handleCollectionPermissionsGet(args) {
+    await this.ensureInitialized();
+    const { collection_id } = args;
+
+    try {
+      const graph = await this.metabaseClient.request('GET', '/api/collection/graph');
+      const collectionPerms = graph.groups;
+
+      const permissions = [];
+      for (const [groupId, perms] of Object.entries(collectionPerms)) {
+        const collPerm = perms[collection_id];
+        if (collPerm) {
+          permissions.push({ group_id: groupId, permission: collPerm });
+        }
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: `Collection ${collection_id} permissions:\n${permissions.map(p =>
+            `  - Group ${p.group_id}: ${p.permission}`
+          ).join('\n') || '  No specific permissions set'}`
+        }]
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `❌ Collection permissions get error: ${error.message}` }] };
+    }
+  }
+
+  async handleCollectionPermissionsUpdate(args) {
+    await this.ensureInitialized();
+    const { collection_id, group_id, permission } = args;
+
+    try {
+      // Get current graph
+      const graph = await this.metabaseClient.request('GET', '/api/collection/graph');
+
+      // Update the permission
+      if (!graph.groups[group_id]) {
+        graph.groups[group_id] = {};
+      }
+      graph.groups[group_id][collection_id] = permission;
+
+      // Save the updated graph
+      await this.metabaseClient.request('PUT', '/api/collection/graph', graph);
+
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ Collection ${collection_id} permission updated: Group ${group_id} = ${permission}`
+        }]
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `❌ Collection permissions update error: ${error.message}` }] };
+    }
+  }
+
+  async handleCollectionCopy(args) {
+    await this.ensureInitialized();
+    const { collection_id, destination_id, new_name } = args;
+
+    try {
+      // Get source collection
+      const sourceCollection = await this.metabaseClient.request('GET', `/api/collection/${collection_id}`);
+
+      // Create new collection
+      const newCollection = await this.metabaseClient.request('POST', '/api/collection', {
+        name: new_name || `Copy of ${sourceCollection.name}`,
+        description: sourceCollection.description,
+        parent_id: destination_id || sourceCollection.parent_id
+      });
+
+      // Get items in source collection
+      const items = await this.metabaseClient.request('GET', `/api/collection/${collection_id}/items`);
+      const allItems = items.data || items;
+
+      let copiedCards = 0;
+      let copiedDashboards = 0;
+
+      // Copy each item
+      for (const item of allItems) {
+        if (item.model === 'card') {
+          await this.handleCardCopy({
+            card_id: item.id,
+            collection_id: newCollection.id
+          });
+          copiedCards++;
+        } else if (item.model === 'dashboard') {
+          await this.handleDashboardCopy({
+            dashboard_id: item.id,
+            collection_id: newCollection.id,
+            deep_copy: false // Don't deep copy cards as they're already being copied
+          });
+          copiedDashboards++;
+        }
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ Collection copied:\n  New Collection ID: ${newCollection.id}\n  Name: ${newCollection.name}\n  Cards copied: ${copiedCards}\n  Dashboards copied: ${copiedDashboards}`
+        }]
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `❌ Collection copy error: ${error.message}` }] };
+    }
+  }
+}

package/src/mcp/handlers/dashboard.js

@@ -0,0 +1,207 @@
+/**
+ * Dashboard Handler Module
+ * Handles dashboard creation, management, and visualization operations
+ */
+
+import { logger } from '../../utils/logger.js';
+
+/**
+ * Handle create dashboard request
+ * @param {object} args
+ * @param {object} context
+ * @returns {Promise<object>}
+ */
+export async function handleCreateDashboard(args, context) {
+    const { metabaseClient } = context;
+
+    const dashboard = await metabaseClient.createDashboard({
+        name: args.name,
+        description: args.description,
+        collection_id: args.collection_id
+    });
+
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `✅ **Dashboard Created!**\\n\\n` +
+                    `• Name: ${dashboard.name}\\n` +
+                    `• ID: ${dashboard.id}\\n` +
+                    `• Collection: ${args.collection_id || 'Root'}`,
+            },
+        ],
+    };
+}
+
+/**
+ * Handle get dashboards list request
+ * @param {object} context
+ * @returns {Promise<object>}
+ */
+export async function handleGetDashboards(context) {
+    const { metabaseClient } = context;
+
+    const dashboards = await metabaseClient.getDashboards();
+
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `📊 **Available Dashboards (${dashboards.length})**\\n\\n` +
+                    dashboards.map(d =>
+                        `• **${d.name}** (ID: ${d.id})\\n  Collection: ${d.collection_id || 'Root'}`
+                    ).join('\\n'),
+            },
+        ],
+    };
+}
+
+/**
+ * Handle add card to dashboard request
+ * @param {object} args
+ * @param {object} context
+ * @returns {Promise<object>}
+ */
+export async function handleAddCardToDashboard(args, context) {
+    const { metabaseClient } = context;
+
+    const position = args.position || {};
+
+    await metabaseClient.addCardToDashboard(args.dashboard_id, args.question_id, {
+        row: position.row || 0,
+        col: position.col || 0,
+        sizeX: position.sizeX || 6,
+        sizeY: position.sizeY || 4
+    });
+
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `✅ **Card Added to Dashboard!**\\n\\n` +
+                    `• Dashboard ID: ${args.dashboard_id}\\n` +
+                    `• Question ID: ${args.question_id}\\n` +
+                    `• Position: (${position.row || 0}, ${position.col || 0})\\n` +
+                    `• Size: ${position.sizeX || 6}x${position.sizeY || 4}`,
+            },
+        ],
+    };
+}
+
+/**
+ * Handle add dashboard filter request
+ * @param {object} args
+ * @param {object} context
+ * @returns {Promise<object>}
+ */
+export async function handleAddDashboardFilter(args, context) {
+    const { metabaseClient } = context;
+
+    await metabaseClient.addDashboardFilter(args.dashboard_id, {
+        name: args.name,
+        type: args.type,
+        field_id: args.field_id,
+        default_value: args.default_value
+    });
+
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `✅ **Filter Added!**\\n\\n` +
+                    `• Dashboard ID: ${args.dashboard_id}\\n` +
+                    `• Filter Name: ${args.name}\\n` +
+                    `• Type: ${args.type}`,
+            },
+        ],
+    };
+}
+
+/**
+ * Handle optimize dashboard layout request
+ * @param {object} args
+ * @param {object} context
+ * @returns {Promise<object>}
+ */
+export async function handleOptimizeDashboardLayout(args, context) {
+    const { metabaseClient } = context;
+
+    const dashboard = await metabaseClient.getDashboard(args.dashboard_id);
+    const cards = dashboard.ordered_cards || [];
+
+    const layoutStyle = args.layout_style || 'executive';
+    const gridWidth = args.grid_width || 12;
+
+    // Calculate optimized positions
+    const optimizedCards = cards.map((card, index) => {
+        const row = Math.floor(index / 2) * 4;
+        const col = (index % 2) * 6;
+
+        return {
+            ...card,
+            row,
+            col,
+            sizeX: 6,
+            sizeY: 4
+        };
+    });
+
+    // Update dashboard
+    await metabaseClient.updateDashboard(args.dashboard_id, {
+        ordered_cards: optimizedCards
+    });
+
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `✅ **Dashboard Layout Optimized!**\\n\\n` +
+                    `• Dashboard ID: ${args.dashboard_id}\\n` +
+                    `• Style: ${layoutStyle}\\n` +
+                    `• Cards Reorganized: ${cards.length}`,
+            },
+        ],
+    };
+}
+
+/**
+ * Handle create executive dashboard request
+ * @param {object} args
+ * @param {object} context
+ * @returns {Promise<object>}
+ */
+export async function handleCreateExecutiveDashboard(args, context) {
+    const { metabaseClient } = context;
+
+    // Create the dashboard first
+    const dashboard = await metabaseClient.createDashboard({
+        name: args.name,
+        description: `Executive dashboard for ${args.business_domain || 'general'} metrics`,
+        collection_id: args.collection_id
+    });
+
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `✅ **Executive Dashboard Created!**\\n\\n` +
+                    `• Dashboard ID: ${dashboard.id}\\n` +
+                    `• Name: ${dashboard.name}\\n` +
+                    `• Business Domain: ${args.business_domain || 'general'}\\n` +
+                    `• Time Period: ${args.time_period || 'last_30_days'}\\n\\n` +
+                    `📝 Next Steps:\\n` +
+                    `• Add questions to this dashboard\\n` +
+                    `• Configure filters for interactive analysis`,
+            },
+        ],
+    };
+}
+
+export default {
+    handleCreateDashboard,
+    handleGetDashboards,
+    handleAddCardToDashboard,
+    handleAddDashboardFilter,
+    handleOptimizeDashboardLayout,
+    handleCreateExecutiveDashboard,
+};