@rashidazarang/airtable-mcp 3.1.0 → 3.2.8

package/package.json

@@ -1,33 +1,41 @@
 {
   "name": "@rashidazarang/airtable-mcp",
-  "version": "3.1.0",
+  "version": "3.2.8",
   "description": "Advanced AI-powered Airtable MCP server with TypeScript support, intelligent analytics, predictive modeling, and enterprise automation capabilities",
-  "main": "airtable_simple_production.js",
+  "main": "dist/typescript/index.js",
   "exports": {
     ".": {
-      "import": "./dist/airtable-mcp-server.js",
-      "require": "./airtable_simple_production.js",
-      "types": "./types/index.d.ts"
+      "import": "./dist/typescript/index.js",
+      "require": "./dist/typescript/index.js",
+      "types": "./types/typescript/index.d.ts"
     },
-    "./types": "./types/index.d.ts",
-    "./types/*": "./types/*.d.ts"
+    "./types": "./types/typescript/app/types.d.ts",
+    "./types/*": "./types/typescript/**/*.d.ts"
   },
   "bin": {
-    "airtable-mcp": "./airtable_simple_production.js",
-    "airtable-mcp-ts": "./dist/airtable-mcp-server.js"
+    "airtable-mcp": "./bin/airtable-mcp.js",
+    "airtable-mcp-cli": "./bin/airtable-crud-cli.js"
   },
   "scripts": {
-    "start": "node airtable_simple_production.js",
-    "start:ts": "node dist/airtable-mcp-server.js",
-    "start:python": "python3.10 inspector_server.py",
-    "test": "node test_mcp_comprehensive.js",
-    "test:quick": "./quick_test.sh",
-    "test:types": "tsc --noEmit",
-    "test:ts": "npm run build && node dist/test-suite.js",
     "build": "tsc",
     "build:watch": "tsc --watch",
-    "dev": "node airtable_simple_production.js --token YOUR_TOKEN --base YOUR_BASE_ID",
-    "dev:ts": "npm run build && npm run start:ts"
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "start": "node dist/typescript/airtable-mcp-server.js",
+    "start:dev": "ts-node src/typescript/airtable-mcp-server.ts",
+    "start:js": "node src/javascript/airtable_simple_production.js",
+    "test": "jest",
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest tests/integration",
+    "test:e2e": "jest tests/e2e",
+    "test:types": "tsc --noEmit",
+    "lint": "eslint src/**/*.{js,ts}",
+    "lint:fix": "eslint src/**/*.{js,ts} --fix",
+    "format": "prettier --write \"src/**/*.{js,ts,json,md}\"",
+    "format:check": "prettier --check \"src/**/*.{js,ts,json,md}\"",
+    "dev": "nodemon --watch src --exec ts-node src/typescript/airtable-mcp-server.ts",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "airtable",
@@ -38,35 +46,45 @@
     "ai",
     "database",
     "typescript",
-    "types"
+    "automation",
+    "enterprise",
+    "analytics"
   ],
   "files": [
-    "airtable_simple.js",
-    "airtable_simple_production.js",
     "dist/",
     "types/",
+    "bin/",
     "README.md",
     "LICENSE",
     "package.json",
-    "tsconfig.json",
-    "examples/",
-    "bin/"
+    "tsconfig.json"
   ],
-  "types": "types/index.d.ts",
+  "types": "types/typescript/index.d.ts",
   "author": "Rashid Azarang",
   "license": "MIT",
   "dependencies": {
-    "@smithery/cli": "^1.0.0",
-    "airtable": "^0.12.2",
-    "dotenv": "^16.0.0"
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "dotenv": "^16.0.0",
+    "zod": "^4.2.1",
+    "zod-to-json-schema": "^3.25.0"
   },
   "devDependencies": {
-    "typescript": "^5.3.0",
+    "@types/dotenv": "^8.2.0",
+    "@types/jest": "^29.5.0",
     "@types/node": "^20.10.0",
-    "@types/dotenv": "^8.2.0"
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.50.0",
+    "eslint-config-prettier": "^9.0.0",
+    "jest": "^29.7.0",
+    "nodemon": "^3.0.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.3.0"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "repository": {
     "type": "git",

package/tsconfig.json

@@ -23,16 +23,22 @@
     "exactOptionalPropertyTypes": true,
     "noImplicitOverride": true,
     "noPropertyAccessFromIndexSignature": false,
-    "noUncheckedIndexedAccess": true
+    "noUncheckedIndexedAccess": true,
+    "types": []
   },
   "include": [
-    "src/**/*"
+    "src/typescript/**/*"
   ],
   "exclude": [
     "node_modules",
     "dist",
     "types",
     "**/*.test.ts",
-    "**/*.spec.ts"
+    "**/*.spec.ts",
+    "src/javascript/**/*",
+    "src/python/**/*",
+    "src/typescript/prompt-templates.ts",
+    "src/typescript/tools-schemas.ts",
+    "src/typescript/**/*.d.ts"
   ]
-}
+}

package/types/typescript/airtable-mcp-server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function start(): Promise<void>;

package/types/typescript/app/airtable-client.d.ts

@@ -0,0 +1,50 @@
+import { RateLimiter } from './rateLimiter';
+import { Logger } from './logger';
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /**
+     * Path including leading slash and version segment, e.g. `/v0/meta/bases/app123`.
+     */
+    path: string;
+    query?: Record<string, string | number | boolean | Array<string | number | boolean> | undefined>;
+    body?: unknown;
+    baseId?: string;
+    idempotencyKey?: string;
+}
+interface ClientOptions {
+    baseLimiter: RateLimiter;
+    patLimiter: RateLimiter;
+    logger: Logger;
+    userAgent: string;
+    patHash: string;
+    maxRetries?: number;
+}
+export declare class AirtableClient {
+    private readonly baseLimiter;
+    private readonly patLimiter;
+    private readonly logger;
+    private readonly userAgent;
+    private readonly pat;
+    private readonly patHash;
+    private readonly maxRetries;
+    constructor(personalAccessToken: string, options: ClientOptions);
+    listBases(): Promise<{
+        bases: unknown[];
+    }>;
+    getBase(baseId: string): Promise<unknown>;
+    listTables(baseId: string): Promise<{
+        tables: unknown[];
+    }>;
+    queryRecords<T = unknown>(baseId: string, table: string, query?: RequestOptions['query']): Promise<T>;
+    createRecords<T = unknown>(baseId: string, table: string, payload: unknown, idempotencyKey?: string): Promise<T>;
+    updateRecords<T = unknown>(baseId: string, table: string, payload: unknown, idempotencyKey?: string): Promise<T>;
+    upsertRecords<T = unknown>(baseId: string, table: string, payload: unknown, idempotencyKey?: string): Promise<T>;
+    private request;
+    private withRetry;
+    private backoffWithJitter;
+    private performRequest;
+    private toDomainError;
+    private safeExtractErrorInfo;
+    private extractRequestId;
+}
+export {};

package/types/typescript/app/config.d.ts

@@ -0,0 +1,17 @@
+import { GovernanceSnapshot } from './types';
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+export interface AirtableAuthConfig {
+    personalAccessToken: string;
+    patHash: string;
+    defaultBaseId?: string;
+    allowedBases: string[];
+    tokenFormatWarnings: string[];
+}
+export interface AppConfig {
+    version: string;
+    auth: AirtableAuthConfig;
+    governance: GovernanceSnapshot;
+    logLevel: LogLevel;
+    exceptionQueueSize: number;
+}
+export declare function loadConfig(): AppConfig;

package/types/typescript/app/context.d.ts

@@ -0,0 +1,12 @@
+import { AppConfig } from './config';
+import { AirtableClient } from './airtable-client';
+import { GovernanceService } from './governance';
+import { ExceptionStore } from './exceptions';
+import { Logger } from './logger';
+export interface AppContext {
+    config: AppConfig;
+    logger: Logger;
+    airtable: AirtableClient;
+    governance: GovernanceService;
+    exceptions: ExceptionStore;
+}

package/types/typescript/app/exceptions.d.ts

@@ -0,0 +1,12 @@
+import { Logger } from './logger';
+import { ListExceptionsInput, ListExceptionsOutput } from './types';
+import { AirtableBrainError } from '../errors';
+export declare class ExceptionStore {
+    private readonly capacity;
+    private readonly items;
+    private readonly logger;
+    constructor(capacity: number, logger: Logger);
+    record(error: AirtableBrainError, summary: string, details?: string, proposedFix?: Record<string, unknown>): void;
+    list(params: ListExceptionsInput): ListExceptionsOutput;
+    private parseCursor;
+}

package/types/typescript/app/governance.d.ts

@@ -0,0 +1,18 @@
+import { GovernanceSnapshot } from './types';
+type Operation = GovernanceSnapshot['allowedOperations'][number];
+export declare class GovernanceService {
+    private readonly snapshot;
+    private readonly tablesByBase;
+    constructor(snapshot: GovernanceSnapshot);
+    ensureBaseAllowed(baseId: string): void;
+    ensureOperationAllowed(operation: Operation): void;
+    ensureTableAllowed(baseId: string, table: string): void;
+    listPiiPolicies(baseId: string, table: string): Array<{
+        field: string;
+        policy: string;
+    }>;
+    getSnapshot(): GovernanceSnapshot;
+    isTableAllowed(baseId: string, table: string): boolean;
+    private buildTableIndex;
+}
+export {};

package/types/typescript/app/logger.d.ts

@@ -0,0 +1,13 @@
+import { LogLevel } from './config';
+export type LogMetadata = Record<string, unknown>;
+export declare class Logger {
+    private readonly level;
+    private readonly context;
+    constructor(level: LogLevel, context?: LogMetadata);
+    child(context: LogMetadata): Logger;
+    error(message: string, metadata?: LogMetadata): void;
+    warn(message: string, metadata?: LogMetadata): void;
+    info(message: string, metadata?: LogMetadata): void;
+    debug(message: string, metadata?: LogMetadata): void;
+    private log;
+}

package/types/typescript/app/rateLimiter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lightweight token-based rate limiter to enforce Airtable quotas.
+ * Maintains per-key queues to preserve ordering and fairness.
+ */
+export declare class RateLimiter {
+    private readonly minIntervalMs;
+    private readonly lockByKey;
+    private readonly nextAvailableByKey;
+    constructor({ maxRequestsPerSecond }: {
+        maxRequestsPerSecond: number;
+    });
+    schedule(key: string): Promise<void>;
+}

package/types/typescript/app/sanitize.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Sanitization utilities for Airtable formula strings.
+ *
+ * Prevents formula injection attacks by escaping user-provided
+ * strings before they're interpolated into Airtable formulas.
+ */
+/**
+ * Escapes a string for safe use within Airtable formula string literals.
+ *
+ * Airtable formulas use double quotes for strings. This function escapes:
+ * - Double quotes (") -> \"
+ * - Backslashes (\) -> \\
+ *
+ * @example
+ * // Safe interpolation in formula:
+ * const formula = `Name = "${escapeFormulaString(userInput)}"`;
+ *
+ * @param input - The user-provided string to escape
+ * @returns The escaped string safe for use in formulas
+ */
+export declare function escapeFormulaString(input: string): string;
+/**
+ * Validates that a formula string doesn't contain obvious injection attempts.
+ *
+ * This is a heuristic check - not foolproof, but catches common patterns.
+ * Should be used in addition to escapeFormulaString, not as a replacement.
+ *
+ * @param formula - The complete formula string to validate
+ * @returns Object with isValid flag and optional warning message
+ */
+export declare function validateFormula(formula: string): {
+    isValid: boolean;
+    warning?: string;
+};
+/**
+ * Builds a safe FIND formula for searching text in a field.
+ *
+ * @param searchTerm - The user-provided search term
+ * @param fieldName - The field name to search in
+ * @returns A safe FIND formula string
+ */
+export declare function buildSafeFindFormula(searchTerm: string, fieldName: string): string;
+/**
+ * Builds a safe equality comparison formula.
+ *
+ * @param fieldName - The field name to compare
+ * @param value - The user-provided value to compare against
+ * @returns A safe equality formula string
+ */
+export declare function buildSafeEqualityFormula(fieldName: string, value: string): string;

package/types/typescript/app/tools/create.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+export declare function registerCreateTool(server: McpServer, ctx: AppContext): void;

package/types/typescript/app/tools/describe.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+export declare function registerDescribeTool(server: McpServer, ctx: AppContext): void;

package/types/typescript/app/tools/handleError.d.ts

@@ -0,0 +1,8 @@
+import { AppContext } from '../context';
+export declare function handleToolError(toolName: string, error: unknown, ctx: AppContext): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/types/typescript/app/tools/index.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+export declare function registerAllTools(server: McpServer, ctx: AppContext): void;

package/types/typescript/app/tools/listBases.d.ts

@@ -0,0 +1,13 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+import { z } from 'zod';
+declare const listBasesOutputSchema: z.ZodObject<{
+    bases: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        permissionLevel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ListBasesOutput = z.infer<typeof listBasesOutputSchema>;
+export declare function registerListBasesTool(server: McpServer, ctx: AppContext): void;
+export {};

package/types/typescript/app/tools/listExceptions.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+export declare function registerExceptionsTool(server: McpServer, ctx: AppContext): void;

package/types/typescript/app/tools/listGovernance.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+export declare function registerGovernanceTool(server: McpServer, ctx: AppContext): void;

package/types/typescript/app/tools/query.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+export declare function registerQueryTool(server: McpServer, ctx: AppContext): void;

package/types/typescript/app/tools/response.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Utility for creating consistent MCP tool responses.
+ *
+ * The MCP protocol requires the `content` array to contain displayable data.
+ * While `structuredContent` is the newer typed output format, most clients
+ * read from `content` for backwards compatibility.
+ */
+export interface ToolResponse<T> {
+    [x: string]: unknown;
+    structuredContent: T;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}
+/**
+ * Creates a tool response with both structuredContent (for typed clients)
+ * and content array (for backwards compatibility with MCP clients).
+ */
+export declare function createToolResponse<T>(data: T): ToolResponse<T>;

package/types/typescript/app/tools/update.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+export declare function registerUpdateTool(server: McpServer, ctx: AppContext): void;

package/types/typescript/app/tools/upsert.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+export declare function registerUpsertTool(server: McpServer, ctx: AppContext): void;

package/types/typescript/app/tools/webhooks.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AppContext } from '../context';
+export declare function registerWebhookTools(server: McpServer, ctx: AppContext): void;