@rashidazarang/airtable-mcp 3.0.0 → 3.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +210 -43
- package/bin/airtable-mcp.js +12 -32
- package/dist/typescript/airtable-mcp-server.js +77 -0
- package/dist/typescript/airtable-mcp-server.js.map +1 -0
- package/dist/typescript/app/airtable-client.js +325 -0
- package/dist/typescript/app/airtable-client.js.map +1 -0
- package/dist/typescript/app/config.js +141 -0
- package/dist/typescript/app/config.js.map +1 -0
- package/dist/typescript/app/context.js +3 -0
- package/dist/typescript/app/context.js.map +1 -0
- package/dist/typescript/app/exceptions.js +85 -0
- package/dist/typescript/app/exceptions.js.map +1 -0
- package/dist/typescript/app/governance.js +58 -0
- package/dist/typescript/app/governance.js.map +1 -0
- package/dist/typescript/app/logger.js +47 -0
- package/dist/typescript/app/logger.js.map +1 -0
- package/dist/typescript/app/rateLimiter.js +37 -0
- package/dist/typescript/app/rateLimiter.js.map +1 -0
- package/dist/typescript/app/tools/create.js +54 -0
- package/dist/typescript/app/tools/create.js.map +1 -0
- package/dist/typescript/app/tools/describe.js +146 -0
- package/dist/typescript/app/tools/describe.js.map +1 -0
- package/dist/typescript/app/tools/handleError.js +54 -0
- package/dist/typescript/app/tools/handleError.js.map +1 -0
- package/dist/typescript/app/tools/index.js +24 -0
- package/dist/typescript/app/tools/index.js.map +1 -0
- package/dist/typescript/app/tools/listBases.js +52 -0
- package/dist/typescript/app/tools/listBases.js.map +1 -0
- package/dist/typescript/app/tools/listExceptions.js +18 -0
- package/dist/typescript/app/tools/listExceptions.js.map +1 -0
- package/dist/typescript/app/tools/listGovernance.js +17 -0
- package/dist/typescript/app/tools/listGovernance.js.map +1 -0
- package/dist/typescript/app/tools/query.js +126 -0
- package/dist/typescript/app/tools/query.js.map +1 -0
- package/dist/typescript/app/tools/update.js +56 -0
- package/dist/typescript/app/tools/update.js.map +1 -0
- package/dist/typescript/app/tools/upsert.js +65 -0
- package/dist/typescript/app/tools/upsert.js.map +1 -0
- package/dist/typescript/app/tools/webhooks.js +44 -0
- package/dist/typescript/app/tools/webhooks.js.map +1 -0
- package/dist/typescript/app/types.js +282 -0
- package/dist/typescript/app/types.js.map +1 -0
- package/dist/typescript/apps-sdk/mappers.js +70 -0
- package/dist/typescript/apps-sdk/mappers.js.map +1 -0
- package/dist/typescript/errors.js +75 -0
- package/dist/typescript/errors.js.map +1 -0
- package/dist/typescript/index.js +27 -0
- package/dist/typescript/index.js.map +1 -0
- package/package.json +63 -17
- package/tsconfig.json +44 -0
- package/types/typescript/airtable-mcp-server.d.ts +2 -0
- package/types/typescript/app/airtable-client.d.ts +49 -0
- package/types/typescript/app/config.d.ts +16 -0
- package/types/typescript/app/context.d.ts +12 -0
- package/types/typescript/app/exceptions.d.ts +12 -0
- package/types/typescript/app/governance.d.ts +18 -0
- package/types/typescript/app/logger.d.ts +13 -0
- package/types/typescript/app/rateLimiter.d.ts +13 -0
- package/types/typescript/app/tools/create.d.ts +3 -0
- package/types/typescript/app/tools/describe.d.ts +3 -0
- package/types/typescript/app/tools/handleError.d.ts +8 -0
- package/types/typescript/app/tools/index.d.ts +3 -0
- package/types/typescript/app/tools/listBases.d.ts +33 -0
- package/types/typescript/app/tools/listExceptions.d.ts +3 -0
- package/types/typescript/app/tools/listGovernance.d.ts +3 -0
- package/types/typescript/app/tools/query.d.ts +3 -0
- package/types/typescript/app/tools/update.d.ts +3 -0
- package/types/typescript/app/tools/upsert.d.ts +3 -0
- package/types/typescript/app/tools/webhooks.d.ts +3 -0
- package/types/typescript/app/types.d.ts +830 -0
- package/types/typescript/apps-sdk/mappers.d.ts +53 -0
- package/types/typescript/errors.d.ts +55 -0
- package/types/typescript/index.d.ts +10 -0
- package/types/typescript/prompt-templates.d.ts +5 -0
- package/types/typescript/test-suite.d.ts +33 -0
- package/types/typescript/tools-schemas.d.ts +5 -0
- package/airtable_simple.js +0 -1561
- package/airtable_simple_production.js +0 -1564
- package/examples/airtable-crud-example.js +0 -203
- package/examples/building-mcp.md +0 -6666
- package/examples/claude_config.json +0 -4
- package/examples/claude_simple_config.json +0 -7
- package/examples/env-demo.js +0 -172
- package/examples/example-tasks-update.json +0 -23
- package/examples/example-tasks.json +0 -26
- package/examples/example_usage.md +0 -124
- package/examples/python_debug_patch.txt +0 -27
- package/examples/sample-transform.js +0 -76
- package/examples/windsurf_mcp_config.json +0 -17
package/README.md
CHANGED
|
@@ -3,21 +3,47 @@
|
|
|
3
3
|
[](https://archestra.ai/mcp-catalog/rashidazarang__airtable-mcp)
|
|
4
4
|
[](https://smithery.ai/server/@rashidazarang/airtable-mcp)
|
|
5
5
|

|
|
6
|
-
[](https://github.com/rashidazarang/airtable-mcp)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
[](https://github.com/rashidazarang/airtable-mcp)
|
|
9
|
+
[](https://github.com/rashidazarang/airtable-mcp)
|
|
8
10
|
[](https://modelcontextprotocol.io/)
|
|
9
11
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
## 🚀 Latest:
|
|
13
|
-
|
|
14
|
-
**
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
- ✅ **
|
|
19
|
-
-
|
|
20
|
-
-
|
|
12
|
+
🤖 **Revolutionary AI Agent v3.2.5** - Advanced AI-powered Airtable MCP server with **fixed TypeScript architecture**, world-class project organization, comprehensive intelligence capabilities, predictive analytics, and enterprise automation features.
|
|
13
|
+
|
|
14
|
+
## 🚀 Latest: v3.2.5 - Optional Base ID & Enhanced Multi-Base Support
|
|
15
|
+
|
|
16
|
+
**Major Improvements** with full backward compatibility:
|
|
17
|
+
- 🔓 **Optional Base ID** - Start without specifying a base, discover them using `list_bases` tool
|
|
18
|
+
- 🔍 **Enhanced Base Discovery** - New `list_bases` tool fully implemented in TypeScript
|
|
19
|
+
- 🎯 **Dynamic Base Selection** - Specify base IDs per tool call, no startup requirement
|
|
20
|
+
- ✅ **Fixed Issue #9** - Resolved "base required at startup" limitation
|
|
21
|
+
- 🔧 **Improved Governance** - Smart base allowlist handling for multi-base workflows
|
|
22
|
+
- 📦 **Full STDIO Support** - Confirmed compatibility with Claude Desktop/Code
|
|
23
|
+
|
|
24
|
+
## 📋 Previous: v3.2.4 - XSS Security Fix & Complete Protection
|
|
25
|
+
|
|
26
|
+
**Major Improvements** with full backward compatibility:
|
|
27
|
+
- 🔧 **TypeScript Architecture Fixed** - Resolved compilation issues, proper separation of types and runtime code
|
|
28
|
+
- 📁 **World-Class Organization** - Restructured project with src/typescript, src/javascript, src/python
|
|
29
|
+
- 🔒 **Security Fix Complete** - Fully resolved command injection vulnerability with comprehensive validation
|
|
30
|
+
- 🔷 **TypeScript Implementation** - Complete type-safe server with strict validation
|
|
31
|
+
- 📘 **Comprehensive Type Definitions** - All 33 tools and 10 AI prompts fully typed
|
|
32
|
+
- 🛡️ **Compile-Time Safety** - Catch errors before runtime with advanced type checking
|
|
33
|
+
- 🎯 **Developer Experience** - IntelliSense, auto-completion, and refactoring support
|
|
34
|
+
- 🔄 **Dual Distribution** - Use with JavaScript or TypeScript, your choice
|
|
35
|
+
|
|
36
|
+
## 🤖 AI Intelligence Suite
|
|
37
|
+
|
|
38
|
+
**Complete AI-Powered Intelligence** with enterprise capabilities:
|
|
39
|
+
- 🤖 **10 AI Prompt Templates** - Advanced analytics, predictions, and automation
|
|
40
|
+
- 🔮 **Predictive Analytics** - Forecasting and trend analysis with confidence intervals
|
|
41
|
+
- 🗣️ **Natural Language Processing** - Query your data using human language
|
|
42
|
+
- 📊 **Business Intelligence** - Automated insights and recommendations
|
|
43
|
+
- 🏗️ **Smart Schema Design** - AI-optimized database architecture
|
|
44
|
+
- ⚡ **Workflow Automation** - Intelligent process optimization
|
|
45
|
+
- 🔍 **Data Quality Auditing** - Comprehensive quality assessment and fixes
|
|
46
|
+
- 📈 **Statistical Analysis** - Advanced analytics with significance testing
|
|
21
47
|
|
|
22
48
|
## ✨ Features
|
|
23
49
|
|
|
@@ -63,13 +89,25 @@
|
|
|
63
89
|
|
|
64
90
|
Choose one of these installation methods:
|
|
65
91
|
|
|
66
|
-
####
|
|
92
|
+
#### 🔷 TypeScript Users (Recommended for Development)
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
# Install with TypeScript support
|
|
96
|
+
npm install -g @rashidazarang/airtable-mcp
|
|
97
|
+
|
|
98
|
+
# For development with types
|
|
99
|
+
npm install --save-dev typescript @types/node
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
#### 📦 JavaScript Users (Production Ready)
|
|
103
|
+
|
|
104
|
+
**Option A: Install via NPM (Recommended)**
|
|
67
105
|
|
|
68
106
|
```bash
|
|
69
107
|
npm install -g @rashidazarang/airtable-mcp
|
|
70
108
|
```
|
|
71
109
|
|
|
72
|
-
|
|
110
|
+
**Option B: Clone from GitHub**
|
|
73
111
|
|
|
74
112
|
```bash
|
|
75
113
|
git clone https://github.com/rashidazarang/airtable-mcp.git
|
|
@@ -83,14 +121,45 @@ Create a `.env` file in your project directory:
|
|
|
83
121
|
|
|
84
122
|
```env
|
|
85
123
|
AIRTABLE_TOKEN=your_personal_access_token_here
|
|
86
|
-
AIRTABLE_BASE_ID=your_base_id_here
|
|
124
|
+
AIRTABLE_BASE_ID=your_base_id_here # OPTIONAL - can be discovered using list_bases tool
|
|
87
125
|
```
|
|
88
126
|
|
|
127
|
+
**New in v3.2.5**: The `AIRTABLE_BASE_ID` is now **optional**! You can:
|
|
128
|
+
- Start without a base ID and use the `list_bases` tool to discover your accessible bases
|
|
129
|
+
- Specify base IDs dynamically in each tool call
|
|
130
|
+
- Set a default base for convenience (recommended)
|
|
131
|
+
|
|
89
132
|
**Security Note**: Never commit `.env` files to version control!
|
|
90
133
|
|
|
91
134
|
### Step 4: Configure Your MCP Client
|
|
92
135
|
|
|
93
|
-
####
|
|
136
|
+
#### 🔷 TypeScript Configuration (Enhanced Developer Experience)
|
|
137
|
+
|
|
138
|
+
Add to your Claude Desktop configuration file with TypeScript binary:
|
|
139
|
+
|
|
140
|
+
**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
141
|
+
**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"mcpServers": {
|
|
146
|
+
"airtable-typescript": {
|
|
147
|
+
"command": "npx",
|
|
148
|
+
"args": ["@rashidazarang/airtable-mcp"],
|
|
149
|
+
"env": {
|
|
150
|
+
"AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN",
|
|
151
|
+
"AIRTABLE_BASE_ID": "YOUR_BASE_ID",
|
|
152
|
+
"NODE_ENV": "production",
|
|
153
|
+
"LOG_LEVEL": "INFO"
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**Note**: `AIRTABLE_BASE_ID` is optional. Omit it to discover bases using `list_bases` tool.
|
|
161
|
+
|
|
162
|
+
#### 📦 JavaScript Configuration (Standard)
|
|
94
163
|
|
|
95
164
|
Add to your Claude Desktop configuration file:
|
|
96
165
|
|
|
@@ -102,19 +171,21 @@ Add to your Claude Desktop configuration file:
|
|
|
102
171
|
"mcpServers": {
|
|
103
172
|
"airtable": {
|
|
104
173
|
"command": "npx",
|
|
105
|
-
"args": [
|
|
106
|
-
|
|
107
|
-
"
|
|
108
|
-
"
|
|
109
|
-
|
|
110
|
-
"YOUR_BASE_ID"
|
|
111
|
-
]
|
|
174
|
+
"args": ["@rashidazarang/airtable-mcp"],
|
|
175
|
+
"env": {
|
|
176
|
+
"AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN",
|
|
177
|
+
"AIRTABLE_BASE_ID": "YOUR_BASE_ID"
|
|
178
|
+
}
|
|
112
179
|
}
|
|
113
180
|
}
|
|
114
181
|
}
|
|
115
182
|
```
|
|
116
183
|
|
|
117
|
-
|
|
184
|
+
**Note**: `AIRTABLE_BASE_ID` is optional. Omit it to discover bases using `list_bases` tool.
|
|
185
|
+
|
|
186
|
+
#### Configuration Without Base ID (New!)
|
|
187
|
+
|
|
188
|
+
Start without specifying a base and discover them dynamically:
|
|
118
189
|
|
|
119
190
|
```json
|
|
120
191
|
{
|
|
@@ -123,14 +194,15 @@ Add to your Claude Desktop configuration file:
|
|
|
123
194
|
"command": "npx",
|
|
124
195
|
"args": ["@rashidazarang/airtable-mcp"],
|
|
125
196
|
"env": {
|
|
126
|
-
"AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN"
|
|
127
|
-
"AIRTABLE_BASE_ID": "YOUR_BASE_ID"
|
|
197
|
+
"AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN"
|
|
128
198
|
}
|
|
129
199
|
}
|
|
130
200
|
}
|
|
131
201
|
}
|
|
132
202
|
```
|
|
133
203
|
|
|
204
|
+
Then use the `list_bases` tool to discover your accessible bases!
|
|
205
|
+
|
|
134
206
|
### Step 5: Restart Your MCP Client
|
|
135
207
|
|
|
136
208
|
After configuration, restart Claude Desktop or your MCP client to load the Airtable server.
|
|
@@ -139,8 +211,41 @@ After configuration, restart Claude Desktop or your MCP client to load the Airta
|
|
|
139
211
|
|
|
140
212
|
Once configured, you can interact with your Airtable data naturally:
|
|
141
213
|
|
|
142
|
-
###
|
|
214
|
+
### 🔷 TypeScript Development
|
|
215
|
+
|
|
216
|
+
```typescript
|
|
217
|
+
import {
|
|
218
|
+
AirtableMCPServer,
|
|
219
|
+
ListRecordsInput,
|
|
220
|
+
AnalyzeDataPrompt
|
|
221
|
+
} from '@rashidazarang/airtable-mcp/types';
|
|
222
|
+
|
|
223
|
+
const server = new AirtableMCPServer();
|
|
224
|
+
|
|
225
|
+
// Type-safe data operations
|
|
226
|
+
const params: ListRecordsInput = {
|
|
227
|
+
table: 'Tasks',
|
|
228
|
+
maxRecords: 10,
|
|
229
|
+
filterByFormula: "Status = 'Active'"
|
|
230
|
+
};
|
|
231
|
+
|
|
232
|
+
const records = await server.handleToolCall('list_records', params);
|
|
233
|
+
|
|
234
|
+
// Type-safe AI analytics
|
|
235
|
+
const analysis: AnalyzeDataPrompt = {
|
|
236
|
+
table: 'Sales',
|
|
237
|
+
analysis_type: 'predictive',
|
|
238
|
+
confidence_level: 0.95
|
|
239
|
+
};
|
|
240
|
+
|
|
241
|
+
const insights = await server.handlePromptGet('analyze_data', analysis);
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### 📦 Natural Language Interactions
|
|
245
|
+
|
|
246
|
+
**Basic Operations**
|
|
143
247
|
```
|
|
248
|
+
"List all my accessible Airtable bases"
|
|
144
249
|
"Show me all records in the Projects table"
|
|
145
250
|
"Create a new task with priority 'High' and due date tomorrow"
|
|
146
251
|
"Update the status of task ID rec123 to 'Completed'"
|
|
@@ -149,7 +254,7 @@ Once configured, you can interact with your Airtable data naturally:
|
|
|
149
254
|
"Search for records where Status equals 'Active'"
|
|
150
255
|
```
|
|
151
256
|
|
|
152
|
-
|
|
257
|
+
**Webhook Operations (v1.4.0+)**
|
|
153
258
|
```
|
|
154
259
|
"Create a webhook for my table that notifies https://my-app.com/webhook"
|
|
155
260
|
"List all active webhooks in my base"
|
|
@@ -157,7 +262,7 @@ Once configured, you can interact with your Airtable data naturally:
|
|
|
157
262
|
"Delete webhook ach123xyz"
|
|
158
263
|
```
|
|
159
264
|
|
|
160
|
-
|
|
265
|
+
**Schema Management (v1.5.0+)**
|
|
161
266
|
```
|
|
162
267
|
"List all my accessible Airtable bases"
|
|
163
268
|
"Show me the complete schema for this base"
|
|
@@ -167,7 +272,7 @@ Once configured, you can interact with your Airtable data naturally:
|
|
|
167
272
|
"What field types are available in Airtable?"
|
|
168
273
|
```
|
|
169
274
|
|
|
170
|
-
|
|
275
|
+
**Batch Operations & Attachments (v1.6.0+)**
|
|
171
276
|
```
|
|
172
277
|
"Create 5 new records at once in the Tasks table"
|
|
173
278
|
"Update multiple records with new status values"
|
|
@@ -248,13 +353,19 @@ Once configured, you can interact with your Airtable data naturally:
|
|
|
248
353
|
| `list_collaborators` | View base collaborators and their permission levels |
|
|
249
354
|
| `list_shares` | List shared views and their public configurations |
|
|
250
355
|
|
|
251
|
-
### 🤖 AI
|
|
252
|
-
| Prompt | Description |
|
|
253
|
-
|
|
254
|
-
| `analyze_data` |
|
|
255
|
-
| `create_report` |
|
|
256
|
-
| `data_insights` |
|
|
257
|
-
| `optimize_workflow` |
|
|
356
|
+
### 🤖 AI Intelligence Suite (10 prompts) - **New in v3.0.0**
|
|
357
|
+
| Prompt | Description | Enterprise Features |
|
|
358
|
+
|--------|-------------|-------------------|
|
|
359
|
+
| `analyze_data` | Advanced statistical analysis with ML insights | Confidence intervals, anomaly detection |
|
|
360
|
+
| `create_report` | Intelligent report generation with recommendations | Multi-stakeholder customization, ROI analysis |
|
|
361
|
+
| `data_insights` | Business intelligence and pattern discovery | Cross-table correlations, predictive indicators |
|
|
362
|
+
| `optimize_workflow` | AI-powered automation recommendations | Change management, implementation roadmaps |
|
|
363
|
+
| `smart_schema_design` | Database optimization with best practices | Compliance-aware (GDPR, HIPAA), scalability planning |
|
|
364
|
+
| `data_quality_audit` | Comprehensive quality assessment and fixes | Automated remediation, governance frameworks |
|
|
365
|
+
| `predictive_analytics` | Forecasting and trend prediction | Multiple algorithms, uncertainty quantification |
|
|
366
|
+
| `natural_language_query` | Process human questions intelligently | Context awareness, confidence scoring |
|
|
367
|
+
| `smart_data_transformation` | AI-assisted data processing | Quality rules, audit trails, optimization |
|
|
368
|
+
| `automation_recommendations` | Workflow optimization suggestions | Technical feasibility, cost-benefit analysis |
|
|
258
369
|
|
|
259
370
|
## 🔧 Advanced Configuration
|
|
260
371
|
|
|
@@ -304,7 +415,28 @@ If you cloned the repository:
|
|
|
304
415
|
|
|
305
416
|
## 🧪 Testing
|
|
306
417
|
|
|
307
|
-
|
|
418
|
+
### 🔷 TypeScript Testing
|
|
419
|
+
|
|
420
|
+
Run the comprehensive TypeScript test suite:
|
|
421
|
+
|
|
422
|
+
```bash
|
|
423
|
+
# Install dependencies first
|
|
424
|
+
npm install
|
|
425
|
+
|
|
426
|
+
# Run TypeScript type checking
|
|
427
|
+
npm run test:types
|
|
428
|
+
|
|
429
|
+
# Run full TypeScript test suite
|
|
430
|
+
npm run test:ts
|
|
431
|
+
|
|
432
|
+
# Build and test TypeScript server
|
|
433
|
+
npm run build
|
|
434
|
+
npm run start:ts
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
### 📦 JavaScript Testing
|
|
438
|
+
|
|
439
|
+
Run the comprehensive test suite to verify all 33 tools:
|
|
308
440
|
|
|
309
441
|
```bash
|
|
310
442
|
# Set environment variables first
|
|
@@ -318,7 +450,15 @@ node airtable_simple.js &
|
|
|
318
450
|
./test_v1.6.0_comprehensive.sh
|
|
319
451
|
```
|
|
320
452
|
|
|
321
|
-
The test suite validates:
|
|
453
|
+
The TypeScript test suite validates:
|
|
454
|
+
- **Type Safety**: Compile-time validation of all interfaces
|
|
455
|
+
- **Enterprise Testing**: 33 tools with strict type checking
|
|
456
|
+
- **AI Prompt Validation**: All 10 AI templates with proper typing
|
|
457
|
+
- **Error Handling**: Type-safe error management
|
|
458
|
+
- **Performance**: Concurrent operations with type safety
|
|
459
|
+
- **Integration**: Full MCP protocol compliance
|
|
460
|
+
|
|
461
|
+
The JavaScript test suite validates:
|
|
322
462
|
- All 33 tools with real API calls
|
|
323
463
|
- Complete CRUD operations
|
|
324
464
|
- Advanced schema management
|
|
@@ -355,7 +495,14 @@ lsof -ti:8010 | xargs kill -9
|
|
|
355
495
|
|
|
356
496
|
## 📚 Documentation
|
|
357
497
|
|
|
358
|
-
|
|
498
|
+
### 🔷 TypeScript Documentation
|
|
499
|
+
- 📘 [TypeScript Examples](./examples/typescript/) - Complete type-safe usage examples
|
|
500
|
+
- 🏗️ [Type Definitions](./types/) - Comprehensive type definitions for all features
|
|
501
|
+
- 🧪 [TypeScript Testing](./src/test-suite.ts) - Enterprise-grade testing framework
|
|
502
|
+
|
|
503
|
+
### 📦 General Documentation
|
|
504
|
+
- 🎆 [Release Notes v3.1.0](./RELEASE_NOTES_v3.1.0.md) - **Latest TypeScript release**
|
|
505
|
+
- [Release Notes v1.6.0](./RELEASE_NOTES_v1.6.0.md) - Major feature release
|
|
359
506
|
- [Release Notes v1.5.0](./RELEASE_NOTES_v1.5.0.md)
|
|
360
507
|
- [Release Notes v1.4.0](./RELEASE_NOTES_v1.4.0.md)
|
|
361
508
|
- [Detailed Setup Guide](./CLAUDE_INTEGRATION.md)
|
|
@@ -364,7 +511,9 @@ lsof -ti:8010 | xargs kill -9
|
|
|
364
511
|
|
|
365
512
|
## 📦 Version History
|
|
366
513
|
|
|
367
|
-
- **
|
|
514
|
+
- **v3.1.0** (2025-08-16) - 🔷 **TypeScript Support**: Enterprise-grade type safety, comprehensive type definitions, dual JS/TS distribution
|
|
515
|
+
- **v3.0.0** (2025-08-16) - 🤖 **Revolutionary AI Agent**: 10 intelligent prompts, predictive analytics, natural language processing
|
|
516
|
+
- **v2.2.3** (2025-08-16) - 🔒 **Security release**: Final XSS vulnerability fixes and enhanced validation
|
|
368
517
|
- **v2.2.0** (2025-08-16) - 🏆 **Major release**: Complete MCP 2024-11-05 protocol implementation
|
|
369
518
|
- **v1.6.0** (2025-08-15) - 🎆 **Major release**: Added batch operations & attachment management (33 total tools)
|
|
370
519
|
- **v1.5.0** (2025-08-15) - Added comprehensive schema management (23 total tools)
|
|
@@ -373,6 +522,24 @@ lsof -ti:8010 | xargs kill -9
|
|
|
373
522
|
- **v1.2.3** (2025-08-11) - Bug fixes and error handling
|
|
374
523
|
- **v1.2.2** (2025-08-10) - Initial stable release
|
|
375
524
|
|
|
525
|
+
## 📂 Project Structure
|
|
526
|
+
|
|
527
|
+
```
|
|
528
|
+
airtable-mcp/
|
|
529
|
+
├── src/ # Source code
|
|
530
|
+
│ ├── index.js # Main entry point
|
|
531
|
+
│ ├── typescript/ # TypeScript implementation
|
|
532
|
+
│ ├── javascript/ # JavaScript implementation
|
|
533
|
+
│ └── python/ # Python implementation
|
|
534
|
+
├── dist/ # Compiled TypeScript output
|
|
535
|
+
├── docs/ # Documentation
|
|
536
|
+
│ ├── guides/ # User guides
|
|
537
|
+
│ └── releases/ # Release notes
|
|
538
|
+
├── tests/ # Test files
|
|
539
|
+
├── examples/ # Usage examples
|
|
540
|
+
└── types/ # TypeScript type definitions
|
|
541
|
+
```
|
|
542
|
+
|
|
376
543
|
## 🤝 Contributing
|
|
377
544
|
|
|
378
545
|
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
|
|
@@ -394,4 +561,4 @@ MIT License - see [LICENSE](./LICENSE) file for details
|
|
|
394
561
|
|
|
395
562
|
---
|
|
396
563
|
|
|
397
|
-
**Version**:
|
|
564
|
+
**Version**: 3.2.4 | **Status**: 🔷 TypeScript Fixed + 🤖 AI Agent | **MCP Protocol**: 2024-11-05 Complete | **Type Safety**: Enterprise-Grade | **Intelligence**: 10 AI Prompts | **Security**: Fully Patched (XSS Fixed) | **Last Updated**: September 9, 2025
|
package/bin/airtable-mcp.js
CHANGED
|
@@ -2,43 +2,23 @@
|
|
|
2
2
|
|
|
3
3
|
const { spawn } = require('child_process');
|
|
4
4
|
const path = require('path');
|
|
5
|
+
const fs = require('fs');
|
|
5
6
|
|
|
6
|
-
|
|
7
|
-
const getPythonPath = () => {
|
|
8
|
-
try {
|
|
9
|
-
const whichPython = require('child_process').execSync('which python3.10').toString().trim();
|
|
10
|
-
return whichPython;
|
|
11
|
-
} catch (e) {
|
|
12
|
-
try {
|
|
13
|
-
const whichPython = require('child_process').execSync('which python3').toString().trim();
|
|
14
|
-
return whichPython;
|
|
15
|
-
} catch (e) {
|
|
16
|
-
return 'python';
|
|
17
|
-
}
|
|
18
|
-
}
|
|
19
|
-
};
|
|
7
|
+
const distServer = path.join(__dirname, '..', 'dist', 'typescript', 'airtable-mcp-server.js');
|
|
20
8
|
|
|
21
|
-
|
|
22
|
-
|
|
9
|
+
if (!fs.existsSync(distServer)) {
|
|
10
|
+
console.error('Airtable MCP: compiled server not found.');
|
|
11
|
+
console.error('Run `npm install && npm run build` and try again.');
|
|
12
|
+
process.exit(1);
|
|
13
|
+
}
|
|
23
14
|
|
|
24
|
-
// Get the arguments
|
|
25
15
|
const args = process.argv.slice(2);
|
|
26
|
-
|
|
27
|
-
// Construct the full command
|
|
28
|
-
const serverProcess = spawn(pythonPath, [serverScript, ...args], {
|
|
16
|
+
const child = spawn(process.execPath, [distServer, ...args], {
|
|
29
17
|
stdio: 'inherit',
|
|
18
|
+
env: process.env,
|
|
30
19
|
});
|
|
31
20
|
|
|
32
|
-
|
|
33
|
-
serverProcess.on('close', (code) => {
|
|
34
|
-
process.exit(code);
|
|
35
|
-
});
|
|
36
|
-
|
|
37
|
-
// Handle signals
|
|
38
|
-
process.on('SIGINT', () => {
|
|
39
|
-
serverProcess.kill('SIGINT');
|
|
40
|
-
});
|
|
21
|
+
child.on('close', (code) => process.exit(code));
|
|
41
22
|
|
|
42
|
-
process.on('
|
|
43
|
-
|
|
44
|
-
});
|
|
23
|
+
process.on('SIGINT', () => child.kill('SIGINT'));
|
|
24
|
+
process.on('SIGTERM', () => child.kill('SIGTERM'));
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
|
+
exports.start = start;
|
|
5
|
+
// Import via require to avoid TS type resolution issues with deep subpath exports
|
|
6
|
+
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
7
|
+
const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp');
|
|
8
|
+
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
9
|
+
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio');
|
|
10
|
+
const config_1 = require("./app/config");
|
|
11
|
+
const logger_1 = require("./app/logger");
|
|
12
|
+
const rateLimiter_1 = require("./app/rateLimiter");
|
|
13
|
+
const airtable_client_1 = require("./app/airtable-client");
|
|
14
|
+
const governance_1 = require("./app/governance");
|
|
15
|
+
const exceptions_1 = require("./app/exceptions");
|
|
16
|
+
const tools_1 = require("./app/tools");
|
|
17
|
+
const PROTOCOL_VERSION = '2024-11-05';
|
|
18
|
+
function buildContext(config, rootLogger) {
|
|
19
|
+
const baseLimiter = new rateLimiter_1.RateLimiter({ maxRequestsPerSecond: 5 });
|
|
20
|
+
const patLimiter = new rateLimiter_1.RateLimiter({ maxRequestsPerSecond: 50 });
|
|
21
|
+
const airtable = new airtable_client_1.AirtableClient(config.auth.personalAccessToken, {
|
|
22
|
+
baseLimiter,
|
|
23
|
+
patLimiter,
|
|
24
|
+
logger: rootLogger.child({ component: 'airtable_client' }),
|
|
25
|
+
userAgent: `airtable-brain-mcp/${config.version}`,
|
|
26
|
+
patHash: config.auth.patHash
|
|
27
|
+
});
|
|
28
|
+
const governance = new governance_1.GovernanceService(config.governance);
|
|
29
|
+
const exceptions = new exceptions_1.ExceptionStore(config.exceptionQueueSize, rootLogger);
|
|
30
|
+
return {
|
|
31
|
+
config,
|
|
32
|
+
logger: rootLogger,
|
|
33
|
+
airtable,
|
|
34
|
+
governance,
|
|
35
|
+
exceptions
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
async function start() {
|
|
39
|
+
const config = (0, config_1.loadConfig)();
|
|
40
|
+
const logger = new logger_1.Logger(config.logLevel, { component: 'server' });
|
|
41
|
+
const context = buildContext(config, logger);
|
|
42
|
+
const server = new McpServer({
|
|
43
|
+
name: 'airtable-brain',
|
|
44
|
+
version: config.version,
|
|
45
|
+
protocolVersion: PROTOCOL_VERSION
|
|
46
|
+
}, {
|
|
47
|
+
capabilities: {
|
|
48
|
+
tools: {},
|
|
49
|
+
prompts: {},
|
|
50
|
+
resources: {}
|
|
51
|
+
},
|
|
52
|
+
instructions: 'Use describe and query tools for read flows. All mutations require diff review and idempotency keys.'
|
|
53
|
+
});
|
|
54
|
+
(0, tools_1.registerAllTools)(server, context);
|
|
55
|
+
const transport = new StdioServerTransport();
|
|
56
|
+
await server.connect(transport);
|
|
57
|
+
logger.info('Airtable Brain MCP server ready', {
|
|
58
|
+
version: config.version,
|
|
59
|
+
protocolVersion: PROTOCOL_VERSION
|
|
60
|
+
});
|
|
61
|
+
const shutdown = async (signal) => {
|
|
62
|
+
logger.info('Shutting down due to signal', { signal });
|
|
63
|
+
await server.close();
|
|
64
|
+
await transport.close();
|
|
65
|
+
process.exit(0);
|
|
66
|
+
};
|
|
67
|
+
process.on('SIGINT', () => void shutdown('SIGINT'));
|
|
68
|
+
process.on('SIGTERM', () => void shutdown('SIGTERM'));
|
|
69
|
+
}
|
|
70
|
+
if (typeof require !== 'undefined' && require.main === module) {
|
|
71
|
+
start().catch((error) => {
|
|
72
|
+
// eslint-disable-next-line no-console
|
|
73
|
+
console.error('Failed to start Airtable Brain MCP server:', error);
|
|
74
|
+
process.exit(1);
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
//# sourceMappingURL=airtable-mcp-server.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"airtable-mcp-server.js","sourceRoot":"","sources":["../../src/typescript/airtable-mcp-server.ts"],"names":[],"mappings":"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"}
|