@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.
Files changed (89) hide show
  1. package/README.md +210 -43
  2. package/bin/airtable-mcp.js +12 -32
  3. package/dist/typescript/airtable-mcp-server.js +77 -0
  4. package/dist/typescript/airtable-mcp-server.js.map +1 -0
  5. package/dist/typescript/app/airtable-client.js +325 -0
  6. package/dist/typescript/app/airtable-client.js.map +1 -0
  7. package/dist/typescript/app/config.js +141 -0
  8. package/dist/typescript/app/config.js.map +1 -0
  9. package/dist/typescript/app/context.js +3 -0
  10. package/dist/typescript/app/context.js.map +1 -0
  11. package/dist/typescript/app/exceptions.js +85 -0
  12. package/dist/typescript/app/exceptions.js.map +1 -0
  13. package/dist/typescript/app/governance.js +58 -0
  14. package/dist/typescript/app/governance.js.map +1 -0
  15. package/dist/typescript/app/logger.js +47 -0
  16. package/dist/typescript/app/logger.js.map +1 -0
  17. package/dist/typescript/app/rateLimiter.js +37 -0
  18. package/dist/typescript/app/rateLimiter.js.map +1 -0
  19. package/dist/typescript/app/tools/create.js +54 -0
  20. package/dist/typescript/app/tools/create.js.map +1 -0
  21. package/dist/typescript/app/tools/describe.js +146 -0
  22. package/dist/typescript/app/tools/describe.js.map +1 -0
  23. package/dist/typescript/app/tools/handleError.js +54 -0
  24. package/dist/typescript/app/tools/handleError.js.map +1 -0
  25. package/dist/typescript/app/tools/index.js +24 -0
  26. package/dist/typescript/app/tools/index.js.map +1 -0
  27. package/dist/typescript/app/tools/listBases.js +52 -0
  28. package/dist/typescript/app/tools/listBases.js.map +1 -0
  29. package/dist/typescript/app/tools/listExceptions.js +18 -0
  30. package/dist/typescript/app/tools/listExceptions.js.map +1 -0
  31. package/dist/typescript/app/tools/listGovernance.js +17 -0
  32. package/dist/typescript/app/tools/listGovernance.js.map +1 -0
  33. package/dist/typescript/app/tools/query.js +126 -0
  34. package/dist/typescript/app/tools/query.js.map +1 -0
  35. package/dist/typescript/app/tools/update.js +56 -0
  36. package/dist/typescript/app/tools/update.js.map +1 -0
  37. package/dist/typescript/app/tools/upsert.js +65 -0
  38. package/dist/typescript/app/tools/upsert.js.map +1 -0
  39. package/dist/typescript/app/tools/webhooks.js +44 -0
  40. package/dist/typescript/app/tools/webhooks.js.map +1 -0
  41. package/dist/typescript/app/types.js +282 -0
  42. package/dist/typescript/app/types.js.map +1 -0
  43. package/dist/typescript/apps-sdk/mappers.js +70 -0
  44. package/dist/typescript/apps-sdk/mappers.js.map +1 -0
  45. package/dist/typescript/errors.js +75 -0
  46. package/dist/typescript/errors.js.map +1 -0
  47. package/dist/typescript/index.js +27 -0
  48. package/dist/typescript/index.js.map +1 -0
  49. package/package.json +63 -17
  50. package/tsconfig.json +44 -0
  51. package/types/typescript/airtable-mcp-server.d.ts +2 -0
  52. package/types/typescript/app/airtable-client.d.ts +49 -0
  53. package/types/typescript/app/config.d.ts +16 -0
  54. package/types/typescript/app/context.d.ts +12 -0
  55. package/types/typescript/app/exceptions.d.ts +12 -0
  56. package/types/typescript/app/governance.d.ts +18 -0
  57. package/types/typescript/app/logger.d.ts +13 -0
  58. package/types/typescript/app/rateLimiter.d.ts +13 -0
  59. package/types/typescript/app/tools/create.d.ts +3 -0
  60. package/types/typescript/app/tools/describe.d.ts +3 -0
  61. package/types/typescript/app/tools/handleError.d.ts +8 -0
  62. package/types/typescript/app/tools/index.d.ts +3 -0
  63. package/types/typescript/app/tools/listBases.d.ts +33 -0
  64. package/types/typescript/app/tools/listExceptions.d.ts +3 -0
  65. package/types/typescript/app/tools/listGovernance.d.ts +3 -0
  66. package/types/typescript/app/tools/query.d.ts +3 -0
  67. package/types/typescript/app/tools/update.d.ts +3 -0
  68. package/types/typescript/app/tools/upsert.d.ts +3 -0
  69. package/types/typescript/app/tools/webhooks.d.ts +3 -0
  70. package/types/typescript/app/types.d.ts +830 -0
  71. package/types/typescript/apps-sdk/mappers.d.ts +53 -0
  72. package/types/typescript/errors.d.ts +55 -0
  73. package/types/typescript/index.d.ts +10 -0
  74. package/types/typescript/prompt-templates.d.ts +5 -0
  75. package/types/typescript/test-suite.d.ts +33 -0
  76. package/types/typescript/tools-schemas.d.ts +5 -0
  77. package/airtable_simple.js +0 -1561
  78. package/airtable_simple_production.js +0 -1564
  79. package/examples/airtable-crud-example.js +0 -203
  80. package/examples/building-mcp.md +0 -6666
  81. package/examples/claude_config.json +0 -4
  82. package/examples/claude_simple_config.json +0 -7
  83. package/examples/env-demo.js +0 -172
  84. package/examples/example-tasks-update.json +0 -23
  85. package/examples/example-tasks.json +0 -26
  86. package/examples/example_usage.md +0 -124
  87. package/examples/python_debug_patch.txt +0 -27
  88. package/examples/sample-transform.js +0 -76
  89. package/examples/windsurf_mcp_config.json +0 -17
package/README.md CHANGED
@@ -3,21 +3,47 @@
3
3
  [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/rashidazarang/airtable-mcp)](https://archestra.ai/mcp-catalog/rashidazarang__airtable-mcp)
4
4
  [![smithery badge](https://smithery.ai/badge/@rashidazarang/airtable-mcp)](https://smithery.ai/server/@rashidazarang/airtable-mcp)
5
5
  ![Airtable](https://img.shields.io/badge/Airtable-18BFFF?style=for-the-badge&logo=Airtable&logoColor=white)
6
- [![MCP](https://img.shields.io/badge/MCP-2.2.1-blue)](https://github.com/rashidazarang/airtable-mcp)
7
- [![Security](https://img.shields.io/badge/Security-Enhanced-green)](https://github.com/rashidazarang/airtable-mcp)
6
+ [![MCP](https://img.shields.io/badge/MCP-3.2.5-blue)](https://github.com/rashidazarang/airtable-mcp)
7
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
8
+ [![AI Agent](https://img.shields.io/badge/AI_Agent-Enhanced-purple)](https://github.com/rashidazarang/airtable-mcp)
9
+ [![Security](https://img.shields.io/badge/Security-Enterprise-green)](https://github.com/rashidazarang/airtable-mcp)
8
10
  [![Protocol](https://img.shields.io/badge/Protocol-2024--11--05-success)](https://modelcontextprotocol.io/)
9
11
 
10
- 🏆 **Complete MCP 2024-11-05 Implementation** - A production-ready Model Context Protocol server that enables AI assistants like Claude to interact with your Airtable bases through a secure, feature-complete interface.
11
-
12
- ## 🚀 Latest: Enhanced v2.2.1
13
-
14
- **Complete MCP Protocol Support** with enterprise security:
15
- - **Prompts** - 4 AI-powered templates for data analysis
16
- - **Sampling** - LLM integration for intelligent operations
17
- - **Roots** - Filesystem boundary management
18
- - ✅ **Logging** - Dynamic structured logging
19
- - **OAuth2** - PKCE authentication flow
20
- - **Security** - XSS protection, input validation, CSP headers
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
- #### Option A: Install via NPM (Recommended)
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
- #### Option B: Clone from GitHub
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
- #### For Claude Desktop
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
- "@rashidazarang/airtable-mcp",
107
- "--token",
108
- "YOUR_AIRTABLE_TOKEN",
109
- "--base",
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
- #### For Environment Variables (More Secure)
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
- ### Basic Operations
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
- ### Webhook Operations (v1.4.0+)
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
- ### Schema Management (v1.5.0+)
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
- ### Batch Operations & Attachments (v1.6.0+)
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 Integration (4 prompts) - **New in v2.2.0**
252
- | Prompt | Description |
253
- |--------|-------------|
254
- | `analyze_data` | AI-powered data analysis with trends and insights |
255
- | `create_report` | Generate comprehensive reports with AI assistance |
256
- | `data_insights` | Discover hidden correlations and patterns |
257
- | `optimize_workflow` | Get AI recommendations for workflow improvements |
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
- Run the comprehensive test suite to verify all 12 tools:
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
- - 🎆 [Release Notes v1.6.0](./RELEASE_NOTES_v1.6.0.md) - **Latest major release**
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
- - **v2.2.1** (2025-08-16) - 🔒 **Security release**: Fixed XSS and format string vulnerabilities
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**: 2.2.1 | **Status**: Production Ready | **MCP Protocol**: 2024-11-05 Complete | **Last Updated**: August 16, 2025
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
@@ -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
- // Find the Python interpreter
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
- const pythonPath = getPythonPath();
22
- const serverScript = path.join(__dirname, '..', 'airtable_mcp', 'src', 'server.py');
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
- // Handle process exit
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('SIGTERM', () => {
43
- serverProcess.kill('SIGTERM');
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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"}