Airtable

Implements a Model Context Protocol server that translates MCP tool calls into Airtable REST API requests, using a layered architecture with separate protocol handling (src/mcpServer.ts), business logic (src/airtableService.ts), and type validation (src/types.ts). The server registers tools dynamically and routes requests through a centralized dispatcher that manages authentication, error handling, and response transformation. Uses node-fetch for HTTP communication and Bearer token authentication via environment variables.

Exposes Airtable base and table schemas as MCP resources that can be queried by clients to understand available tables, fields, and data types without hardcoding schema information. The server fetches base metadata via Airtable's REST API and converts field definitions into JSON Schema format using zod-to-json-schema, then registers these as MCP resources that clients can request to introspect the database structure. This enables AI agents to dynamically adapt their queries based on actual schema rather than static configuration.

Implements list_records, create_record, update_records, and delete_record tools that map to Airtable REST API endpoints with support for filtering via Airtable's formula syntax, sorting by multiple fields, and selecting specific fields to reduce payload size. The AirtableService class constructs query parameters (filterByFormula, sort, fields) and sends HTTP requests with Bearer token authentication. Responses are parsed and validated against Zod schemas before returning to the MCP client, ensuring type safety across the protocol boundary.

Manages Airtable API authentication by reading a personal access token from the AIRTABLE_API_KEY environment variable and injecting it as a Bearer token in the Authorization header for all HTTP requests. The AirtableService class centralizes credential handling, ensuring tokens are never logged or exposed in error messages. Supports multiple deployment models (direct execution, NPX, Docker) by reading credentials from environment at startup, enabling secure credential injection without hardcoding.

Uses Zod schemas defined in src/types.ts to validate all request parameters and API responses at runtime, catching type mismatches before they reach Airtable. The zod-to-json-schema library automatically converts Zod schemas to JSON Schema format for MCP resource definitions, eliminating manual schema duplication. This enables self-describing tool interfaces where clients can inspect expected parameter types and response structures without consulting documentation.

Supports three deployment models through configurable transport layers: direct Node.js execution (node dist/index.js), NPX package integration (npx airtable-mcp-server for Claude Desktop), and containerized deployment (Docker with environment variable injection). The src/index.ts entry point initializes the MCP server with transport configuration based on deployment context, enabling the same codebase to run in different environments without modification. Uses @modelcontextprotocol/sdk transport abstractions to handle stdio, HTTP, or other protocol transports.

Wraps Airtable REST API responses with error handling that catches HTTP errors, rate limits, and invalid requests, then transforms them into MCP-compatible error responses. The AirtableService class checks HTTP status codes and parses Airtable error messages (e.g., 'INVALID_REQUEST_UNKNOWN', 'RATE_LIMIT_EXCEEDED') to provide actionable feedback to clients. Implements retry logic for transient failures (5xx errors) with exponential backoff, reducing client-side retry complexity.

Handles Airtable's 100-record-per-request limit by implementing pagination through the offset parameter in list_records tool. The server returns pagination metadata (offset, pageSize, hasMore) alongside records, enabling clients to request subsequent pages without manual offset calculation. Supports configurable page size (default 100, max 100 per Airtable API limits) and automatic iteration for clients that request all records.