feat(attachments): add autotask_create_ticket_attachment tool (#55) (#62)

Adds a new MCP tool and service method for uploading file attachments
to Autotask tickets via POST /Tickets/{id}/Attachments. File content
is accepted as a base64-encoded string (MCP is JSON-RPC, so binary
bytes must be base64-encoded).

The service method validates the base64 input and enforces Autotask's
3 MB hard limit on ticket attachments locally, returning a clear error
instead of a cryptic 400 from the API. API validation errors are
surfaced using the same pattern as #32.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: asachs01

src/handlers/tool.definitions.ts

@@ -1274,6 +1274,43 @@ export const TOOL_DEFINITIONS: McpTool[] = [
       required: ['ticketId']
     }
   },
+  {
+    name: 'autotask_create_ticket_attachment',
+    description:
+      'Upload a file attachment to an existing ticket. The file content must be passed as a base64-encoded string in the `data` field (MCP is JSON-RPC, so binary bytes must be base64-encoded). Autotask enforces a 3 MB hard limit on ticket attachments; this tool validates the decoded size before calling the API and returns a clear error if the limit is exceeded. Example: { ticketId: 12345, title: "screenshot.png", data: "iVBORw0KGgoAAAANSUhEUgAA..." }',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticketId: {
+          type: 'number',
+          description: 'The ticket ID to attach the file to'
+        },
+        title: {
+          type: 'string',
+          description: 'Display title for the attachment (typically the filename, e.g. "screenshot.png")'
+        },
+        data: {
+          type: 'string',
+          description:
+            'Base64-encoded file content. Maximum decoded size: 3 MB (Autotask ticket attachment limit). Example: read a file and pass its base64 representation here.'
+        },
+        fullPath: {
+          type: 'string',
+          description: 'Original filename including any path. Defaults to `title` if not provided.'
+        },
+        contentType: {
+          type: 'string',
+          description: 'MIME type of the file (e.g. "image/png", "application/pdf"). Optional.'
+        },
+        publish: {
+          type: 'number',
+          description: 'Visibility: 1 = All Autotask Users (default), 2 = Internal Users Only',
+          default: 1
+        }
+      },
+      required: ['ticketId', 'title', 'data']
+    }
+  },
 
   // Expense Reports tools
   {
@@ -2906,7 +2943,7 @@ export const TOOL_CATEGORIES: Record<string, { description: string; tools: strin
   },
   tickets: {
     description: 'Search, create, update tickets and manage ticket notes, attachments, and charges',
-    tools: ['autotask_search_tickets', 'autotask_get_ticket_details', 'autotask_create_ticket', 'autotask_update_ticket', 'autotask_get_ticket_note', 'autotask_search_ticket_notes', 'autotask_create_ticket_note', 'autotask_get_ticket_attachment', 'autotask_search_ticket_attachments', 'autotask_get_ticket_charge', 'autotask_search_ticket_charges', 'autotask_create_ticket_charge', 'autotask_update_ticket_charge', 'autotask_delete_ticket_charge']
+    tools: ['autotask_search_tickets', 'autotask_get_ticket_details', 'autotask_create_ticket', 'autotask_update_ticket', 'autotask_get_ticket_note', 'autotask_search_ticket_notes', 'autotask_create_ticket_note', 'autotask_get_ticket_attachment', 'autotask_search_ticket_attachments', 'autotask_create_ticket_attachment', 'autotask_get_ticket_charge', 'autotask_search_ticket_charges', 'autotask_create_ticket_charge', 'autotask_update_ticket_charge', 'autotask_delete_ticket_charge']
   },
   projects: {
     description: 'Search and create projects, tasks, phases, and project notes',

src/handlers/tool.handler.ts

@@ -1078,6 +1078,23 @@ export class AutotaskToolHandler {
       ['autotask_search_ticket_attachments', async (a) => {
         const r = await s.searchTicketAttachments(a.ticketId, { pageSize: a.pageSize }); return { result: r, message: `Found ${r.length} ticket attachments` };
       }],
+      ['autotask_create_ticket_attachment', async (a) => {
+        // Never log `data` (base64 file bytes) — can be large / contain PII.
+        const decodedBytes = typeof a.data === 'string'
+          ? Buffer.from(a.data, 'base64').length
+          : 0;
+        this.logger.info(
+          `autotask_create_ticket_attachment invoked: ticketId=${a.ticketId} title="${a.title}" bytes=${decodedBytes}`
+        );
+        const id = await s.createTicketAttachment(a.ticketId, {
+          title: a.title,
+          fullPath: a.fullPath || a.title,
+          data: a.data,
+          contentType: a.contentType,
+          publish: a.publish ?? 1
+        });
+        return { result: id, message: `Successfully created ticket attachment with ID: ${id}` };
+      }],
 
       // Expense Reports
       ['autotask_get_expense_report', async (a) => {

src/services/autotask.service.ts

@@ -20,6 +20,7 @@ import {
   AutotaskCompanyNote,
   AutotaskTicketAttachment,
   AutotaskTicketChecklistItem,
+  AutotaskTicketAttachmentCreateRequest,
   AutotaskExpenseReport,
   AutotaskExpenseItem,
   AutotaskQuote,
@@ -1516,6 +1517,82 @@ export class AutotaskService {
     }
   }
 
+  /**
+   * Upload a file attachment to a ticket. `data.data` must be a base64-encoded
+   * string of the raw file bytes. Autotask enforces a 3MB hard limit on ticket
+   * attachments; we validate locally so callers get a clear error instead of a
+   * cryptic 400 from the API.
+   */
+  async createTicketAttachment(
+    ticketId: number,
+    data: AutotaskTicketAttachmentCreateRequest
+  ): Promise<number> {
+    const MAX_ATTACHMENT_BYTES = 3 * 1024 * 1024; // 3 MB
+
+    if (!data || typeof data.data !== 'string' || data.data.length === 0) {
+      throw new Error('createTicketAttachment: `data` (base64-encoded file content) is required');
+    }
+    if (!data.title) {
+      throw new Error('createTicketAttachment: `title` is required');
+    }
+
+    // Validate base64 and decoded size up front.
+    let decodedLength: number;
+    try {
+      const buf = Buffer.from(data.data, 'base64');
+      // Buffer.from silently drops invalid chars, so round-trip to detect garbage.
+      if (buf.toString('base64').replace(/=+$/, '') !== data.data.replace(/\s+/g, '').replace(/=+$/, '')) {
+        throw new Error('invalid base64');
+      }
+      decodedLength = buf.length;
+    } catch {
+      throw new Error('createTicketAttachment: `data` is not valid base64-encoded content');
+    }
+
+    if (decodedLength === 0) {
+      throw new Error('createTicketAttachment: decoded attachment is empty');
+    }
+    if (decodedLength > MAX_ATTACHMENT_BYTES) {
+      throw new Error(
+        `createTicketAttachment: attachment is ${decodedLength} bytes which exceeds the Autotask 3MB (${MAX_ATTACHMENT_BYTES} byte) limit for ticket attachments`
+      );
+    }
+
+    const client = await this.ensureClient();
+
+    const payload = {
+      title: data.title,
+      fullPath: data.fullPath || data.title,
+      data: data.data,
+      attachmentType: data.attachmentType || 'FILE_ATTACHMENT',
+      contentType: data.contentType,
+      publish: data.publish ?? 1,
+      parentId: ticketId,
+      parentType: 4 // Ticket
+    };
+
+    try {
+      this.logger.info(
+        `Creating ticket attachment - ticketId=${ticketId} title="${data.title}" bytes=${decodedLength}`
+      );
+      const axiosInstance = (client as any).axios;
+      const response = await axiosInstance.post(`/Tickets/${ticketId}/Attachments`, payload);
+      const attachmentId = response.data?.itemId ?? response.data?.id;
+      this.logger.info(`Ticket attachment created with ID: ${attachmentId} for ticket ${ticketId}`);
+      return attachmentId;
+    } catch (error) {
+      this.logger.error(`Failed to create ticket attachment for ticket ${ticketId}:`, error);
+      // Surface Autotask API validation errors rather than a generic 500.
+      const apiErrors: string[] | undefined =
+        (error as any)?.originalError?.response?.data?.errors ||
+        (error as any)?.response?.data?.errors;
+      if (apiErrors && apiErrors.length > 0) {
+        throw new Error(`Autotask API error: ${apiErrors.join('; ')}`);
+      }
+      throw error;
+    }
+  }
+
   // Expense entities
   async getExpenseReport(id: number): Promise<AutotaskExpenseReport | null> {
     const client = await this.ensureClient();

src/types/autotask.ts

@@ -261,6 +261,20 @@ export interface AutotaskTicketAttachment {
   [key: string]: any;
 }
 
+/**
+ * Request payload for creating a ticket attachment via
+ * POST /Tickets/{id}/Attachments. Autotask expects the file bytes
+ * as a base64-encoded string in `data`.
+ */
+export interface AutotaskTicketAttachmentCreateRequest {
+  title: string;
+  fullPath: string;
+  data: string; // base64-encoded file bytes
+  attachmentType?: string; // defaults to 'FILE_ATTACHMENT'
+  contentType?: string;
+  publish?: number; // 1 = All Autotask Users, 2 = Internal Users Only
+}
+
 export interface AutotaskExpenseReport {
   id?: number;
   name?: string;

tests/autotask-service.test.ts

@@ -133,11 +133,79 @@ describe('AutotaskService', () => {
 
     test('should handle attachment methods with proper error messages', async () => {
       const service = new AutotaskService(mockConfig, mockLogger);
-      
+
       await expect(service.getTicketAttachment(123, 456)).rejects.toThrow();
       await expect(service.searchTicketAttachments(123)).rejects.toThrow();
     });
 
+    describe('createTicketAttachment', () => {
+      const validBase64 = Buffer.from('hello world').toString('base64');
+
+      test('rejects invalid base64 before any HTTP call', async () => {
+        const service = new AutotaskService(mockConfig, mockLogger);
+        // Spy to ensure ensureClient is never reached
+        const ensureSpy = jest
+          .spyOn(service as any, 'ensureClient')
+          .mockResolvedValue({ axios: { post: jest.fn() } });
+
+        await expect(
+          service.createTicketAttachment(123, {
+            title: 'bad.bin',
+            fullPath: 'bad.bin',
+            data: 'not*valid*base64!!!'
+          })
+        ).rejects.toThrow(/not valid base64/);
+
+        expect(ensureSpy).not.toHaveBeenCalled();
+      });
+
+      test('rejects oversized attachments before any HTTP call', async () => {
+        const service = new AutotaskService(mockConfig, mockLogger);
+        const ensureSpy = jest
+          .spyOn(service as any, 'ensureClient')
+          .mockResolvedValue({ axios: { post: jest.fn() } });
+
+        // 4 MB of zero bytes, base64-encoded
+        const big = Buffer.alloc(4 * 1024 * 1024).toString('base64');
+        await expect(
+          service.createTicketAttachment(123, {
+            title: 'huge.bin',
+            fullPath: 'huge.bin',
+            data: big
+          })
+        ).rejects.toThrow(/exceeds the Autotask 3MB/);
+
+        expect(ensureSpy).not.toHaveBeenCalled();
+      });
+
+      test('happy path posts to /Tickets/{id}/Attachments and returns itemId', async () => {
+        const service = new AutotaskService(mockConfig, mockLogger);
+        const post = jest.fn().mockResolvedValue({ data: { itemId: 987 } });
+        jest
+          .spyOn(service as any, 'ensureClient')
+          .mockResolvedValue({ axios: { post } });
+
+        const id = await service.createTicketAttachment(555, {
+          title: 'readme.txt',
+          fullPath: 'readme.txt',
+          data: validBase64,
+          contentType: 'text/plain',
+          publish: 1
+        });
+
+        expect(id).toBe(987);
+        expect(post).toHaveBeenCalledTimes(1);
+        const [url, body] = post.mock.calls[0];
+        expect(url).toBe('/Tickets/555/Attachments');
+        expect(body.title).toBe('readme.txt');
+        expect(body.fullPath).toBe('readme.txt');
+        expect(body.data).toBe(validBase64);
+        expect(body.attachmentType).toBe('FILE_ATTACHMENT');
+        expect(body.publish).toBe(1);
+        expect(body.parentId).toBe(555);
+      });
+    });
+
     test('should handle expense methods with proper error messages', async () => {
       const service = new AutotaskService(mockConfig, mockLogger);