@rashidazarang/airtable-mcp 2.1.0 → 2.2.0

package/API_DOCUMENTATION.md

@@ -1,897 +0,0 @@
-# 📚 Airtable MCP Server API Documentation v2.1
-
-## 🚀 Overview
-
-The Enhanced Airtable MCP Server v2.1 provides a comprehensive Model Context Protocol implementation with OAuth2 authentication, enterprise security features, and complete Airtable API integration.
-
-**🎯 Trust Score**: Contributing to our **100/100 Trust Score** goal through complete documentation coverage.
-
----
-
-## 🔧 Quick Start
-
-### 🐳 Docker (Recommended)
-```bash
-docker run -p 8010:8010 \
-  -e AIRTABLE_TOKEN=your_token \
-  -e AIRTABLE_BASE_ID=your_base_id \
-  rashidazarang/airtable-mcp:latest
-```
-
-### 📦 NPM Installation
-```bash
-npm install -g @rashidazarang/airtable-mcp
-airtable-mcp --token YOUR_TOKEN --base YOUR_BASE_ID
-```
-
-### 🔨 Local Development
-```bash
-git clone https://github.com/rashidazarang/airtable-mcp.git
-cd airtable-mcp
-npm install
-node airtable_mcp_v2_oauth.js --token YOUR_TOKEN --base YOUR_BASE_ID
-```
-
----
-
-## 🌐 API Endpoints
-
-### Base URL
-```
-http://localhost:8010
-```
-
-### Core Endpoints
-
-| Endpoint | Method | Description | Auth Required |
-|----------|--------|-------------|---------------|
-| `/mcp` | POST | MCP protocol endpoint | ✅ |
-| `/health` | GET | Health check | ❌ |
-| `/docs` | GET | Interactive documentation | ❌ |
-| `/oauth/authorize` | GET | OAuth2 authorization | ❌ |
-| `/oauth/callback` | GET | OAuth2 callback | ❌ |
-
----
-
-## 🔐 Authentication
-
-### 🔑 API Token (Simple)
-```bash
-export AIRTABLE_TOKEN="patXXXXXXXXXXXXXXXX"
-export AIRTABLE_BASE_ID="appXXXXXXXXXXXXXXXX"
-```
-
-### 🛡️ OAuth2 (Recommended)
-```bash
-# 1. Start server
-node airtable_mcp_v2_oauth.js
-
-# 2. Visit authorization URL
-curl http://localhost:8010/oauth/authorize
-
-# 3. Complete OAuth flow
-# Server will handle token exchange automatically
-```
-
-### 🔒 Environment Variables
-```bash
-# Required
-AIRTABLE_TOKEN=your_personal_access_token
-AIRTABLE_BASE_ID=your_base_id
-
-# Optional OAuth2
-AIRTABLE_CLIENT_ID=your_oauth_client_id
-AIRTABLE_CLIENT_SECRET=your_oauth_client_secret
-OAUTH_REDIRECT_URI=http://localhost:8010/oauth/callback
-
-# Optional Configuration
-LOG_LEVEL=INFO
-PORT=8010
-HOST=localhost
-ALLOWED_ORIGINS=*
-```
-
----
-
-## 📋 MCP Protocol Implementation
-
-### 🔄 Initialization
-
-**Request:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "method": "initialize",
-  "params": {
-    "protocolVersion": "2024-11-05",
-    "capabilities": {
-      "roots": {}
-    }
-  }
-}
-```
-
-**Response:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "result": {
-    "protocolVersion": "2024-11-05",
-    "capabilities": {
-      "tools": { "listChanged": true },
-      "resources": { "subscribe": true, "listChanged": true },
-      "prompts": { "listChanged": true },
-      "sampling": {},
-      "roots": { "listChanged": true },
-      "logging": {},
-      "authentication": { "oauth2": true, "apiKey": true }
-    },
-    "serverInfo": {
-      "name": "Enhanced Airtable MCP Server v2.1",
-      "version": "2.1.0",
-      "description": "Complete MCP protocol with OAuth2, security, and enterprise features"
-    }
-  }
-}
-```
-
----
-
-## 🛠️ Tools API
-
-### 📋 List Available Tools
-
-**Request:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 2,
-  "method": "tools/list"
-}
-```
-
-**Response:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 2,
-  "result": {
-    "tools": [
-      {
-        "name": "list_tables",
-        "description": "List all tables in the Airtable base with enhanced metadata",
-        "inputSchema": {
-          "type": "object",
-          "properties": {
-            "include_schema": {
-              "type": "boolean",
-              "description": "Include detailed field schema information",
-              "default": false
-            }
-          }
-        }
-      },
-      {
-        "name": "oauth_authorize",
-        "description": "Initiate OAuth2 authorization flow for enhanced security",
-        "inputSchema": {
-          "type": "object",
-          "properties": {
-            "redirect_uri": {
-              "type": "string",
-              "description": "OAuth redirect URI (optional)",
-              "format": "uri"
-            }
-          }
-        }
-      }
-    ]
-  }
-}
-```
-
-### 🔧 Execute Tool
-
-**Request:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 3,
-  "method": "tools/call",
-  "params": {
-    "name": "list_tables",
-    "arguments": {
-      "include_schema": true
-    }
-  }
-}
-```
-
-**Response:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 3,
-  "result": {
-    "content": [
-      {
-        "type": "text",
-        "text": "📊 **Found 4 table(s):**\n\n**1. Tasks**\n   • ID: `tblXXXXXXXXXXXXXXXX`\n   • Fields: 5\n   • Schema: Name (singleLineText), Status (singleSelect), Priority (singleSelect), Due Date (date), Notes (longText)"
-      }
-    ]
-  }
-}
-```
-
----
-
-## 🛠️ Available Tools Reference
-
-### 📊 Data Operations
-
-#### 🗂️ list_tables
-Lists all tables in your Airtable base with optional schema information.
-
-**Parameters:**
-- `include_schema` (boolean, optional): Include detailed field schema information
-
-**Example:**
-```bash
-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",
-      "arguments": {
-        "include_schema": true
-      }
-    }
-  }'
-```
-
-#### 📋 list_records
-Retrieves records from a specific table with filtering and pagination.
-
-**Parameters:**
-- `table` (string, required): Table name or ID
-- `maxRecords` (number, optional): Maximum number of records to return
-- `view` (string, optional): View name or ID
-- `filterByFormula` (string, optional): Airtable formula for filtering
-
-**Example:**
-```bash
-curl -X POST http://localhost:8010/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 2,
-    "method": "tools/call",
-    "params": {
-      "name": "list_records",
-      "arguments": {
-        "table": "Tasks",
-        "maxRecords": 10,
-        "filterByFormula": "AND({Status} = \"Active\", {Priority} = \"High\")"
-      }
-    }
-  }'
-```
-
-### 🔐 Security & Authentication
-
-#### 🛡️ oauth_authorize
-Initiates OAuth2 authorization flow for enhanced security.
-
-**Parameters:**
-- `redirect_uri` (string, optional): Custom redirect URI
-
-**Example:**
-```bash
-curl -X POST http://localhost:8010/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 3,
-    "method": "tools/call",
-    "params": {
-      "name": "oauth_authorize",
-      "arguments": {}
-    }
-  }'
-```
-
-#### 🔍 oauth_status
-Checks current OAuth2 authentication status.
-
-**Example:**
-```bash
-curl -X POST http://localhost:8010/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 4,
-    "method": "tools/call",
-    "params": {
-      "name": "oauth_status",
-      "arguments": {}
-    }
-  }'
-```
-
-#### 🛡️ security_audit
-Performs comprehensive security audit of current configuration.
-
-**Parameters:**
-- `include_tokens` (boolean, optional): Include token validation in audit
-
-**Example:**
-```bash
-curl -X POST http://localhost:8010/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 5,
-    "method": "tools/call",
-    "params": {
-      "name": "security_audit",
-      "arguments": {
-        "include_tokens": false
-      }
-    }
-  }'
-```
-
----
-
-## 📚 Resources API
-
-### 📋 List Resources
-
-**Request:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 6,
-  "method": "resources/list"
-}
-```
-
-**Response:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 6,
-  "result": {
-    "resources": [
-      {
-        "uri": "airtable://schema/appXXXXXXXXXXXXXXXX",
-        "name": "Base Schema",
-        "description": "Complete schema information for your Airtable base",
-        "mimeType": "application/json"
-      },
-      {
-        "uri": "airtable://docs/api",
-        "name": "API Documentation",
-        "description": "Interactive API documentation and examples",
-        "mimeType": "text/markdown"
-      }
-    ]
-  }
-}
-```
-
-### 📖 Read Resource
-
-**Request:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 7,
-  "method": "resources/read",
-  "params": {
-    "uri": "airtable://schema/appXXXXXXXXXXXXXXXX"
-  }
-}
-```
-
----
-
-## 💬 Prompts API
-
-### 📋 List Prompts
-
-**Request:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 8,
-  "method": "prompts/list"
-}
-```
-
-**Response:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 8,
-  "result": {
-    "prompts": [
-      {
-        "id": "data_analysis_assistant",
-        "name": "Data Analysis Assistant",
-        "description": "AI-powered data analysis for your Airtable base"
-      },
-      {
-        "id": "schema_optimization_advisor",
-        "name": "Schema Optimization Advisor",
-        "description": "Get AI recommendations for optimizing your base structure"
-      }
-    ]
-  }
-}
-```
-
-### 🤖 Execute Prompt
-
-**Request:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 9,
-  "method": "prompts/get",
-  "params": {
-    "name": "data_analysis_assistant",
-    "arguments": {
-      "table": "Sales",
-      "analysis_type": "trends"
-    }
-  }
-}
-```
-
----
-
-## 📊 Logging API
-
-### 🔧 Set Log Level
-
-**Request:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 10,
-  "method": "logging/setLevel",
-  "params": {
-    "level": "DEBUG"
-  }
-}
-```
-
-**Response:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 10,
-  "result": {
-    "level": "DEBUG",
-    "previousLevel": "INFO",
-    "availableLevels": ["ERROR", "WARN", "INFO", "DEBUG", "TRACE"]
-  }
-}
-```
-
----
-
-## 🛡️ Security Features
-
-### 🚦 Rate Limiting
-- **Limit**: 60 requests per minute per client
-- **Headers**: `X-RateLimit-Remaining`, `X-RateLimit-Reset`
-- **Response**: HTTP 429 when exceeded
-
-### 🔒 Security Headers
-```http
-X-Content-Type-Options: nosniff
-X-Frame-Options: DENY
-X-XSS-Protection: 1; mode=block
-Strict-Transport-Security: max-age=31536000; includeSubDomains
-Content-Security-Policy: default-src 'self'; script-src 'self'
-```
-
-### ✅ Input Validation
-- **JSON Schema Validation**: All inputs validated against schema
-- **Sanitization**: XSS prevention and input cleaning
-- **Length Limits**: Reasonable limits on input sizes
-- **Type Checking**: Strict type validation
-
----
-
-## 📊 Monitoring & Health
-
-### 🏥 Health Check
-
-**Request:**
-```bash
-curl http://localhost:8010/health
-```
-
-**Response:**
-```json
-{
-  "status": "healthy",
-  "version": "2.1.0",
-  "features": ["oauth2", "security", "rate-limiting"],
-  "uptime": 3600.123,
-  "timestamp": "2025-08-16T00:00:00.000Z"
-}
-```
-
-### 📈 Metrics
-```bash
-# Server metrics
-curl http://localhost:8010/metrics
-
-# Detailed health info
-curl http://localhost:8010/health?detailed=true
-```
-
----
-
-## 🚨 Error Handling
-
-### Error Response Format
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "error": {
-    "code": -32000,
-    "message": "Rate limit exceeded. Maximum 60 requests per minute.",
-    "data": {
-      "type": "RateLimitError",
-      "retryAfter": 60,
-      "limit": 60,
-      "remaining": 0
-    }
-  }
-}
-```
-
-### Common Error Codes
-
-| Code | Description | HTTP Status |
-|------|-------------|-------------|
-| -32700 | Parse error | 400 |
-| -32600 | Invalid Request | 400 |
-| -32601 | Method not found | 404 |
-| -32602 | Invalid params | 400 |
-| -32603 | Internal error | 500 |
-| -32000 | Server error | 500 |
-
-### Airtable-Specific Errors
-
-| Code | Description | Solution |
-|------|-------------|----------|
-| 401 | Invalid token | Check your Personal Access Token |
-| 403 | Permission denied | Verify token scopes |
-| 404 | Base/table not found | Check Base ID and table names |
-| 422 | Invalid data | Validate field types and values |
-| 429 | Rate limited | Implement backoff strategy |
-
----
-
-## 🧪 Testing & Examples
-
-### 🔧 Integration Test Suite
-```bash
-# Run comprehensive tests
-npm test
-
-# Test specific functionality
-npm run test:oauth
-npm run test:security
-npm run test:mcp
-```
-
-### 📝 Example Workflows
-
-#### 1. Basic Data Retrieval
-```javascript
-// Initialize MCP client
-const client = new MCPClient('http://localhost:8010/mcp');
-
-// Initialize connection
-await client.initialize();
-
-// List tables
-const tables = await client.callTool('list_tables', {
-  include_schema: true
-});
-
-// Get records
-const records = await client.callTool('list_records', {
-  table: 'Tasks',
-  maxRecords: 10,
-  filterByFormula: '{Status} = "Active"'
-});
-```
-
-#### 2. OAuth2 Authentication
-```javascript
-// Start OAuth flow
-const authUrl = await client.callTool('oauth_authorize');
-console.log('Visit:', authUrl.authorization_url);
-
-// Check status after user authorization
-const status = await client.callTool('oauth_status');
-console.log('Authenticated:', status.authenticated);
-```
-
-#### 3. Security Audit
-```javascript
-// Perform security audit
-const audit = await client.callTool('security_audit', {
-  include_tokens: false
-});
-console.log('Security status:', audit);
-```
-
----
-
-## 🚀 Performance & Optimization
-
-### 📊 Performance Metrics
-- **Response Time**: < 100ms for cached requests
-- **Throughput**: 60 requests/minute/client
-- **Memory Usage**: < 100MB base memory
-- **CPU Usage**: < 5% under normal load
-
-### ⚡ Optimization Tips
-1. **Caching**: Responses cached for 60 seconds
-2. **Connection Pooling**: Reuse HTTP connections
-3. **Batch Requests**: Use pagination for large datasets
-4. **Field Selection**: Request only needed fields
-5. **Filtering**: Use Airtable formulas for server-side filtering
-
----
-
-## 🔧 Configuration Reference
-
-### 🌐 Environment Variables
-
-```bash
-# Core Configuration
-AIRTABLE_TOKEN=pat...              # Personal Access Token (required)
-AIRTABLE_BASE_ID=app...            # Base ID (required)
-PORT=8010                          # Server port (default: 8010)
-HOST=localhost                     # Server host (default: localhost)
-
-# OAuth2 Configuration  
-AIRTABLE_CLIENT_ID=oauth_client_id      # OAuth2 client ID
-AIRTABLE_CLIENT_SECRET=oauth_secret     # OAuth2 client secret
-OAUTH_REDIRECT_URI=http://...           # OAuth2 redirect URI
-
-# Security Configuration
-ALLOWED_ORIGINS=*                  # CORS allowed origins
-MAX_REQUESTS_PER_MINUTE=60        # Rate limit (default: 60)
-SESSION_SECRET=random_secret       # Session encryption key
-
-# Logging Configuration
-LOG_LEVEL=INFO                     # Log level (ERROR, WARN, INFO, DEBUG, TRACE)
-LOG_FORMAT=json                    # Log format (json, text)
-LOG_FILE=/var/log/mcp.log         # Log file path
-
-# Performance Configuration
-CACHE_TTL=60                       # Cache TTL in seconds
-CONNECTION_TIMEOUT=30000           # Connection timeout in ms
-REQUEST_TIMEOUT=10000              # Request timeout in ms
-```
-
-### 📋 Command Line Options
-
-```bash
-node airtable_mcp_v2_oauth.js [options]
-
-Options:
-  --token <token>     Airtable Personal Access Token
-  --base <base_id>    Airtable Base ID
-  --port <port>       Server port (default: 8010)
-  --host <host>       Server host (default: localhost)
-  --log-level <level> Log level (default: INFO)
-  --help             Show help
-  --version          Show version
-```
-
----
-
-## 🔗 Integration Examples
-
-### 🖥️ Claude Desktop Configuration
-
-```json
-{
-  "mcpServers": {
-    "airtable": {
-      "command": "npx",
-      "args": ["@rashidazarang/airtable-mcp"],
-      "env": {
-        "AIRTABLE_TOKEN": "YOUR_TOKEN",
-        "AIRTABLE_BASE_ID": "YOUR_BASE_ID"
-      }
-    }
-  }
-}
-```
-
-### 💻 VS Code with Cline
-
-```json
-{
-  "cline.mcpServers": [
-    {
-      "name": "airtable",
-      "transport": {
-        "type": "stdio",
-        "command": "node",
-        "args": ["path/to/airtable_mcp_v2_oauth.js"]
-      }
-    }
-  ]
-}
-```
-
-### 🐳 Docker Compose
-
-```yaml
-version: '3.8'
-services:
-  airtable-mcp:
-    image: rashidazarang/airtable-mcp:latest
-    ports:
-      - "8010:8010"
-    environment:
-      - AIRTABLE_TOKEN=${AIRTABLE_TOKEN}
-      - AIRTABLE_BASE_ID=${AIRTABLE_BASE_ID}
-      - LOG_LEVEL=INFO
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8010/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-```
-
----
-
-## 🛠️ Development & Contributing
-
-### 🏗️ Development Setup
-
-```bash
-# Clone repository
-git clone https://github.com/rashidazarang/airtable-mcp.git
-cd airtable-mcp
-
-# Install dependencies
-npm install
-
-# Set up environment
-cp .env.example .env
-# Edit .env with your credentials
-
-# Start development server
-npm run dev
-
-# Run tests
-npm test
-
-# Build for production
-npm run build
-```
-
-### 🧪 Testing
-
-```bash
-# Unit tests
-npm run test:unit
-
-# Integration tests
-npm run test:integration
-
-# Security tests
-npm run test:security
-
-# Performance tests
-npm run test:performance
-
-# Coverage report
-npm run coverage
-```
-
-### 📝 API Documentation Updates
-
-To update this documentation:
-
-1. Edit the source in `API_DOCUMENTATION.md`
-2. Run documentation generation: `npm run docs:generate`
-3. Test examples: `npm run docs:test`
-4. Submit a pull request with the updates
-
----
-
-## 🆘 Troubleshooting
-
-### Common Issues
-
-#### 🔐 Authentication Errors
-```bash
-# Problem: "Invalid token" error
-# Solution: Verify token and scopes
-curl -H "Authorization: Bearer $AIRTABLE_TOKEN" \
-  https://api.airtable.com/v0/meta/whoami
-```
-
-#### 🌐 Connection Issues
-```bash
-# Problem: "Connection refused"
-# Solution: Check if server is running
-curl http://localhost:8010/health
-```
-
-#### 📊 Rate Limiting
-```bash
-# Problem: "Rate limit exceeded"
-# Solution: Implement exponential backoff
-for i in {1..5}; do
-  sleep $((2**i))
-  curl http://localhost:8010/mcp
-done
-```
-
-### 🐞 Debug Mode
-
-```bash
-# Enable debug logging
-export LOG_LEVEL=DEBUG
-node airtable_mcp_v2_oauth.js
-
-# Trace mode for detailed logging
-export LOG_LEVEL=TRACE
-node airtable_mcp_v2_oauth.js
-```
-
----
-
-## 📞 Support & Community
-
-### 🆘 Getting Help
-- **📚 Documentation**: [GitHub Wiki](https://github.com/rashidazarang/airtable-mcp/wiki)
-- **💬 Discussions**: [GitHub Discussions](https://github.com/rashidazarang/airtable-mcp/discussions)
-- **🐛 Issues**: [GitHub Issues](https://github.com/rashidazarang/airtable-mcp/issues)
-- **🔒 Security**: security@[domain]
-
-### 🤝 Contributing
-1. Read our [Contributing Guide](./CONTRIBUTING.md)
-2. Follow our [Code of Conduct](./CODE_OF_CONDUCT.md)
-3. Check our [Development Guide](./DEVELOPMENT.md)
-4. Submit pull requests with comprehensive tests
-
-### 📊 Trust Score Progress
-This documentation contributes to our **100/100 Trust Score** goal by providing:
-- ✅ **Comprehensive Coverage**: All APIs documented
-- ✅ **Interactive Examples**: Working code samples
-- ✅ **Security Guidelines**: Best practices included
-- ✅ **Error Handling**: Complete error reference
-- ✅ **Integration Guides**: Multiple client examples
-
----
-
-**📅 Last Updated**: August 2025  
-**📋 Version**: 2.1.0  
-**🎯 Trust Score Target**: 100/100  
-**📧 Contact**: api-docs@[domain]