Autotask MCP Server

Instructions

Implementation Reference

• src/handlers/tool.handler.ts:502-521 (schema)

  Tool schema definition including name, description, and input schema requiring ticketId and optional pageSize.

  {
    name: 'search_ticket_notes',
    description: 'Search for notes on a specific ticket',
    inputSchema: {
      type: 'object',
      properties: {
        ticketId: {
          type: 'number',
          description: 'The ticket ID to search notes for'
        },
        pageSize: {
          type: 'number',
          description: 'Number of results to return (default: 25, max: 100)',
          minimum: 1,
          maximum: 100
        }
      },
      required: ['ticketId']
    }
  },

• src/handlers/tool.handler.ts:1179-1182 (handler)

  MCP tool handler logic in callTool switch statement: extracts args, calls autotaskService.searchTicketNotes, sets success message.

  case 'search_ticket_notes':
    result = await this.autotaskService.searchTicketNotes(args.ticketId, { pageSize: args.pageSize });
    message = `Found ${result.length} ticket notes`;
    break;

• src/services/autotask.service.ts:1217-1240 (helper)

  Core service method implementing the search: queries Autotask notes.list API filtered by ticketId with pagination support, returns typed AutotaskTicketNote[]

  async searchTicketNotes(ticketId: number, options: AutotaskQueryOptionsExtended = {}): Promise<AutotaskTicketNote[]> {
    const client = await this.ensureClient();
    
    try {
      this.logger.debug(`Searching ticket notes for ticket ${ticketId}:`, options);
      
      // Set reasonable limits for notes
      const optimizedOptions = {
        filter: [
          { field: 'ticketId', op: 'eq', value: ticketId }
        ],
        pageSize: options.pageSize || 25
      };
  
      const result = await client.notes.list(optimizedOptions);
      const notes = (result.data as any[]) || [];
      
      this.logger.info(`Retrieved ${notes.length} ticket notes`);
      return notes as AutotaskTicketNote[];
    } catch (error) {
      this.logger.error(`Failed to search ticket notes for ticket ${ticketId}:`, error);
      throw error;
    }
  }

• src/mcp/server.ts:98-110 (registration)

  MCP server registers the ListTools handler which delegates to toolHandler.listTools() returning all tools including search_ticket_notes.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    try {
      this.logger.debug('Handling list tools request');
      const tools = await this.toolHandler.listTools();
      return { tools };
    } catch (error) {
      this.logger.error('Failed to list tools:', error);
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to list tools: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  });

• src/mcp/server.ts:112-131 (handler)

  MCP server registers the CallTool handler which delegates tool execution (including search_ticket_notes) to toolHandler.callTool.

  // Call a tool
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      this.logger.debug(`Handling tool call: ${request.params.name}`);
      const result = await this.toolHandler.callTool(
        request.params.name,
        request.params.arguments || {}
      );
      return {
        content: result.content,
        isError: result.isError
      };
    } catch (error) {
      this.logger.error(`Failed to call tool ${request.params.name}:`, error);
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to call tool: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  });