Add upload_attachment tool for direct file uploads (#86)

* Add upload_attachment tool for Airtable API

Co-authored-by: Cursor <cursoragent@cursor.com>

* Deduplicate AirtableRecordSchema and clarify upload_attachment file description

- Extract shared AirtableRecordSchema in types.ts, replacing 5 inline
  copies across airtableService.ts
- Reuse AirtableRecordSchema for upload-attachment.ts outputSchema
- Clarify that the file parameter expects raw base64 (no data URL prefix)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: David <david@example.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 4 people

src/airtableService.ts

@@ -15,6 +15,7 @@ import {
 	FieldSchema,
 	CommentSchema,
 	ListCommentsResponseSchema,
+	AirtableRecordSchema,
 	type FieldSet,
 } from './types.js';
 import {enhanceAirtableError} from './enhanceAirtableError.js';
@@ -84,7 +85,7 @@ export class AirtableService implements IAirtableService {
 			const response = await this.fetchFromAPI(
 				`/v0/${baseId}/${tableId}?${queryParams.toString()}`,
 				z.object({
-					records: z.array(z.object({id: z.string(), fields: z.record(z.string(), z.any())})),
+					records: z.array(AirtableRecordSchema),
 					offset: z.string().optional(),
 				}),
 			);
@@ -99,14 +100,14 @@ export class AirtableService implements IAirtableService {
 	async getRecord(baseId: string, tableId: string, recordId: string): Promise<AirtableRecord> {
 		return this.fetchFromAPI(
 			`/v0/${baseId}/${tableId}/${recordId}`,
-			z.object({id: z.string(), fields: z.record(z.string(), z.any())}),
+			AirtableRecordSchema,
 		);
 	}
 
 	async createRecord(baseId: string, tableId: string, fields: FieldSet): Promise<AirtableRecord> {
 		return this.fetchFromAPI(
 			`/v0/${baseId}/${tableId}`,
-			z.object({id: z.string(), fields: z.record(z.string(), z.any())}),
+			AirtableRecordSchema,
 			{
 				method: 'POST',
 				body: JSON.stringify({fields}),
@@ -121,7 +122,7 @@ export class AirtableService implements IAirtableService {
 	): Promise<AirtableRecord[]> {
 		const response = await this.fetchFromAPI(
 			`/v0/${baseId}/${tableId}`,
-			z.object({records: z.array(z.object({id: z.string(), fields: z.record(z.string(), z.any())}))}),
+			z.object({records: z.array(AirtableRecordSchema)}),
 			{
 				method: 'PATCH',
 				body: JSON.stringify({records}),
@@ -263,6 +264,27 @@ export class AirtableService implements IAirtableService {
 		return this.fetchFromAPI(endpoint, ListCommentsResponseSchema);
 	}
 
+	async uploadAttachment(
+		baseId: string,
+		recordId: string,
+		attachmentFieldIdOrName: string,
+		file: string,
+		filename: string,
+		contentType: string,
+	): Promise<AirtableRecord> {
+		const contentBaseUrl = 'https://content.airtable.com';
+		const endpoint = `/v0/${baseId}/${recordId}/${encodeURIComponent(attachmentFieldIdOrName)}/uploadAttachment`;
+		return this.fetchFromAPI(
+			endpoint,
+			AirtableRecordSchema,
+			{
+				method: 'POST',
+				body: JSON.stringify({contentType, file, filename}),
+			},
+			contentBaseUrl,
+		);
+	}
+
 	private async validateAndGetSearchFields(
 		baseId: string,
 		tableId: string,
@@ -305,8 +327,14 @@ export class AirtableService implements IAirtableService {
 		return searchableFields;
 	}
 
-	private async fetchFromAPI<T>(endpoint: string, schema: z.ZodType<T>, options: RequestInit = {}): Promise<T> {
-		const response = await this.fetch(`${this.baseUrl}${endpoint}`, {
+	private async fetchFromAPI<T>(
+		endpoint: string,
+		schema: z.ZodType<T>,
+		options: RequestInit = {},
+		baseUrl?: string,
+	): Promise<T> {
+		const url = (baseUrl ?? this.baseUrl) + endpoint;
+		const response = await this.fetch(url, {
 			...options,
 			headers: {
 				Authorization: `Bearer ${this.apiKey}`,

src/e2e.test.ts

@@ -231,6 +231,7 @@ describe.each([
 				'update_field',
 				'create_comment',
 				'list_comments',
+				'upload_attachment',
 			]);
 			expect(result.tools[0]).toMatchObject({
 				name: 'list_records',

src/mcpServer.test.ts

@@ -136,7 +136,7 @@ describe('AirtableMCPServer', () => {
 				params: {},
 			});
 
-			expect((response.result.tools as Tool[]).length).toBe(15);
+			expect((response.result.tools as Tool[]).length).toBe(16);
 			expect((response.result.tools as Tool[])[0]).toMatchObject({
 				name: expect.any(String),
 				description: expect.any(String),

src/tools/index.ts

@@ -15,6 +15,7 @@ import {registerCreateField} from './create-field.js';
 import {registerUpdateField} from './update-field.js';
 import {registerCreateComment} from './create-comment.js';
 import {registerListComments} from './list-comments.js';
+import {registerUploadAttachment} from './upload-attachment.js';
 
 export type {ToolContext} from './types.js';
 
@@ -34,4 +35,5 @@ export function registerAll(server: McpServer, ctx: ToolContext): void {
 	registerUpdateField(server, ctx);
 	registerCreateComment(server, ctx);
 	registerListComments(server, ctx);
+	registerUploadAttachment(server, ctx);
 }

src/tools/upload-attachment.ts

@@ -0,0 +1,47 @@
+import type {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+import {z} from 'zod';
+import type {ToolContext} from './types.js';
+import {baseId} from './schemas.js';
+import {jsonResult} from '../utils/response.js';
+import {AirtableRecordSchema} from '../types.js';
+
+const outputSchema = AirtableRecordSchema;
+
+export function registerUploadAttachment(server: McpServer, ctx: ToolContext): void {
+	server.registerTool(
+		'upload_attachment',
+		{
+			title: 'Upload Attachment',
+			description:
+				'Upload a file directly to an attachment field on an existing record using Airtable\'s upload API. Supports files up to 5 MB. For larger files, use create_record or update_records with a public URL. The record must already exist.',
+			inputSchema: {
+				...baseId,
+				recordId: z.string().describe('The ID of the existing record (e.g. recXXXXXXXXXXXXXX)'),
+				attachmentFieldIdOrName: z
+					.string()
+					.describe('The ID or name of the attachment field (e.g. fldXXXXXXXXXXXXXX or "Images")'),
+				file: z.string().describe('Raw base64-encoded file content (no data URL prefix)'),
+				filename: z.string().describe('Filename for the attachment (e.g. "image.jpg")'),
+				contentType: z
+					.string()
+					.describe('MIME type of the file (e.g. "image/jpeg", "image/png", "application/pdf")'),
+			},
+			outputSchema,
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+			},
+		},
+		async (args) => {
+			const record = await ctx.airtableService.uploadAttachment(
+				args.baseId,
+				args.recordId,
+				args.attachmentFieldIdOrName,
+				args.file,
+				args.filename,
+				args.contentType,
+			);
+			return jsonResult(outputSchema.parse({id: record.id, fields: record.fields}));
+		},
+	);
+}

src/types.ts

@@ -561,7 +561,8 @@ export type Comment = z.infer<typeof CommentSchema>;
 export type ListCommentsResponse = z.infer<typeof ListCommentsResponseSchema>;
 
 export type FieldSet = Record<string, any>;
-export type AirtableRecord = {id: string; fields: FieldSet};
+export const AirtableRecordSchema = z.object({id: z.string(), fields: z.record(z.string(), z.any())});
+export type AirtableRecord = z.infer<typeof AirtableRecordSchema>;
 
 export type ListRecordsOptions = {
 	view?: z.infer<typeof ListRecordsArgsSchema.shape.view>;
@@ -585,6 +586,14 @@ export type IAirtableService = {
 	searchRecords(baseId: string, tableId: string, searchTerm: string, fieldIds?: string[], maxRecords?: number, view?: string): Promise<AirtableRecord[]>;
 	createComment(baseId: string, tableId: string, recordId: string, text: string, parentCommentId?: string): Promise<Comment>;
 	listComments(baseId: string, tableId: string, recordId: string, pageSize?: number, offset?: string): Promise<ListCommentsResponse>;
+	uploadAttachment(
+		baseId: string,
+		recordId: string,
+		attachmentFieldIdOrName: string,
+		file: string,
+		filename: string,
+		contentType: string,
+	): Promise<AirtableRecord>;
 };
 
 export type IAirtableMCPServer = {