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;
    }
  }