Fix compatibility issues with Claude and Windsurf. Add AbortController polyfill and improve JSON parsing.

Author: rashidazarang

CLAUDE_INTEGRATION.md

@@ -1,114 +1,109 @@
-# Using Airtable MCP with Claude
+# Claude/Windsurf Integration Guide
 
-This guide explains how to integrate the Airtable MCP with various Claude MCP clients.
+This guide explains how to set up the Airtable MCP for use with Claude (including Anthropic's tools and in VSCode extensions like Windsurf).
 
-## Compatible Claude MCP Clients
+## Setup for Claude
 
-This MCP works with any client that supports Anthropic's Model Context Protocol (MCP), including:
+### Requirements
 
-- [Claude Desktop](https://claude.ai/desktop)
-- [Cursor](https://cursor.sh/)
-- [Cline](https://github.com/lpw/cline)
-- [Zed](https://zed.dev/)
-- Any other MCP-compatible client
+- Node.js v14 or higher
+- An Airtable account with Personal Access Token
+- An Airtable base you want to connect to
 
-## Recommended: Using Smithery (Easiest Method)
+### Configuration
 
-The recommended way to use this MCP is through Smithery, which handles all dependencies and configuration automatically:
+Claude requires the configuration to be specified in JSON format. Here's how to set up the configuration for Claude:
 
-1. **Configure your MCP client**:
-   - Edit your client's MCP configuration file (e.g., `~/.cursor/mcp.json`)
-   - Add the following configuration:
+1. In Claude settings, add a new MCP server with these settings:
+   - Name: `airtable-mcp`
+   - Command: `npx`
+   - Arguments:
+     ```
+     -y @smithery/cli@latest run @rashidazarang/airtable-mcp --config {"airtable_token":"your_token_here","base_id":"your_base_id_here"}
+     ```
 
+2. **IMPORTANT: JSON Format**  
+   Make sure the JSON in the `--config` parameter is properly formatted:
+   - No line breaks
+   - No extra backslashes
+   - No surrounding quotes
+
+### Troubleshooting JSON Issues
+
+If you encounter the error `Unexpected token 'F', "Found & ig"... is not valid JSON`, try these fixes:
+
+1. **Method 1: Simplify JSON** - Remove any complex characters from your token and try again.
+
+2. **Method 2: Escape Properly** - Make sure you format the command with proper escaping:
+   ```
+   -y @smithery/cli@latest run @rashidazarang/airtable-mcp --config {\"airtable_token\":\"your_token_here\",\"base_id\":\"your_base_id_here\"}
+   ```
+
+3. **Method 3: Use Separate Parameters** - Instead of using --config, use individual parameters:
+   ```
+   -y @smithery/cli@latest run @rashidazarang/airtable-mcp --token your_token_here --base your_base_id_here
+   ```
+
+## Setup for Windsurf
+
+Windsurf users should use a dedicated config file to avoid JSON parsing issues:
+
+1. Create a file called `mcp_config.json` with:
    ```json
    {
      "mcpServers": {
-       "airtable-mcp": {
+       "AIRTABLE": {
          "command": "npx",
          "args": [
            "-y",
            "@smithery/cli@latest",
            "run",
            "@rashidazarang/airtable-mcp",
-           "--config",
-           "{\"airtable_token\":\"YOUR_AIRTABLE_TOKEN\\\"\",\"base_id\":\"YOUR_BASE_ID\"}"
+           "--token",
+           "your_token_here",
+           "--base",
+           "your_base_id_here"
          ]
        }
      }
    }
    ```
 
-2. **Replace tokens**:
-   - Replace `YOUR_AIRTABLE_TOKEN\"` with your Airtable Personal Access Token (maintaining the backslash and quote)
-   - Replace `YOUR_BASE_ID` with your Airtable base ID
+2. In Windsurf settings, configure it to use this file.
 
-3. **Restart your client** to load the new tools
+## Common Issues
 
-## Setting Up with Claude Desktop
+### AbortController Error
 
-1. **Install the Airtable MCP**:
-   ```bash
-   npm install -g airtable-mcp
-   ```
-
-2. **Start the MCP server**:
-   ```bash
-   airtable-mcp --token "your_airtable_token" --base "your_base_id"
-   ```
-
-3. **Configure Claude Desktop**:
-   - Open Claude Desktop
-   - Go to Settings > Tools > Add Tool
-   - For the tool URL, use: `http://localhost:8010/mcp` (default port)
-   - Click "Add Tool"
-   - You'll now see the Airtable tools in Claude's tool palette
-
-## Setting Up with Cursor
-
-1. **Edit your Cursor MCP configuration**:
-   - Open or create the file: `~/.cursor/mcp.json`
-   - Add the Smithery configuration as described in the "Recommended" section above
-
-2. **Restart Cursor** to load the new tools
-
-## Setting Up with Cline
-
-1. **Start the MCP server**:
-   ```bash
-   npx airtable-mcp --token "your_airtable_token" --base "your_base_id"
-   ```
-
-2. **Run Cline with MCP support**:
-   ```bash
-   cline --mcp-urls http://localhost:8010/mcp
-   ```
+If you see an error like `ReferenceError: AbortController is not defined`, this is because you're using an older version of Node.js that doesn't include this feature. Options to fix:
 
-## Using the MCP in Claude
+1. **Update Node.js** (recommended) - Install Node.js v15+ which includes AbortController natively.
 
-Once configured, you can use natural language to work with Airtable data. Here are some examples:
+2. **Use Polyfill** - New versions of our MCP (1.1.0+) automatically add a polyfill for older Node versions.
 
-- "Can you list all the tables in our Airtable base?"
-- "Get all records from the Projects table where Status is Complete"
-- "Create a new record in the Contacts table with name John Smith and email [email protected]"
-- "Update the Budget field for the Marketing project to $15,000"
+### Server Disconnected or Timeout Errors
 
-## Testing Your Setup
+1. Check that your Airtable token is valid and has the necessary permissions
+2. Ensure you have proper internet connectivity
+3. Try restarting the MCP server
+4. Check the logs for any specific error messages
 
-To confirm your MCP setup is working correctly:
+## Using the MCP with Claude
 
-1. Restart your MCP client after making configuration changes
-2. Start a conversation with Claude
-3. Ask a simple question like "Can you list all the tables in my Airtable base?"
-4. Claude should respond with a list of tables from your Airtable base
+Once connected, you can use the following tools:
 
-If you see tables listed, congratulations! Your Airtable MCP is working correctly.
+- `list_bases` - Show available Airtable bases
+- `list_tables` - List tables in the current base
+- `list_records` - Get records from a specific table
+- `create_records` - Add new records to a table
+- `update_records` - Modify existing records
 
-## Troubleshooting
+For example, in Claude, you might ask:
+"Please list all tables in my Airtable base and then show me records from the 'Contacts' table."
 
-- **Tool not appearing**: Make sure the MCP server is running and the client is properly configured
-- **Authentication errors**: Verify your Airtable token has the necessary permissions
-- **Connection issues**: Confirm the MCP server is running on the expected port (default is 8010)
-- **JSON escaping issues**: Make sure the backslash characters in the configuration are preserved
-- **Smithery not found**: Try installing the Smithery CLI globally with `npm install -g @smithery/cli`
+## Support
 
-For more detailed troubleshooting, check the server logs where you started the Airtable MCP. 
+If you continue to experience issues, please report them on GitHub with:
+- Error messages
+- Node.js version (`node -v`)
+- Operating system details 

README.md

@@ -51,17 +51,44 @@ This MCP has been updated to work with the latest MCP SDK version. The new imple
 - Airtable API token
 - A compatible MCP client (Cursor, Claude Desktop, etc.)
 
-### Smithery Installation (Recommended)
+### Recommended: Using Smithery via NPX (Easiest Method)
 
-The easiest way to install:
+The simplest way to use this MCP is through Smithery via NPX. This handles all dependencies and configuration automatically.
+
+1. Configure your MCP client by adding the following to your MCP configuration file (e.g., `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "airtable-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@smithery/cli@latest",
+        "run",
+        "@rashidazarang/airtable-mcp",
+        "--config",
+        "{\"airtable_token\":\"YOUR_AIRTABLE_TOKEN\\\"\",\"base_id\":\"YOUR_BASE_ID\"}"
+      ]
+    }
+  }
+}
+```
+
+2. Replace `YOUR_AIRTABLE_TOKEN\"` with your Airtable API token (maintaining the backslash and quote), and `YOUR_BASE_ID` with your Airtable base ID.
+3. Restart your MCP client to load the new tools.
+
+### Smithery Web Installation (Alternative)
+
+Another easy installation method:
 
 1. Visit [Smithery](https://smithery.ai)
 2. Search for "@rashidazarang/airtable-mcp"
 3. Click "Install" and follow the prompts
 
-### Quick Setup with NPX (Alternative)
+### Traditional NPX Installation (Advanced)
 
-Another fast way to get started:
+If you prefer a more traditional approach:
 
 ```bash
 # Install globally
@@ -147,4 +174,36 @@ MIT
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Using with Claude and Windsurf
+
+### Version 1.2.0 Update: Improved Compatibility
+
+The latest version includes important fixes to address common issues:
+
+1. **AbortController Compatibility**: Added polyfill for Node.js versions < 15.0.0
+2. **JSON Parsing Improvements**: Enhanced handling of malformed JSON configurations
+3. **Windsurf Support**: Special configuration templates for Windsurf users
+
+### Common Issues and Solutions
+
+#### JSON Format Errors
+
+If you see errors like `Unexpected token 'F', "Found & ig"... is not valid JSON`, try:
+
+1. **Use Individual Parameters**:
+   ```
+   npx -y @smithery/cli@latest run @rashidazarang/airtable-mcp --token YOUR_TOKEN --base YOUR_BASE_ID
+   ```
+
+2. **For Windsurf Users**: Use the template in `examples/windsurf_mcp_config.json`
+
+#### AbortController Not Defined
+
+This typically happens on older Node.js versions. The current version includes an automatic polyfill, but you can also:
+
+1. **Update Node.js**: Install Node.js v15+ for native AbortController support
+2. **Update This Package**: Make sure you're using version 1.2.0 or higher
+
+See [CLAUDE_INTEGRATION.md](./CLAUDE_INTEGRATION.md) for detailed setup instructions.

examples/claude_config.json

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

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"
+      ]
+    }
+  }
+} 

index.js

@@ -4,6 +4,24 @@ 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');
@@ -91,7 +109,36 @@ if (config) {
       console.log(`✅ Using base ID from config: ${configObj.base_id}`);
     }
   } catch (e) {
-    console.warn('⚠️ Could not parse config JSON, passing it directly to Python script');
+    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) {

inspector_server.py

@@ -39,12 +39,31 @@ def parse_args():
     try:
         # Strip any trailing quotes or backslashes that might be present
         config_str = args.config_json.rstrip('\\"')
-        logger.info(f"Parsing config: {config_str}")
+        # Additional sanitization for JSON format
+        config_str = config_str.strip()
+        # Handle escaped quotes
+        if config_str.startswith('"') and config_str.endswith('"'):
+            config_str = config_str[1:-1]
+        # Fix escaped quotes within JSON
+        config_str = config_str.replace('\\"', '"')
+        # Replace escaped backslashes
+        config_str = config_str.replace('\\\\', '\\')
+        
+        logger.info(f"Parsing sanitized config: {config_str}")
         config = json.loads(config_str)
         logger.info(f"Successfully parsed config: {config}")
     except json.JSONDecodeError as e:
         logger.error(f"Failed to parse config JSON: {e}")
         logger.error(f"Raw config string: {args.config_json}")
+        # Try one more approach - sometimes config is double-quoted JSON
+        try:
+            # Try to interpret as Python string literal
+            import ast
+            literal_str = ast.literal_eval(f"'''{args.config_json}'''")
+            config = json.loads(literal_str)
+            logger.info(f"Successfully parsed config using ast: {config}")
+        except Exception as ast_error:
+            logger.error(f"Failed alternate parsing method: {ast_error}")
 
 # Create MCP server
 app = FastMCP("Airtable Tools")