@rashidazarang/airtable-mcp 1.6.0 → 2.1.1

package/IMPROVEMENT_PROPOSAL.md

@@ -1,371 +0,0 @@
-# Airtable MCP Improvement Proposal
-
-## Current State Analysis
-
-### Existing Tools (v1.2.4)
-1. **list_tables** - Lists all tables in a base
-2. **list_records** - Lists records from a specific table
-
-### Missing Core CRUD Operations
-The MCP currently only supports READ operations. We need full CRUD capabilities.
-
-## Proposed New Features
-
-### 🔥 Priority 1: Complete CRUD Operations
-
-#### 1. **create_record**
-Create new records in any table
-```javascript
-{
-  name: "create_record",
-  params: {
-    table: "string",
-    fields: "object"
-  }
-}
-```
-
-#### 2. **update_record**
-Update existing records
-```javascript
-{
-  name: "update_record",
-  params: {
-    table: "string",
-    recordId: "string",
-    fields: "object"
-  }
-}
-```
-
-#### 3. **delete_record**
-Delete records from tables
-```javascript
-{
-  name: "delete_record",
-  params: {
-    table: "string",
-    recordId: "string"
-  }
-}
-```
-
-#### 4. **batch_operations**
-Perform bulk create/update/delete (up to 10 records)
-```javascript
-{
-  name: "batch_operations",
-  params: {
-    table: "string",
-    operation: "create|update|delete",
-    records: "array"
-  }
-}
-```
-
-### 🚀 Priority 2: Advanced Query & Filter
-
-#### 5. **search_records**
-Search with complex filters and sorting
-```javascript
-{
-  name: "search_records",
-  params: {
-    table: "string",
-    filterByFormula: "string",  // Airtable formula syntax
-    sort: [{field: "string", direction: "asc|desc"}],
-    maxRecords: "number",
-    fields: ["string"]  // Specific fields to return
-  }
-}
-```
-
-#### 6. **get_record_by_id**
-Get a single record by its ID
-```javascript
-{
-  name: "get_record_by_id",
-  params: {
-    table: "string",
-    recordId: "string"
-  }
-}
-```
-
-### 📊 Priority 3: Schema Management
-
-#### 7. **get_table_schema**
-Get detailed field information for a table
-```javascript
-{
-  name: "get_table_schema",
-  params: {
-    table: "string"
-  }
-}
-```
-
-#### 8. **create_table**
-Create a new table in the base
-```javascript
-{
-  name: "create_table",
-  params: {
-    name: "string",
-    fields: [{name: "string", type: "string", options: "object"}]
-  }
-}
-```
-
-#### 9. **create_field**
-Add a new field to an existing table
-```javascript
-{
-  name: "create_field",
-  params: {
-    table: "string",
-    field: {name: "string", type: "string", options: "object"}
-  }
-}
-```
-
-### 🔄 Priority 4: Data Management
-
-#### 10. **export_table**
-Export entire table as JSON/CSV
-```javascript
-{
-  name: "export_table",
-  params: {
-    table: "string",
-    format: "json|csv"
-  }
-}
-```
-
-#### 11. **import_data**
-Import data from JSON/CSV
-```javascript
-{
-  name: "import_data",
-  params: {
-    table: "string",
-    data: "string|array",
-    format: "json|csv",
-    updateExisting: "boolean"
-  }
-}
-```
-
-#### 12. **duplicate_table**
-Clone a table with or without data
-```javascript
-{
-  name: "duplicate_table",
-  params: {
-    sourceTable: "string",
-    newName: "string",
-    includeData: "boolean"
-  }
-}
-```
-
-### 🔗 Priority 5: Relationships & Links
-
-#### 13. **link_records**
-Create links between records in linked fields
-```javascript
-{
-  name: "link_records",
-  params: {
-    sourceTable: "string",
-    sourceRecordId: "string",
-    linkField: "string",
-    targetRecordIds: ["string"]
-  }
-}
-```
-
-#### 14. **get_linked_records**
-Fetch all records linked from a specific record
-```javascript
-{
-  name: "get_linked_records",
-  params: {
-    table: "string",
-    recordId: "string",
-    linkField: "string"
-  }
-}
-```
-
-### 📈 Priority 6: Analytics & Aggregation
-
-#### 15. **aggregate_data**
-Perform aggregations on table data
-```javascript
-{
-  name: "aggregate_data",
-  params: {
-    table: "string",
-    aggregations: [{
-      field: "string",
-      function: "sum|avg|count|min|max"
-    }],
-    groupBy: ["string"]
-  }
-}
-```
-
-#### 16. **get_table_stats**
-Get statistics about a table
-```javascript
-{
-  name: "get_table_stats",
-  params: {
-    table: "string"
-  }
-  // Returns: record count, field types, storage size, etc.
-}
-```
-
-### 🔍 Priority 7: Views Management
-
-#### 17. **list_views**
-List all views in a table
-```javascript
-{
-  name: "list_views",
-  params: {
-    table: "string"
-  }
-}
-```
-
-#### 18. **get_view_records**
-Get records from a specific view
-```javascript
-{
-  name: "get_view_records",
-  params: {
-    table: "string",
-    view: "string"
-  }
-}
-```
-
-### 🎨 Priority 8: Attachments & Media
-
-#### 19. **upload_attachment**
-Upload files to attachment fields
-```javascript
-{
-  name: "upload_attachment",
-  params: {
-    table: "string",
-    recordId: "string",
-    field: "string",
-    fileUrl: "string|base64"
-  }
-}
-```
-
-#### 20. **get_attachments**
-Download attachments from records
-```javascript
-{
-  name: "get_attachments",
-  params: {
-    table: "string",
-    recordId: "string",
-    field: "string"
-  }
-}
-```
-
-## Implementation Roadmap
-
-### Phase 1 (Version 1.3.0) - Essential CRUD
-- ✅ create_record
-- ✅ update_record
-- ✅ delete_record
-- ✅ get_record_by_id
-- ✅ search_records
-
-### Phase 2 (Version 1.4.0) - Batch & Schema
-- batch_operations
-- get_table_schema
-- export_table
-- import_data
-
-### Phase 3 (Version 1.5.0) - Advanced Features
-- create_table
-- create_field
-- link_records
-- get_linked_records
-
-### Phase 4 (Version 2.0.0) - Enterprise Features
-- aggregate_data
-- Views management
-- Attachments handling
-- Webhooks support
-
-## Technical Considerations
-
-### Rate Limiting
-- Implement request queuing to respect 5 req/sec limit
-- Add retry logic with exponential backoff
-- Cache frequently accessed data
-
-### Error Handling
-- Detailed error messages for debugging
-- Graceful fallbacks for missing permissions
-- Validation of input parameters
-
-### Performance
-- Implement pagination for large datasets
-- Add optional field filtering to reduce payload
-- Support streaming for large exports
-
-### Security
-- Validate all input to prevent injection
-- Support field-level permissions
-- Add optional audit logging
-
-## Usage Examples
-
-### Creating a Record
-```
-"Create a new task in the Tasks table with title 'Review proposal' and status 'In Progress'"
-```
-
-### Complex Search
-```
-"Find all high-priority tasks assigned to John that are due this week"
-```
-
-### Bulk Operations
-```
-"Mark all tasks with status 'Done' as archived"
-```
-
-### Data Export
-```
-"Export the entire Customers table as a CSV file"
-```
-
-## Benefits
-
-1. **Complete Functionality**: Full CRUD operations matching Airtable's capabilities
-2. **Natural Language**: All operations accessible through conversational AI
-3. **Productivity**: Batch operations and data import/export save time
-4. **Flexibility**: Support for complex queries and relationships
-5. **Enterprise Ready**: Schema management and analytics features
-
-## Next Steps
-
-1. Prioritize features based on user needs
-2. Implement Phase 1 features (essential CRUD)
-3. Add comprehensive testing for each new tool
-4. Update documentation with examples
-5. Gather user feedback for Phase 2 planning

package/INSTALLATION.md

@@ -1,183 +0,0 @@
-# Installation
-
-Airtable MCP embeds Airtable database connectivity directly into your AI-powered code editor
-
-## Getting Started
-
-Built by Rashid Azarang,
-
-Airtable MCP gives AI code editors and agents the ability to access and manipulate your Airtable databases for powerful data management capabilities - all in a secure manner with your own API tokens.
-
-With this MCP server tool, you can enable AI code editors and agents to have access to:
-
-* List and access all your Airtable bases
-* Browse tables, fields, and record data
-* Create, read, update, and delete records
-* Export and manipulate schemas
-* Perform complex queries against your data
-* Create data migration mappings
-* Analyze and transform your Airtable data
-
-That way, you can simply tell Cursor or any AI code editor with MCP integrations:
-
-"Show me all the tables in my Airtable base"
-
-"Find all records from the Customers table where the status is Active and the last purchase was after January 1st"
-
-"Create a new record in the Products table with these fields..."
-
-"Export the schema of my current Airtable base"
-
-"Help me create a mapping between these two tables for data migration"
-
----
-
-## Requirements
-
-* Node.js 14+ installed on your machine
-* Python 3.10+ installed on your machine (automatically detected)
-* Airtable Personal Access Token (API Key)
-* MCP Client Application (Cursor, Claude Desktop, Cline, Zed, etc.)
-
-**Note**: Model Context Protocol (MCP) is specific to Anthropic models. When using an editor like Cursor, make sure to enable composer agent with Claude 3.5 Sonnet selected as the model.
-
----
-
-## Installation
-
-### 1. Install via Smithery (Easiest)
-
-The easiest way to install Airtable MCP is through Smithery:
-
-1. Visit [Smithery](https://smithery.ai)
-2. Search for "@rashidazarang/airtable-mcp"
-3. Click "Install" and follow the prompts to configure with your Airtable token and base ID
-
-### 2. Install via NPX (Alternative)
-
-Another simple way to install and use Airtable MCP is via NPX:
-
-```bash
-# Install globally
-npm install -g airtable-mcp
-
-# Or use directly with npx (no installation needed)
-npx airtable-mcp --token YOUR_AIRTABLE_TOKEN --base YOUR_BASE_ID
-```
-
-### 3. Get Your Airtable API Token
-
-1. Log in to your Airtable account
-2. Go to your [Account Settings](https://airtable.com/account)
-3. Navigate to the "API" section
-4. Create a Personal Access Token with appropriate permissions
-5. Copy your token to use in the configuration
-
-### 4. Configure Your MCP Client
-
-#### For Cursor:
-
-1. Go to Cursor Settings
-2. Navigate to Features, scroll down to MCP Servers and click "Add new MCP server"
-3. Give it a unique name (airtable-tools), set type to "command" and set the command to:
-
-**For macOS/Linux/Windows:**
-```bash
-npx airtable-mcp --token YOUR_AIRTABLE_TOKEN --base YOUR_BASE_ID
-```
-
-Replace `YOUR_AIRTABLE_TOKEN` with your Airtable Personal Access Token and `YOUR_BASE_ID` with your default Airtable base ID (optional).
-
-#### For Advanced Users via ~/.cursor/mcp.json:
-
-Edit your `~/.cursor/mcp.json` file to include:
-
-```json
-{
-  "mcpServers": {
-    "airtable-tools": {
-      "command": "npx",
-      "args": [
-        "airtable-mcp",
-        "--token", "YOUR_AIRTABLE_TOKEN",
-        "--base", "YOUR_BASE_ID"
-      ]
-    }
-  }
-}
-```
-
-### 5. Verify Connection
-
-1. Restart your MCP client (Cursor, etc.)
-2. Create a new query using the Composer Agent with Claude 3.5 Sonnet model
-3. Ask something like "List my Airtable bases" or "Show me the tables in my current base"
-4. You should see a response with your Airtable data
-
-### 6. For Production Use (Optional)
-
-For continuous availability, you can set up Airtable MCP using PM2:
-
-```bash
-# Install PM2 if you don't have it
-npm install -g pm2
-
-# Create a PM2 config file
-echo 'module.exports = {
-  apps: [
-    {
-      name: "airtable-mcp",
-      script: "npx",
-      args: [
-        "airtable-mcp",
-        "--token", "YOUR_AIRTABLE_TOKEN",
-        "--base", "YOUR_BASE_ID"
-      ],
-      env: {
-        PATH: process.env.PATH,
-      },
-    },
-  ],
-};' > ecosystem.config.js
-
-# Start the process
-pm2 start ecosystem.config.js
-
-# Set it to start on boot
-pm2 startup
-pm2 save
-```
-
----
-
-## Troubleshooting
-
-Here are some common issues and their solutions:
-
-### Error: Unable to connect to Airtable API
-
-- Double-check your Airtable API token is correct and has sufficient permissions
-- Verify your internet connection
-- Check if Airtable API is experiencing downtime
-
-### Issue: MCP server not connecting
-
-- Make sure Node.js 14+ and Python 3.10+ are installed and in your PATH
-- Try specifying a specific version: `npx airtable-mcp@latest`
-- Check the Cursor logs for any connection errors
-
-### Error: Base not found
-
-- Verify your base ID is correct
-- Make sure your API token has access to the specified base
-- Try listing all bases first to confirm access
-
-### Issue: Permission denied errors
-
-- Make sure your token has the necessary permissions for the operations you're trying to perform
-- Check if you're attempting operations on tables/bases that your token doesn't have access to
-
-### For more help
-
-- Open an issue on the [GitHub repository](https://github.com/rashidazarang/airtable-mcp/issues)
-- Check the Airtable API documentation for any API-specific errors 

package/ISSUE_RESPONSES.md

@@ -1,171 +0,0 @@
-# GitHub Issue Responses
-
-## Issue #7: Personal Access Token Leakage
-
-Thank you for responsibly disclosing this security vulnerability. This has been fixed in v1.2.4.
-
-### Actions Taken:
-✅ Removed all hardcoded tokens from test files
-✅ Updated code to require environment variables for credentials
-✅ Added SECURITY_NOTICE.md with rotation instructions
-✅ The exposed tokens have been invalidated
-
-### Changes Made:
-- `test_client.py` - Now uses environment variables
-- `test_mcp_comprehensive.js` - Now uses environment variables
-- Added `.env.example` file for secure configuration
-- Updated documentation with security best practices
-
-All users should update to v1.2.4 immediately. The exposed tokens are no longer valid, and users must use their own Airtable credentials.
-
-Thank you for helping improve the security of this project!
-
----
-
-## Issue #6: [Server Bug] @rashidazarang/airtable-mcp
-
-This issue has been resolved in v1.2.4! 
-
-### Root Cause:
-The Smithery configuration was using the Python implementation which had compatibility issues with MCP 1.4.1.
-
-### Solution:
-- Updated `smithery.yaml` to use the stable JavaScript implementation (`airtable_simple.js`)
-- Fixed authentication flow to properly handle credentials
-- Added proper environment variable support
-
-### To fix:
-1. Update to v1.2.4: `npm install @rashidazarang/airtable-mcp@latest`
-2. Reconfigure with your credentials as shown in the updated README
-3. Restart Claude Desktop
-
-The server should now connect properly without the "API key is required" error.
-
----
-
-## Issue #5: When Using Smithy, throwing 'Streamable HTTP error: Error POSTing to endpoint (HTTP 400): null'
-
-Fixed in v1.2.4! This was the same root cause as Issue #6.
-
-### What was wrong:
-- The Python server had MCP compatibility issues
-- Authentication wasn't being handled correctly
-- The Smithery configuration was misconfigured
-
-### What we fixed:
-- Switched to the JavaScript implementation
-- Updated smithery.yaml with proper configuration
-- Fixed credential passing through Smithery
-
-### How to resolve:
-```bash
-# Update to latest version
-npm install -g @rashidazarang/airtable-mcp@latest
-
-# Or if using Smithery directly:
-npx @smithery/cli install @rashidazarang/airtable-mcp --update
-```
-
-Then reconfigure with your Airtable credentials. The HTTP 400 errors should be resolved.
-
----
-
-## Issue #4: Glama listing is missing Dockerfile
-
-Fixed in v1.2.4!
-
-### Changes:
-- Created `Dockerfile.node` specifically for Node.js deployment
-- Updated `smithery.yaml` to reference the correct Dockerfile
-- The original Dockerfile is retained for backward compatibility
-
-The Dockerfile is now included and properly configured for cloud deployments.
-
----
-
-# GitHub Release Text for v1.2.4
-
-## 🚨 Critical Security Release - v1.2.4
-
-### ⚠️ IMPORTANT SECURITY FIX
-
-This release addresses a **critical security vulnerability** where API tokens were hardcoded in test files. All users should update immediately.
-
-### 🔒 Security Fixes
-- **Removed hardcoded API tokens** from all test files (fixes #7)
-- Test files now require environment variables for credentials
-- Added comprehensive security documentation
-- Previously exposed tokens have been invalidated
-
-### 🐛 Bug Fixes
-- **Fixed Smithery deployment issues** (fixes #5, #6)
-  - Resolved HTTP 400 errors when connecting through Smithery
-  - Fixed "API key is required for remote connections" error
-  - Switched to stable JavaScript implementation for cloud deployments
-- **Added missing Dockerfile** for Glama listing (fixes #4)
-
-### ✨ Improvements
-- Added environment variable support for secure credential management
-- Improved logging with configurable levels (ERROR, WARN, INFO, DEBUG)
-- Enhanced error messages for better debugging
-- Updated documentation with clear setup instructions
-
-### 📦 What's Changed
-- `test_client.py` - Now uses environment variables
-- `test_mcp_comprehensive.js` - Now uses environment variables  
-- `airtable_simple.js` - Added env variable and logging support
-- `smithery.yaml` - Fixed to use JavaScript implementation
-- `Dockerfile.node` - New optimized Docker image for Node.js
-- `SECURITY_NOTICE.md` - Important security information
-- `README.md` - Complete rewrite with better instructions
-
-### 💔 Breaking Changes
-Test files now require environment variables:
-```bash
-export AIRTABLE_TOKEN="your_token"
-export AIRTABLE_BASE_ID="your_base_id"
-```
-
-### 📋 Migration Instructions
-
-1. **Update to v1.2.4:**
-   ```bash
-   npm install -g @rashidazarang/airtable-mcp@latest
-   ```
-
-2. **Set up environment variables:**
-   ```bash
-   export AIRTABLE_TOKEN="your_personal_token"
-   export AIRTABLE_BASE_ID="your_base_id"
-   ```
-
-3. **Update your MCP configuration** (see README for details)
-
-4. **Restart your MCP client**
-
-### 🙏 Acknowledgments
-Special thanks to @BXXC-SDXZ for responsibly disclosing the security vulnerability, and to @ricklesgibson and @punkpeye for reporting the deployment issues.
-
-### ⚠️ Security Note
-If you were using the previously exposed tokens, they have been revoked. You must use your own Airtable credentials going forward.
-
-**Full Changelog**: https://github.com/rashidazarang/airtable-mcp/compare/v1.2.3...v1.2.4
-
----
-
-## NPM Publish Commands
-
-```bash
-# Make sure you're logged in to npm
-npm login
-
-# Update version (already done in package.json)
-npm version 1.2.4
-
-# Publish to npm
-npm publish --access public
-
-# Create git tag
-git tag -a v1.2.4 -m "Critical security fix and Smithery deployment fixes"
-git push origin v1.2.4
-```