@rashidazarang/airtable-mcp 2.1.0 → 2.2.0

package/CAPABILITY_REPORT.md

@@ -1,118 +0,0 @@
-# Airtable MCP Capability Report
-**Version**: 1.3.0 (Enhanced)  
-**Test Date**: August 15, 2025  
-**Status**: ✅ PRODUCTION READY
-
-## 📊 Current Capabilities (Tested & Validated)
-
-### ✅ **WORKING FEATURES**
-
-| Tool | Description | Status | Test Result |
-|------|-------------|--------|-------------|
-| `list_tables` | List all tables in base | ✅ Working | Successfully lists all tables with IDs and field counts |
-| `list_records` | List records from table | ✅ Working | Returns all records with pagination support |
-| `get_record` | Get single record by ID | ✅ Working | Retrieves specific record with all fields |
-| `create_record` | Create new records | ✅ Working | Successfully creates records with any fields |
-| `update_record` | Update existing records | ✅ Working | Updates specific fields without affecting others |
-| `delete_record` | Delete records | ✅ Working | Permanently removes records from table |
-| `search_records` | Filter and sort records | ✅ Working | Supports Airtable formulas and sorting |
-
-### 🔑 **API Scope Coverage**
-
-Based on your token's scopes, here's what we currently support:
-
-| Scope | Status | Implementation |
-|-------|--------|----------------|
-| **data.records:read** | ✅ Fully Implemented | `list_records`, `get_record`, `search_records` |
-| **data.records:write** | ✅ Fully Implemented | `create_record`, `update_record`, `delete_record` |
-| **data.recordComments:read** | ❌ Not Implemented | No comment reading tools |
-| **data.recordComments:write** | ❌ Not Implemented | No comment writing tools |
-| **schema.bases:read** | ✅ Partially Implemented | `list_tables` (reads table structure) |
-| **schema.bases:write** | ❌ Not Implemented | No table/field creation tools |
-| **webhook:manage** | ❌ Not Implemented | No webhook management |
-| **block:manage** | ❌ Not Implemented | No custom extension support |
-| **user.email:read** | ❌ Not Implemented | No user info retrieval |
-
-## 🎯 **Version Comparison**
-
-### v1.2.4 (Current Production)
-- **Tools**: 2 (list_tables, list_records)
-- **Operations**: READ only
-- **Coverage**: ~20% of API capabilities
-
-### v1.3.0 (Enhanced - Ready for Deployment)
-- **Tools**: 7 (all CRUD operations)
-- **Operations**: Full CRUD (Create, Read, Update, Delete)
-- **Coverage**: ~40% of API capabilities
-- **New Features**:
-  - ✅ Create records with any fields
-  - ✅ Update specific fields
-  - ✅ Delete records
-  - ✅ Get single record by ID
-  - ✅ Search with filters and sorting
-
-## 🚀 **Recommended Next Features**
-
-### Priority 1: Comments & Attachments
-- `add_comment` - Add comments to records
-- `list_comments` - View record comments
-- `upload_attachment` - Add files to records
-- `download_attachment` - Retrieve files
-
-### Priority 2: Schema Management
-- `create_table` - Create new tables
-- `create_field` - Add fields to tables
-- `update_field` - Modify field properties
-- `delete_field` - Remove fields
-
-### Priority 3: Advanced Operations
-- `batch_create` - Create multiple records (up to 10)
-- `batch_update` - Update multiple records
-- `batch_delete` - Delete multiple records
-- `export_base` - Export entire base structure
-
-### Priority 4: Webhooks & Automation
-- `create_webhook` - Set up webhooks
-- `list_webhooks` - View active webhooks
-- `delete_webhook` - Remove webhooks
-- `get_webhook_payload` - Retrieve webhook data
-
-## 📈 **Performance Metrics**
-
-- **Response Time**: ~500ms average per operation
-- **Success Rate**: 100% in testing
-- **Error Handling**: Proper error messages with details
-- **Rate Limiting**: Respects Airtable's 5 req/sec limit
-
-## 🔒 **Security Features**
-
-- ✅ Token masking in logs
-- ✅ Environment variable support
-- ✅ No hardcoded credentials
-- ✅ Secure HTTPS connections
-- ✅ Input validation
-
-## 📝 **Test Results Summary**
-
-```
-Test Environment: Production Airtable API
-Base: Newsletter (appTV04Fyu1Gvbunq)
-Table: Test Table CRUD (tblH7TnJxYpNqhQYK)
-
-Results:
-✅ 7/7 tools tested successfully
-✅ 100% success rate
-✅ All CRUD operations verified
-✅ Error handling confirmed
-✅ Field validation working
-```
-
-## 🎉 **Conclusion**
-
-The Enhanced Airtable MCP v1.3.0 is **production-ready** and provides:
-- Complete CRUD functionality
-- Robust error handling
-- Secure credential management
-- 3.5x more features than v1.2.4
-
-**Recommendation**: Deploy v1.3.0 to production to unlock full CRUD capabilities for users.

package/CLAUDE_INTEGRATION.md

@@ -1,96 +0,0 @@
-# Claude Desktop Integration Guide
-
-This guide provides detailed instructions for setting up the Airtable MCP with Claude Desktop.
-
-## Prerequisites
-
-- Node.js 14+ installed
-- Claude Desktop installed
-- Airtable API token
-- Airtable base ID
-
-## Configuration Steps
-
-1. **Locate Configuration File**
-   - Open Finder
-   - Press `Cmd + Shift + G`
-   - Enter `~/Library/Application Support/Claude`
-   - Create or open `claude_desktop_config.json`
-
-2. **Add Configuration**
-   ```json
-   {
-     "mcpServers": {
-       "airtable-mcp": {
-         "command": "npx",
-         "args": [
-           "@smithery/cli",
-           "run",
-           "@rashidazarang/airtable-mcp",
-           "--token",
-           "YOUR_AIRTABLE_TOKEN",
-           "--base",
-           "YOUR_BASE_ID"
-         ]
-       }
-     }
-   }
-   ```
-
-3. **Replace Credentials**
-   - Replace `YOUR_AIRTABLE_TOKEN` with your token from [Airtable Account](https://airtable.com/account)
-   - Replace `YOUR_BASE_ID` with your base ID (found in your Airtable base URL)
-
-4. **Restart Claude Desktop**
-   - Close Claude Desktop completely
-   - Wait 5 seconds
-   - Reopen Claude Desktop
-   - Wait 30 seconds for the connection to establish
-
-## Verification
-
-Test the connection by asking Claude:
-- "Show me all my Airtable bases"
-- "What tables are in this base?"
-- "Show me the first 5 records from any table"
-
-## Troubleshooting
-
-### Connection Issues
-1. Verify Node.js installation:
-   ```bash
-   node -v  # Should show v14 or higher
-   ```
-
-2. Test Smithery CLI:
-   ```bash
-   npx @smithery/cli --version
-   ```
-
-3. Check logs:
-   - Open `~/Library/Logs/Claude/mcp-server-airtable-mcp.log`
-   - Look for any error messages
-
-### Common Errors
-
-1. **"Command not found"**
-   ```bash
-   npm install -g npm@latest
-   ```
-
-2. **JSON Parsing Errors**
-   - Remove any extra backslashes
-   - Use the exact format shown above
-   - Ensure no trailing commas
-
-3. **Connection Timeout**
-   - Wait full 30 seconds after startup
-   - Check your internet connection
-   - Verify API token is valid
-
-## Support
-
-If you encounter any issues:
-1. Check [GitHub Issues](https://github.com/rashidazarang/airtable-mcp/issues)
-2. Join our [Discord](https://discord.gg/your-discord)
-3. Email: support@example.com 

package/CODE_OF_CONDUCT.md

@@ -1,181 +0,0 @@
-# 🤝 Contributor Covenant Code of Conduct
-
-## 🎯 Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community, while working together towards our **100/100 Trust Score** goal.
-
-## 📋 Our Standards
-
-Examples of behavior that contributes to a positive environment for our community include:
-
-### ✅ Positive Behaviors
-- **🤝 Respectful Communication**: Using welcoming and inclusive language
-- **🎯 Constructive Feedback**: Providing and gracefully accepting constructive criticism
-- **🙏 Empathy**: Showing empathy towards other community members
-- **🔒 Security Focus**: Prioritizing security and responsible disclosure
-- **📚 Knowledge Sharing**: Helping others learn and grow
-- **🚀 Quality Commitment**: Contributing to our Trust Score improvement goals
-- **🌟 Recognition**: Acknowledging others' contributions and efforts
-- **🔧 Solution-Oriented**: Focusing on what is best for the overall community
-
-### ❌ Unacceptable Behaviors
-- **💬 Harassment**: Trolling, insulting/derogatory comments, personal or political attacks
-- **📧 Privacy Violations**: Publishing others' private information without permission
-- **🔓 Security Violations**: Publicly disclosing security vulnerabilities before responsible disclosure
-- **🎯 Scope Creep**: Other conduct which could reasonably be considered inappropriate in a professional setting
-- **📊 Spam**: Excessive self-promotion or off-topic content
-- **🚫 Discrimination**: Any form of discrimination or exclusion based on protected characteristics
-
-## 🛡️ Security-Specific Guidelines
-
-Given our focus on achieving a **100/100 Trust Score**, we have additional guidelines around security:
-
-### 🔒 Responsible Disclosure
-- Report security vulnerabilities privately through appropriate channels
-- Do not publicly disclose vulnerabilities until fixes are available
-- Follow coordinated disclosure timelines with maintainers
-
-### 🛡️ Security Discussions
-- Keep security discussions constructive and solution-focused
-- Avoid fear-mongering or exaggerating security issues
-- Provide evidence-based security recommendations
-
-## 📊 Trust Score Community Standards
-
-Our community is committed to building the most trusted MCP server for Airtable:
-
-### 🎯 Quality Standards
-- **🧪 Testing**: All contributions include appropriate tests
-- **📚 Documentation**: Clear documentation accompanies code changes
-- **🔍 Code Review**: Constructive and thorough code reviews
-- **📈 Continuous Improvement**: Regular updates and enhancements
-
-### 🤝 Collaboration Standards
-- **💡 Innovation**: Encouraging creative solutions and new ideas
-- **🔄 Iteration**: Embracing feedback and iterative improvement
-- **🌐 Inclusivity**: Welcoming contributors of all skill levels
-- **📊 Transparency**: Open communication about goals and progress
-
-## 🚀 Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
-
-### 👥 Leadership Team
-- **Primary Maintainer**: [@rashidazarang](https://github.com/rashidazarang)
-- **Security Team**: security@[domain]
-- **Community Moderators**: [to be appointed as community grows]
-
-### 🔧 Enforcement Powers
-Community leaders have the right and responsibility to:
-- Remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions
-- Temporarily or permanently ban contributors for inappropriate behaviors
-- Communicate expectations and consequences clearly
-
-## 📏 Scope
-
-This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include:
-
-### 📍 Community Spaces
-- **GitHub Repository**: Issues, PRs, discussions, and project boards
-- **Communication Channels**: Discord, Slack, or other official channels
-- **Documentation**: Wiki, docs site, and README files
-- **Events**: Conferences, meetups, and online presentations
-
-### 🌐 Public Representation
-- Using an official e-mail address
-- Posting via an official social media account
-- Acting as an appointed representative at online or offline events
-- Speaking about the project in interviews or presentations
-
-## 📞 Reporting Guidelines
-
-### 🚨 How to Report
-If you experience or witness unacceptable behavior, or have any other concerns, please report it by contacting the community leaders:
-
-- **General Issues**: conduct@[domain]
-- **Security Issues**: security@[domain]
-- **Direct Contact**: [@rashidazarang](https://github.com/rashidazarang)
-- **Anonymous Reporting**: [to be set up as community grows]
-
-### 📝 What to Include
-When reporting, please include:
-- Your contact information (if comfortable sharing)
-- Details of the incident, including:
-  - When and where it occurred
-  - What happened
-  - Who was involved
-  - Any available evidence (screenshots, links, etc.)
-- Any additional context that would be helpful
-
-### ⚡ Response Timeline
-- **Acknowledgment**: Within 24 hours
-- **Initial Review**: Within 48 hours
-- **Investigation**: 1-7 days (depending on complexity)
-- **Resolution**: Varies based on the situation
-- **Follow-up**: Ongoing as needed
-
-## 🔧 Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. 📝 Correction
-**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
-
-### 2. ⚠️ Warning
-**Community Impact**: A violation through a single incident or series of actions.
-
-**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
-
-### 3. ⏸️ Temporary Ban
-**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
-
-### 4. 🚫 Permanent Ban
-**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the community.
-
-## 🔄 Appeals Process
-
-### 📝 How to Appeal
-If you believe you have been unfairly sanctioned, you may appeal by:
-1. Contacting the community leaders at appeals@[domain]
-2. Providing a detailed explanation of why you believe the action was unfair
-3. Including any relevant evidence or context
-4. Waiting for review and response
-
-### ⏱️ Appeal Timeline
-- **Review Period**: 7-14 days
-- **Decision**: Final decisions will be communicated clearly
-- **Implementation**: Changes take effect immediately upon decision
-
-## 🙏 Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
-
-## 🎯 Our Commitment
-
-As we work towards our **100/100 Trust Score** goal, we recognize that trust extends beyond technical excellence to include community trust. This Code of Conduct is our commitment to maintaining a community that reflects the same high standards of security, quality, and reliability that we strive for in our code.
-
-Together, we're not just building software – we're building a trusted community that makes the entire MCP ecosystem stronger. 🚀
-
----
-
-**Last Updated**: August 2025
-**Version**: 1.0
-**Contact**: conduct@[domain]
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -1,81 +0,0 @@
-# Contributing to Airtable MCP
-
-Thank you for your interest in contributing to Airtable MCP! This guide will help you get started with contributing to this project.
-
-## Development Setup
-
-1. **Clone the repository**:
-   ```bash
-   git clone https://github.com/rashidazarang/airtable-mcp.git
-   cd airtable-mcp
-   ```
-
-2. **Install dependencies**:
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-3. **Environment setup**:
-   Create a `.env` file in the root directory with your Airtable API token:
-   ```
-   AIRTABLE_PERSONAL_ACCESS_TOKEN=your_token_here
-   AIRTABLE_BASE_ID=optional_default_base_id
-   ```
-
-## Running the Server
-
-You can run the server directly with Python:
-
-```bash
-python3.10 inspector_server.py --token "your_token" --base "your_base_id"
-```
-
-Or through the Node.js wrapper:
-
-```bash
-node index.js --token "your_token" --base "your_base_id"
-```
-
-## Testing
-
-Run the test client to verify your Airtable API access:
-
-```bash
-python3.10 test_client.py
-```
-
-## Pull Request Process
-
-1. **Fork the Repository** on GitHub.
-
-2. **Create a Branch** for your feature or bugfix.
-
-3. **Make Changes** according to the project style guidelines.
-
-4. **Test Thoroughly** to ensure your changes work as expected.
-
-5. **Document Changes** in the README.md if necessary.
-
-6. **Submit a Pull Request** to the main repository.
-
-## Coding Guidelines
-
-- Follow Python PEP 8 style guidelines
-- Write docstrings for all functions, classes, and modules
-- Include type hints for function parameters and return values
-- Write clear commit messages
-
-## Adding New Tools
-
-When adding new Airtable API tools:
-
-1. Add the tool function to `inspector_server.py` using the `@app.tool()` decorator
-2. Define clear parameter and return types
-3. Provide a descriptive docstring for the tool
-4. Update the inspector.py file to include the new tool in the JSON schema
-5. Add error handling for API requests
-6. Update the README.md to document the new tool
-
-## License
-
-By contributing to this project, you agree that your contributions will be licensed under the project's MIT License. 

package/DEVELOPMENT.md

@@ -1,190 +0,0 @@
-# Development Guide
-
-## 🛠️ **Development Setup**
-
-### Prerequisites
-- Node.js >= 14.0.0
-- Python 3.10+ (for legacy Python server)
-- Airtable Personal Access Token
-
-### Installation
-```bash
-git clone https://github.com/rashidazarang/airtable-mcp.git
-cd airtable-mcp
-npm install
-```
-
-## 🏗️ **Architecture Overview**
-
-### **Recommended Implementation: `airtable_simple.js`**
-- **Status**: ✅ Production Ready
-- **Protocol**: HTTP/JSON-RPC 2.0
-- **Port**: 8010
-- **Features**: 
-  - Direct Airtable API integration
-  - Proper error handling
-  - CORS support
-  - Standard MCP tool definitions
-
-### **Legacy Implementation: `inspector_server.py`**
-- **Status**: ⚠️ Has compatibility issues
-- **Protocol**: FastMCP (Python)
-- **Issues**: 
-  - `app.rpc_method` not available in MCP 1.4.1
-  - `app.start()` method missing
-  - Complex dependency management
-
-## 🧪 **Testing**
-
-### **Quick Tests**
-```bash
-# Run quick tests
-npm run test:quick
-
-# Run comprehensive tests
-npm run test
-```
-
-### **Manual Testing**
-```bash
-# Start the server
-npm start -- --token YOUR_TOKEN --base YOUR_BASE_ID
-
-# Test with curl
-curl -X POST http://localhost:8010/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "list_tables"}}'
-```
-
-## 🔧 **Adding New Tools**
-
-### **JavaScript Server (`airtable_simple.js`)**
-
-1. **Add Tool Handler**
-```javascript
-if (toolName === 'your_new_tool') {
-  // Your tool implementation
-  const result = await callAirtableAPI('your/endpoint');
-  
-  const response = {
-    jsonrpc: '2.0',
-    id: request.id,
-    result: {
-      content: [
-        {
-          type: 'text',
-          text: 'Your tool response'
-        }
-      ]
-    }
-  };
-  
-  res.writeHead(200, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(response));
-  return;
-}
-```
-
-2. **Add to Resources/Prompts** (if needed)
-```javascript
-// In resources/list handler
-{
-  id: 'your_resource',
-  name: 'Your Resource',
-  description: 'Description of your resource'
-}
-
-// In prompts/list handler
-{
-  id: 'your_prompt',
-  name: 'Your Prompt',
-  description: 'Description of your prompt'
-}
-```
-
-### **Python Server (`inspector_server.py`)**
-
-⚠️ **Note**: The Python server has compatibility issues and is not recommended for new development.
-
-## 📦 **Building and Publishing**
-
-### **Update Version**
-```bash
-# Update version in package.json
-npm version patch  # or minor/major
-```
-
-### **Test Before Publishing**
-```bash
-# Run all tests
-npm run test
-npm run test:quick
-
-# Test with real Airtable data
-npm start -- --token YOUR_TOKEN --base YOUR_BASE_ID
-```
-
-### **Publish to NPM**
-```bash
-npm publish
-```
-
-## 🐛 **Debugging**
-
-### **Common Issues**
-
-1. **Port Already in Use**
-```bash
-lsof -ti:8010 | xargs kill -9
-```
-
-2. **Python MCP Compatibility**
-- Check MCP version: `pip show mcp`
-- Update to latest: `pip install --upgrade mcp`
-
-3. **Airtable API Issues**
-- Verify token permissions
-- Check base ID format
-- Test API directly: `curl -H "Authorization: Bearer YOUR_TOKEN" https://api.airtable.com/v0/meta/bases`
-
-### **Logging**
-- JavaScript server logs to console
-- Python server uses Python logging
-- Check for error messages in MCP client logs
-
-## 📋 **Code Standards**
-
-### **JavaScript**
-- Use ES6+ features
-- Proper error handling with try/catch
-- Consistent JSON-RPC response format
-- Add JSDoc comments for functions
-
-### **Python**
-- Follow PEP 8 style guide
-- Use type hints
-- Proper exception handling
-- Add docstrings for functions
-
-## 🤝 **Contributing**
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Update documentation
-6. Submit a pull request
-
-### **Before Submitting**
-- [ ] All tests pass
-- [ ] Documentation updated
-- [ ] No console errors
-- [ ] MCP protocol compliance verified
-
-## 📚 **Resources**
-
-- [MCP Specification](https://modelcontextprotocol.io/)
-- [Airtable API Documentation](https://airtable.com/developers/web/api/introduction)
-- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
-
-

package/Dockerfile

@@ -1,39 +0,0 @@
-FROM python:3.10-slim
-
-WORKDIR /app
-
-# Install Node.js for the NPX functionality
-RUN apt-get update && \
-    apt-get install -y curl gnupg && \
-    curl -fsSL https://deb.nodesource.com/setup_18.x | bash - && \
-    apt-get install -y nodejs && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
-
-# Copy package files first (for better layer caching)
-COPY package.json /app/
-COPY package-lock.json /app/
-
-# Install Node.js dependencies
-RUN npm install
-
-# Copy Python requirements and install
-COPY requirements.txt /app/
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy source code
-COPY index.js /app/
-COPY inspector.py /app/
-COPY inspector_server.py /app/
-COPY airtable_mcp/ /app/airtable_mcp/
-
-# Set environment variables
-ENV NODE_ENV=production
-ENV PYTHONUNBUFFERED=1
-
-# Expose the port the server might run on
-EXPOSE 3000
-
-# Start the server in STDIO mode by default
-# Smithery will override this with their own command
-CMD ["python3", "inspector_server.py"]