Autotask MCP Server

Instructions

Implementation Reference

• src/services/autotask.service.ts:232-301 (handler)

  Core handler function that implements the search_contacts tool logic. Performs paginated query to Autotask Contacts API using autotask-node client, with automatic full pagination unless pageSize specified.
  async searchContacts(options: AutotaskQueryOptions = {}): Promise<AutotaskContact[]> { const client = await this.ensureClient(); try { this.logger.debug('Searching contacts with options:', options); // PAGINATION BY DEFAULT for data accuracy // Only limit results when user explicitly provides pageSize if (options.pageSize !== undefined && options.pageSize > 0) { // User wants limited results const queryOptions = { ...options, pageSize: Math.min(options.pageSize, 500) // Respect user limit, max 500 per request }; this.logger.debug('Single page request with user-specified limit:', queryOptions); const result = await client.contacts.list(queryOptions as any); const contacts = (result.data as AutotaskContact[]) || []; this.logger.info(`Retrieved ${contacts.length} contacts (limited by user to ${options.pageSize})`); return contacts; } else { // DEFAULT: Get ALL matching contacts via pagination for complete accuracy const allContacts: AutotaskContact[] = []; const pageSize = 500; // Use max safe page size for efficiency let currentPage = 1; let hasMorePages = true; while (hasMorePages) { const queryOptions = { ...options, pageSize: pageSize, page: currentPage }; this.logger.debug(`Fetching contacts page ${currentPage}...`); const result = await client.contacts.list(queryOptions as any); const contacts = (result.data as AutotaskContact[]) || []; if (contacts.length === 0) { hasMorePages = false; } else { allContacts.push(...contacts); // Check if we got a full page - if not, we're done if (contacts.length < pageSize) { hasMorePages = false; } else { currentPage++; } } // Safety check to prevent infinite loops if (currentPage > 30) { this.logger.warn('Contact pagination safety limit reached at 30 pages (15,000 contacts)'); hasMorePages = false; } } this.logger.info(`Retrieved ${allContacts.length} contacts across ${currentPage} pages (COMPLETE dataset for accuracy)`); return allContacts; } } catch (error) { this.logger.error('Failed to search contacts:', error); throw error; } }
• src/handlers/tool.handler.ts:168-194 (registration)

  Tool registration in listTools(): defines name 'search_contacts', description, and input schema. Returned by MCP listTools handler.
  name: 'search_contacts', description: 'Search for contacts in Autotask with optional filters', inputSchema: { type: 'object', properties: { searchTerm: { type: 'string', description: 'Search term for contact name or email' }, companyID: { type: 'number', description: 'Filter by company ID' }, isActive: { type: 'number', description: 'Filter by active status (1=active, 0=inactive)' }, pageSize: { type: 'number', description: 'Number of results to return (default: 50, max: 200)', minimum: 1, maximum: 200 } }, required: [] } },
• src/handlers/tool.handler.ts:1091-1094 (handler)

  MCP tool dispatch in callTool(): handles 'search_contacts' case by delegating to AutotaskService.searchContacts(args).
  case 'search_contacts': result = await this.autotaskService.searchContacts(args); message = `Found ${result.length} contacts`; break;
• src/types/mcp.ts:84-84 (schema)

  Type constant defining internal tool name mapping.
  SEARCH_CONTACTS: 'autotask_search_contacts',
• src/handlers/resource.handler.ts:126-128 (helper)

  Usage in resource handler for autotask://contacts resource listing.
  data = await this.autotaskService.searchContacts({ pageSize: 100 }); description = `List of ${data.length} contacts`; }