Attio MCP Server

Instructions

Implementation Reference

• src/config/tool-aliases.ts:19-24 (registration)

  Deprecated tool alias that maps user-called 'search-records' to canonical 'records_search' tool
  'search-records': { target: 'records_search', reason: 'Phase 1 search tool rename (#776)', since: SINCE_PHASE_1, removal: 'v1.x (TBD)', },
• src/handlers/tool-configs/universal/core/index.ts:37-45 (registration)

  Registers 'records_search' tool configuration as part of core universal operations
  records_search: searchRecordsConfig, records_get_details: getRecordDetailsConfig, 'create-record': createRecordConfig, 'update-record': updateRecordConfig, 'delete-record': deleteRecordConfig, records_get_attributes: getAttributesConfig, records_discover_attributes: discoverAttributesConfig, records_get_info: getDetailedInfoConfig, };
• src/handlers/tool-configs/universal/core/search-operations.ts:155-168 (schema)

  MCP tool definition including input schema (searchRecordsSchema) and description for 'records_search'
  export const searchRecordsDefinition = { name: 'records_search', description: formatToolDescription({ capability: 'Search across companies, people, deals, tasks, and records', boundaries: 'create or modify records', constraints: 'Returns max 100 results (default: 10)', recoveryHint: 'use records.discover_attributes to find searchable fields', }), inputSchema: searchRecordsSchema, annotations: { readOnlyHint: true, idempotentHint: true, }, };
• src/handlers/tool-configs/universal/core/search-operations.ts:20-153 (handler)

  MCP tool handler configuration for 'records_search': validates params, calls handleUniversalSearch (delegates to UniversalSearchService), handles errors and formats results
  export const searchRecordsConfig: UniversalToolConfig< UniversalSearchParams, AttioRecord[] > = { name: 'records_search', handler: async (params: UniversalSearchParams): Promise<AttioRecord[]> => { try { const sanitizedParams = validateUniversalToolParams( 'records_search', params ); return await handleUniversalSearch(sanitizedParams); } catch (error: unknown) { return await handleSearchError( error, params.resource_type, params as unknown as Record<string, unknown> ); } }, formatResult: ( results: AttioRecord[] | { data: AttioRecord[] }, ...args: unknown[] ): string => { const resourceType = args[0] as UniversalResourceType | undefined; if (!results) { const typeName = resourceType ? getPluralResourceType(resourceType) : 'records'; return `Found 0 ${typeName}`; } const recordsArray = Array.isArray(results) ? results : (results?.data ?? []); if (!Array.isArray(recordsArray) || recordsArray.length === 0) { const typeName = resourceType ? getPluralResourceType(resourceType) : 'records'; return `Found 0 ${typeName}`; } const typeName = resourceType ? getPluralResourceType(resourceType) : 'records'; const formattedResults = recordsArray .map((record, index) => { let identifier = 'Unnamed'; let id = String(record.id?.record_id || 'unknown'); const values = record.values || {}; const getFirstValue = (field: unknown): string | undefined => { if (!field || !Array.isArray(field) || field.length === 0) return undefined; const firstItem = field[0] as { value?: string }; return firstItem && typeof firstItem === 'object' && firstItem !== null && 'value' in firstItem ? String(firstItem.value) : undefined; }; if (resourceType === UniversalResourceType.TASKS) { identifier = typeof values.content === 'string' ? values.content : getFirstValue(values.content) || 'Unnamed'; id = String(record.id?.task_id || record.id?.record_id || 'unknown'); } else if (resourceType === UniversalResourceType.PEOPLE) { const valuesAny = values as Record<string, unknown>; const name = (valuesAny?.name as { full_name?: string }[] | undefined)?.[0] ?.full_name || (valuesAny?.name as { value?: string }[] | undefined)?.[0]?.value || (valuesAny?.name as { formatted?: string }[] | undefined)?.[0] ?.formatted || (valuesAny?.full_name as { value?: string }[] | undefined)?.[0] ?.value || getFirstValue(values.name) || 'Unnamed'; const emailValue = ( valuesAny?.email_addresses as | { email_address?: string }[] | undefined )?.[0]?.email_address || ( valuesAny?.email_addresses as { value?: string }[] | undefined )?.[0]?.value || getFirstValue(values.email) || getFirstValue(valuesAny.email_addresses); identifier = emailValue ? `${name} (${emailValue})` : name; } else if (resourceType === UniversalResourceType.COMPANIES) { const name = typeof values.name === 'string' ? values.name : getFirstValue(values.name) || 'Unnamed'; const website = getFirstValue(values.website); const domain = values.domains && Array.isArray(values.domains) && values.domains.length > 0 ? (values.domains[0] as { domain?: string }).domain : undefined; const email = getFirstValue(values.email); const contactInfo = website || domain || email; identifier = contactInfo ? `${name} (${contactInfo})` : name; } else { const nameValue = getFirstValue(values.name); const titleValue = getFirstValue(values.title); identifier = nameValue || titleValue || 'Unnamed'; } return `${index + 1}. ${identifier} (ID: ${id})`; }) .join('\n'); return `Found ${recordsArray.length} ${typeName}:\n${formattedResults}`; }, structuredOutput: ( results: AttioRecord[] | { data: AttioRecord[] } ): Record<string, unknown> => { // Return the raw records array for JSON parsing const recordsArray = Array.isArray(results) ? results : (results?.data ?? []); return { data: recordsArray, count: recordsArray.length }; }, };
• src/services/UniversalSearchService.ts:200-378 (handler)

  Core search implementation: handles validation, performance tracking, timeframe processing, and delegates to resource-specific strategies or Query API via performSearchByResourceType
  static async searchRecords( params: UniversalSearchParams ): Promise<AttioRecord[]> { const { resource_type, query, filters, limit, offset, search_type = SearchType.BASIC, fields, match_type = MatchType.PARTIAL, sort = SortType.NAME, // New TC search parameters relationship_target_type, relationship_target_id, timeframe_attribute, start_date, end_date, date_operator, content_fields, use_or_logic, // Issue #475: New date filtering parameters date_from, date_to, created_after, created_before, updated_after, updated_before, timeframe, date_field, } = params; // Start performance tracking const perfId = enhancedPerformanceTracker.startOperation( 'search-records', 'search', { resourceType: resource_type, hasQuery: !!query, hasFilters: !!(filters && Object.keys(filters).length > 0), limit, offset, searchType: search_type, hasFields: !!(fields && fields.length > 0), matchType: match_type, sortType: sort, } ); // Track validation timing const validationStart = performance.now(); // Validate pagination parameters using ValidationService ValidationService.validatePaginationParameters({ limit, offset }, perfId); // Validate filter schema for malformed advanced filters ValidationService.validateFiltersSchema(filters); enhancedPerformanceTracker.markTiming( perfId, 'validation', performance.now() - validationStart ); // Issue #475: Convert user-friendly date parameters to API format let processedTimeframeParams = { timeframe_attribute, start_date, end_date, date_operator, }; try { const dateConversion = convertDateParamsToTimeframeQuery({ date_from, date_to, created_after, created_before, updated_after, updated_before, timeframe, date_field, }); if (dateConversion) { // Use converted parameters, prioritizing user-friendly parameters processedTimeframeParams = { ...processedTimeframeParams, ...dateConversion, }; } } catch (dateError: unknown) { // Re-throw date validation errors with helpful context const errorMessage = dateError instanceof Error ? `Date parameter validation failed: ${dateError.message}` : 'Invalid date parameters provided'; throw new Error(errorMessage); } // Auto-detect timeframe searches and FORCE them to use the Query API let finalSearchType = search_type; const hasTimeframeParams = processedTimeframeParams.timeframe_attribute && (processedTimeframeParams.start_date || processedTimeframeParams.end_date); if (hasTimeframeParams) { finalSearchType = SearchType.TIMEFRAME; debug( 'UniversalSearchService', 'FORCING timeframe search to use Query API (advanced search API does not support date comparisons)', { originalSearchType: search_type, timeframe_attribute: processedTimeframeParams.timeframe_attribute, start_date: processedTimeframeParams.start_date, end_date: processedTimeframeParams.end_date, date_operator: processedTimeframeParams.date_operator, } ); } // Track API call timing const apiStart = enhancedPerformanceTracker.markApiStart(perfId); let results: AttioRecord[]; try { results = await this.performSearchByResourceType( resource_type, { query, filters, limit, offset, search_type: finalSearchType, fields, match_type, sort, // New TC search parameters relationship_target_type, relationship_target_id, // Use processed timeframe parameters (Issue #475) timeframe_attribute: processedTimeframeParams.timeframe_attribute, start_date: processedTimeframeParams.start_date, end_date: processedTimeframeParams.end_date, date_operator: processedTimeframeParams.date_operator, content_fields, use_or_logic, }, perfId, apiStart ); enhancedPerformanceTracker.markApiEnd(perfId, apiStart); enhancedPerformanceTracker.endOperation(perfId, true, undefined, 200, { recordCount: results.length, }); return results; } catch (apiError: unknown) { enhancedPerformanceTracker.markApiEnd(perfId, apiStart); const errorObj = apiError as Record<string, unknown>; const statusCode = ((errorObj?.response as Record<string, unknown>)?.status as number) || (errorObj?.statusCode as number) || 500; const errorMessage = apiError instanceof Error ? apiError.message : 'Search failed'; enhancedPerformanceTracker.endOperation( perfId, false, errorMessage, statusCode ); throw apiError; } }