@rashidazarang/airtable-mcp 1.5.0 → 2.1.0

package/airtable-clipper/docs/SETUP.md

@@ -0,0 +1,291 @@
+# 🚀 Setup Guide - Airtable Clipper
+
+This guide will walk you through setting up Airtable Clipper in under 5 minutes.
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+- **Chrome Browser** (version 88 or higher)
+- **Airtable Account** (free or paid)
+- **Internet Connection** for Airtable API access
+
+## Step 1: Install the Extension
+
+### Option A: Chrome Web Store (Recommended)
+1. Visit the [Airtable Clipper Chrome Web Store page](https://chrome.google.com/webstore/detail/airtable-clipper/EXTENSION_ID)
+2. Click **"Add to Chrome"**
+3. Confirm by clicking **"Add Extension"**
+4. You'll see the Airtable Clipper icon (📎) in your Chrome toolbar
+
+### Option B: Manual Installation (Developers)
+1. Download the latest release from [GitHub](https://github.com/rashidazarang/airtable-clipper/releases)
+2. Unzip the downloaded file
+3. Open Chrome and go to `chrome://extensions/`
+4. Enable **"Developer mode"** (toggle in top-right)
+5. Click **"Load unpacked"** and select the `extension` folder
+6. The extension will appear in your toolbar
+
+## Step 2: Get Your Airtable Credentials
+
+### 2.1 Create a Personal Access Token
+
+1. **Go to Airtable Token Creation Page**
+   - Visit [airtable.com/create/tokens](https://airtable.com/create/tokens)
+   - Sign in to your Airtable account if prompted
+
+2. **Create New Token**
+   - Click **"Create new token"**
+   - **Name**: `Airtable Clipper` (or any name you prefer)
+   - **Description**: `Chrome extension for web clipping`
+
+3. **Add Required Scopes**
+   Select these permissions:
+   - ✅ `data.records:read` - Read records from your tables
+   - ✅ `data.records:write` - Create and update records
+   - ✅ `schema.bases:read` - Read table structures
+
+4. **Add Base Access**
+   - Click **"Add a base"**
+   - Select the base(s) you want to clip data to
+   - Choose **"All current and future tables in this base"**
+
+5. **Create Token**
+   - Click **"Create token"**
+   - **⚠️ Copy and save the token immediately** - it starts with `pat...`
+   - You won't be able to see it again!
+
+### 2.2 Get Your Base ID
+
+1. **Open Your Airtable Base**
+   - Go to [airtable.com](https://airtable.com)
+   - Open the base where you want to save clipped data
+
+2. **Copy Base ID from URL**
+   - Look at the URL in your browser address bar
+   - Find the part that looks like: `https://airtable.com/appXXXXXXXXXXXXXX/...`
+   - Copy the **Base ID** (the part starting with `app`)
+   - Example: `appTV04Fyu1Gvbunq`
+
+![Base ID Location](images/base-id-location.png)
+
+## Step 3: Configure the Extension
+
+1. **Open Extension Popup**
+   - Click the Airtable Clipper icon (📎) in your Chrome toolbar
+   - You should see the setup screen
+
+2. **Enter Your Credentials**
+   - **Personal Access Token**: Paste your token (starts with `pat...`)
+   - **Base ID**: Paste your base ID (starts with `app...`)
+
+![Setup Screen](images/setup-screen.png)
+
+3. **Test Connection**
+   - Click **"Connect to Airtable"**
+   - You should see "Connected successfully!" message
+   - The extension will load your table names automatically
+
+4. **Configure Tables (Optional)**
+   - **Default Table**: Where general web clips will be saved (default: "Clips")
+   - **LinkedIn Table**: Where LinkedIn profiles will be saved (default: "Contacts")
+   - You can change these later in settings
+
+## Step 4: Create Tables (If Needed)
+
+The extension works best with properly structured tables. Here are recommended setups:
+
+### For LinkedIn Contacts (Recommended Table: "Contacts")
+
+Create a table with these fields:
+
+| Field Name | Field Type | Description |
+|------------|------------|-------------|
+| Name | Single line text | Contact's full name |
+| Title | Single line text | Job title |
+| Company | Single line text | Company name |
+| Location | Single line text | Location/city |
+| Email | Email | Email address (auto-guessed) |
+| Phone | Phone number | Phone number |
+| LinkedIn URL | URL | Link to LinkedIn profile |
+| Date Added | Date | When contact was saved |
+| Source | Single select | How contact was added |
+| Lead Score | Number | Data quality score (0-100) |
+| Notes | Long text | Additional information |
+| Tags | Multiple select | Relevant tags |
+
+### For General Web Clips (Recommended Table: "Clips")
+
+Create a table with these fields:
+
+| Field Name | Field Type | Description |
+|------------|------------|-------------|
+| Title | Single line text | Page/article title |
+| URL | URL | Source webpage URL |
+| Content | Long text | Extracted content |
+| Date Saved | Date | When content was clipped |
+| Type | Single select | Content type (Article, Profile, etc.) |
+| Domain | Single line text | Website domain |
+| Tags | Multiple select | Auto-generated tags |
+| Quality Score | Number | Extraction quality (0-100) |
+
+### Quick Table Creation
+
+You can also let the extension suggest table structures:
+
+1. Try to save some content first
+2. If tables don't exist, the extension will show an error with suggested fields
+3. Create the tables manually with the suggested structure
+4. Try saving again
+
+## Step 5: Test the Extension
+
+### Test 1: Save a LinkedIn Profile
+
+1. **Visit a LinkedIn Profile**
+   - Go to any public LinkedIn profile (e.g., `linkedin.com/in/username`)
+   - Make sure you're not on the LinkedIn home feed
+
+2. **Save the Profile**
+   - Click the Airtable Clipper icon
+   - Click **"Save Profile"** or just **"Quick Save"**
+   - You should see a success notification
+
+3. **Check Airtable**
+   - Open your Airtable base
+   - Check the "Contacts" table (or your LinkedIn table)
+   - You should see the profile data saved
+
+### Test 2: Save a General Web Page
+
+1. **Visit Any Website**
+   - Go to an article, blog post, or any webpage
+   - Try a site like Medium, GitHub, or Stack Overflow
+
+2. **Save the Page**
+   - Click the Airtable Clipper icon
+   - Click **"Quick Save"**
+   - Wait for the success notification
+
+3. **Check Airtable**
+   - Check your "Clips" table (or default table)
+   - You should see the page data saved
+
+## Step 6: Explore Features
+
+### Floating Action Button
+- Visit supported sites (LinkedIn, GitHub, etc.)
+- Look for the floating 📎 button in the bottom-right corner
+- Click it for quick saving
+
+### Right-Click Menu
+- Right-click anywhere on a webpage
+- Look for "Save to Airtable" in the context menu
+- Great for saving selected text or specific content
+
+### Bulk Mode
+- Hold **Shift** and click the extension icon
+- Or use keyboard shortcut: **Cmd+Shift+B** (Mac) or **Ctrl+Shift+B** (Windows)
+- Click multiple items on the page to select them
+- Click **"Save Selected"** to save everything at once
+
+### Keyboard Shortcuts
+- **Quick Save**: `Cmd+Shift+S` (Mac) or `Ctrl+Shift+S` (Windows)
+- **Bulk Mode**: `Cmd+Shift+B` (Mac) or `Ctrl+Shift+B` (Windows)
+
+## Troubleshooting Common Issues
+
+### ❌ "Connection Failed" Error
+
+**Check Your Token:**
+- Make sure you copied the complete token (starts with `pat`)
+- Token should be about 40-50 characters long
+- Verify you have the required scopes enabled
+
+**Check Your Base ID:**
+- Make sure it starts with `app` (not `tbl` or other prefixes)
+- Should be exactly 17 characters long
+- Copy from the URL, not from the table ID
+
+**Test Manually:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+     https://api.airtable.com/v0/meta/bases/YOUR_BASE_ID/tables
+```
+
+### ❌ "Failed to Extract Data" Error
+
+**Page Not Supported:**
+- Try refreshing the page and trying again
+- Some dynamic sites need a moment to load content
+- Not all websites may be supported yet
+
+**LinkedIn Specific:**
+- Make sure you're on a profile page (`linkedin.com/in/username`)
+- Some profiles may be private or have limited public data
+- Try a different profile
+
+### ❌ "Table Not Found" Error
+
+**Create Missing Tables:**
+- The extension can't create tables automatically
+- Create tables manually in Airtable with the suggested field names
+- Make sure table names match exactly (case-sensitive)
+
+### 🐌 Slow Performance
+
+**Browser Issues:**
+- Close unused tabs to free up memory
+- Disable other extensions temporarily
+- Restart Chrome if it becomes sluggish
+
+**Network Issues:**
+- Check your internet connection
+- Airtable API may be temporarily slow
+- Try again in a few minutes
+
+## Advanced Configuration
+
+### Custom Field Mapping
+
+You can customize how extracted data maps to your Airtable fields:
+
+1. Click the extension icon
+2. Click **"Settings"** at the bottom
+3. Modify the table and field mappings
+4. Changes are saved automatically
+
+### Automation Settings
+
+- **Auto-Save LinkedIn**: Automatically save LinkedIn profiles when you visit them
+- **Duplicate Detection**: Skip saving if a similar record already exists
+- **Notifications**: Control when you see success/error messages
+
+### Privacy Settings
+
+- **Data Processing**: All data processing happens locally in your browser
+- **No Tracking**: The extension doesn't track your browsing or send data to external servers
+- **Storage**: Settings are synced across your Chrome browsers via Chrome Sync
+
+## Getting Help
+
+If you're still having issues:
+
+1. **Check the Documentation**: [Full docs](../README.md)
+2. **Search Issues**: [GitHub Issues](https://github.com/rashidazarang/airtable-clipper/issues)
+3. **Ask for Help**: [GitHub Discussions](https://github.com/rashidazarang/airtable-clipper/discussions)
+4. **Report Bugs**: [Create a new issue](https://github.com/rashidazarang/airtable-clipper/issues/new)
+
+Include this information when asking for help:
+- Chrome version
+- Extension version
+- Website you're trying to clip from
+- Error message (if any)
+- Steps to reproduce the issue
+
+---
+
+**Next Steps:**
+- [Learn advanced features](ADVANCED.md)
+- [See use case examples](EXAMPLES.md)
+- [Contribute to the project](../README.md#contributing)

package/airtable-clipper/extension/background.js

@@ -0,0 +1,337 @@
+// Airtable Clipper - Background Service Worker
+// Handles context menus, notifications, and cross-tab communication
+
+class BackgroundService {
+  constructor() {
+    this.init();
+  }
+
+  init() {
+    // Create context menu on installation
+    chrome.runtime.onInstalled.addListener(() => {
+      this.createContextMenus();
+      this.setupNotifications();
+    });
+
+    // Handle context menu clicks
+    chrome.contextMenus.onClicked.addListener((info, tab) => {
+      this.handleContextMenuClick(info, tab);
+    });
+
+    // Handle messages from content scripts and popup
+    chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+      this.handleMessage(message, sender, sendResponse);
+      return true; // Keep message channel open for async responses
+    });
+
+    // Handle extension icon clicks
+    chrome.action.onClicked.addListener((tab) => {
+      this.handleActionClick(tab);
+    });
+
+    // Periodic cleanup
+    chrome.alarms.onAlarm.addListener((alarm) => {
+      if (alarm.name === 'cleanup') {
+        this.cleanupStorage();
+      }
+    });
+
+    // Set up cleanup alarm
+    chrome.alarms.create('cleanup', { delayInMinutes: 60, periodInMinutes: 60 });
+  }
+
+  createContextMenus() {
+    // Remove existing menus
+    chrome.contextMenus.removeAll();
+
+    // Main menu
+    chrome.contextMenus.create({
+      id: 'save-to-airtable',
+      title: 'Save to Airtable',
+      contexts: ['page', 'selection', 'link', 'image']
+    });
+
+    // LinkedIn specific
+    chrome.contextMenus.create({
+      id: 'save-linkedin-profile',
+      title: 'Save LinkedIn Profile',
+      contexts: ['page'],
+      documentUrlPatterns: ['*://www.linkedin.com/in/*', '*://linkedin.com/in/*']
+    });
+
+    // Quick save selection
+    chrome.contextMenus.create({
+      id: 'quick-save-selection',
+      title: 'Quick Save Selected Text',
+      contexts: ['selection']
+    });
+  }
+
+  async handleContextMenuClick(info, tab) {
+    try {
+      switch (info.menuItemId) {
+        case 'save-to-airtable':
+          await this.triggerSave(tab, { type: 'general', info });
+          break;
+        case 'save-linkedin-profile':
+          await this.triggerSave(tab, { type: 'linkedin', info });
+          break;
+        case 'quick-save-selection':
+          await this.triggerSave(tab, { type: 'selection', text: info.selectionText });
+          break;
+      }
+    } catch (error) {
+      console.error('Context menu error:', error);
+      this.showErrorNotification(error.message);
+    }
+  }
+
+  async triggerSave(tab, data) {
+    // Send message to content script to initiate save
+    try {
+      const response = await chrome.tabs.sendMessage(tab.id, {
+        action: 'triggerSave',
+        data: data
+      });
+
+      if (response && response.success) {
+        this.showSuccessNotification('Content saved to Airtable!');
+      } else {
+        throw new Error(response?.error || 'Failed to save content');
+      }
+    } catch (error) {
+      console.error('Save trigger error:', error);
+      // Fallback: open popup if content script isn't available
+      chrome.action.openPopup();
+    }
+  }
+
+  async handleMessage(message, sender, sendResponse) {
+    try {
+      switch (message.action) {
+        case 'saveToAirtable':
+          const result = await this.saveToAirtable(message.data);
+          sendResponse({ success: true, result });
+          break;
+
+        case 'getSettings':
+          const settings = await this.getSettings();
+          sendResponse({ success: true, settings });
+          break;
+
+        case 'saveSettings':
+          await this.saveSettings(message.settings);
+          sendResponse({ success: true });
+          break;
+
+        case 'showNotification':
+          this.showNotification(message.title, message.message, message.type);
+          sendResponse({ success: true });
+          break;
+
+        case 'openSidePanel':
+          if (sender.tab) {
+            chrome.sidePanel.open({ tabId: sender.tab.id });
+          }
+          sendResponse({ success: true });
+          break;
+
+        default:
+          sendResponse({ success: false, error: 'Unknown action' });
+      }
+    } catch (error) {
+      console.error('Message handler error:', error);
+      sendResponse({ success: false, error: error.message });
+    }
+  }
+
+  async saveToAirtable(data) {
+    // Get user settings
+    const settings = await this.getSettings();
+    
+    if (!settings.airtableToken || !settings.baseId) {
+      throw new Error('Airtable credentials not configured');
+    }
+
+    // Import Airtable client
+    const { AirtableClient } = await import('./lib/airtable-client.js');
+    const client = new AirtableClient(settings.airtableToken, settings.baseId);
+
+    // Process and save data
+    const processedData = await this.processData(data, settings);
+    const result = await client.createRecord(processedData.table, processedData.fields);
+
+    // Update usage stats
+    await this.updateUsageStats();
+
+    return result;
+  }
+
+  async processData(data, settings) {
+    // Smart data processing based on content type
+    if (data.type === 'linkedin') {
+      return {
+        table: settings.linkedinTable || 'Contacts',
+        fields: this.processLinkedInData(data)
+      };
+    } else if (data.type === 'selection') {
+      return {
+        table: settings.defaultTable || 'Clips',
+        fields: {
+          'Content': data.text,
+          'Source URL': data.url,
+          'Date Saved': new Date().toISOString(),
+          'Type': 'Text Selection'
+        }
+      };
+    } else {
+      return {
+        table: settings.defaultTable || 'Clips',
+        fields: {
+          'Title': data.title || 'Untitled',
+          'URL': data.url,
+          'Content': data.content,
+          'Date Saved': new Date().toISOString(),
+          'Type': 'Web Page'
+        }
+      };
+    }
+  }
+
+  processLinkedInData(data) {
+    return {
+      'Name': data.name || '',
+      'Title': data.title || '',
+      'Company': data.company || '',
+      'Location': data.location || '',
+      'LinkedIn URL': data.url || '',
+      'Date Added': new Date().toISOString(),
+      'Source': 'LinkedIn',
+      'Notes': data.about ? data.about.substring(0, 500) + '...' : ''
+    };
+  }
+
+  async getSettings() {
+    const result = await chrome.storage.sync.get([
+      'airtableToken',
+      'baseId',
+      'linkedinTable',
+      'defaultTable',
+      'autoSave',
+      'notifications'
+    ]);
+
+    return {
+      airtableToken: result.airtableToken || '',
+      baseId: result.baseId || '',
+      linkedinTable: result.linkedinTable || 'Contacts',
+      defaultTable: result.defaultTable || 'Clips',
+      autoSave: result.autoSave || false,
+      notifications: result.notifications !== false // Default to true
+    };
+  }
+
+  async saveSettings(settings) {
+    await chrome.storage.sync.set(settings);
+  }
+
+  async updateUsageStats() {
+    const stats = await chrome.storage.local.get(['usageStats']);
+    const currentStats = stats.usageStats || {
+      totalClips: 0,
+      weeklyClips: 0,
+      lastResetDate: new Date().toDateString()
+    };
+
+    // Reset weekly counter if it's a new week
+    const today = new Date().toDateString();
+    if (currentStats.lastResetDate !== today) {
+      const lastReset = new Date(currentStats.lastResetDate);
+      const daysSinceReset = Math.floor((Date.now() - lastReset.getTime()) / (1000 * 60 * 60 * 24));
+      
+      if (daysSinceReset >= 7) {
+        currentStats.weeklyClips = 0;
+        currentStats.lastResetDate = today;
+      }
+    }
+
+    currentStats.totalClips++;
+    currentStats.weeklyClips++;
+
+    await chrome.storage.local.set({ usageStats: currentStats });
+  }
+
+  setupNotifications() {
+    // Check if notifications are supported
+    if ('notifications' in chrome) {
+      // Request notification permission if needed
+      chrome.notifications.getPermissionLevel((level) => {
+        if (level !== 'granted') {
+          console.log('Notification permission not granted');
+        }
+      });
+    }
+  }
+
+  showSuccessNotification(message) {
+    this.showNotification('Success!', message, 'success');
+  }
+
+  showErrorNotification(message) {
+    this.showNotification('Error', message, 'error');
+  }
+
+  async showNotification(title, message, type = 'basic') {
+    const settings = await this.getSettings();
+    if (!settings.notifications) return;
+
+    const iconUrl = type === 'error' ? 'icons/icon-error-48.png' : 'icons/icon-48.png';
+
+    chrome.notifications.create({
+      type: 'basic',
+      iconUrl: iconUrl,
+      title: title,
+      message: message
+    });
+  }
+
+  async handleActionClick(tab) {
+    // Check if this is a LinkedIn profile page
+    if (tab.url.includes('linkedin.com/in/')) {
+      // Try to extract LinkedIn data automatically
+      try {
+        await this.triggerSave(tab, { type: 'linkedin' });
+      } catch (error) {
+        // Fallback to opening popup
+        chrome.action.openPopup();
+      }
+    } else {
+      // Open popup for general pages
+      chrome.action.openPopup();
+    }
+  }
+
+  async cleanupStorage() {
+    // Clean up old temporary data
+    const result = await chrome.storage.local.get(null);
+    const keysToRemove = [];
+
+    for (const [key, value] of Object.entries(result)) {
+      // Remove temporary data older than 24 hours
+      if (key.startsWith('temp_') && value.timestamp) {
+        const age = Date.now() - value.timestamp;
+        if (age > 24 * 60 * 60 * 1000) { // 24 hours
+          keysToRemove.push(key);
+        }
+      }
+    }
+
+    if (keysToRemove.length > 0) {
+      await chrome.storage.local.remove(keysToRemove);
+      console.log(`Cleaned up ${keysToRemove.length} temporary items`);
+    }
+  }
+}
+
+// Initialize the background service
+new BackgroundService();