@rashidazarang/airtable-mcp 1.2.0

package/examples/claude_config.json

@@ -0,0 +1,4 @@
+{
+  "airtable_token": "YOUR_AIRTABLE_TOKEN",
+  "base_id": "YOUR_BASE_ID"
+} 

package/examples/env-demo.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * Demo script that uses the AIRTABLE_BASE_ID from the .env file
+ * Demonstrates various operations with the Airtable API
+ */
+
+require('dotenv').config();
+const baseUtils = require('../tools/airtable-base');
+const crudUtils = require('../tools/airtable-crud');
+const schemaUtils = require('../tools/airtable-schema');
+
+// Constants
+const DEMO_TABLE_NAME = 'ENV Demo Table';
+const SAMPLE_RECORDS = [
+  { Name: 'Record from ENV Demo', Description: 'Created using AIRTABLE_BASE_ID from .env file', Status: 'Active' },
+  { Name: 'Another ENV Record', Description: 'Second record from the environment demo', Status: 'Pending' }
+];
+
+async function runDemo() {
+  console.log('=================================');
+  console.log('     AIRTABLE ENV DEMO SCRIPT    ');
+  console.log('=================================');
+  
+  // Check environment variables
+  if (!process.env.AIRTABLE_PERSONAL_ACCESS_TOKEN) {
+    console.error('❌ Error: AIRTABLE_PERSONAL_ACCESS_TOKEN is not set in .env file');
+    process.exit(1);
+  }
+  
+  if (!process.env.AIRTABLE_BASE_ID) {
+    console.error('❌ Error: AIRTABLE_BASE_ID is not set in .env file');
+    process.exit(1);
+  }
+  
+  const baseId = process.env.AIRTABLE_BASE_ID;
+  console.log(`✅ Using AIRTABLE_BASE_ID: ${baseId}`);
+  
+  try {
+    // Step 1: Verify base access
+    console.log('\nStep 1: Verifying access to the base...');
+    const baseAccess = await baseUtils.checkBaseAccess(baseId);
+    
+    if (!baseAccess.accessible) {
+      console.error(`❌ Error: Cannot access base with ID ${baseId}`);
+      console.error(`   Reason: ${baseAccess.error}`);
+      process.exit(1);
+    }
+    
+    console.log(`✅ Access confirmed to base: ${baseAccess.name}`);
+    
+    // Step 2: List existing tables
+    console.log('\nStep 2: Listing existing tables...');
+    const tables = await baseUtils.listTables(baseId);
+    console.log(`✅ Found ${tables.length} tables in the base`);
+    
+    // Step 3: Check if our demo table exists
+    console.log('\nStep 3: Checking if demo table exists...');
+    const demoTableExists = await crudUtils.tableExists(baseId, DEMO_TABLE_NAME);
+    
+    if (demoTableExists) {
+      console.log(`✅ Demo table "${DEMO_TABLE_NAME}" already exists`);
+    } else {
+      console.log(`ℹ️ Demo table "${DEMO_TABLE_NAME}" does not exist, creating it...`);
+      
+      // Step 4: Create the demo table
+      console.log('\nStep 4: Creating the demo table...');
+      const tableConfig = {
+        name: DEMO_TABLE_NAME,
+        description: 'Table created from the Environment Demo script',
+        fields: [
+          {
+            name: 'Name',
+            type: 'singleLineText',
+            description: 'Record name'
+          },
+          {
+            name: 'Description',
+            type: 'multilineText',
+            description: 'Record description'
+          },
+          {
+            name: 'Status',
+            type: 'singleSelect',
+            options: {
+              choices: [
+                { name: 'Active' },
+                { name: 'Pending' },
+                { name: 'Completed' }
+              ]
+            },
+            description: 'Current status'
+          },
+          {
+            name: 'Created',
+            type: 'date',
+            options: {
+              dateFormat: {
+                name: 'local'
+              }
+            },
+            description: 'Creation date'
+          }
+        ]
+      };
+      
+      await schemaUtils.createTable(baseId, tableConfig);
+      console.log(`✅ Created demo table: ${DEMO_TABLE_NAME}`);
+    }
+    
+    // Step 5: Create sample records
+    console.log('\nStep 5: Creating sample records...');
+    // Add today's date to all records
+    const recordsWithDate = SAMPLE_RECORDS.map(record => ({
+      ...record,
+      Created: new Date().toISOString().split('T')[0] // Format as YYYY-MM-DD
+    }));
+    
+    const createdRecords = await crudUtils.createRecords(baseId, DEMO_TABLE_NAME, recordsWithDate);
+    console.log(`✅ Created ${createdRecords.length} sample records`);
+    
+    // Step 6: Read records back
+    console.log('\nStep 6: Reading records from the table...');
+    const records = await crudUtils.readRecords(baseId, DEMO_TABLE_NAME, 100);
+    console.log(`✅ Read ${records.length} records from the table`);
+    
+    console.log('\nSample record:');
+    console.log(JSON.stringify(records[0], null, 2));
+    
+    // Step 7: Update a record
+    console.log('\nStep 7: Updating the first record...');
+    const recordToUpdate = {
+      id: createdRecords[0].id,
+      fields: {
+        Description: createdRecords[0].Description + ' (UPDATED)',
+        Status: 'Completed'
+      }
+    };
+    
+    const updatedRecords = await crudUtils.updateRecords(baseId, DEMO_TABLE_NAME, [recordToUpdate]);
+    console.log(`✅ Updated ${updatedRecords.length} record`);
+    
+    // Step 8: Get the updated record
+    console.log('\nStep 8: Getting the updated record...');
+    const updatedRecord = await crudUtils.getRecord(baseId, DEMO_TABLE_NAME, createdRecords[0].id);
+    console.log('Updated record:');
+    console.log(JSON.stringify(updatedRecord, null, 2));
+    
+    // Step 9: Demonstrate filtering records
+    console.log('\nStep 9: Filtering records by status...');
+    const completedRecords = await crudUtils.readRecords(baseId, DEMO_TABLE_NAME, 100, 'Status="Completed"');
+    console.log(`✅ Found ${completedRecords.length} records with Status="Completed"`);
+    
+    console.log('\n=================================');
+    console.log('      ENV DEMO COMPLETED         ');
+    console.log('=================================');
+    console.log('\nThis script demonstrated:');
+    console.log('1. Loading environment variables from .env file');
+    console.log('2. Accessing an Airtable base using AIRTABLE_BASE_ID');
+    console.log('3. Creating a table (if it doesn\'t exist)');
+    console.log('4. Creating, reading, and updating records');
+    console.log('5. Filtering records using Airtable formulas');
+    console.log('\nAll operations used the AIRTABLE_BASE_ID environment variable');
+    
+  } catch (error) {
+    console.error(`❌ Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Run the demo
+runDemo(); 

package/examples/example-tasks-update.json

@@ -0,0 +1,23 @@
+[
+  {
+    "id": "rec1qeTzIUy1p8DF5",
+    "fields": {
+      "Status": "Completed",
+      "Description": "Implement the new feature requested by the client (UPDATED)"
+    }
+  },
+  {
+    "id": "recA443jGkhk4fe8B",
+    "fields": {
+      "Status": "Completed",
+      "Priority": "High"
+    }
+  },
+  {
+    "id": "recvMTGZYKi8Dcds4",
+    "fields": {
+      "Status": "In Progress",
+      "Description": "Write comprehensive documentation for the project (IN PROGRESS)"
+    }
+  }
+] 

package/examples/example-tasks.json

@@ -0,0 +1,26 @@
+[
+  {
+    "id": "rec1qeTzIUy1p8DF5",
+    "Name": "Add new feature",
+    "Description": "Implement the new feature requested by the client",
+    "Status": "In Progress",
+    "Priority": "Medium",
+    "DueDate": "2024-01-15"
+  },
+  {
+    "id": "recA443jGkhk4fe8B",
+    "Name": "Fix login bug",
+    "Description": "Users are experiencing issues with the login process",
+    "Status": "In Progress",
+    "Priority": "Critical",
+    "DueDate": "2023-11-15"
+  },
+  {
+    "id": "recvMTGZYKi8Dcds4",
+    "Name": "Complete project documentation",
+    "Description": "Write comprehensive documentation for the project",
+    "Status": "In Progress",
+    "Priority": "High",
+    "DueDate": "2023-12-31"
+  }
+]

package/examples/example_usage.md

@@ -0,0 +1,124 @@
+# Airtable MCP Example Usage
+
+This document provides examples of how to use the Airtable MCP tools within a compatible MCP client like Cursor.
+
+## Base Management
+
+### List all available bases
+
+```
+Using the Airtable MCP, please list all the bases I have access to.
+```
+
+### Set the active base
+
+```
+Set the active Airtable base to "Project Management" (or use the base ID directly).
+```
+
+## Table Operations
+
+### List all tables in the current base
+
+```
+Show me all the tables in my current Airtable base.
+```
+
+### View table structure
+
+```
+Show me the structure of the "Tasks" table, including all fields and their types.
+```
+
+## Record Operations
+
+### List records
+
+```
+Show me the first 10 records from the "Clients" table.
+```
+
+### Filter records
+
+```
+Find all "Tasks" with a status of "In Progress" and due date before today.
+```
+
+### Get a specific record
+
+```
+Get the record with ID "rec123456" from the "Projects" table.
+```
+
+### Create a new record
+
+```
+Create a new record in the "Tasks" table with the following information:
+- Title: "Complete project documentation"
+- Status: "Not Started"
+- Due Date: "2024-12-31"
+- Assigned To: "John Smith"
+```
+
+### Update an existing record
+
+```
+Update the task with ID "rec123456" in the "Tasks" table:
+- Change status to "In Progress"
+- Update due date to "2024-11-30"
+```
+
+### Delete a record
+
+```
+Delete the record with ID "rec123456" from the "Tasks" table.
+```
+
+## Schema Management
+
+### Export the schema
+
+```
+Export the schema of my current Airtable base in JSON format.
+```
+
+### Compare schemas
+
+```
+Compare this schema with my current base schema to identify any differences.
+```
+
+## Data Migration
+
+### Generate field mapping
+
+```
+Generate a field mapping between the "Clients" and "Customers" tables.
+```
+
+### Migrate data
+
+```
+Migrate data from the "Clients" table to the "Customers" table using the generated mapping.
+```
+
+## Tips for Better Results
+
+1. **Be specific** when referencing table and field names
+2. **Use record IDs** when updating or deleting specific records
+3. **Use natural language** to describe the operations you want to perform
+4. **Check your base ID** is correctly set if you get unexpected results
+5. **Format JSON data** properly when creating or updating records
+
+## Combining Operations
+
+You can combine multiple operations in a single request:
+
+```
+Please help me organize my project data:
+1. First, show me all the tables in my base
+2. Then, list the overdue tasks (status is not "Complete" and due date is before today)
+3. Finally, update those tasks to have a status of "Urgent"
+```
+
+The Airtable MCP can help with complex workflows by understanding your intentions and executing the appropriate sequence of operations. 

package/examples/sample-transform.js

@@ -0,0 +1,76 @@
+/**
+ * Sample transform function for syncing data between tables
+ * 
+ * This module demonstrates how to transform records when syncing
+ * between two tables with different schemas.
+ * 
+ * To use with the airtable-crud.js sync command:
+ * node airtable-crud.js sync "Source Table" "Target Table" sample-transform.js
+ */
+
+/**
+ * Transform function that converts records from source table format to target table format
+ * @param {Object} sourceRecord - Record from the source table
+ * @returns {Object} - Transformed record for the target table
+ */
+function transform(sourceRecord) {
+  // Example: Converting a customer record to a simplified format
+  
+  // Extract the needed fields
+  const { id, Name, Email, Phone, "Company Name": Company, "Date Added": DateAdded, Status } = sourceRecord;
+  
+  // Create the transformed record
+  const transformedRecord = {
+    // You can optionally include the source record ID
+    // This is useful for updating existing records in sync operations
+    // "Source Record ID": id,
+    
+    // Map fields from source to target
+    CustomerName: Name,
+    CustomerEmail: Email,
+    CustomerPhone: Phone || '',
+    Organization: Company || 'Individual',
+    
+    // Transform dates
+    JoinDate: DateAdded,
+    
+    // Add calculated fields
+    CustomerCategory: Company ? 'Business' : 'Individual',
+    
+    // Transform status to a different format
+    IsActive: Status === 'Active',
+    
+    // Add constant values
+    DataSource: 'Customer Table Sync',
+    LastSyncedAt: new Date().toISOString()
+  };
+  
+  return transformedRecord;
+}
+
+// You can define other utility functions here
+
+/**
+ * Helper function to clean and format phone numbers
+ * @param {string} phone - Raw phone number
+ * @returns {string} - Formatted phone number
+ */
+function formatPhoneNumber(phone) {
+  if (!phone) return '';
+  
+  // Remove non-numeric characters
+  const cleaned = ('' + phone).replace(/\D/g, '');
+  
+  // Format as (XXX) XXX-XXXX
+  const match = cleaned.match(/^(\d{3})(\d{3})(\d{4})$/);
+  if (match) {
+    return '(' + match[1] + ') ' + match[2] + '-' + match[3];
+  }
+  
+  return phone;
+}
+
+// Export the transform function
+module.exports = {
+  transform
+}; 

package/examples/windsurf_mcp_config.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "AIRTABLE": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@smithery/cli@latest",
+        "run",
+        "@rashidazarang/airtable-mcp",
+        "--token",
+        "YOUR_AIRTABLE_TOKEN",
+        "--base",
+        "YOUR_BASE_ID"
+      ]
+    }
+  }
+} 

package/index.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execSync } = require('child_process');
+const { spawn } = require('child_process');
+
+// Polyfill for AbortController in older Node.js versions
+if (typeof globalThis.AbortController === 'undefined') {
+  globalThis.AbortController = class AbortController {
+    constructor() {
+      this.signal = {
+        aborted: false,
+        addEventListener: () => {},
+        removeEventListener: () => {},
+        dispatchEvent: () => true
+      };
+    }
+    abort() {
+      this.signal.aborted = true;
+    }
+  };
+  console.log('ℹ️ Added AbortController polyfill for compatibility with older Node.js versions');
+}
+
+// Parse command-line arguments
+const args = process.argv.slice(2);
+let tokenIndex = args.indexOf('--token');
+let baseIndex = args.indexOf('--base');
+let configIndex = args.indexOf('--config');
+
+// Extract token, base ID and config
+const token = tokenIndex !== -1 && tokenIndex + 1 < args.length ? args[tokenIndex + 1] : null;
+const baseId = baseIndex !== -1 && baseIndex + 1 < args.length ? args[baseIndex + 1] : null;
+const config = configIndex !== -1 && configIndex + 1 < args.length ? args[configIndex + 1] : null;
+
+console.log('🔌 Airtable MCP - Connecting your AI to Airtable');
+console.log('-----------------------------------------------');
+
+// Find Python interpreter
+const getPythonPath = () => {
+  try {
+    const whichPython = execSync('which python3.10').toString().trim();
+    return whichPython;
+  } catch (e) {
+    try {
+      const whichPython = execSync('which python3').toString().trim();
+      return whichPython;
+    } catch (e) {
+      return 'python';
+    }
+  }
+};
+
+// Check Python version
+const checkPythonVersion = (pythonPath) => {
+  try {
+    const versionStr = execSync(`${pythonPath} --version`).toString().trim();
+    const versionMatch = versionStr.match(/Python (\d+)\.(\d+)/);
+    if (versionMatch) {
+      const major = parseInt(versionMatch[1]);
+      const minor = parseInt(versionMatch[2]);
+      return (major > 3 || (major === 3 && minor >= 10));
+    }
+    return false;
+  } catch (e) {
+    return false;
+  }
+};
+
+const pythonPath = getPythonPath();
+
+// Verify Python compatibility
+if (!checkPythonVersion(pythonPath)) {
+  console.error('❌ Error: MCP SDK requires Python 3.10+');
+  console.error('Please install Python 3.10 or newer and try again.');
+  process.exit(1);
+}
+
+// We now use inspector_server.py instead of server.py
+const serverScript = path.join(__dirname, 'inspector_server.py');
+
+// Check if the script exists
+try {
+  require('fs').accessSync(serverScript, require('fs').constants.F_OK);
+} catch (e) {
+  console.error(`❌ Error: Could not find server script at ${serverScript}`);
+  console.error('Please make sure you have the complete package installed.');
+  process.exit(1);
+}
+
+// Prepare arguments for the Python script
+const scriptArgs = [serverScript];
+if (token) {
+  scriptArgs.push('--token', token);
+}
+if (baseId) {
+  scriptArgs.push('--base', baseId);
+}
+if (config) {
+  scriptArgs.push('--config', config);
+  
+  // Try to extract and log info from config
+  try {
+    const configObj = JSON.parse(config);
+    if (configObj.airtable_token) {
+      console.log('✅ Using API token from config');
+    }
+    if (configObj.base_id) {
+      console.log(`✅ Using base ID from config: ${configObj.base_id}`);
+    }
+  } catch (e) {
+    console.warn('⚠️ Could not parse config JSON, attempting to sanitize...');
+    
+    // Sanitize config JSON - fix common formatting issues
+    try {
+      // Remove any unexpected line breaks, extra quotes, and escape characters
+      const sanitizedConfig = config
+        .replace(/[\r\n]+/g, '')
+        .replace(/\\+"/g, '"')
+        .replace(/^"/, '')
+        .replace(/"$/, '')
+        .replace(/\\/g, '');
+      
+      // Try parsing it
+      const configObj = JSON.parse(sanitizedConfig);
+      if (configObj) {
+        console.log('✅ Successfully sanitized config JSON');
+        // Update config with sanitized version
+        scriptArgs[scriptArgs.indexOf(config)] = sanitizedConfig;
+        config = sanitizedConfig;
+        
+        if (configObj.airtable_token) {
+          console.log('✅ Using API token from sanitized config');
+        }
+        if (configObj.base_id) {
+          console.log(`✅ Using base ID from sanitized config: ${configObj.base_id}`);
+        }
+      }
+    } catch (sanitizeErr) {
+      console.warn('⚠️ Could not sanitize config JSON, passing it directly to Python script');
+    }
+  }
+} else {
+  if (token) {
+    console.log('✅ Using provided API token');
+  } else {
+    console.log('⚠️ No API token provided, will try to use .env file');
+  }
+
+  if (baseId) {
+    console.log(`✅ Using base ID: ${baseId}`);
+  } else {
+    console.log('ℹ️ No base ID provided, will need to set one later');
+  }
+}
+
+// Execute the Python script
+const serverProcess = spawn(pythonPath, scriptArgs, {
+  stdio: 'inherit',
+});
+
+// Handle process exit
+serverProcess.on('close', (code) => {
+  if (code !== 0) {
+    console.error(`❌ Airtable MCP server exited with code ${code}`);
+  }
+  process.exit(code);
+});
+
+// Handle signals
+process.on('SIGINT', () => {
+  console.log('\n👋 Shutting down Airtable MCP server...');
+  serverProcess.kill('SIGINT');
+});
+
+process.on('SIGTERM', () => {
+  console.log('\n👋 Shutting down Airtable MCP server...');
+  serverProcess.kill('SIGTERM');
+});